@gjsify/rolldown-plugin-gjsify 0.3.14

package/lib/utils/alias.js

@@ -0,0 +1,29 @@
+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";
+export const setNodeAliasPrefix = (ALIASES) => {
+    // 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) => ALIASES_GENERAL_FOR_GJS;
+const getAliasesNodeForGjs = (options) => setNodeAliasPrefix(ALIASES_NODE_FOR_GJS);
+const getAliasesWebForGjs = (options) => ALIASES_WEB_FOR_GJS;
+const getAliasesGeneralForNode = (options) => ALIASES_GENERAL_FOR_NODE;
+const getAliasesGjsForNode = (options) => ALIASES_GJS_FOR_NODE;
+const getAliasesWebForNode = (options) => ALIASES_WEB_FOR_NODE;
+export const getAliasesForGjs = (options) => {
+    return { ...getAliasesGeneralForGjs(options), ...getAliasesNodeForGjs(options), ...getAliasesWebForGjs(options) };
+};
+export const getAliasesForNode = (options) => {
+    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/lib/utils/auto-globals.d.ts

@@ -0,0 +1,72 @@
+import { type InputOptions, type RolldownPluginOption, type TransformOptions } from 'rolldown';
+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 */
+    injectPath: string | undefined;
+}
+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 declare function detectAutoGlobals(analysisOptions: AnalysisOptions, pluginOptions: Omit<PluginOptions, 'autoGlobalsInject'>, gjsifyPluginFactory: GjsifyPluginFactory, verbose?: boolean, options?: DetectAutoGlobalsOptions): Promise<AutoGlobalsResult>;
+export {};

package/lib/utils/auto-globals.js

@@ -0,0 +1,193 @@
+// 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 } 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';
+const GLOBALS_MAP = GJS_GLOBALS_MAP;
+/** Maximum iterations to prevent runaway loops on pathological inputs. */
+const MAX_ITERATIONS = 5;
+function setsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const x of a)
+        if (!b.has(x))
+            return false;
+    return true;
+}
+async function applyExcludeGlobals(detected, currentInject, extraRegisterPaths, excludeGlobals) {
+    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) {
+    const paths = new Set();
+    for (const name of detected) {
+        const path = GLOBALS_MAP[name];
+        if (path)
+            paths.add(path);
+    }
+    return paths;
+}
+/**
+ * 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, pluginOptions, gjsifyPluginFactory, verbose, options = {}) {
+    const extraRegisterPaths = options.extraGlobalsList
+        ? resolveGlobalsList(options.extraGlobalsList)
+        : new Set();
+    const excludeSet = new Set(options.excludeGlobals ?? []);
+    let detected = new Set();
+    let currentInject = 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,
+        });
+        // 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 = [];
+        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.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();
+        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, injectPath) {
+    if (input === undefined)
+        return [injectPath];
+    if (typeof input === 'string')
+        return [input, injectPath];
+    if (Array.isArray(input)) {
+        return [...input, injectPath];
+    }
+    return { ...input, __gjsify_inject: injectPath };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Parse bundled JS code and return the set of free (unbound) identifiers
+ * that match known GJS globals from `GJS_GLOBALS_MAP`.
+ *
+ * "Free" means the identifier is referenced but never declared in the
+ * module (var/let/const/function/class/import/param/catch).
+ *
+ * After esbuild bundling + minification, local variables that shadow
+ * globals are renamed to short names, so any surviving known-global name
+ * in the output is almost certainly a true global reference. The
+ * declared-names check is a safety net for edge cases where esbuild
+ * keeps the original name.
+ *
+ * `typeof X` references ARE included — if code guards with
+ * `typeof fetch !== 'undefined'`, it intends to use fetch when available
+ * and we can provide it.
+ */
+export declare function detectFreeGlobals(code: string): Set<string>;

package/lib/utils/detect-free-globals.js

@@ -0,0 +1,268 @@
+// Detect free (unbound) global identifiers in bundled JS output.
+//
+// Used by the `--globals auto` two-pass build: the first esbuild pass
+// produces a minified bundle without globals injection, this module
+// parses it with acorn and finds references to known GJS globals that
+// are not locally declared. The result feeds the second pass's inject
+// stub so only actually-needed globals are registered.
+import * as acorn from 'acorn';
+import * as walk from 'acorn-walk';
+import { GJS_GLOBALS_MAP } from '@gjsify/resolve-npm/globals-map';
+const KNOWN_GLOBALS = new Set(Object.keys(GJS_GLOBALS_MAP));
+/**
+ * Method markers — `<host>.<method>(…)` patterns that imply a global
+ * identifier should be injected even though the identifier itself never
+ * appears in the bundle.
+ *
+ * Example: a project that calls `navigator.getGamepads()` doesn't reference
+ * any of the gamepad-related identifiers in the globals map, but it still
+ * needs `@gjsify/gamepad/register` to patch `navigator` with the method.
+ * This marker maps `navigator.getGamepads` → inject the `GamepadEvent`
+ * register path (which is the gamepad package's register entry).
+ *
+ * Keyed by `host.method` (lowercase host, exact method name). Values are
+ * KNOWN_GLOBALS identifiers — the detector adds them as free globals if
+ * the corresponding member expression is found in the bundle.
+ */
+const METHOD_MARKERS = {
+    // Gamepad API — navigator.getGamepads is patched on by @gjsify/gamepad/register
+    'navigator.getGamepads': 'GamepadEvent',
+    // WebRTC — navigator.mediaDevices is patched on by @gjsify/webrtc/register/media-devices
+    'navigator.mediaDevices': 'MediaDevices',
+    // WebAssembly Promise APIs — the runtime stubs throw at first call, so
+    // any reference to these methods needs the `@gjsify/webassembly` polyfill.
+    // The register entry replaces the stubs with wrappers around the working
+    // synchronous `new WebAssembly.{Module,Instance}` constructors.
+    'WebAssembly.compile': 'WebAssembly',
+    'WebAssembly.compileStreaming': 'WebAssembly',
+    'WebAssembly.instantiate': 'WebAssembly',
+    'WebAssembly.instantiateStreaming': 'WebAssembly',
+    'WebAssembly.validate': 'WebAssembly',
+    // Note: URL.createObjectURL / URL.revokeObjectURL don't need markers —
+    // they are first-class static methods on @gjsify/url's URL class, so the
+    // free `URL` identifier (detected directly, maps to
+    // @gjsify/node-globals/register/url in GJS_GLOBALS_MAP) already pulls in
+    // the correct register module.
+};
+/**
+ * Extract all bound names from a binding pattern
+ * (Identifier, ObjectPattern, ArrayPattern, AssignmentPattern, RestElement).
+ */
+function extractBindingNames(node) {
+    if (!node)
+        return [];
+    switch (node.type) {
+        case 'Identifier':
+            return [node.name];
+        case 'ObjectPattern':
+            return node.properties.flatMap((p) => p.type === 'RestElement'
+                ? extractBindingNames(p.argument)
+                : extractBindingNames(p.value));
+        case 'ArrayPattern':
+            return node.elements.flatMap((e) => e
+                ? e.type === 'RestElement'
+                    ? extractBindingNames(e.argument)
+                    : extractBindingNames(e)
+                : []);
+        case 'AssignmentPattern':
+            return extractBindingNames(node.left);
+        case 'RestElement':
+            return extractBindingNames(node.argument);
+        default:
+            return [];
+    }
+}
+/**
+ * Parse bundled JS code and return the set of free (unbound) identifiers
+ * that match known GJS globals from `GJS_GLOBALS_MAP`.
+ *
+ * "Free" means the identifier is referenced but never declared in the
+ * module (var/let/const/function/class/import/param/catch).
+ *
+ * After esbuild bundling + minification, local variables that shadow
+ * globals are renamed to short names, so any surviving known-global name
+ * in the output is almost certainly a true global reference. The
+ * declared-names check is a safety net for edge cases where esbuild
+ * keeps the original name.
+ *
+ * `typeof X` references ARE included — if code guards with
+ * `typeof fetch !== 'undefined'`, it intends to use fetch when available
+ * and we can provide it.
+ */
+export function detectFreeGlobals(code) {
+    const ast = acorn.parse(code, {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+    });
+    // --- Pass 1: collect all declared names across the entire module ---
+    const declaredNames = new Set();
+    walk.simple(ast, {
+        VariableDeclarator(node) {
+            for (const name of extractBindingNames(node.id)) {
+                declaredNames.add(name);
+            }
+        },
+        FunctionDeclaration(node) {
+            if (node.id)
+                declaredNames.add(node.id.name);
+            for (const param of node.params) {
+                for (const name of extractBindingNames(param)) {
+                    declaredNames.add(name);
+                }
+            }
+        },
+        FunctionExpression(node) {
+            if (node.id)
+                declaredNames.add(node.id.name);
+            for (const param of node.params) {
+                for (const name of extractBindingNames(param)) {
+                    declaredNames.add(name);
+                }
+            }
+        },
+        ArrowFunctionExpression(node) {
+            for (const param of node.params) {
+                for (const name of extractBindingNames(param)) {
+                    declaredNames.add(name);
+                }
+            }
+        },
+        ClassDeclaration(node) {
+            if (node.id)
+                declaredNames.add(node.id.name);
+        },
+        ImportSpecifier(node) {
+            declaredNames.add(node.local.name);
+        },
+        ImportDefaultSpecifier(node) {
+            declaredNames.add(node.local.name);
+        },
+        ImportNamespaceSpecifier(node) {
+            declaredNames.add(node.local.name);
+        },
+        CatchClause(node) {
+            if (node.param) {
+                for (const name of extractBindingNames(node.param)) {
+                    declaredNames.add(name);
+                }
+            }
+        },
+    });
+    // --- Pass 2: find Identifier nodes in reference position ---
+    // Also detects MemberExpressions like `globalThis.X` / `global.X` /
+    // `window.X` / `self.X` where X is a known global. esbuild's `define`
+    // config replaces `global`/`window` with `globalThis`, but we accept
+    // all four host-object names for safety (esbuild also never renames
+    // these because they are language keywords / pre-defined globals).
+    const freeGlobals = new Set();
+    const HOST_OBJECTS = new Set(['globalThis', 'global', 'window', 'self', 'globalObject']);
+    walk.ancestor(ast, {
+        MemberExpression(node) {
+            // Only dot-access — skip computed (bracket) access since the
+            // property is then a dynamic Expression, not a known name.
+            if (node.computed)
+                return;
+            if (node.object.type !== 'Identifier')
+                return;
+            if (node.property.type !== 'Identifier')
+                return;
+            const objName = node.object.name;
+            const propName = node.property.name;
+            // Pattern A: globalThis.X / global.X / window.X / self.X
+            // The property is a known global identifier itself.
+            if (HOST_OBJECTS.has(objName)) {
+                if (KNOWN_GLOBALS.has(propName)) {
+                    freeGlobals.add(propName);
+                }
+                return;
+            }
+            // Pattern B: known-instance method markers like
+            // `navigator.getGamepads` → marker map forwards to a global
+            // identifier that triggers the right register path even though
+            // the identifier itself never appears in the bundle.
+            const markerKey = `${objName}.${propName}`;
+            const markerTarget = METHOD_MARKERS[markerKey];
+            if (markerTarget && KNOWN_GLOBALS.has(markerTarget)) {
+                freeGlobals.add(markerTarget);
+            }
+        },
+        Identifier(node, ancestors) {
+            const name = node.name;
+            // Quick filter: only check known globals
+            if (!KNOWN_GLOBALS.has(name))
+                return;
+            // Skip if locally declared
+            if (declaredNames.has(name))
+                return;
+            // Determine if this Identifier is in a reference position
+            // by checking the parent node.
+            const parent = ancestors[ancestors.length - 2];
+            if (!parent) {
+                freeGlobals.add(name);
+                return;
+            }
+            switch (parent.type) {
+                // obj.prop — skip if this is the non-computed property
+                case 'MemberExpression': {
+                    const mem = parent;
+                    if (mem.property === node && !mem.computed)
+                        return;
+                    break;
+                }
+                // { key: value } — skip if this is the non-computed key
+                case 'Property': {
+                    const prop = parent;
+                    if (prop.key === node && !prop.computed)
+                        return;
+                    break;
+                }
+                // Method/property definitions in classes
+                case 'MethodDefinition':
+                case 'PropertyDefinition': {
+                    const def = parent;
+                    if (def.key === node && !def.computed)
+                        return;
+                    break;
+                }
+                // label: — skip
+                case 'LabeledStatement': {
+                    const labeled = parent;
+                    if (labeled.label === node)
+                        return;
+                    break;
+                }
+                // export { X as Y } — skip the exported name
+                case 'ExportSpecifier': {
+                    const spec = parent;
+                    if (spec.exported === node)
+                        return;
+                    break;
+                }
+                // Declaration ids (function name, class name, variable id)
+                // are already in declaredNames, but guard anyway
+                case 'FunctionDeclaration':
+                case 'FunctionExpression':
+                case 'ClassDeclaration':
+                case 'ClassExpression': {
+                    const decl = parent;
+                    if (decl.id === node)
+                        return;
+                    break;
+                }
+                case 'VariableDeclarator': {
+                    const vd = parent;
+                    if (vd.id === node)
+                        return;
+                    break;
+                }
+                // import { X } / import X — already in declaredNames
+                case 'ImportSpecifier':
+                case 'ImportDefaultSpecifier':
+                case 'ImportNamespaceSpecifier':
+                    return;
+            }
+            freeGlobals.add(name);
+        },
+    });
+    return freeGlobals;
+}

package/lib/utils/entry-points.d.ts

@@ -0,0 +1,2 @@
+export type EntryPoints = string | string[] | Record<string, string>;
+export declare const globToEntryPoints: (_entryPoints: EntryPoints | undefined, ignore?: string[]) => Promise<EntryPoints | undefined>;

package/lib/utils/entry-points.js

@@ -0,0 +1,38 @@
+// Glob expansion for Rolldown entry-point input.
+//
+// Rolldown's `input` accepts:
+//   - a single path string
+//   - an array of strings
+//   - a record mapping output names to input paths
+//
+// `globToEntryPoints` accepts the same shapes and expands any glob patterns
+// against the filesystem via `fast-glob`. Pure-string entries return as-is
+// when they don't contain wildcards (fast-glob handles that gracefully).
+//
+// `.d.ts` files are always excluded — they are type-only declarations,
+// not parseable as runtime modules. esbuild handled this implicitly via
+// its loader table; Rolldown's Oxc parser errors on declaration-only
+// shapes (`get foo(): T;`).
+import fastGlob from 'fast-glob';
+const DEFAULT_IGNORE = ['**/*.d.ts'];
+export const globToEntryPoints = async (_entryPoints, ignore = []) => {
+    if (_entryPoints === undefined)
+        return undefined;
+    const fullIgnore = [...DEFAULT_IGNORE, ...ignore];
+    if (typeof _entryPoints === 'string') {
+        const expanded = await fastGlob([_entryPoints], { ignore: fullIgnore });
+        return expanded;
+    }
+    if (Array.isArray(_entryPoints)) {
+        return await fastGlob(_entryPoints, { ignore: fullIgnore });
+    }
+    const entryPoints = {};
+    for (const input in _entryPoints) {
+        const output = _entryPoints[input];
+        const inputs = await fastGlob(input, { ignore: fullIgnore });
+        for (const matched of inputs) {
+            entryPoints[matched] = output;
+        }
+    }
+    return entryPoints;
+};

package/lib/utils/extension.d.ts

@@ -0,0 +1 @@
+export declare const getJsExtensions: (allowExt?: string) => Record<string, string>;

package/lib/utils/extension.js

@@ -0,0 +1,7 @@
+export const getJsExtensions = (allowExt) => {
+    const extensions = { '.js': '.js', '.ts': '.js', '.mts': '.js', '.cts': '.js', '.cjs': '.js', '.mjs': '.js' };
+    if (allowExt && extensions[allowExt]) {
+        delete extensions[allowExt];
+    }
+    return extensions;
+};

package/lib/utils/index.d.ts

@@ -0,0 +1,7 @@
+export * from './alias.js';
+export * from './entry-points.js';
+export * from './extension.js';
+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';

package/lib/utils/index.js

@@ -0,0 +1,7 @@
+export * from './alias.js';
+export * from './entry-points.js';
+export * from './extension.js';
+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';

package/lib/utils/inline-static-reads.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Run the inliner on a source string. Returns the rewritten source (or the
+ * original string when no inlining applied) and the count of edits applied.
+ *
+ * Safe to call on any JS source. Files that don't reference `readFileSync` /
+ * `readdirSync` / `existsSync` skip the AST parse entirely (cheap fast path).
+ */
+export declare function inlineStaticReads(src: string, sourceFilePath: string): {
+    contents: string;
+    inlined: number;
+};