fix(dotenv): register dotenv.parse so it stops compiling to a swallowed runtime throw

[jdalton]

Problem

dotenv.parse(...) compiles to a deferred throw-on-reach runtime error, even though the native implementation has always been there and linked into every binary.

js_dotenv_parse is defined and exported by both crates/perry-stdlib/src/dotenv.rs and the bundled well-known binding crates/perry-ext-dotenv/src/lib.rs, and it is declared to codegen in runtime_decls/stdlib_ffi/utilities.rs. What was missing was the last two links in the chain: the API manifest only ever registered dotenv.config, and NATIVE_MODULE_TABLE only ever had a config dispatch row. So the #463 unimplemented-API gate fired on every dotenv.parse call site and — under the default (defer) policy — compiled it to a value that throws only if reached.

Before:

$ perry repro.ts -o repro && ./repro
notice: 1 ahead-of-time-unsupported site handled at runtime:
  - unimplemented API   repro.ts:3   → deferred runtime error (throws only if reached)
Error: dotenv.parse is not implemented in Perry (ahead-of-time) (repro.ts:3)

Why this is a data-loss bug, not a missing feature

The usual shape for loading a config file is a try/catch around the parse, because a malformed .env is not supposed to be fatal. Socket Firewall's readConfigFile() is exactly that:

function readConfigFile(p: string) {
  try {
    return dotenv.parse(fs.readFileSync(p, 'utf8'))
  } catch {
    return {}
  }
}

The deferred throw lands inside that catch, so it is swallowed. The program does not crash, does not warn, and does not print a deferred-site notice at runtime — it simply runs as though the user had no .env file at all. Every setting in it is silently dropped. A user debugging "why is my config being ignored" has nothing to go on.

Fix

Two rows, no new runtime code.

• crates/perry-codegen/src/lower_call/native_table/utils_crypto.rs — add the dotenv.parse dispatch row: args: &[NA_STR], ret: NR_OBJ_FROM_JSON_STR.
• crates/perry-api-manifest/src/entries/part_1.rs — register dotenv.parse(src: string): any.
• docs/api/perry.d.ts, docs/src/api/reference.md — regenerated from the manifest.

The return kind is the load-bearing detail. js_dotenv_parse hands back a JSON string, not an object. NR_OBJ_FROM_JSON_STR is the existing return kind (used by jsonwebtoken.decode) that pipes the pointer through js_json_parse, so what TypeScript actually receives is a real object. With a plain NR_STR the call would have compiled and "worked" while returning the string {"FOO":"bar"}, and parsed.FOO would have read undefined — a quieter version of the same bug. The test asserts the return kind for that reason.

Verification

End-to-end against a perry-dev build:

import dotenv from 'dotenv';
const parsed = dotenv.parse('FOO=bar\n# comment\nBAZ="qux"\nNUM=42\n');
console.log(typeof parsed);                            // object
console.log(parsed.FOO, parsed.BAZ, parsed.NUM);       // bar qux 42
console.log(Object.keys(parsed).sort().join(','));     // BAZ,FOO,NUM

function readConfigFile(text: string) {
  try { return dotenv.parse(text) as Record<string, string> } catch { return {} }
}
console.log(readConfigFile('API_TOKEN=secret\n').API_TOKEN);  // secret

import { parse } from 'dotenv';
console.log(parse('A=1\n').A);                         // 1
console.log(typeof dotenv.parse(''), Object.keys(dotenv.parse('')).length);  // object 0

Compiles with zero deferred-site notices and exits 0 with the output above. Both the default-import (dotenv.parse) and named-import (import { parse }) forms route through the new row. Empty input returns {}, not null.

Tests

Both are #[cfg(test)] unit tests in src/, so they run in the per-PR cargo-test gate (--lib --bins) rather than only in the nightly integration tier.

• perry-api-manifest — dotenv_parse_is_registered: asserts the symbol exists, is a static module method, and takes one String parameter.
• perry-codegen — dotenv_parse_dispatches_to_native_impl_as_an_object: asserts the dispatch row points at js_dotenv_parse, takes NA_STR, and returns NR_OBJ_FROM_JSON_STR.

cargo test --lib -p perry-api-manifest (35 passed) and cargo test --lib -p perry-codegen (515 passed) are green, as is cargo test -p perry-codegen --test manifest_consistency (the #512 drift gate that keeps the two tables in sync).

Note on the version bump

This is one of three independent PRs I am opening off the same main. Each bumps [workspace.package] version to 0.5.1278 per the CLAUDE.md flow, so whichever lands second and third will need the version line rebased.

Summary by CodeRabbit

• New Features
  • Added dotenv.parse(src) to parse dotenv-formatted text into an object.
  • Supports both default and named imports.
  • Handles empty input and deferred notices correctly.
• Documentation
  • Updated API documentation and reference listings to include dotenv.parse.
• Chores
  • Updated the project version to 0.5.1278.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 57faa730-3086-4cb2-9441-4f0560a64d90

📥 Commits

Reviewing files that changed from the base of the PR and between eeb8ce4 and 23d1dd3.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (8)

• CLAUDE.md
• Cargo.toml
• changelog.d/7199-dotenv-parse-manifest-wiring.md
• crates/perry-api-manifest/src/entries/part_1.rs
• crates/perry-api-manifest/src/lib.rs
• crates/perry-codegen/src/lower_call/native_table/utils_crypto.rs
• docs/api/perry.d.ts
• docs/src/api/reference.md

---

📝 Walkthrough

Walkthrough

dotenv.parse(src) is registered in the API manifest, routed through native dispatch, and converted from a JSON string to an object. Tests validate the manifest and dispatch metadata. Generated API references, changelog data, and version metadata are updated.

Changes

dotenv.parse API

Layer / File(s)	Summary
Manifest contract and registration crates/perry-api-manifest/src/entries/part_1.rs, crates/perry-api-manifest/src/lib.rs	Adds dotenv.parse(src: string): any to the manifest and validates its registration, parameter count, and parameter type.
Native dispatch and decoding crates/perry-codegen/src/lower_call/native_table/utils_crypto.rs	Routes dotenv.parse to js_dotenv_parse, passes the string argument, and converts the JSON-string result to an object. Tests validate the dispatch metadata and return type.
API publication and version metadata docs/api/perry.d.ts, docs/src/api/reference.md, changelog.d/7199-dotenv-parse-manifest-wiring.md, Cargo.toml, CLAUDE.md	Updates generated API declarations, API counts, changelog content, and the workspace and documented versions to 0.5.1278.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant Manifest as API manifest
  participant Dispatch as Native dispatch table
  participant Parser as js_dotenv_parse
  participant Runtime as Object runtime
  Caller->>Manifest: resolve dotenv.parse(src)
  Manifest-->>Dispatch: provide native method contract
  Dispatch->>Parser: pass src string
  Parser-->>Dispatch: return JSON string
  Dispatch->>Runtime: decode JSON string as object
  Runtime-->>Caller: return parsed object

Loading

Suggested labels: bug

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is detailed and relevant but omits the template headings, related issue, checklist, and required test-plan checklist.	Use the repository template headings and checklist, state the related issue or n/a, and address the prohibited version and CLAUDE.md changes.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: registering dotenv.parse to prevent swallowed runtime errors.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}