@gjsify/rolldown-plugin-gjsify 0.3.14

package/src/plugins/shebang.ts

@@ -0,0 +1,33 @@
+// Inject a `#!/usr/bin/env -S gjs -m` shebang at byte 0 of entry chunks.
+//
+// Rolldown's `output.banner` would also work, but a renderChunk hook with
+// `order: 'post'` makes ordering declarative — the shebang lands AFTER all
+// other banner / process-stub plugins have run, which is required because
+// the `#` character is only valid as the very first byte of the file under
+// SpiderMonkey 128+.
+
+import type { Plugin } from 'rolldown';
+
+export const GJS_SHEBANG = '#!/usr/bin/env -S gjs -m';
+
+export interface ShebangPluginOptions {
+    enabled?: boolean;
+    /** Override the shebang line. Defaults to `GJS_SHEBANG`. */
+    line?: string;
+}
+
+export function shebangPlugin(options: ShebangPluginOptions = {}): Plugin | null {
+    if (!options.enabled) return null;
+    const line = options.line ?? GJS_SHEBANG;
+    return {
+        name: 'gjsify-shebang',
+        renderChunk: {
+            order: 'post' as const,
+            handler(code, chunk) {
+                if (!chunk.isEntry) return null;
+                if (code.startsWith('#!')) return null;
+                return { code: line + '\n' + code, map: null };
+            },
+        },
+    };
+}

package/src/shims/console-gjs.ts

@@ -0,0 +1,25 @@
+// 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.
+//
+// `@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).
+//
+// 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.
+// @ts-ignore — resolved by Rolldown at user-build time, not by tsc here.
+import { log, info, debug, warn, error, dir, dirxml, table, time, timeEnd, timeLog, trace, assert, clear, count, countReset, group, groupCollapsed, groupEnd, profile, profileEnd, timeStamp } from '@gjsify/console';
+
+export const console = {
+    log, info, debug, warn, error, dir, dirxml, table,
+    time, timeEnd, timeLog, trace, assert, clear,
+    count, countReset, group, groupCollapsed, groupEnd,
+    profile, profileEnd, timeStamp,
+};

package/src/types/app.ts

@@ -0,0 +1 @@
+export type App = 'gjs' | 'node' | 'browser';

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './app.js';
+export * from './resolve-alias-options.js';
+export * from './plugin-options.js';

package/src/types/plugin-options.ts

@@ -0,0 +1,48 @@
+import type { App } from './app.js';
+
+/** CSS handling forwarded to Rolldown / Lightning CSS. */
+export interface GjsifyCssOptions {
+    /** Browserslist-compatible target list. Defaults to `['firefox60']` for `--app gjs`. */
+    target?: string[];
+    /** Whether to minify the emitted CSS. Defaults to bundle-level `minify`. */
+    minify?: boolean;
+}
+
+export interface PluginOptions {
+    debug?: boolean;
+    app?: App;
+    aliases?: Record<string, string>;
+    /** Glob patterns to exclude when expanding entry points. */
+    exclude?: string[];
+    jsExtension?: string;
+    /** Override the bundle output format. */
+    format?: 'esm' | 'cjs';
+    /**
+     * Library mode — `'esm' | 'cjs'`. When set, the plugin emits an
+     * unbundled multi-entry library suitable for republication on npm
+     * rather than a single application bundle.
+     */
+    library?: 'esm' | 'cjs';
+    /**
+     * Inject a console shim into GJS builds that uses print()/printerr() instead
+     * of `GLib.log_structured()`. Removes the "Gjs-Console-Message:" prefix and
+     * lets the terminal interpret ANSI escape codes correctly. Only applies to
+     * `--app gjs`. Defaults to `true`.
+     */
+    consoleShim?: boolean;
+    /** Enable Deepkit TypeScript reflection. Defaults to `false`. */
+    reflection?: boolean;
+    /** CSS pipeline options forwarded to the Rolldown / Lightning CSS layer. */
+    css?: GjsifyCssOptions;
+    /**
+     * Path to a pre-computed globals stub file. The stub is an ESM file
+     * containing one `import '<pkg>/register';` per entry from the user's
+     * `--globals` CLI flag. When set, the plugin appends the stub path to
+     * Rolldown's inject list alongside the console shim.
+     *
+     * The plugin does no scanning or inference at this layer — the CLI is the
+     * sole source of truth for which `/register` modules get included. Only
+     * applies to `--app gjs`.
+     */
+    autoGlobalsInject?: string;
+}

package/src/types/resolve-alias-options.ts

@@ -0,0 +1 @@
+export interface ResolveAliasOptions { }

package/src/utils/alias.ts

@@ -0,0 +1,46 @@
+import {
+    EXTERNALS_NODE,
+    EXTERNALS_NPM,
+    ALIASES_GENERAL_FOR_GJS,
+    ALIASES_NODE_FOR_GJS,
+    ALIASES_WEB_FOR_GJS,
+    ALIASES_GENERAL_FOR_NODE,
+    ALIASES_GJS_FOR_NODE,
+    ALIASES_WEB_FOR_NODE
+} from "@gjsify/resolve-npm";
+
+import type { ResolveAliasOptions } from '../types/index.js';
+
+export const setNodeAliasPrefix = (ALIASES: Record<string, string>) => {
+    // Also resolve alias names with `node:${ALIAS}`
+    for (const ALIAS in ALIASES) {
+        if(ALIAS.startsWith('node:')) {
+            continue
+        }
+        const key = `node:${ALIAS}`;
+        if(!ALIASES[key]) ALIASES[key] = ALIASES[ALIAS];
+    }
+    return ALIASES;
+}
+
+const getAliasesGeneralForGjs = (options: ResolveAliasOptions) => ALIASES_GENERAL_FOR_GJS;
+const getAliasesNodeForGjs = (options: ResolveAliasOptions) => setNodeAliasPrefix(ALIASES_NODE_FOR_GJS);
+const getAliasesWebForGjs = (options: ResolveAliasOptions) => ALIASES_WEB_FOR_GJS;
+
+const getAliasesGeneralForNode = (options: ResolveAliasOptions) => ALIASES_GENERAL_FOR_NODE;
+const getAliasesGjsForNode = (options: ResolveAliasOptions) => ALIASES_GJS_FOR_NODE;
+const getAliasesWebForNode = (options: ResolveAliasOptions) => ALIASES_WEB_FOR_NODE;
+
+export const getAliasesForGjs = (options: ResolveAliasOptions) => {
+    return {...getAliasesGeneralForGjs(options), ...getAliasesNodeForGjs(options), ...getAliasesWebForGjs(options) }
+}
+
+export const getAliasesForNode = (options: ResolveAliasOptions) => {
+    return {...getAliasesGeneralForNode(options), ...getAliasesGjsForNode(options), ...getAliasesWebForNode(options) }
+}
+
+/** Array of Node.js build in module names (also with node: prefix) */
+export const externalNode = [...EXTERNALS_NODE, ...EXTERNALS_NODE.map(E => `node:${E}`)];
+
+/** Array of NPM module names for which we have our own implementation */
+export const externalNPM = [...EXTERNALS_NPM];

package/src/utils/auto-globals.ts

@@ -0,0 +1,283 @@
+// Iterative multi-pass build orchestrator for `--globals auto`.
+//
+// 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: 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.
+
+import { rolldown, type InputOptions, type OutputChunk, type RolldownPluginOption, type TransformOptions } from 'rolldown';
+import { detectFreeGlobals } from './detect-free-globals.js';
+import { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
+import { GJS_GLOBALS_MAP } from '@gjsify/resolve-npm/globals-map';
+import type { PluginOptions } from '../types/plugin-options.js';
+
+const GLOBALS_MAP: Record<string, string> = GJS_GLOBALS_MAP;
+
+/** Maximum iterations to prevent runaway loops on pathological inputs. */
+const MAX_ITERATIONS = 5;
+
+export interface AutoGlobalsResult {
+    /** Global identifiers detected in the bundle */
+    detected: Set<string>;
+    /** Path to the generated inject stub, or undefined if no globals needed */
+    injectPath: string | undefined;
+}
+
+function setsEqual(a: Set<string>, b: Set<string>): boolean {
+    if (a.size !== b.size) return false;
+    for (const x of a) if (!b.has(x)) return false;
+    return true;
+}
+
+async function applyExcludeGlobals(
+    detected: Set<string>,
+    currentInject: string | undefined,
+    extraRegisterPaths: Set<string>,
+    excludeGlobals: string[] | undefined,
+): Promise<AutoGlobalsResult> {
+    if (!excludeGlobals?.length) return { detected, injectPath: currentInject };
+
+    for (const id of excludeGlobals) detected.delete(id);
+    const filtered = detectedToRegisterPaths(detected);
+    for (const p of extraRegisterPaths) filtered.add(p);
+    const injectPath = filtered.size > 0 ? (await writeRegisterInjectFile(filtered)) ?? undefined : undefined;
+    return { detected, injectPath };
+}
+
+function detectedToRegisterPaths(detected: Set<string>): Set<string> {
+    const paths = new Set<string>();
+    for (const name of detected) {
+        const path = GLOBALS_MAP[name];
+        if (path) paths.add(path);
+    }
+    return paths;
+}
+
+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`).
+     */
+    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.
+     */
+    excludeGlobals?: 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.
+ */
+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.
+     */
+    transform?: TransformOptions;
+    /** Format for the analysis bundle output. 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`.
+ */
+type GjsifyPluginFactory = (
+    options: PluginOptions,
+) => RolldownPluginOption | Promise<RolldownPluginOption>;
+
+/**
+ * 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`.
+ */
+export async function detectAutoGlobals(
+    analysisOptions: AnalysisOptions,
+    pluginOptions: Omit<PluginOptions, 'autoGlobalsInject'>,
+    gjsifyPluginFactory: GjsifyPluginFactory,
+    verbose?: boolean,
+    options: DetectAutoGlobalsOptions = {},
+): Promise<AutoGlobalsResult> {
+    const extraRegisterPaths = options.extraGlobalsList
+        ? resolveGlobalsList(options.extraGlobalsList)
+        : new Set<string>();
+
+    const excludeSet = new Set(options.excludeGlobals ?? []);
+
+    let detected = new Set<string>();
+    let currentInject: string | undefined = undefined;
+
+    if (extraRegisterPaths.size > 0) {
+        currentInject = (await writeRegisterInjectFile(extraRegisterPaths)) ?? 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.
+    const callerPlugins = (analysisOptions.plugins ?? []).filter((p) => {
+        const name = p && typeof p === 'object' && 'name' in p ? p.name : undefined;
+        return name !== 'gjsify' && name !== 'gjsify-orchestrator';
+    });
+
+    for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
+        const gjsifyInstance = await gjsifyPluginFactory({
+            ...pluginOptions,
+            autoGlobalsInject: currentInject,
+        } as PluginOptions);
+
+        // 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.
+        const inputWithInject = currentInject
+            ? appendInjectAsEntry(analysisOptions.input, currentInject)
+            : analysisOptions.input;
+
+        const build = await rolldown({
+            input: inputWithInject,
+            external: analysisOptions.external,
+            resolve: analysisOptions.resolve,
+            transform: analysisOptions.transform,
+            plugins: [...callerPlugins, gjsifyInstance],
+            logLevel: 'silent',
+        });
+
+        const chunkCodes: string[] = [];
+        try {
+            const result = await build.generate({
+                format: analysisOptions.format ?? 'esm',
+                minify: false,
+                sourcemap: false,
+            });
+            for (const entry of result.output) {
+                if (entry.type === 'chunk') chunkCodes.push((entry as OutputChunk).code);
+            }
+        } finally {
+            await build.close();
+        }
+
+        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.
+        const newDetected = new Set<string>();
+        for (const code of chunkCodes) {
+            for (const id of detectFreeGlobals(code)) newDetected.add(id);
+        }
+
+        // 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.
+        if (excludeSet.size > 0) {
+            for (const id of excludeSet) newDetected.delete(id);
+        }
+
+        // Fixpoint check: detection is monotonic — once a global is needed,
+        // more code gets pulled in by the next pass, which can only ADD
+        // requirements. So a set that didn't grow is a converged set.
+        if (setsEqual(detected, newDetected)) {
+            if (verbose) {
+                const sorted = [...detected].sort();
+                const extras = extraRegisterPaths.size > 0 ? ` (+ ${extraRegisterPaths.size} extra register module(s))` : '';
+                console.debug(
+                    `[gjsify] --globals auto: converged after ${iteration - 1} iteration(s), ${detected.size} global(s)${sorted.length ? ': ' + sorted.join(', ') : ''}${extras}`,
+                );
+            }
+            return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals);
+        }
+
+        detected = newDetected;
+        const registerPaths = detectedToRegisterPaths(detected);
+        for (const p of extraRegisterPaths) registerPaths.add(p);
+
+        if (registerPaths.size === 0) {
+            return { detected, injectPath: undefined };
+        }
+
+        currentInject = (await writeRegisterInjectFile(registerPaths)) ?? undefined;
+
+        if (verbose) {
+            const sorted = [...detected].sort();
+            console.debug(
+                `[gjsify] --globals auto: iteration ${iteration}, ${detected.size} global(s)${sorted.length ? ': ' + sorted.join(', ') : ''}`,
+            );
+        }
+    }
+
+    if (verbose) {
+        console.debug(
+            `[gjsify] --globals auto: hit max iterations (${MAX_ITERATIONS}), using last detected set`,
+        );
+    }
+    return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals);
+}
+
+/**
+ * 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.
+ */
+function appendInjectAsEntry(
+    input: InputOptions['input'],
+    injectPath: string,
+): InputOptions['input'] {
+    if (input === undefined) return [injectPath];
+    if (typeof input === 'string') return [input, injectPath];
+    if (Array.isArray(input)) {
+        return [...input, injectPath];
+    }
+    return { ...input, __gjsify_inject: injectPath };
+}