@gjsify/rolldown-plugin-gjsify 0.23.0 → 0.24.2

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

@@ -0,0 +1,318 @@
+// Resolver-layer guard: an unresolvable `@gjsify/*` edge is a build ERROR,
+// never a silent external.
+//
+// ## The failure this closes
+//
+// 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.
+import { dirname } from 'node:path';
+/** Bare `@gjsify/*` package specifier — the workspace edge this guard protects. */
+const WORKSPACE_SCOPE = '@gjsify/';
+/**
+ * How many reverse-looked-up source specifiers the error may name before the
+ * list stops being evidence and becomes noise. A per-builtin target inverts to
+ * 2 (`fs` + `node:fs`); a shared sink like `@gjsify/empty` inverts to ~50.
+ */
+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.
+ */
+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.
+    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`).
+ */
+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.
+    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];
+    const candidate = aliasTarget ?? source;
+    // The alias target may itself be declared external (`system` →
+    // `@gjsify/node-gi/system` on the node target).
+    if (candidate !== source && isExternal?.(candidate)) {
+        return { verdict: 'ignore', reason: 'declared-external' };
+    }
+    if (!isWorkspaceSpecifier(candidate))
+        return { verdict: 'ignore', reason: 'out-of-scope' };
+    return aliasTarget === undefined ? { verdict: 'check', candidate } : { verdict: 'check', candidate, aliasTarget };
+}
+/** A `@gjsify/*` edge the build promised to substitute could not be resolved. */
+export class UnresolvedWorkspaceImportError extends Error {
+    details;
+    constructor(details) {
+        super(formatUnresolvedWorkspaceImport(details));
+        this.name = 'UnresolvedWorkspaceImportError';
+        this.details = details;
+    }
+}
+/**
+ * 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.
+ */
+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.
+    const reversed = aliasedFrom ?? [];
+    const substitutedFor = aliasTarget === undefined ? (reversed.length <= MAX_REPORTED_ALIAS_SOURCES ? reversed : []) : [source];
+    const quoted = substitutedFor.map((s) => `\`${s}\``).join(', ');
+    const headline = substitutedFor.length === 0
+        ? `gjsify build --app ${target}: cannot resolve the workspace package \`${candidate}\`.`
+        : `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.
+    const surviving = substitutedFor.length === 0 ? [source] : substitutedFor;
+    const symptom = target !== 'gjs'
+        ? ''
+        : surviving.some((s) => s.startsWith('node:'))
+            ? ' Stock GJS aborts the whole module graph at load: ' +
+                '"ImportError: Unsupported URI scheme for importing: node".'
+            : ' Stock GJS would fail at load with "Module not found" — its ESM loader has no node_modules ' +
+                'walker and does not follow `package.json#exports` for bare specifiers.';
+    const consequence = (substitutedFor.length === 0
+        ? `Leaving it unresolved would silently externalise \`${source}\` into the bundle, which the ` +
+            `\`--app ${target}\` runtime cannot resolve.`
+        : `Leaving it unresolved would silently externalise the ORIGINAL ${substitutedFor.length === 1 ? 'specifier' : 'specifiers'} ${quoted} into the ` +
+            `bundle, defeating the substitution the \`--app ${target}\` target exists to perform.`) + symptom;
+    return [
+        headline,
+        `  imported by: ${importer}`,
+        '',
+        consequence,
+        '',
+        'Likely causes:',
+        '  - `node_modules` is missing or incomplete — run `gjsify install` (`--immutable` in CI).',
+        `  - the workspace package is not built: its \`exports["."]\` names a \`lib/\` that does not exist —`,
+        '    run `gjsify run build:infra`, or `gjsify workspace <pkg> build` for the one package.',
+        `  - \`${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).
+ */
+export function buildReverseAliasIndex(aliases) {
+    const index = new Map();
+    if (!aliases)
+        return index;
+    for (const [from, to] of Object.entries(aliases)) {
+        const existing = index.get(to);
+        if (existing)
+            existing.push(from);
+        else
+            index.set(to, [from]);
+    }
+    for (const list of index.values())
+        list.sort();
+    return index;
+}
+/**
+ * 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.
+ */
+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.
+    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`.
+    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.
+    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.
+                const importer = typeof rawImporter === 'string' ? rawImporter : undefined;
+                if (extraOptions?.isEntry)
+                    return null;
+                const verdict = classifyImport({ source, importer, aliases, isExternal });
+                if (verdict.verdict === 'ignore')
+                    return null;
+                // `kind` participates in the key: it selects the `import`
+                // vs `require` export condition, so the same specifier can
+                // legitimately resolve to different files from one directory.
+                const key = `${verdict.candidate}\0${importer === undefined ? '' : dirname(importer)}\0${extraOptions?.kind ?? ''}`;
+                const cached = resolvedCache.get(key);
+                if (cached)
+                    return cached;
+                if (inFlight.has(key))
+                    return null;
+                inFlight.add(key);
+                let resolved;
+                try {
+                    resolved = await this.resolve(verdict.candidate, importer, {
+                        skipSelf: true,
+                        kind: extraOptions?.kind,
+                    });
+                }
+                finally {
+                    inFlight.delete(key);
+                }
+                if (resolved) {
+                    resolvedCache.set(key, resolved);
+                    return resolved;
+                }
+                throw new UnresolvedWorkspaceImportError({
+                    target,
+                    source,
+                    candidate: verdict.candidate,
+                    aliasTarget: verdict.aliasTarget,
+                    aliasedFrom: reverseAliases.get(verdict.candidate)?.filter((s) => s !== source),
+                    importer: importer ?? '<entry>',
+                });
+            },
+        },
+    };
+}

package/lib/utils/auto-globals.js

@@ -319,7 +319,12 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
                     ?.GJSIFY_DEBUG_AUTO_GLOBALS) {
                     const path = `/tmp/gjsify-auto-globals-failed-chunk-${i}.mjs`;
                     try {
-                        // eslint-disable-next-line @typescript-eslint/no-require-imports
+                        // 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.)
                         const fs = await import('node:fs');
                         fs.writeFileSync(path, code);
                         console.error(`[gjsify-auto-globals] parse failed on chunk #${i} — wrote ${path} for inspection`);

package/lib/utils/entry-wrapper.js

@@ -7,6 +7,7 @@
 // first, then re-exports the real entry. `\0`-prefixed ids are Rollup's
 // convention for synthetic modules — Rolldown treats them as not-from-disk and
 // skips the default loader.
+import { GJSIFY_VIRTUAL_PREFIX } from './virtual-module-id.js';
 /**
  * If there are side-effect imports to land alongside the user's entry, wrap each
  * entry in a virtual module that imports them first then re-exports the entry.
@@ -22,7 +23,7 @@ export function wrapInputWithSideEffects(input, sideEffects, opts = {}) {
         return { input, plugin: null };
     }
     const userEntries = new Map(); // virtualId → realPath
-    const PREFIX = '\0gjsify-entry:';
+    const PREFIX = `${GJSIFY_VIRTUAL_PREFIX}entry:`;
     function wrap(realPath) {
         const id = PREFIX + realPath;
         userEntries.set(id, realPath);

package/lib/utils/index.d.ts

@@ -6,3 +6,4 @@ export * from './merge.js';
 export { detectFreeGlobals } from './detect-free-globals.js';
 export { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
 export { inlineStaticReads } from './inline-static-reads.js';
+export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';

package/lib/utils/index.js

@@ -6,3 +6,4 @@ export * from './merge.js';
 export { detectFreeGlobals } from './detect-free-globals.js';
 export { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
 export { inlineStaticReads } from './inline-static-reads.js';
+export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';

package/lib/utils/virtual-module-id.d.ts

@@ -0,0 +1,14 @@
+/** Shared prefix of every gjsify-generated (synthetic) module id. */
+export declare const GJSIFY_VIRTUAL_PREFIX = "\0gjsify-";
+/**
+ * Is `id` a module gjsify's own plugins generated (as opposed to a user/npm
+ * source file)?
+ *
+ * Used by `aliasPlugin` to scope the alias tables to REAL source: generated
+ * module bodies name the runtime module they need explicitly and must not be
+ * re-pointed by a user alias or a slot-routing entry.
+ *
+ * @param id A Rolldown module id — typically a `resolveId` `importer`, which is
+ *   `undefined` for entry modules.
+ */
+export declare function isGjsifyVirtualModuleId(id: string | undefined | null): boolean;

package/lib/utils/virtual-module-id.js

@@ -0,0 +1,36 @@
+// The ONE prefix every synthetic module id emitted by a gjsify plugin carries.
+//
+// Rollup/Rolldown convention is that a `\0`-prefixed id is not-from-disk; every
+// gjsify plugin that emits one additionally namespaces it with `gjsify-`
+// (`\0gjsify-entry:`, `\0gjsify-gi-node:`, `\0gjsify-napi-addon:`,
+// `\0gjsify-empty-gjs-import`). Deriving those ids from THIS constant turns that
+// naming habit into an enforced invariant, which matters because the alias layer
+// keys off it: a module whose SOURCE we generated must bind to the RUNTIME's real
+// modules, never to whatever a user `--alias` retargets a specifier onto.
+//
+// Concretely (the bug that motivated this): `gjsGiNodePlugin`'s virtual module
+// emits `import { createRequire } from 'node:module'`. Under the node-gi consumer
+// harness — which builds `--alias node:module=@gjsify/module` to put the polyfill
+// UNDER TEST behind the specifier — that import was rewritten onto the polyfill
+// itself, so the bundle called `@gjsify/module`'s `createRequire` at top level
+// before its lazy GLib namespace proxy existed (`TypeError: Cannot read
+// properties of undefined (reading 'filename_from_uri')`), and past that hit a
+// genuine cycle: the polyfill's Gio-backed CJS loader needs GLib, and GLib is
+// reached through `@gjsify/node-gi/gi` — which is what the virtual module was
+// loading in the first place.
+/** Shared prefix of every gjsify-generated (synthetic) module id. */
+export const GJSIFY_VIRTUAL_PREFIX = '\0gjsify-';
+/**
+ * Is `id` a module gjsify's own plugins generated (as opposed to a user/npm
+ * source file)?
+ *
+ * Used by `aliasPlugin` to scope the alias tables to REAL source: generated
+ * module bodies name the runtime module they need explicitly and must not be
+ * re-pointed by a user alias or a slot-routing entry.
+ *
+ * @param id A Rolldown module id — typically a `resolveId` `importer`, which is
+ *   `undefined` for entry modules.
+ */
+export function isGjsifyVirtualModuleId(id) {
+    return typeof id === 'string' && id.startsWith(GJSIFY_VIRTUAL_PREFIX);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/rolldown-plugin-gjsify",
-    "version": "0.23.0",
+    "version": "0.24.2",
     "description": "Rolldown / Rollup / Vite plugin orchestrator for GJS, Node, and Browser targets",
     "type": "module",
     "main": "lib/index.js",
@@ -55,11 +55,11 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "@gjsify/console": "^0.23.0",
-        "@gjsify/resolve-npm": "^0.23.0",
-        "@gjsify/rolldown-plugin-deepkit": "^0.23.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.23.0",
-        "@gjsify/vite-plugin-blueprint": "^0.23.0",
+        "@gjsify/console": "^0.24.2",
+        "@gjsify/resolve-npm": "^0.24.2",
+        "@gjsify/rolldown-plugin-deepkit": "^0.24.2",
+        "@gjsify/rolldown-plugin-pnp": "^0.24.2",
+        "@gjsify/vite-plugin-blueprint": "^0.24.2",
         "@rollup/pluginutils": "^5.4.0",
         "acorn": "^8.17.0",
         "acorn-walk": "^8.3.5",
@@ -68,7 +68,7 @@
         "sass": "^1.101.0"
     },
     "peerDependencies": {
-        "@gjsify/lightningcss-native": "^0.23.0",
+        "@gjsify/lightningcss-native": "^0.24.2",
         "rolldown": "^1.1.4"
     },
     "peerDependenciesMeta": {