@gjsify/rolldown-plugin-gjsify 0.36.0 → 0.38.0

package/lib/utils/auto-globals.js

@@ -1,22 +1,16 @@
-// Iterative multi-pass build orchestrator for `--globals auto`.
+// Iterative multi-pass build orchestrator for `--globals auto`. The "analyse the
+// bundled output AFTER tree-shaking" property is bundler-agnostic and load-bearing —
+// AGENTS.md § "Tree-shakeability invariants — permanent", plus the rationale block
+// atop `detect-free-globals.ts`.
 //
-// Architecturally identical to the esbuild predecessor — only the inner
-// build call swaps `esbuild.build()` for `rolldown()`. The "after
-// tree-shaking" analysis property is bundler-agnostic and load-bearing
-// per AGENTS.md "Tree-shakeability invariants — permanent". See the
-// rationale block at the top of `detect-free-globals.ts`.
+// Pass 1: bundle with no globals injection → parsed by acorn for free globals.
+// Pass 2: bundle with the detected globals injected → the injected register modules
+//         pull in MORE code referencing more globals (a tree-shaking dependency
+//         cycle), so the set can still grow.
+// Pass N: repeat until it converges, capped at MAX_ITERATIONS.
 //
-// Pass 1: rolldown() with no globals injection
-//         → in-memory bundle parsed by acorn for free globals
-// Pass 2: rolldown() with detected globals injected
-//         → some injected register modules pull in MORE code that
-//           references additional globals (tree-shaking dependency cycle)
-// Pass N: repeat until the detected set converges (typically 2–3 iterations,
-//         capped at MAX_ITERATIONS=5)
-//
-// We deliberately do NOT minify the analysis builds: minification can
-// alias `globalThis` to a short variable and defeat MemberExpression
-// detection in detect-free-globals.ts.
+// The analysis builds MUST NOT minify: minification aliases `globalThis` to a short
+// variable and defeats MemberExpression detection in detect-free-globals.ts.
 const defaultBundler = async ({ rolldownInput, format }) => {
     // Indirect specifier so the GJS bundle doesn't pull npm rolldown in
     // statically. Only reached when the caller doesn't override (Node).
@@ -46,19 +40,16 @@ const GI_BACKED = GJS_GI_BACKED_REGISTERS;
 /** Maximum iterations to prevent runaway loops on pathological inputs. */
 const MAX_ITERATIONS = 5;
 /**
- * Expand a detected-identifier set with the PRECOMPUTED transitive closure of
- * the register modules those identifiers inject (the committed
- * `register-globals-closure` map, generated by
+ * Expand a detected-identifier set with the PRECOMPUTED transitive closure of the
+ * register modules those identifiers inject (`register-globals-closure`, generated by
  * `packages/infra/cli/scripts/generate-register-closure.mjs`).
  *
- * The iterative loop's passes 2..N exist only to discover which ADDITIONAL
- * globals the injected register modules' own code references — static,
- * per-register information. Seeding pass 2 with the full closure makes the
- * loop converge at the very next pass (a verification bundle), collapsing
- * ~3-5 analysis bundles to 2 for every `--globals auto` build. A stale or
- * missing closure entry is SAFE: the verification pass detects unexpected
- * growth and the loop simply continues iterating (slower + a hint to
- * regenerate).
+ * Passes 2..N of the plain loop exist only to discover which ADDITIONAL globals the
+ * injected registers' own code references — static, per-register information. Seeding
+ * pass 2 with the full closure makes the loop converge at the next (verification)
+ * pass, collapsing ~3-5 analysis bundles to 2. A stale or missing entry is SAFE: the
+ * verification pass sees the unexpected growth and the loop keeps iterating, slower,
+ * with a hint to regenerate.
  */
 function expandWithClosure(detected, excludeSet) {
     const out = new Set(detected);
@@ -95,16 +86,14 @@ async function applyExcludeGlobals(detected, currentInject, extraRegisterPaths,
         for (const id of excludeGlobals)
             detected.delete(id);
     }
-    // Final register set that will be injected (detected → register paths,
-    // plus any --globals auto,<extras>). Computed for BOTH paths so the
-    // GI-backed diagnostic below fires whether or not excludeGlobals is set.
+    // Computed for BOTH paths so the GI-backed diagnostic fires whether or not
+    // excludeGlobals is set.
     const finalPaths = detectedToRegisterPaths(detected);
     for (const p of extraRegisterPaths)
         finalPaths.add(p);
     emitGiBackedDiagnostic(finalPaths, detected, cwd);
-    // No exclude: `currentInject` already reflects `finalPaths` (built in the
-    // loop), so reuse it — re-running filterResolvableRegisterPaths here would
-    // emit its skip warnings a second time.
+    // No exclude: `currentInject` already reflects `finalPaths`, so reuse it —
+    // re-running filterResolvableRegisterPaths would repeat its skip warnings.
     if (!excludeGlobals?.length)
         return { detected, injectPath: currentInject };
     const filtered = cwd ? filterResolvableRegisterPaths(finalPaths, cwd) : finalPaths;
@@ -134,18 +123,14 @@ function giNamespacesForRegister(registerPath) {
     return null;
 }
 /**
- * Build the build-time note for any GI-backed register modules in a final
- * inject set, or null when none are GI-backed. Pure (no I/O) so it is
- * unit-testable; `emitGiBackedDiagnostic` is the side-effecting wrapper.
- *
- * `--globals auto` injecting a GI-backed register makes the bundle
- * hard-require a GTK/GNOME runtime at load — under a GTK-less host (headless
- * type-check container, SSR generator, plain CI) it throws `Typelib … not
- * found`. The note names which globals triggered the injection so that
- * otherwise-silent runtime crash is traceable at build time.
+ * The build-time note for any GI-backed register modules in a final inject set, or
+ * null when none are. Pure so it is unit-testable; `emitGiBackedDiagnostic` is the
+ * side-effecting wrapper.
  *
- * @param registerPaths the final register paths to be injected
- * @param detected the converged detected-global set (for naming trigger refs)
+ * Injecting a GI-backed register makes the bundle hard-require a GTK/GNOME runtime at
+ * load, so under a GTK-less host (headless type-check container, SSR generator, plain
+ * CI) it throws `Typelib … not found`. Naming the triggering globals makes that
+ * otherwise-silent runtime crash traceable at build time.
  */
 export function describeGiBackedInjection(registerPaths, detected) {
     const giRegisters = new Set();
@@ -179,11 +164,10 @@ export function describeGiBackedInjection(registerPaths, detected) {
 /** Emitted at most once per process so multi-pass / multi-build runs stay quiet. */
 let giNoteEmitted = false;
 /**
- * console.warn the GI-backed-injection note once per process. Pre-filters
- * `registerPaths` to the ones that will ACTUALLY be injected — GI-backed AND
- * (quietly) resolvable from the project — so the note never mentions a
- * register that gets dropped. Uses `isRegisterPathResolvable` (no warning),
- * not `filterResolvableRegisterPaths`, to avoid duplicating its skip warnings.
+ * Warn the GI-backed-injection note once per process. Pre-filters `registerPaths` to
+ * the ones that will ACTUALLY be injected so the note never mentions a dropped
+ * register, via `isRegisterPathResolvable` rather than
+ * `filterResolvableRegisterPaths` to avoid duplicating that one's skip warnings.
  */
 function emitGiBackedDiagnostic(registerPaths, detected, cwd) {
     if (giNoteEmitted)
@@ -206,21 +190,10 @@ function isFullConfig(v) {
     return v !== null && typeof v === 'object' && !Array.isArray(v) && 'plugins' in v && 'options' in v;
 }
 /**
- * Run an iterative Rolldown build (in-memory) with acorn-based global
- * detection. Each pass uses the globals discovered by the previous pass,
- * stopping once the detected set is stable (fixpoint reached).
- *
- * Returns the inject stub path that the caller should pass to the
- * final (real) build via `pluginOptions.autoGlobalsInject`.
- *
- * @param analysisOptions Rolldown input options for the in-memory build.
- * @param pluginOptions Gjsify plugin options (without `autoGlobalsInject`,
- *   which this function computes).
- * @param gjsifyPluginFactory Factory returning the gjsify plugin instance
- *   for a given set of plugin options. Provided by the caller to avoid a
- *   cyclic import between this module and `../plugin.ts`.
- * @param verbose Emit per-iteration debug output to console.
- * @param options Optional `extraGlobalsList` / `excludeGlobals`.
+ * Run the iterative in-memory build with acorn-based global detection, each pass
+ * seeded by the previous pass's globals, until the detected set is stable. Returns the
+ * inject stub path the caller passes to the final build via
+ * `pluginOptions.autoGlobalsInject`.
  */
 export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPluginFactory, verbose, options = {}, bundler = defaultBundler) {
     const extraRegisterPaths = options.extraGlobalsList
@@ -234,9 +207,8 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
         const resolvableExtra = cwd ? filterResolvableRegisterPaths(extraRegisterPaths, cwd) : extraRegisterPaths;
         currentInject = (await writeRegisterInjectFile(resolvableExtra, cwd)) ?? undefined;
     }
-    // Caller-provided plugins (e.g. PnP relay) survive every pass; the
-    // gjsify plugin appended last so its hooks run after any custom
-    // resolvers / loaders.
+    // Caller plugins (e.g. the PnP relay) survive every pass; the gjsify plugin is
+    // appended last so its hooks run after any custom resolvers / loaders.
     const callerPlugins = (analysisOptions.plugins ?? []).filter((p) => {
         const name = p && typeof p === 'object' && 'name' in p ? p.name : undefined;
         return name !== 'gjsify' && name !== 'gjsify-orchestrator';
@@ -246,13 +218,6 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
             ...pluginOptions,
             autoGlobalsInject: currentInject,
         });
-        // Two factory shapes are supported: a plain plugin array (legacy)
-        // or the orchestrator config `{ options, plugins }`. The latter
-        // gives auto-globals access to the per-app `resolve.conditionNames`
-        // / `mainFields` / `external` / `treeshake` settings — without
-        // these, native-rolldown defaults to a different module-resolution
-        // condition set than npm-rolldown, packages resolve to different
-        // entries, and the detected global set diverges between engines.
         let gjsifyInstance;
         let orchestratorOptions;
         if (isFullConfig(factoryResult)) {
@@ -262,28 +227,21 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
         else {
             gjsifyInstance = factoryResult;
         }
-        // The auto-globals inject stub is a side-effect-only ESM file that
-        // imports `<pkg>/register/<feature>` paths. Rolldown's `transform.inject`
-        // is the source-AST per-identifier rewrite we MUST NOT use (see
-        // AGENTS.md "Tree-shakeability invariants"). Instead, when the
-        // analyser has produced an inject path, append it as an additional
-        // entry — Rolldown bundles its side effects into the output and the
-        // detector sees the resulting identifier references.
+        // The inject stub is a side-effect-only ESM file importing
+        // `<pkg>/register/<feature>` paths, appended as an ADDITIONAL ENTRY so Rolldown
+        // bundles its side effects and the detector sees the resulting references.
+        // Rolldown's `transform.inject` is the source-AST per-identifier rewrite the
+        // tree-shakeability invariants forbid.
         const inputWithInject = currentInject
             ? appendInjectAsEntry(analysisOptions.input, currentInject)
             : analysisOptions.input;
-        // Merge resolve + external + transform from the orchestrator's
-        // options so the analysis bundle goes through the same module
-        // resolution as the final build. Analysis-side overrides
-        // (`analysisOptions.*`) win when explicitly set.
+        // Take resolve/external/transform from the orchestrator so the analysis bundle
+        // goes through the same module resolution as the final build; explicit
+        // analysis-side overrides win.
         const mergedResolve = analysisOptions.resolve ?? orchestratorOptions?.resolve;
         const mergedExternal = analysisOptions.external ?? orchestratorOptions?.external;
         const mergedTransform = analysisOptions.transform ?? orchestratorOptions?.transform;
         const orchTreeshake = orchestratorOptions?.treeshake;
-        // Inline-collect both halves of the plugin chain in their existing
-        // shape: caller plugins first (PnP, user text-loaders), then the
-        // gjsify chain (which may be either a single RolldownPluginOption
-        // or an array of them depending on the factory shape).
         const gjsifyPluginsArray = Array.isArray(gjsifyInstance) ? gjsifyInstance : [gjsifyInstance];
         const chunkCodes = await bundler({
             rolldownInput: {
@@ -300,11 +258,9 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
         if (chunkCodes.length === 0) {
             return { detected: new Set(), injectPath: currentInject };
         }
-        // Parse each chunk independently and union the detected sets.
-        // Rolldown emits one chunk per entry — concatenating them would
-        // produce a syntactically invalid combined program (duplicate
-        // top-level declarations: `File`, `Buffer`, …) that acorn can't
-        // parse. Per-chunk parsing keeps each chunk's lexical scope intact.
+        // Per-chunk parse, then union: Rolldown emits one chunk per entry, and
+        // concatenating them yields duplicate top-level declarations (`File`,
+        // `Buffer`, …) that acorn rejects as an invalid program.
         const newDetected = new Set();
         for (let i = 0; i < chunkCodes.length; i++) {
             const code = chunkCodes[i] ?? '';
@@ -315,49 +271,40 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
             catch (e) {
                 if (globalThis.process?.env
                     ?.GJSIFY_DEBUG_AUTO_GLOBALS) {
-                    // `tmpdir()`, not a literal `/tmp` — on Windows that wrote
-                    // to `<drive>:\tmp\`, and the `writeFileSync` is inside a
-                    // `catch`, so the dump silently did not appear where the
-                    // log line below says it did.
+                    // `tmpdir()`, not a literal `/tmp`: on Windows that wrote to
+                    // `<drive>:\tmp\`, and since the `writeFileSync` sits inside a
+                    // `catch` the dump silently did not appear where the log line
+                    // below says it did.
                     const os = await import('node:os');
                     const nodePath = await import('node:path');
                     const path = nodePath.join(os.tmpdir(), `gjsify-auto-globals-failed-chunk-${i}.mjs`);
                     try {
-                        // Dynamic `import()` on purpose: this is a debug-only
-                        // branch and the module graph should not carry
-                        // `node:fs` for it. (It is NOT a `require` — it never
-                        // was; the rule-disable comment that used to sit here
-                        // named a rule that cannot apply to an import
-                        // expression.)
+                        // Dynamic `import()` so this debug-only branch keeps `node:fs`
+                        // out of the module graph.
                         const fs = await import('node:fs');
                         fs.writeFileSync(path, code);
                         console.error(`[gjsify-auto-globals] parse failed on chunk #${i} — wrote ${path} for inspection`);
                     }
                     catch {
-                        // Deliberately swallowed, and the ONLY reason this
-                        // catch is legitimate: writing the debug dump is
-                        // best-effort (permissions, disk), and letting its
-                        // failure escape would replace the real parse error
-                        // `e` — rethrown below — with a misleading one.
+                        // Swallowed on purpose: writing the debug dump is best-effort
+                        // (permissions, disk), and letting its failure escape would
+                        // replace the real parse error `e`, rethrown below.
                     }
                 }
                 throw e;
             }
         }
-        // Apply excludeGlobals BEFORE writing the next iteration's inject file.
-        // Otherwise an excluded identifier would still appear in the inject
-        // import list and the analysis build itself would fail when the
-        // corresponding `@gjsify/<pkg>/register/<feature>` is not in the
-        // project's resolvable dep tree.
+        // Before writing the next iteration's inject file: otherwise an excluded
+        // identifier still lands in the inject import list and the analysis build fails
+        // when its `@gjsify/<pkg>/register/<feature>` is not in the project's dep tree.
         if (excludeSet.size > 0) {
             for (const id of excludeSet)
                 newDetected.delete(id);
         }
-        // Fixpoint check: detection is monotonic — injecting registers can
-        // only ADD references. The injected set (`detected`) may be a
-        // SUPERSET of what the bundle actually references (the closure-map
-        // expansion below deliberately over-approximates), so convergence is
-        // "this pass found nothing OUTSIDE the injected set", not equality.
+        // Fixpoint check: detection is monotonic (injecting registers can only ADD
+        // references) and the closure expansion below deliberately over-approximates, so
+        // convergence is "this pass found nothing OUTSIDE the injected set", not
+        // equality.
         if (isSubset(newDetected, detected)) {
             if (verbose) {
                 const sorted = [...detected].sort();
@@ -366,21 +313,17 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
             }
             return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals, cwd);
         }
-        // Seed the next pass with the PRECOMPUTED closure of every detected
-        // identifier's register module — the static answer to what passes
-        // 2..N of the plain loop would re-discover one bundle at a time.
-        // Union with the previously-injected set keeps growth monotonic
-        // (an over-approximated superset must never shrink, or the subset
-        // convergence check could oscillate).
+        // Seed the next pass with the precomputed closure. Unioning with the
+        // previously-injected set keeps growth monotonic — an over-approximated superset
+        // that shrank could make the subset convergence check oscillate.
         const expanded = options.disableClosureExpansion ? newDetected : expandWithClosure(newDetected, excludeSet);
         if (verbose && expanded.size > newDetected.size) {
             console.debug(`[gjsify] --globals auto: closure map expanded ${newDetected.size} → ${expanded.size} global(s)`);
         }
         if (iteration > 1 && verbose) {
-            // Reaching a growth pass after the closure-seeded pass means the
-            // committed closure map no longer covers a register module's
-            // references — correctness is preserved by iterating, but builds
-            // pay extra passes until the map is regenerated.
+            // A growth pass after the closure-seeded pass means the committed map no
+            // longer covers a register's references: iterating keeps it correct, but
+            // builds pay extra passes until the map is regenerated.
             console.debug('[gjsify] --globals auto: detection grew past the closure-map expansion — the committed ' +
                 'register-globals-closure map looks stale. Regenerate via ' +
                 '`node packages/infra/cli/scripts/generate-register-closure.mjs`.');
@@ -389,11 +332,9 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
         let registerPaths = detectedToRegisterPaths(detected);
         for (const p of extraRegisterPaths)
             registerPaths.add(p);
-        // Filter out register paths whose polyfill package is not installed
-        // in the project. An unresolvable import in the analysis bundle causes
-        // a hard Rolldown error — emitting it is strictly worse than skipping
-        // with a warning. The caller can add the dep or use --exclude-globals
-        // to acknowledge the gap. See AGENTS.md fix (a) rationale.
+        // Drop register paths whose polyfill package is not installed: an unresolvable
+        // import is a HARD Rolldown error, strictly worse than skipping with a warning.
+        // The caller adds the dep or acknowledges the gap via --exclude-globals.
         if (cwd)
             registerPaths = filterResolvableRegisterPaths(registerPaths, cwd);
         if (registerPaths.size === 0) {
@@ -420,24 +361,21 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
  *  1. a GJS ambient global (`print`/`printerr`/`log`/`logError`/`ARGV`/
  *     `imports`) referenced as a BARE identifier — the legacy GJS-source shape
  *     `@gjsify/node-gi/globals` seeds (`detectGjsAmbientGlobals`);
- *  2. a STATIC import of `@gjsify/node-gi` (root or subpath) — the shape the
- *     bare GJS built-ins (`system`/`gettext`/`cairo`) are externalised to, i.e.
- *     the PORTABLE GJS-source spelling (`detectNodeGiModuleImports`). A bundle
- *     retaining one is already bound to the bridge at load, so flipping
- *     injection cannot cost plain-Node loadability — while a portable GJS app
- *     with no ambient global at all (e.g. `system.programArgs` instead of
- *     `ARGV`) would otherwise get its `@girs/*` bodies emptied and its globals
- *     shim dropped (the `gjsify storybook --runtime node` no-`requireGi`
- *     regression).
+ *  2. a STATIC import of `@gjsify/node-gi` (root or subpath) — the shape the bare GJS
+ *     built-ins are externalised to, i.e. the PORTABLE GJS-source spelling
+ *     (`detectNodeGiModuleImports`). A bundle retaining one is already bound to the
+ *     bridge at load, so flipping injection cannot cost plain-Node loadability, while
+ *     a portable GJS app with no ambient global at all (`system.programArgs` instead
+ *     of `ARGV`) would otherwise get its `@girs/*` bodies emptied and its globals shim
+ *     dropped (the `gjsify storybook --runtime node` no-`requireGi` regression).
  *
- * A SINGLE pass suffices (unlike the GJS register-injection loop): the shim is
- * EXTERNAL, so injecting it adds no bundled code that could reference more
- * globals — there is no tree-shaking dependency cycle to converge.
+ * A SINGLE pass suffices, unlike the GJS register-injection loop: the shim is EXTERNAL,
+ * so injecting it adds no bundled code that could reference more globals — no
+ * tree-shaking dependency cycle to converge.
  *
- * Critically, detection is on the bundled output AFTER tree-shaking, so a
- * `print`/`imports` reference behind statically-dead code does not trigger
- * injection — importing the shim eagerly loads the native node-gi addon, which
- * crashes on plain Node without node-gi. See `detectGjsAmbientGlobals`.
+ * Detection is on the bundled output AFTER tree-shaking, so a `print`/`imports`
+ * reference behind statically-dead code does not trigger injection — importing the shim
+ * eagerly loads the native node-gi addon, which crashes on plain Node without node-gi.
  */
 export async function detectNodeGiGlobals(analysisOptions, pluginOptions, gjsifyPluginFactory, bundler = defaultBundler) {
     const factoryResult = await gjsifyPluginFactory(pluginOptions);
@@ -455,17 +393,12 @@ export async function detectNodeGiGlobals(analysisOptions, pluginOptions, gjsify
         return name !== 'gjsify' && name !== 'gjsify-orchestrator';
     });
     const gjsifyPluginsArray = Array.isArray(gjsifyInstance) ? gjsifyInstance : [gjsifyInstance];
-    // Reuse the FULL orchestrator options as the base so the analysis bundle
-    // goes through the EXACT SAME module resolution as the real `--app node`
-    // build — most importantly `platform: 'node'`, without which Rolldown does
-    // not treat `node:*` as builtins and the @gjsify/rolldown-plugin-pnp
-    // resolver rejects `node:fs` in a non-Node context (`RESOLVE_ERROR`). It
-    // also carries `external` (the node externals incl. `@gjsify/node-gi/*`),
-    // `resolve` (conditionNames/mainFields) and `treeshake`. We strip only the
-    // disk-write `output` (the in-memory `generate({format})` handles output)
-    // and override `input`/`plugins`. Analysis-side overrides win when set.
-    // Mirrors how `detectAutoGlobals` reuses the orchestrator config, with the
-    // platform/external/resolve carried verbatim instead of cherry-picked.
+    // The FULL orchestrator options as the base (only `output` stripped, `input`/
+    // `plugins` overridden) so the analysis bundle goes through the EXACT SAME module
+    // resolution as the real `--app node` build. Most importantly `platform: 'node'`:
+    // without it Rolldown does not treat `node:*` as builtins and
+    // `@gjsify/rolldown-plugin-pnp` rejects `node:fs` with a `RESOLVE_ERROR`. Carried
+    // verbatim rather than cherry-picked, unlike `detectAutoGlobals`.
     const baseOptions = orchestratorOptions ? { ...orchestratorOptions } : {};
     delete baseOptions.output;
     let chunkCodes;
@@ -484,11 +417,9 @@ export async function detectNodeGiGlobals(analysisOptions, pluginOptions, gjsify
         });
     }
     catch (e) {
-        // Fail SAFE: a detection-pass failure must NEVER break a build that
-        // would otherwise succeed. Fall back to NOT injecting the shim — worst
-        // case is a missing global (a clear `ReferenceError: print is not
-        // defined` at runtime, recoverable via `--globals` or an explicit
-        // `import '@gjsify/node-gi/globals'`), never a hard build failure.
+        // Fail SAFE: a detection-pass failure must never break a build that would
+        // otherwise succeed. Not injecting costs at worst a `ReferenceError: print is
+        // not defined` at runtime, recoverable via `--globals` or an explicit import.
         console.warn('[gjsify] --app node: could not analyse the bundle for GJS ambient globals ' +
             `(${e instanceof Error ? e.message : String(e)}); skipping @gjsify/node-gi/globals ` +
             'injection. If this build uses print/imports/ARGV, add `import ' +
@@ -504,10 +435,8 @@ export async function detectNodeGiGlobals(analysisOptions, pluginOptions, gjsify
     return false;
 }
 /**
- * Append an additional entry path to a Rolldown `input` value while
- * preserving its shape (string → array, array → array, record → record).
- * The new entry is given the synthetic name `__gjsify_inject` when the
- * record form is used so it doesn't collide with user-named outputs.
+ * Append an entry path to a Rolldown `input` value, preserving its shape. In the record
+ * form the synthetic name `__gjsify_inject` avoids colliding with user-named outputs.
  */
 function appendInjectAsEntry(input, injectPath) {
     if (input === undefined)

package/lib/utils/detect-free-globals.d.ts

@@ -1,62 +1,43 @@
 /**
- * Parse bundled JS output and return the set of free (unbound) identifiers that
- * match the known web/Node GJS globals from `GJS_GLOBALS_MAP`. Drives the
- * `--app gjs --globals auto` injection. See `scanFreeGlobals` for the rules.
+ * Free identifiers in bundled output that match the known web/Node globals in
+ * `GJS_GLOBALS_MAP` — drives `--app gjs --globals auto`. Rules: `scanFreeGlobals`.
  */
 export declare function detectFreeGlobals(code: string): Set<string>;
 /**
- * The GJS ambient globals that exist implicitly under gjs but not on Node:
- * `print`/`printerr`/`log`/`logError`, the `ARGV` array, and the legacy
- * `imports` object (`imports.gi.Gtk`, `imports.system`, `imports.gettext`).
- * `@gjsify/node-gi/globals` seeds these on `globalThis` when imported.
- *
- * This is the REVERSE of `GJS_GLOBALS_MAP` (which maps Node/Web globals onto
- * GJS): it's the set the `--app node` target injects the node-gi globals shim
- * for. Kept here next to the detector so the two never drift.
+ * The globals that exist implicitly under gjs but not on Node, seeded on `globalThis` by
+ * `@gjsify/node-gi/globals`. The REVERSE of `GJS_GLOBALS_MAP`: the set whose presence
+ * makes `--app node` inject that shim. Kept beside the detector so the two never drift.
  */
 export declare const GJS_AMBIENT_GLOBALS: ReadonlySet<string>;
 /**
- * Detect references to the GJS ambient globals (`GJS_AMBIENT_GLOBALS`) in a
- * bundled `--app node` chunk — the signal that the bundle needs
- * `@gjsify/node-gi/globals` injected.
+ * References to `GJS_AMBIENT_GLOBALS` in a bundled `--app node` chunk — the signal that
+ * the bundle needs `@gjsify/node-gi/globals`.
  *
- * Runs on the bundled output AFTER tree-shaking (same property the GJS path
- * relies on), so a `print`/`imports` reference behind a statically-dead branch
- * does not trigger injection. Detects only BARE free identifiers — the genuine
- * GJS-source shape (`print(...)`, `imports.gi.Gtk`). The `globalThis.imports` /
- * `globalThis.print` host-member form is the cross-platform isomorphic-GUARD
- * shape (`if (typeof globalThis.imports !== 'undefined') { … }`) and is
- * deliberately ignored: injecting `@gjsify/node-gi/globals` for it would break
- * plain-Node loadability of a package that merely gates GJS usage (the bare
- * external import is unresolvable without node-gi; the shim eagerly loads the
- * native addon). Pure `typeof imports` probes are deferred too. See
- * `ignoreHostMembers`.
+ * Runs on the output AFTER tree-shaking, so a reference behind a statically-dead branch
+ * does not trigger injection, and matches only BARE identifiers (`print(...)`,
+ * `imports.gi.Gtk`) — see `ignoreHostMembers` for why the host-member form is ignored.
  */
 export declare function detectGjsAmbientGlobals(code: string): Set<string>;
 /**
- * Detect a STATIC import of `@gjsify/node-gi` (root or any subpath) in a
- * bundled `--app node` chunk — the second genuine-GJS-source signal next to
- * `detectGjsAmbientGlobals`.
+ * A STATIC import of `@gjsify/node-gi` (root or subpath) in a bundled `--app node`
+ * chunk — the second genuine-GJS-source signal beside `detectGjsAmbientGlobals`.
  *
- * Why this is a signal: the bare GJS built-in modules (`system`/`gettext`/
- * `cairo`) are rewritten to `@gjsify/node-gi/<name>` and kept EXTERNAL as
- * top-level import statements, so any bundle whose tree-shaken graph retains
- * one is ALREADY bound to the bridge at load — Node resolves the external at
- * link time and fails without node-gi installed. Treating that bundle as a
- * GJS-source build therefore cannot cost plain-Node loadability; NOT treating
- * it as one is how a portable GJS app that spells `ARGV` as
- * `system.programArgs` (the AGENTS.md-mandated spelling) lost its `@girs/*`
- * bodies and its globals shim in one go — `gjsify storybook --runtime node`
- * emitted a bundle with no `requireGi` at all.
+ * It is a signal because the bare GJS built-ins are rewritten to
+ * `@gjsify/node-gi/<name>` and kept EXTERNAL as top-level imports: a tree-shaken graph
+ * that retains one is ALREADY bound to the bridge at load (Node resolves the external
+ * at link time and fails without node-gi), so treating it as a GJS-source build cannot
+ * cost plain-Node loadability. NOT treating it as one is how a portable GJS app
+ * spelling `ARGV` as `system.programArgs` lost its `@girs/*` bodies and its globals
+ * shim in one go — `gjsify storybook --runtime node` emitted a bundle with no
+ * `requireGi` at all.
  *
- * Why a surviving `gi://` import is deliberately NOT a signal: its shim loads
- * node-gi LAZILY through a `require('@gjsify/node-gi/gi')` CALL — not an import
- * statement, so this scan is structurally blind to it, by design. A
- * cross-platform package with a gjs-gated `gi://` import stays loadable on
- * plain Node (the #641 lesson, pinned by `tests/e2e/node-gi-globals-inject`),
- * and flipping injection for it would break exactly that.
+ * A surviving `gi://` import is deliberately NOT a signal: its shim loads node-gi LAZILY
+ * through a `require('@gjsify/node-gi/gi')` CALL, so this scan is structurally blind to
+ * it by design. A cross-platform package with a gjs-gated `gi://` import stays loadable
+ * on plain Node (#641, pinned by `tests/e2e/node-gi-globals-inject`), and flipping
+ * injection for it would break exactly that.
  *
- * Scans import/re-export STATEMENTS via the AST (never text), so a quoted
- * `'@gjsify/node-gi/system'` inside a test name or template cannot trigger.
+ * Scans import/re-export STATEMENTS via the AST, never text, so a quoted specifier in a
+ * test name or template cannot trigger.
  */
 export declare function detectNodeGiModuleImports(code: string): boolean;