@gjsify/resolve-npm 0.23.0 → 0.24.1

package/lib/index.mjs

@@ -19,25 +19,44 @@ import { getDerivedAliasesSync as _getDerivedAliasesSync } from './runtime-alias
  *
  * ## Why this exists (ADR 0014)
  *
- * The alias layer was designed as a TWO-PASS chain, and `app/browser.ts` says
- * so in its own comment: the curated table maps a bare specifier
- * (`os`, `node:os`) to `@gjsify/<X>`, and "the dynamic per-runtimes-triplet
- * resolver (`getDerivedAliasesSync`) finishes the routing in a second pass".
+ * A curated table maps a bare specifier (`os`, `node:os`) to `@gjsify/<X>`,
+ * while the derived per-runtimes-triplet map (`getDerivedAliasesSync`) maps
+ * `@gjsify/os` → `@gjsify/os/browser`. Applying the second to the values of
+ * the first is what makes ADR 0014's platform-entry routing reach a browser
+ * bundle at all: those bundles hit the packages through the bare/`node:` form,
+ * not by package name. (A direct `import … from '@gjsify/os'` routes on its own
+ * — it is a plain key hit in the merged map.)
  *
- * That second pass never fires for a bare specifier. `aliasPlugin` resolves a
- * hit via `this.resolve(target, importer, { skipSelf: true })`, and `skipSelf`
- * deliberately excludes the gjsify alias plugin from the nested resolution —
- * so `os` → `@gjsify/os` lands on the package ROOT and the derived entry
- * `@gjsify/os` → `@gjsify/os/browser` is never consulted. A direct
- * `import … from '@gjsify/os'` in source DOES route (single hop, verified);
- * a browser bundle importing bare `os` does not. Since every browser bundle
- * reaches these packages through the bare/`node:` form, the platform-entry
- * routing of ADR 0014 would have been inert without this.
+ * ## Why HERE and not as a second pass in `aliasPlugin`
  *
- * Composing the two maps here — at the point the bare table is materialised —
- * collapses the chain to a single hop, keeps the curated table itself a pure
- * bare-name → package statement (no slot policy duplicated into it), and needs
- * no change in the bundler plugins.
+ * This looks like it wants to be a resolver chain — `os` → `@gjsify/os` →
+ * `@gjsify/os/browser` — but it must not be one. Slot routing may only be
+ * applied to values that CAME FROM a curated/derived table, and by the time
+ * `aliasPlugin` sees the map it has been merged flat across four tiers
+ * (derived → curated `ALIASES_*` → per-target overrides → user `--alias`,
+ * later wins — see `app/*.ts`). Tier information is gone, so a chain there
+ * would re-route USER aliases too:
+ *
+ *   - `scripts/node-gi-consumer-harness.mjs` builds `--alias node:<x>=@gjsify/<x>`
+ *     to put the POLYFILL under test behind a Node builtin. 34 of those
+ *     polyfills declare `runtimes.node: "native"`, so a second hop hands back
+ *     `@gjsify/<x>/globals` — Node's own builtin — and the suite measures
+ *     nothing while reporting green.
+ *   - Value-level chaining also has no notion of the documented KEY-level
+ *     "curated wins over derived" precedence. Measured on the composed maps:
+ *     `gjs` 0 of 114 entries would change, `node` 0 of 148 — and on
+ *     `nativescript` the only 4 changes are regressions (`fs` →
+ *     `@gjsify/native-fs-bridge` → `@gjsify/empty`, because a bridge package
+ *     that IS the native implementation declares `nativescript: "native"`,
+ *     which routes to a `globals.mjs` it does not ship).
+ *
+ * So composition happens at materialisation, where the tiers are still
+ * distinguishable, the curated table stays a pure bare-name → package
+ * statement (no slot policy duplicated into it), and `aliasPlugin` keeps its
+ * one-hop `skipSelf: true` contract. Composing a table is therefore an
+ * explicit, per-table decision; `ALIASES_NODE_FOR_NATIVESCRIPT` is
+ * deliberately NOT composed (see the STATUS.md TODO on the `native` slot's
+ * double meaning for the bridge packages).
  *
  * Evaluated LAZILY (on property read) and cached: `getDerivedAliasesSync` walks
  * the workspace, and importing `@gjsify/resolve-npm` must not pay for a
@@ -249,45 +268,93 @@ export const ALIASES_NODE_FOR_GJS = {
  * the routing in a second pass (`@gjsify/<X>` → `@gjsify/<X>/globals` or
  * `@gjsify/empty` depending on the slot declaration).
  *
- * `none`-slot entries are deliberately hardcoded to `@gjsify/empty` here
- * (e.g. `child_process`, `fs`, `net`, ...) rather than relying on the dynamic
- * runtime layer — bare `fs` / `net` / ... do NOT start with `@gjsify/` and
- * therefore never enter `getDerivedAliasesSync`. This table is the bridge.
+ * `none`-slot entries are deliberately hardcoded here rather than relying on the
+ * dynamic runtime layer — bare `fs` / `net` / ... do NOT start with `@gjsify/`
+ * and therefore never enter `getDerivedAliasesSync`. This table is the bridge.
+ *
+ * ## `@gjsify/empty` is a LAST resort, and every remaining one is classified
+ *
+ * A value of `@gjsify/empty` is an ANONYMOUS redirect: a shared
+ * `export default {}` that a dozen unrelated specifiers also resolve to. That
+ * makes it indistinguishable, in an emitted bundle, from an ACCIDENTAL alias —
+ * which is how `@gjsify/canvas2d`'s build could start emitting a stray
+ * `@gjsify/empty` import without anything noticing. It is also export-less, so
+ * `import { spawn } from 'child_process'` binds `undefined` and dies later at
+ * `spawn is not a function`, naming neither the module nor the platform.
+ *
+ * So a redirect is NAMED wherever a name exists, and each entry still pointing
+ * at `@gjsify/empty` carries an inline classification so the remaining work is
+ * visible rather than implied:
+ *
+ *   (A)  wireable now — the package declares a browser slot and ships the entry;
+ *        the value names that entry. No `(A)` entries remain except
+ *        `dns/promises`, which needs a `./browser/promises` subpath first.
+ *   (A') native-available — the browser HAS the API (`fetch`, `WebSocket`); the
+ *        honest target is a `/globals` re-export, not an empty module.
+ *   (B)  simulatable but unbuilt — a real Web analogue exists (`cluster` over
+ *        Web Workers, `dgram` over WebRTC data channels, `v8.serialize` over
+ *        `structuredClone`, `readline` over any stream). `@gjsify/empty` until
+ *        someone builds it.
+ *   (C)  impossible — no Web API can ever back it. These get a NAMED throwing
+ *        stub at `@gjsify/<X>/browser` (today: `child_process`, `net`, `tls`).
+ *        `http2` / `inspector` are also `(C)` but not yet written; `repl` /
+ *        `wasi` are `(C)` with no owning `@gjsify/*` package to host a stub.
+ *
+ * A `(C)` stub keeps its package's `runtimes.browser: "none"` declaration: the
+ * MODULE genuinely is not usable on the runtime. The stub does not make it
+ * usable, it makes the unusability legible — it exports the module's real named
+ * shape (so linking succeeds) and throws a structured `ENOTSUP` naming the
+ * module, the runtime and the calling site. Exports whose answer IS
+ * platform-independent (`net.isIP`, `tls.checkServerIdentity`) stay real; a
+ * blanket thrower would replace one lie with another.
  *
- * NOTE — UNWIRED IN THIS PR. The browser-app orchestrator
- * (`packages/infra/rolldown-plugin-gjsify/src/app/browser.ts`) does NOT
- * consume this map yet. PR-D (T-Plan Sektion 2b-ii + 2b-iii, Welle 3) flips
- * `browser.ts` to spread `ALIASES_NODE_FOR_BROWSER` (+ generated `node:*`
- * prefix-map) into its `aliasMap` UNDER `browserPolyfillAliases` and the user
- * aliases. Decoupled here so the table is exportable / reviewable in
- * isolation, while consumer wiring waits on the R1 wave delivering browser-
- * baubable `@gjsify/{process,buffer,stream,...}` builds. Adopt only when the
- * per-package browser slots are R1-validated.
+ * A `partial`-slot package names its `./browser` PLATFORM ENTRY here, not its
+ * package root. `withDerivedSlotRouting` only rewrites a value when the slot is
+ * `polyfill` (ADR 0014), so a curated value of `@gjsify/<X>` for a `partial`
+ * package would hand the bundler the GJS root body — whose `@girs/*` imports
+ * `gjsImportsEmptyPlugin` replaces with `{}`, producing the silent
+ * `GLib.Checksum is not a constructor` failure ADR 0014 exists to eliminate.
+ * `partial` must mean "degrades at call time", never "crashes at first use".
+ * Naming the subpath is safe precisely where the platform entry is already at
+ * VALUE-export parity with the root (else routing would trade a call-time
+ * degradation for a build-time MISSING_EXPORT) — which is why this is a
+ * per-package curated decision and NOT a blanket change to `resolveSlot`'s
+ * `partial` case. Machine-checked by `scripts/audit-runtimes.mjs`'
+ * `curated-alias-routing` invariant.
+ *
+ * WIRED. The browser-app orchestrator
+ * (`packages/infra/rolldown-plugin-gjsify/src/app/browser.ts`) spreads this map
+ * — plus a generated `node:*` prefix variant of every key — into its `aliasMap`
+ * between the derived slot routing and the per-target / user aliases. So every
+ * value here is a resolve target a `--app browser` build actually takes; a
+ * mistake in this table is a shipping bug, not a staged proposal. (The former
+ * "UNWIRED IN THIS PR" note dated from before that wiring landed and is what
+ * made the `crypto` / `zlib` root-body routing read as latent.)
  */
 const ALIASES_NODE_FOR_BROWSER_TABLE = {
     'assert':              '@gjsify/assert',
     'assert/strict':       '@gjsify/assert/strict',
     'async_hooks':         '@gjsify/async_hooks',
     'buffer':              '@gjsify/buffer',
-    'child_process':       '@gjsify/empty',        // none-slot — browser has no process model
-    'cluster':             '@gjsify/empty',
+    'child_process':       '@gjsify/child_process/browser', // none slot — NAMED throwing stub
+    'cluster':             '@gjsify/empty',        // (B) simulatable over Web Workers — unbuilt
     'console':             '@gjsify/console',
     'constants':           '@gjsify/constants',
-    'crypto':              '@gjsify/crypto',
-    'dgram':               '@gjsify/empty',
+    'crypto':              '@gjsify/crypto/browser',   // partial slot — name the platform entry
+    'dgram':               '@gjsify/empty',        // (B) simulatable over WebRTC data channels — unbuilt
     'diagnostics_channel': '@gjsify/diagnostics_channel',
-    'dns':                 '@gjsify/empty',
-    'dns/promises':        '@gjsify/empty',
+    'dns':                 '@gjsify/dns/browser',      // partial slot — name the platform entry
+    'dns/promises':        '@gjsify/empty',        // (A) blocked: no ./browser/promises subpath yet
     'domain':              '@gjsify/domain',
     'events':              '@gjsify/events',
-    'fs':                  '@gjsify/empty',        // phase 1: stub; later @gjsify/fs/browser
-    'fs/promises':         '@gjsify/empty',
-    'http':                '@gjsify/empty',        // browser fetch covers most cases
-    'http2':               '@gjsify/empty',
-    'https':               '@gjsify/empty',
-    'inspector':           '@gjsify/empty',
-    'module':              '@gjsify/empty',
-    'net':                 '@gjsify/empty',
+    'fs':                  '@gjsify/fs/browser',       // partial slot — name the platform entry
+    'fs/promises':         '@gjsify/fs/browser/promises',
+    'http':                '@gjsify/http/browser',     // partial slot — name the platform entry
+    'http2':               '@gjsify/empty',        // (C) impossible — needs a named throwing stub
+    'https':               '@gjsify/https/browser',    // partial slot — name the platform entry
+    'inspector':           '@gjsify/empty',        // (C) impossible — needs a named throwing stub
+    'module':              '@gjsify/module/browser',   // partial slot — name the platform entry
+    'net':                 '@gjsify/net/browser',      // none slot — NAMED throwing stub
     'os':                  '@gjsify/os',
     'path':                '@gjsify/path',
     'path/posix':          '@gjsify/path/posix',
@@ -296,9 +363,9 @@ const ALIASES_NODE_FOR_BROWSER_TABLE = {
     'process':             '@gjsify/process',      // PR-D: flips today's `@gjsify/empty`
     'punycode':            '@gjsify/punycode',
     'querystring':         '@gjsify/querystring',
-    'readline':            '@gjsify/empty',
-    'readline/promises':   '@gjsify/empty',
-    'repl':                '@gjsify/empty',
+    'readline':            '@gjsify/empty',        // (B) stream-generic; simulatable — unbuilt
+    'readline/promises':   '@gjsify/empty',        // (B) stream-generic; simulatable — unbuilt
+    'repl':                '@gjsify/empty',        // (C) impossible, and no @gjsify/repl package exists
     'stream':              '@gjsify/stream',
     'stream/web':          '@gjsify/stream/web',
     'stream/consumers':    '@gjsify/stream/consumers',
@@ -307,22 +374,22 @@ const ALIASES_NODE_FOR_BROWSER_TABLE = {
     'sys':                 '@gjsify/sys',
     'timers':              '@gjsify/timers',
     'timers/promises':     '@gjsify/timers/promises',
-    'tls':                 '@gjsify/empty',
-    'tty':                 '@gjsify/empty',
+    'tls':                 '@gjsify/tls/browser',      // none slot — NAMED throwing stub
+    'tty':                 '@gjsify/empty',        // (B) isatty()===false is honest — unbuilt
     'url':                 '@gjsify/url',
     'util':                '@gjsify/util',
     'util/types':          '@gjsify/util/types',
-    'v8':                  '@gjsify/empty',
+    'v8':                  '@gjsify/empty',        // (B) serialize/deserialize over structuredClone — unbuilt
     'vm':                  '@gjsify/vm',
-    'wasi':                '@gjsify/empty',
-    'sqlite':              '@gjsify/empty',
-    'worker_threads':      '@gjsify/empty',
-    'zlib':                '@gjsify/zlib',
+    'wasi':                '@gjsify/empty',        // (C) impossible, and no @gjsify/wasi package exists
+    'sqlite':              '@gjsify/sqlite/browser',   // partial slot — name the platform entry
+    'worker_threads':      '@gjsify/worker_threads/browser', // partial slot — name the platform entry
+    'zlib':                '@gjsify/zlib/browser',     // partial slot — name the platform entry
 
     // Third-party
-    'node-fetch':          '@gjsify/empty',        // browser native fetch
-    'ws':                  '@gjsify/empty',        // browser native WebSocket
-    'isomorphic-ws':       '@gjsify/empty',
+    'node-fetch':          '@gjsify/empty',        // (A') native-available: wants @gjsify/fetch/globals
+    'ws':                  '@gjsify/ws/browser',       // partial slot — name the platform entry
+    'isomorphic-ws':       '@gjsify/empty',        // (A') native-available: wants a WebSocket re-export
 }
 
 /**
@@ -351,11 +418,18 @@ export const ALIASES_NODE_FOR_BROWSER = withDerivedSlotRouting(
  * - **Mobile-tractable Node built-ins → `@gjsify/<X>`.** `assert`,
  *   `async_hooks`, `buffer`, `crypto`, `events`, `fs`, `os`, `path`,
  *   `process`, `stream`, `string_decoder`, `url`, `util`, `querystring`
- *   route to their gjsify polyfills. The polyfills themselves may declare
- *   `runtimes.nativescript = "polyfill" | "partial" | "none"`; the
- *   triplet-driven `getDerivedAliasesSync('nativescript')` second pass
- *   reads the declaration and either keeps the resolution as-is (polyfill /
- *   partial) or redirects to `/globals` (native) or `@gjsify/empty` (none).
+ *   route to their gjsify polyfills. NOTE: unlike `ALIASES_NODE_FOR_BROWSER`,
+ *   this table is deliberately NOT wrapped in `withDerivedSlotRouting` — the
+ *   VALUES here are taken as final. Composing it today would only change 4 of
+ *   122 entries and all four are regressions: `fs`/`fs/promises` point at
+ *   `@gjsify/native-fs-bridge`, which declares `nativescript: "native"` meaning
+ *   "this package IS the native implementation", while the slot vocabulary's
+ *   `native` means "the RUNTIME provides it, route to `<pkg>/globals`" — a file
+ *   the bridge does not ship, so the composed value degrades to
+ *   `@gjsify/empty`. Settle the bridge packages' slot declarations first (see
+ *   STATUS.md `Open TODOs`), then compose. An import by PACKAGE NAME does route
+ *   per the declared slot (plain key hit in the merged map) — which is why the
+ *   bridges are ALREADY emptied on that path today, same TODO.
  * - **`ws` / `isomorphic-ws` → `@gjsify/empty`.** NS apps use `WebSocket`
  *   from the global runtime, not the `ws` package.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/resolve-npm",
-    "version": "0.23.0",
+    "version": "0.24.1",
     "description": "Resolve NPM package aliases",
     "type": "module",
     "main": "lib/index.mjs",