feat: ns:util builtin module (inspect, format)

[edusperoni]

Description

Android mirror of NativeScript/ios#418. Stacked on #1991 (feat/inspect) — review only the last commit.

Runtime-provided modules get a resolution scheme. require("ns:util"), import util, { inspect } from "ns:util" and await import("ns:util") all resolve to the same per-realm module, and console.* gains Node's %-substitution. docs/ns-builtin-modules.md (added here, same document as the iOS PR) is the cross-runtime contract both runtimes implement, with a non-normative Android section.

v1 exports — ns:util: inspect(value[, options]) (the console formatter from the inspect PR, same instance) and format(fmt, ...args) (Node's %s %d %i %f %j %o %O %%).

Resolution rules

• ns:/node: specifiers are intercepted before any filesystem or npm resolution in all three entry points: the CommonJS require path (ModuleInternal::RequireCallbackImpl), the ES module resolve callback, and the dynamic-import host callback (ModuleInternalCallbacks.cpp). A builtin can never be shadowed by a file or a package.
• ESM is served by v8::Module::CreateSyntheticModule, exporting every member by name plus default; instantiated, evaluated and cached per realm.
• Unknown names fail with exactly No such built-in module: <specifier> — synchronously for require, as a rejection for import().
• Builtins are singletons per realm: the main context and every worker build their own exports object. Android has no Caches class, so per-realm caches are isolate-keyed maps released on isolate disposal; the process-global g_moduleRegistry deliberately holds none of this state.
• Bare specifiers are untouched: require("util") still resolves through npm exactly as before (there is a test asserting it does not return the builtin).
• Exports are frozen.

The internal require (new wrapper parameter) — the builtin wrapper becomes (exports, require, module, binding, primordials), Node's order. That require is created once per realm and resolves builtin specifiers only — no path, no package, no filesystem — with an in-progress guard so cycles throw instead of recursing. It's how node:util (node-util.js, its own lazy builtin) consumes ns:util and re-exports: all Node-compat adaptation lives in the shim, ns-util.js carries none, and the two module objects are distinct and separately frozen (nodeUtil.inspect === nsUtil.inspect, objects differ).

console integration — the arg-joining routine calls the cached format with the full argument list, so console.log("%d apples", 3) prints 3 apples while console.log("100%"), unknown specifiers and a dangling % stay verbatim. Non-format calls keep joining with spaces; if the builtin is unavailable the old per-argument loop still runs, so logging can never be taken down by the formatter.

⚠️ Behavior changes (aligning the pre-existing ESM node: polyfills with the contract):

• The generic fallback for unshimmed node: imports (console.warn + export default {}, which broke at first use) is removed — they now fail with No such built-in module: node:<name>.
• The node:fs stub whose every member threw on use is removed for the same reason (the contract requires missing members to be absent, never present-but-throwing) — node:fs now fails with the not-found message.
• The functional node:url (fileURLToPath/pathToFileURL), node:module (createRequire) and node:path polyfills are kept unchanged, import-only — require("node:path") reports not-found while import works, mirroring iOS's pre-registry node:url asymmetry. Documented in the doc's Android non-normative section.

Related Pull Requests

• feat: ns:util builtin module (inspect, format) ios#418 (iOS counterpart; the contract doc is shared verbatim)
• feat: budgeted console formatter (inspect builtin) #1991 (base)

Does your pull request have unit tests?

Yes — 21 new device specs (tests/testNsUtil.js + a static-import .mjs fixture covering the resolve callback, + a worker spec asserting a worker builds its own ns:util instance): frozen exports, require/static/dynamic-import singleton identity, every format specifier incl. %%/unknown/dangling %/%j on a circular value/extras/non-string first arg, node:util distinctness with shared members, exact unknown-ns:/node: messages in both schemes, and the bare-util non-change. Full suite: 648 specs, 0 failures (627 baseline + 21).

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 989ca4e1-d696-4c97-b5b6-ea9c31941548

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}