@gjsify/rolldown-plugin-gjsify 0.36.0 → 0.38.0

package/lib/plugins/unresolved-workspace-import.js

@@ -1,85 +1,24 @@
-// Resolver-layer guard: an unresolvable `@gjsify/*` edge is a build ERROR,
-// never a silent external.
+// Resolver-layer guard: an unresolvable `@gjsify/*` edge is a build ERROR, never a
+// silent external. Full rationale, the measured incident and the legitimate-vs-broken
+// line: ../../AGENTS.md § "Unresolvable `@gjsify/*` edge".
 //
-// ## The failure this closes
+// Why this sits UPSTREAM of `utils/gjs-bundle-guard.ts` (which refuses to EMIT a
+// `--app gjs` bundle still importing a bare `node:` specifier, and stays as the last
+// line of defence). That guard is:
+//   - gjs-only — the same silent externalisation happens on `--app node`/`browser`,
+//     where a surviving bare `@gjsify/foo` is equally unloadable and no
+//     `node:`-shaped symptom exists to detect;
+//   - symptom-shaped — it names `node:fs`, not the `@gjsify/fs` edge that failed,
+//     and cannot name the importer;
+//   - post-tree-shake — an unresolved edge that gets shaken out leaves no trace, so
+//     the artefact passes while the build is still wrong.
 //
-// Rolldown (like Rollup) treats an import nothing resolves as EXTERNAL: it
-// emits an `UNRESOLVED_IMPORT` **warning**, re-emits the ORIGINAL specifier
-// into the output, and exits 0. For a normal bundler that is a reasonable
-// default — the specifier might be provided by the host. For `gjsify build` it
-// is not, because the `@gjsify/*` edge that failed is precisely the SUBSTITUTION
-// that makes the bundle runnable on the target:
-//
-//     import { readFileSync } from 'node:fs'
-//        → aliasPlugin rewrites to `@gjsify/fs`
-//        → `@gjsify/fs` cannot be resolved (no `node_modules`, or the workspace
-//          package has no built `lib/` so its `exports["."]` points at a file
-//          that does not exist)
-//        → aliasPlugin falls through, nothing else claims it
-//        → `node:fs` is externalised, the build "succeeds"
-//
-// Measured on `packages/infra/cli/dist/cli.gjs.mjs` (repo task #63): 1 bare
-// `node:` import on `origin/main` vs 11 from a worktree with no `node_modules`
-// — a bundle stock GJS aborts on before one line runs
-// (`ImportError: Unsupported URI scheme for importing: node`). The pre-commit
-// hook then rebuilt and AUTO-STAGED it, and nothing local objected: tsc, lint,
-// format, unit and e2e all run the Node entry, never the emitted GJS bundle.
-//
-// ## Why this is upstream of the `--app gjs` `node:` guard (PR #828)
-//
-// `utils/gjs-bundle-guard.ts` reads the finished module graph and refuses to
-// EMIT a `--app gjs` bundle that still statically imports a bare `node:`
-// specifier. That is the right last line of defence, and it stays. But it is:
-//
-//   - **gjs-only** — the same silent externalisation happens on `--app node`
-//     and `--app browser`, where a surviving bare `@gjsify/foo` is equally
-//     unloadable and no `node:`-shaped symptom exists to detect;
-//   - **symptom-shaped** — it names `node:fs`, not the `@gjsify/fs` edge that
-//     actually failed, and cannot name the importer;
-//   - **post-tree-shake** — an unresolved edge that gets shaken out leaves no
-//     trace at all, so the artefact passes while the build is still wrong.
-//
-// This guard fires at RESOLUTION time instead: it names the specifier, the
-// substitution target, the importer, and the likely cause.
-//
-// ## The legitimate-vs-broken line
-//
-// A blanket "fail on any external" would break every real build — externals are
-// load-bearing on every target (`gi://*`, `cairo`/`system`/`gettext` on gjs; the
-// whole `EXTERNALS_NODE` set plus `@gjsify/node-gi*` and `node-datachannel` on
-// node; whatever the user passed to `--external`). Those never reach the
-// unresolved fallback by accident — a `resolveId` hook or the `external` option
-// CLAIMS them, deliberately. So the distinction drawn here is:
-//
-//   DECLARED external  → legitimate, ignored. Asked via the target's own
-//                        externals predicate (`isExternal`), i.e. exactly the
-//                        policy `externalsPlugin` enforces, so the guard and the
-//                        policy cannot drift.
-//   PROMISED, missing  → broken. Either (a) the specifier has an entry in the
-//                        target's substitution table and that target does not
-//                        resolve, or (b) the specifier IS a bare `@gjsify/*`
-//                        workspace package that does not resolve.
-//   anything else      → not our business. A missing `lodash` is a plain
-//                        dependency bug that `UNRESOLVED_IMPORT` already
-//                        reports; widening to every bare specifier would turn a
-//                        genuinely optional peer into a hard build failure, and
-//                        this guard's whole claim is that the `@gjsify/*` edge
-//                        is NOT optional — the target cannot run without it.
-//
-// On (a): the check is keyed on the ALIAS TARGET being a `@gjsify/*` package,
-// not merely on the entry existing. Every value in the curated + derived tables
-// is a `@gjsify/*` specifier today, so this is a distinction without a
-// difference for them — but it keeps a user `--alias foo=./some/local.js` (or a
-// shim path like `random-access-file/index.js`) on the old fall-through
-// behaviour instead of promoting a user's own mapping mistake to a fatal error
-// in a plugin they did not ask for.
-//
-// ## Not registered for `--library`
-//
-// Library mode PRESERVES imports on purpose (`preserveModules`, bare specifiers
-// kept so the consumer resolves them). An unresolved `@gjsify/*` there is the
-// contract, not a bug, so `library/lib.ts` deliberately does not compose this
-// plugin.
+// Case (a) of the fatal line keys on the ALIAS TARGET being a `@gjsify/*` package,
+// not merely on the entry existing. Every value in the curated + derived tables is
+// `@gjsify/*` today, so it makes no difference for them — but it keeps a user
+// `--alias foo=./some/local.js` (or a shim path like `random-access-file/index.js`)
+// on the old fall-through instead of promoting a user's own mapping mistake to a
+// fatal error in a plugin they did not ask for.
 import { dirname } from 'node:path';
 /** Bare `@gjsify/*` package specifier — the workspace edge this guard protects. */
 const WORKSPACE_SCOPE = '@gjsify/';
@@ -90,41 +29,33 @@ const WORKSPACE_SCOPE = '@gjsify/';
  */
 const MAX_REPORTED_ALIAS_SOURCES = 4;
 /**
- * Is `id` a bare `@gjsify/*` package specifier (root or subpath)?
- *
- * Deliberately excludes disk paths and synthetic ids: a resolved
- * `/…/node_modules/@gjsify/fs/lib/esm/index.js` is already resolved, and a
- * `\0gjsify-*` virtual id belongs to the plugin that emitted it.
+ * Is `id` a bare `@gjsify/*` package specifier (root or subpath)? Excludes disk
+ * paths and synthetic ids: a resolved `…/node_modules/@gjsify/fs/…` is already
+ * resolved, and a `\0gjsify-*` virtual id belongs to the plugin that emitted it.
  */
 export function isWorkspaceSpecifier(id) {
     if (!id.startsWith(WORKSPACE_SCOPE))
         return false;
     if (id.includes('\0'))
         return false;
-    // `@gjsify/fs` and `@gjsify/fs/register/x` qualify; `@gjsify/` and
-    // `@gjsify//x` do not (no package name). A resolved disk path can never
-    // reach here — it is absolute or `./`-relative, so it never starts with the
-    // scope in the first place.
+    // `@gjsify/fs/register/x` qualifies; `@gjsify/` and `@gjsify//x` do not.
     const rest = id.slice(WORKSPACE_SCOPE.length);
     return rest.length > 0 && !rest.startsWith('/');
 }
 /**
- * Pure decision: does this import edge have to resolve, and to what?
- *
- * Split out from the plugin so the legitimate-vs-broken line is unit-testable
- * without a bundler (`packages/infra/cli/src/unresolved-workspace-import.spec.ts`).
+ * Pure decision: does this import edge have to resolve, and to what? Split out from
+ * the plugin so the legitimate-vs-broken line is unit-testable without a bundler
+ * (`packages/infra/cli/src/unresolved-workspace-import.spec.ts`).
  */
 export function classifyImport(input) {
     const { source, importer, aliases, isExternal } = input;
-    // Entry modules are files the caller named; they are resolved by the
-    // orchestrator, never externalised.
+    // Entry modules are files the caller named — resolved by the orchestrator, never
+    // externalised.
     if (importer === undefined)
         return { verdict: 'ignore', reason: 'entry' };
-    // Relative / absolute / synthetic ids are not workspace edges.
     if (source.startsWith('.') || source.startsWith('/') || source.startsWith('\0')) {
         return { verdict: 'ignore', reason: 'not-bare' };
     }
-    // A specifier the target DECLARES external is a deliberate external.
     if (isExternal?.(source))
         return { verdict: 'ignore', reason: 'declared-external' };
     const aliasTarget = aliases?.[source];
@@ -148,22 +79,17 @@ export class UnresolvedWorkspaceImportError extends Error {
     }
 }
 /**
- * The actionable message. Names the specifier, the importer and the likely
- * cause — the three things `UNRESOLVED_IMPORT` (and the post-hoc `node:` guard)
- * cannot tell you.
+ * The actionable message: names the specifier, the importer and the likely cause —
+ * the three things `UNRESOLVED_IMPORT` and the post-hoc `node:` guard cannot.
  */
 export function formatUnresolvedWorkspaceImport(details) {
     const { target, source, candidate, aliasTarget, aliasedFrom, importer } = details;
-    // The specifiers `candidate` was standing in for: `source` itself when IT
-    // carried the table entry, else whatever the reverse lookup recovered.
-    //
-    // The reverse lookup is only reported when its fan-in is SMALL. A shared
-    // sink inverts to a useless wall of text — `@gjsify/empty` is the browser
-    // target for 49 specifiers, and printing all of them says nothing about
-    // which one this importer wrote, while `@gjsify/fs` inverts to exactly
-    // `['fs','node:fs']` (the two spellings of one builtin), which is the
-    // information the reader needs. Above the threshold, fall back to naming
-    // the package alone rather than guessing.
+    // The specifiers `candidate` stood in for: `source` when IT carried the table
+    // entry, else the reverse lookup — but only when its fan-in is SMALL. A shared
+    // sink inverts to a wall of text (`@gjsify/empty` is the browser target for 49
+    // specifiers) that says nothing about which one this importer wrote, while
+    // `@gjsify/fs` inverts to exactly the two spellings of one builtin. Above the
+    // threshold, name the package alone rather than guess.
     const reversed = aliasedFrom ?? [];
     const substitutedFor = aliasTarget === undefined ? (reversed.length <= MAX_REPORTED_ALIAS_SOURCES ? reversed : []) : [source];
     const quoted = substitutedFor.map((s) => `\`${s}\``).join(', ');
@@ -172,10 +98,9 @@ export function formatUnresolvedWorkspaceImport(details) {
         : `gjsify build --app ${target}: cannot resolve \`${candidate}\`, the \`--app ${target}\` ` +
             `substitution for ${quoted}.`;
     // The symptom is a property of the SPECIFIER that would survive, not of the
-    // target: only a `node:` specifier reaching stock GJS produces the URI-scheme
-    // abort; a bare `@gjsify/*` or `<pkg>/register` one produces `Module not
-    // found` (GJS's ESM loader has no node_modules walker and does not follow
-    // `exports` maps). Naming the wrong one sends the reader hunting the wrong bug.
+    // target: only a `node:` specifier reaching stock GJS gives the URI-scheme abort,
+    // while a bare `@gjsify/*` gives `Module not found`. Naming the wrong one sends
+    // the reader hunting the wrong bug.
     const surviving = substitutedFor.length === 0 ? [source] : substitutedFor;
     const symptom = target !== 'gjs'
         ? ''
@@ -202,12 +127,7 @@ export function formatUnresolvedWorkspaceImport(details) {
         `  - \`${candidate}\` is genuinely not a dependency of this project — add it.`,
     ].join('\n');
 }
-/**
- * Reverse the substitution table: alias TARGET → the specifiers that route to it.
- *
- * Built once per plugin instance (the tables run to ~150 entries per target, and
- * the guard only consults this on the failure path).
- */
+/** Reverse the substitution table: alias TARGET → the specifiers that route to it. */
 export function buildReverseAliasIndex(aliases) {
     const index = new Map();
     if (!aliases)
@@ -226,54 +146,42 @@ export function buildReverseAliasIndex(aliases) {
 /**
  * Refuse a build whose `@gjsify/*` substitution could not be resolved.
  *
- * `order: 'post'` so every deliberate claim — `aliasPlugin` (`pre`),
- * `napiNodeAddonPlugin` (`pre`), `gjsGiNodePlugin` (`pre`),
- * `gjsImportsEmptyPlugin`, `externalsPlugin` — gets first refusal. Only ids that
- * NOTHING claimed reach this hook, i.e. exactly the ones headed for the
- * unresolved-import fallback.
- *
- * The hook re-runs the full resolution chain via `this.resolve(…, { skipSelf })`
- * — which is what Rolldown's builtin resolver would have done next — and returns
- * its result when it succeeds, so a healthy build resolves the specifier exactly
- * once and behaves identically. Only a genuine `null` throws.
+ * `order: 'post'` so every deliberate claim (alias/napi/gi-node at `pre`,
+ * imports-empty/externals at normal) gets first refusal — only ids NOTHING claimed
+ * reach this hook. It then re-runs the resolution Rolldown would have run next
+ * (`this.resolve(…, { skipSelf })`) and returns that, so a healthy build resolves
+ * each specifier exactly once and behaves identically. Only a genuine `null` throws.
  */
 export function unresolvedWorkspaceImportPlugin(options) {
     const { target, aliases, isExternal } = options;
-    // Re-entrancy belt: `skipSelf: true` is supposed to keep our own
-    // `this.resolve` from re-entering this hook, but a hang is a far worse
-    // failure than a missed check, so the in-flight candidate is tracked
-    // explicitly. Keyed by `candidate\0importer` — the same package legitimately
-    // resolves from many importers.
+    // Re-entrancy belt: `skipSelf: true` should keep our own `this.resolve` out of
+    // this hook, but a hang is a far worse failure than a missed check. Keyed by
+    // `candidate\0importer` — the same package legitimately resolves from many.
     const inFlight = new Set();
-    // Alias TARGET → the specifiers that route to it. Only read on the failure
-    // path, to recover the `node:fs` behind a failed `@gjsify/fs`.
+    // Read only on the failure path, to recover the `node:fs` behind a failed
+    // `@gjsify/fs`.
     const reverseAliases = buildReverseAliasIndex(aliases);
-    // Successful resolutions, memoized per (candidate, importer DIRECTORY) —
-    // the pair node resolution actually depends on, so a hit is the answer the
-    // chain would have recomputed. Without it this hook was the single most
-    // expensive plugin in a CLI-bundle build (32% of plugin time): `@gjsify/*`
-    // edges repeat across hundreds of modules, and each miss re-runs the whole
-    // `pre`-order chain (alias, napi-addon, gi-node) for the same target. Same
-    // shape + rationale as `napiNodeAddonPlugin`'s `bareEntryCache` (#840).
-    // Only POSITIVE results are cached: a failure throws, so it is never hot,
-    // and caching it could outlive a package appearing mid-watch.
+    // Successful resolutions memoized per (candidate, importer DIRECTORY) — the pair
+    // node resolution actually depends on, so a hit is the answer the chain would have
+    // recomputed. Without it this hook was the most expensive plugin in a CLI-bundle
+    // build (32% of plugin time): `@gjsify/*` edges repeat across hundreds of modules
+    // and each miss re-runs the whole `pre`-order chain. POSITIVE results only — a
+    // failure throws, so it is never hot, and caching it could outlive a package
+    // appearing mid-watch.
     const resolvedCache = new Map();
     return {
         name: 'gjsify-unresolved-workspace-import',
         resolveId: {
             order: 'post',
             async handler(source, rawImporter, extraOptions) {
-                // The two engines disagree on "no importer": npm `rolldown`
-                // passes `undefined`, `@gjsify/rolldown-native` passes `null`
-                // (its hook payload round-trips through JSON, which has no
-                // `undefined`). `classifyImport` reads an absent importer as
-                // "this is an ENTRY, never externalised" via `=== undefined`,
-                // and `null` fails that test — so under the GJS bundler an
-                // entry module would have been resolved as a normal edge and
-                // could throw this plugin's error for a file the caller named
-                // explicitly. Normalise once, at the boundary — same fix as
-                // `napiNodeAddonPlugin` (#840), whose `dirname(null)` threw
-                // and took the whole GJS build down as an UNHANDLEABLE_ERROR.
+                // The two engines disagree on "no importer": npm `rolldown` passes
+                // `undefined`, `@gjsify/rolldown-native` passes `null` (its hook
+                // payload round-trips through JSON, which has no `undefined`).
+                // `classifyImport` reads an absent importer as "ENTRY, never
+                // externalised" via `=== undefined`, which `null` fails — so under
+                // the GJS bundler an entry module got treated as a normal edge and
+                // could throw this plugin's error for a file the caller named.
+                // Normalise once, at the boundary (same fix as `napiNodeAddonPlugin`).
                 const importer = typeof rawImporter === 'string' ? rawImporter : undefined;
                 if (extraOptions?.isEntry)
                     return null;

package/lib/shims/console-gjs.js

@@ -1,27 +1,19 @@
 // GJS console shim — bundled into GJS user builds via Rolldown's `inject`.
-// Uses print()/printerr() on GJS, bypassing GLib.log_structured() — no
-// `Gjs-Console-Message:` prefix, ANSI escapes work, output goes to
-// stdout/stderr instead of GLib's logging stream.
+// Routes through print()/printerr() rather than GLib.log_structured(): no
+// `Gjs-Console-Message:` prefix, ANSI escapes survive, output on stdout/stderr.
 //
-// `@gjsify/console` is resolved by the user's `gjsify build` Rolldown
-// run, NOT by tsc here. The bare specifier survives compilation and only
-// gets followed at user-build time, where the CLI's `@gjsify/node-polyfills`
-// dep tree has the package. tsc on this package would otherwise need the
-// `@gjsify/console` lib to be pre-built (build-order coupling).
+// `globalThis.console` is non-writable AND non-configurable in GJS — re-measured
+// on 1.88/SM 140, so it is a property of the runtime and not of one version — which
+// is why nothing here assigns to it. Rolldown's `inject` rewrites bare `console`
+// references to a named import from this shim instead.
 //
-// We can't reassign `globalThis.console` on SpiderMonkey 128 — the
-// property is non-configurable. Rolldown's `inject` option rewrites bare
-// `console` references to a named import from this shim instead, leaving
-// `globalThis.console` untouched and routing user `console.log(…)` calls
-// through our object.
+// The `@gjsify/console` specifier is followed at USER-build time by Rolldown, not by
+// tsc here; resolving it here would make this package depend on that one being built
+// first. Hence the namespace import: a single statement no formatter can wrap, so the
+// `@ts-ignore` stays on the line directly above it. A multi-line named import would
+// let oxfmt detach the suppression from the `from '@gjsify/console'` line.
 // @ts-ignore — resolved by Rolldown at user-build time, not by tsc here.
 import * as gjsConsole from '@gjsify/console';
-// NOTE: a namespace import is used deliberately. It is a single statement that
-// no formatter (oxfmt) can wrap across lines, so the `@ts-ignore` above always
-// sits on the line immediately preceding the import and reliably suppresses the
-// TS2307 (`@gjsify/console` is resolved by Rolldown at user-build time, not by
-// tsc here). A multi-line named import would let the reformatter detach the
-// suppression from the offending `from '@gjsify/console'` line.
 export const console = {
     log: gjsConsole.log,
     info: gjsConsole.info,

package/lib/utils/auto-globals.d.ts

@@ -1,14 +1,10 @@
 import type { InputOptions, RolldownPluginOption, TransformOptions } from 'rolldown';
 /**
- * In-memory bundle function — returns the per-entry chunk code strings.
- * Implementations: npm rolldown (Node default), `@gjsify/rolldown-native`
- * (GJS). Pulled out so auto-globals can run under either engine without
- * hardcoding npm rolldown (which can't load under GJS — the Rust prebuild's
- * init code uses `require('node:fs')` synchronously).
- *
- * The default impl below dynamically imports npm rolldown; the CLI
- * overrides this from `actions/build.ts` to route via the same engine the
- * final build uses.
+ * In-memory bundle function returning the per-entry chunk code strings, injected so
+ * auto-globals runs under either engine: npm rolldown cannot load under GJS (its Rust
+ * prebuild's init code calls `require('node:fs')` synchronously). The default impl
+ * dynamically imports npm rolldown; the CLI overrides it from `actions/build.ts` to
+ * route via the same engine the final build uses.
  */
 export type AnalysisBundler = (input: {
     rolldownInput: InputOptions;
@@ -16,101 +12,73 @@ export type AnalysisBundler = (input: {
 }) => Promise<string[]>;
 import type { PluginOptions } from '../types/plugin-options.js';
 export interface AutoGlobalsResult {
-    /** Global identifiers detected in the bundle */
     detected: Set<string>;
-    /** Path to the generated inject stub, or undefined if no globals needed */
+    /** Path to the generated inject stub; undefined when no globals are needed. */
     injectPath: string | undefined;
 }
 /**
- * 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 declare function describeGiBackedInjection(registerPaths: Set<string>, detected: Set<string>): string | null;
 export interface DetectAutoGlobalsOptions {
     /**
-     * Extra explicit identifiers (or group aliases like `dom`/`web`/`node`)
-     * that should always be injected, in addition to whatever the iterative
-     * detection finds. Used by `--globals auto,<extras>` for cases where
-     * the detector cannot statically see a global because it's accessed via
-     * indirection (e.g. Excalibur's `BrowserComponent.nativeComponent.matchMedia`).
+     * Identifiers or group aliases (`dom`/`web`/`node`) always injected on top of what
+     * detection finds — `--globals auto,<extras>`, for globals reached through
+     * indirection the detector cannot follow statically (Excalibur's
+     * `BrowserComponent.nativeComponent.matchMedia`).
      */
     extraGlobalsList?: string;
     /**
-     * Identifiers to remove from the auto-detected set before writing the
-     * inject stub. Useful for globals that appear as false positives from
-     * dead browser-compat code in npm dependencies whose polyfills require
-     * unavailable native libraries.
+     * Identifiers to remove before writing the inject stub — for false positives from
+     * dead browser-compat code in deps whose polyfills need unavailable native libs.
      */
     excludeGlobals?: string[];
     /**
-     * Skip the committed register-globals closure-map expansion and run the
-     * pure iterative loop. Used by the closure-map GENERATOR
-     * (`packages/infra/cli/scripts/generate-register-closure.mjs`): computing
-     * a register module's closure THROUGH the committed map would re-add
-     * every identifier the OLD entry contained — removed globals could never
-     * leave the map (a ratchet, with transitive pollution into sibling
+     * Skip the closure-map expansion and run the pure iterative loop. Only the
+     * closure-map GENERATOR sets this: computing a register's closure THROUGH the
+     * committed map would re-add every identifier the OLD entry contained, so removed
+     * globals could never leave it (a ratchet, with transitive pollution into sibling
      * entries) and `--check` would stay green on semantically stale data.
-     * Builds never set this; the expansion is exactly what makes them
-     * converge after one detection pass.
      */
     disableClosureExpansion?: boolean;
     /**
-     * Working directory of the project being built. Used to locate the
-     * project's `node_modules` when checking whether a detected global's
-     * polyfill package is actually installed.
-     *
-     * When omitted the resolvability gate is BYPASSED (every detected
-     * register path is written as-is) to preserve the original behaviour
-     * for callers that don't know the project root. The real CLI build
-     * (`actions/build.ts`) passes `process.cwd()` so the gate is active in
-     * a normal `gjsify build`.
+     * Project root, used to locate `node_modules` when checking whether a detected
+     * global's polyfill package is installed. Omitting it BYPASSES that resolvability
+     * gate (every detected register path is written as-is); the real CLI build passes
+     * `process.cwd()`.
      */
     cwd?: string;
 }
 /**
- * Build options accepted by the analyser. A subset of Rolldown's
- * `InputOptions` plus the `output` shape used by `RolldownBuild.generate`.
- *
- * The caller passes the same input + output options it would use for the
- * final build (input, plugins, external, define, …). We strip output-side
- * fields that would force a write-to-disk and replace them with in-memory
- * settings.
+ * Build options for the analyser: the same input options the caller would use for the
+ * final build, with the output-side fields that force a write-to-disk stripped and
+ * replaced by in-memory settings.
  */
 export interface AnalysisOptions {
     input: InputOptions['input'];
     plugins?: RolldownPluginOption[];
     external?: InputOptions['external'];
     resolve?: InputOptions['resolve'];
-    /**
-     * Pass-through to Rolldown's `transform` (Oxc-driven) — `define`,
-     * `dropLabels`, `treeShake`, etc. live here in Rolldown's shape.
-     */
+    /** Pass-through to Rolldown's Oxc-driven `transform` (`define`, `treeShake`, …). */
     transform?: TransformOptions;
-    /** Format for the analysis bundle output. Use 'esm' to match the final build. */
+    /** Use 'esm' to match the final build. */
     format?: 'esm' | 'cjs' | 'iife';
 }
 /**
- * Build a `gjsifyPlugin` for the analyser to insert into the plugin array.
- * Late-imported via dynamic `await import()` to break the cyclic dep
- * between this file and `../plugin.ts`.
- *
- * Returns either the plugin array directly (legacy form) or the full
- * orchestrator config `{ options, plugins }`. The latter shape lets
- * `detectAutoGlobals` reuse the orchestrator's `resolve.conditionNames` /
- * `mainFields` / `external` / `treeshake` settings for the in-memory
- * analysis bundle — without that, native-rolldown and npm-rolldown default
- * to different module-resolution conditions and the bundled output (and
- * therefore the detected free-global set) diverges between engines.
+ * Supplies the gjsify plugin to the analyser; passed in by the caller to break the
+ * cyclic dep between this file and `../plugin.ts`. Returns either the plugin array
+ * alone or the full orchestrator config `{ options, plugins }` — the latter lets the
+ * analysis bundle reuse the orchestrator's `resolve.conditionNames`/`mainFields`/
+ * `external`/`treeshake`, without which native-rolldown and npm-rolldown default to
+ * different module-resolution conditions and the detected free-global set diverges
+ * between engines.
  */
 type GjsifyFactoryReturn = RolldownPluginOption | {
     options: InputOptions;
@@ -118,21 +86,10 @@ type GjsifyFactoryReturn = RolldownPluginOption | {
 };
 type GjsifyPluginFactory = (options: PluginOptions) => GjsifyFactoryReturn | Promise<GjsifyFactoryReturn>;
 /**
- * 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 declare function detectAutoGlobals(analysisOptions: AnalysisOptions, pluginOptions: Omit<PluginOptions, 'autoGlobalsInject'>, gjsifyPluginFactory: GjsifyPluginFactory, verbose?: boolean, options?: DetectAutoGlobalsOptions, bundler?: AnalysisBundler): Promise<AutoGlobalsResult>;
 /**
@@ -145,24 +102,21 @@ export declare function detectAutoGlobals(analysisOptions: AnalysisOptions, plug
  *  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 declare function detectNodeGiGlobals(analysisOptions: AnalysisOptions, pluginOptions: Omit<PluginOptions, 'nodeGiGlobalsInject'>, gjsifyPluginFactory: GjsifyPluginFactory, bundler?: AnalysisBundler): Promise<boolean>;
 export {};