fix(fs): route named promises import to the fs/promises submodule namespace

[jdalton]

import { promises } from "node:fs" silently gives back the wrong API: every call like promises.realpath(p) resolves undefined instead of a value.

Background on the mechanism: Node exposes the promise-based fs API two ways — the node:fs/promises submodule, and a promises named export on node:fs that is the same namespace object. So import { promises } from "node:fs" must bind a namespace whose members are promise-returning functions, exactly as import * as promises from "node:fs/promises" would. The compiler's named-import lowering instead treated promises like any other named export of fs: a native method reference (fs.promises). A later promises.realpath(p) therefore dispatched the callback-API fs.realpath — whose return value is undefined by design (the result arrives via callback) — so the awaited call quietly produced undefined, and everything downstream of the "resolved path" broke.

Minimal repro

import { promises } from "node:fs";

const real = await promises.realpath(".");
console.log(real);   // undefined — dispatched callback-API fs.realpath

Root cause (two layers)

• crates/perry-hir/src/lower/module_decl.rs:221 — the named-import table's generic arm mapped { promises } from fs/dns/stream to a native method <mod>.promises instead of the <mod>/promises submodule namespace.
• crates/perry-codegen/src/lower_call/native/mod.rs:383 — once the HIR routes the binding to the submodule, the call arrives as a receiver-less NativeMethodCall { module: "fs/promises", method }, and codegen had no arm for that shape: it fell to the TAG_UNDEFINED sentinel, so even a correctly-routed binding still resolved undefined.

The fix is one arm per layer: module_decl routes { promises } from fs/dns/stream to the <mod>/promises submodule (exactly like the star-import), and codegen dispatches the receiver-less submodule call on the populated submodule namespace singleton (js_node_submodule_namespace), whose members are the real promise-returning thunks.

Test plan

$ cargo build -p perry-codegen -p perry-hir
Finished `dev` profile

Verified end-to-end on the repro above: promises.realpath(".") returns the resolved path where it previously resolved undefined. (The failing shape needs a full compile-and-run of a program importing { promises }; the existing fs integration corpus covers the star-import path this change reuses.)

Found while compiling a manifest generation CLI — a real-world TypeScript CLI with a deep pnpm dependency graph. Independent of the other fixes from that effort; lands standalone.

Summary by CodeRabbit

• Bug Fixes
  • Fixed named imports for Node.js promise APIs from fs, dns, and stream.
  • Promise-based methods such as realpath now correctly return promises instead of producing undefined results.
  • Improved handling of promise submodule APIs when imported from Node.js built-ins.

[coderabbitai]

Warning

Review limit reached

@jdalton, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 32 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2b7ab32e-8416-4cc0-ab5f-0160a63c8a2f

📥 Commits

Reviewing files that changed from the base of the PR and between 03aa1ae and cb6cdc8.

📒 Files selected for processing (3)

• changelog.d/7006-fs-promises-named-import.md
• crates/perry-codegen/src/lower_call/native/mod.rs
• crates/perry-hir/src/lower/module_decl.rs

📝 Walkthrough

Walkthrough

This change routes Node promises named imports to fs/promises, dns/promises, and stream/promises namespaces, and adds receiver-less native dispatch for fs/promises and stream/promises methods.

Changes

Promise submodule routing

Layer / File(s)	Summary
Route named promises imports to submodules crates/perry-hir/src/lower/module_decl.rs, changelog.d/7006-fs-promises-named-import.md	Native promises imports from Node fs, dns, and stream now bind to their corresponding promise submodule namespaces, with the fix documented in the changelog.
Dispatch receiver-less promise calls crates/perry-codegen/src/lower_call/native/mod.rs	Calls targeting fs/promises and stream/promises now create the submodule namespace, lower arguments, and invoke the requested native method.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• PerryTS/perry#6694: Uses stream/promises exports in related stream promise handling.
• PerryTS/perry#6820: Adds related fs/promises submodule installer and feature detection logic.
• PerryTS/perry#6857: Adds fs/promises functionality using the corrected dispatch path.

Suggested labels: bug

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main fix: named promises imports now route to the fs/promises namespace.
Description check	✅ Passed	The description covers the bug, root cause, fix, and test plan, but omits the explicit Related issue and Checklist sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.}