@gjsify/cli 0.51.1 → 0.53.0

package/lib/actions/build.d.ts

@@ -1,6 +1,7 @@
 import type { ConfigData } from '../types/index.js';
 import type { App } from '@gjsify/rolldown-plugin-gjsify';
 import type { RolldownOutput } from 'rolldown';
+import { type RunBundleOptions } from '../bundler-pick.js';
 export declare class BuildAction {
     readonly configData: ConfigData;
     constructor(configData?: ConfigData);
@@ -186,11 +187,31 @@ export declare class BuildAction {
          */
         resolveFromToolchain?: boolean;
     }): Promise<string>;
+    /**
+     * The uncached half of {@link bundleFileForGjsCached}: bundle `inputPath` to
+     * `outfile` as one self-contained `--app gjs` module. `gjsify exec` calls it
+     * directly because it keys its artifacts by CONTENT (package version, lockfile,
+     * CLI version — `utils/exec-bin.ts`) rather than by mtime.
+     */
+    static bundleFileForGjs(inputPath: string, outfile: string, opts: {
+        verbose?: boolean;
+        define?: Record<string, string>;
+        preserveDefaultExport?: boolean;
+        globals?: string;
+        excludeGlobals?: string[];
+        /** The running CLI's file, or null — see `resolveFromToolchain` above; the CALLER decides. */
+        toolchainAnchor?: string | null;
+        /** `silent` drops warnings, never errors — errors reject the build either way. */
+        logLevel?: 'silent';
+    }): Promise<void>;
+    /** The running CLI's own file — the toolchain anchor `gjsify exec` hands {@link bundleFileForGjs}. */
+    static runningCliFile(): string | null;
     /** Application mode */
     buildApp(app?: App, opts?: {
         watch?: boolean;
         preserveDefaultExport?: boolean;
         toolchainAnchor?: string;
+        onWatchFiles?: RunBundleOptions['onWatchFiles'];
     }): Promise<RolldownOutput[]>;
     /**
      * Drive `rolldown.watch(...)`: rebuild on source change, apply the
@@ -203,5 +224,6 @@ export declare class BuildAction {
         library?: boolean;
         app?: App;
         watch?: boolean;
+        onWatchFiles?: RunBundleOptions['onWatchFiles'];
     }): Promise<RolldownOutput[]>;
 }

package/lib/actions/build.js

@@ -555,6 +555,16 @@ export class BuildAction {
         }
         if (opts.verbose)
             console.debug(`[gjsify] bundling ${inputPath} for GJS → ${outfile}`);
+        await BuildAction.bundleFileForGjs(inputPath, outfile, { ...opts, toolchainAnchor: anchorFile });
+        return outfile;
+    }
+    /**
+     * The uncached half of {@link bundleFileForGjsCached}: bundle `inputPath` to
+     * `outfile` as one self-contained `--app gjs` module. `gjsify exec` calls it
+     * directly because it keys its artifacts by CONTENT (package version, lockfile,
+     * CLI version — `utils/exec-bin.ts`) rather than by mtime.
+     */
+    static async bundleFileForGjs(inputPath, outfile, opts) {
         await mkdir(dirname(outfile), { recursive: true });
         await new BuildAction({
             verbose: opts.verbose,
@@ -564,15 +574,18 @@ export class BuildAction {
                 input: inputPath,
                 output: { file: outfile },
                 ...(opts.define ? { transform: { define: opts.define } } : {}),
+                ...(opts.logLevel ? { logLevel: opts.logLevel } : {}),
             },
         }).buildApp('gjs', {
             preserveDefaultExport: opts.preserveDefaultExport ?? true,
-            // See `opts.resolveFromToolchain`: the CALLER decides whether this input is
-            // toolchain, because this helper alone cannot tell a config file from a
-            // consumer's `node ./src/main.mjs`.
-            ...(anchorFile === null ? {} : { toolchainAnchor: anchorFile }),
+            // The CALLER decides whether this input is toolchain, because this helper
+            // alone cannot tell a config file from a consumer's `node ./src/main.mjs`.
+            ...(opts.toolchainAnchor ? { toolchainAnchor: opts.toolchainAnchor } : {}),
         });
-        return outfile;
+    }
+    /** The running CLI's own file — the toolchain anchor `gjsify exec` hands {@link bundleFileForGjs}. */
+    static runningCliFile() {
+        return runningCliFile();
     }
     /** Application mode */
     async buildApp(app = 'gjs', opts = {}) {
@@ -712,7 +725,13 @@ export class BuildAction {
             // unresolvable import would hard-crash the analysis pass.
             // Mirrors the explicit-globals path (resolveGlobalsInject)
             // and resolveUserPlugins above, which already anchor on cwd.
-            { extraGlobalsList: extras, excludeGlobals, cwd: process.cwd() }, bundleToChunks);
+            {
+                extraGlobalsList: extras,
+                excludeGlobals,
+                cwd: process.cwd(),
+                // The same fallback the resolver gets, or the gate drops what it would rescue.
+                ...(opts.toolchainAnchor !== undefined ? { toolchainDir: dirname(opts.toolchainAnchor) } : {}),
+            }, bundleToChunks);
             pluginOpts.autoGlobalsInject = injectPath;
         }
         else if (app === 'node' && autoMode) {
@@ -803,7 +822,7 @@ export class BuildAction {
             await this.runWatchLoop(finalOpts, app, outfile, outdir, verbose);
             return [];
         }
-        const writeResult = await runBundle(finalOpts);
+        const writeResult = await runBundle(finalOpts, { onWatchFiles: opts.onWatchFiles });
         // GJS truncates module source at a raw U+0000 (it is handed to SpiderMonkey as a
         // NUL-terminated C string), so escape any the minifier emitted before anything else
         // touches the file. See utils/gjs-source-escape.ts.
@@ -920,14 +939,23 @@ export class BuildAction {
         }
         await closed;
     }
-    async start(buildType = { app: 'gjs' }) {
+    async start(buildType = {
+        app: 'gjs',
+    }) {
         if (buildType.library) {
+            // `onWatchFiles` has no consumer here and is deliberately NOT
+            // forwarded: a `--library` build emits a published package, and
+            // nothing asks whether it is stale (`gjsify test` is the only
+            // freshness check, and it never builds a library).
             if (buildType.watch) {
                 throw new Error('gjsify build: --watch is not supported with --library (library mode would emit watcher rebuilds for every produced format; use --app gjs|node|browser instead).');
             }
             return await this.buildLibrary();
         }
-        return await this.buildApp(buildType.app, { watch: buildType.watch });
+        return await this.buildApp(buildType.app, {
+            watch: buildType.watch,
+            onWatchFiles: buildType.onWatchFiles,
+        });
     }
 }
 async function runOneLibraryBuild(args) {

package/lib/bundler-pick.d.ts

@@ -8,6 +8,20 @@ export interface NativePluginContext {
         id: string;
         external: boolean;
     } | null>;
+    /**
+     * rolldown's `this.addWatchFile`, collected by the native facade into
+     * `BundleResult.watchedFiles` — the native half of what npm rolldown reports
+     * as `RolldownBuild.watchFiles`.
+     *
+     * OPTIONAL here on purpose. The engine is resolved through several anchors
+     * and a global-prefix copy can answer first (measured 2026-09-29 on a dev
+     * host whose project-local engine was the current one), so a plugin cannot
+     * assume the method exists: it is this bridge's documented stance that an
+     * unimplemented context method FAILS at hook-call time, and a build must
+     * not fail over bookkeeping. `gjsify-css-as-string` therefore
+     * feature-detects and warns once.
+     */
+    addWatchFile(id: string): void;
     warn(message: string): void;
     error(message: string): never;
 }
@@ -72,11 +86,33 @@ export declare function bundleToChunks(input: {
  * and is responsible for invoking `watcher.close()` on shutdown.
  */
 export declare function runWatch(finalOpts: BundlerOptions): Promise<RolldownWatcher>;
+/** What one build reported about the files its output depends on. */
+export interface BuildWatchList {
+    /**
+     * The engine's watch list: npm rolldown's `RolldownBuild.watchFiles` (its
+     * module set plus every `this.addWatchFile`), the native facade's
+     * `watchedFiles` (the declared half — the native engine reports no modules,
+     * hence the two halves rather than either). Read BEFORE `close()`, which is
+     * where the npm getter is still alive.
+     */
+    files: readonly string[];
+    /**
+     * `false` when the engine CANNOT report one at all (a `@gjsify/rolldown-native`
+     * older than `addWatchFile`). A caller that judges a build's inputs on this
+     * list has to refuse to trust it — the file a plugin read itself is then
+     * invisible, and a stale bundle would read as current.
+     */
+    reportedByEngine: boolean;
+}
+/** Where a build's own input list goes. Absent → the caller does not want it. */
+export interface RunBundleOptions {
+    onWatchFiles?: (watch: BuildWatchList) => void;
+}
 /**
  * Run a bundle with the picked engine. Drop-in replacement for the
  * `rolldown(opts).write(opts.output)` flow used directly in build.ts.
  */
-export declare function runBundle(finalOpts: BundlerOptions): Promise<RolldownOutput>;
+export declare function runBundle(finalOpts: BundlerOptions, options?: RunBundleOptions): Promise<RolldownOutput>;
 export declare function shouldUseNative(): Promise<boolean>;
 /**
  * Walk parent directories from `startDir` (and optionally a second anchor

package/lib/bundler-pick.js

@@ -10,7 +10,7 @@
 // synchronous require of a builtin, so the load dies before any `.node` is opened.
 // The distinction is not pedantry — it says an N-API host alone would not be
 // enough; the wrapper has to be bypassed too, which is exactly what
-// `napiNodeAddonPlugin` does for napi-rs packages. See `status/open-todos.md`
+// `napiNodeAddonPlugin` does for napi-rs packages. See `status/open-todos/README.md`
 // § "Can `@gjsify/napi` retire the hand-written `-native` bridges?".
 //
 // `GJSIFY_BUNDLER=native|npm` overrides that: `native` throws when the prebuild is
@@ -30,7 +30,7 @@
 import { promises as fs, existsSync } from 'node:fs';
 import * as path from 'node:path';
 import { createRequire } from 'node:module';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { resolveNpmPackage } from './utils/resolve-npm-package.js';
 // Static, not dynamic: `diagnoseNativeEngine()` is synchronous and called inside a
 // `throw` expression. Safe because check-system-deps imports only `node:` builtins,
@@ -80,7 +80,8 @@ async function loadNpmRolldown() {
 function diagnoseNativeEngine() {
     let pkgDir = null;
     try {
-        const bundleDir = path.dirname(new URL(import.meta.url).pathname);
+        // Not `new URL(...).pathname`: on win32 that is `/C:/...`, percent-encoded, no path.
+        const bundleDir = path.dirname(fileURLToPath(import.meta.url));
         pkgDir = findRolldownNativeDir(process.cwd(), bundleDir);
     }
     catch {
@@ -131,23 +132,39 @@ function diagnoseNativeEngine() {
     // reads the same tables `gjsify system-check` does, so the answer cannot drift
     // from the declaration.
     const missing = missingSystemDepsFor('@gjsify/rolldown-native');
-    if (missing.length > 0) {
-        const names = missing.map((d) => d.name).join(', ');
+    const names = missing.map((d) => d.name).join(', ');
+    const cmd = missing.length > 0 ? buildInstallCommand(detectPackageManager(), missing) : null;
+    const installHint = missing.length === 0
+        ? undefined
+        : cmd
+            ? `Install it:\n  ${cmd}`
+            : `Install ${names} with your system package manager (this host's manager was not recognised, so no command is suggested rather than a wrong one).`;
+    // (0) The measurement could not run at all. First, because everything below
+    // reasons from a measurement: with no reading in hand, (2) would assert the
+    // prebuild IS on girepository's search path — a positive claim this PR
+    // exists to make measurable, so its absence is stated rather than papered over.
+    if (_utilsCoreError !== null) {
+        parts.push(`\nNOT MEASURED — the native-library probe could not be loaded, so nothing below is a reading of this host:\n  ${_utilsCoreError instanceof Error ? _utilsCoreError.message : String(_utilsCoreError)}`);
+    }
+    // (1) The loader's own answer, when `tryLoadNative()` measured one: the file
+    // that would not open and the dependency it named. It outranks (2), which only
+    // knows what pkg-config can see — the dependency may be one no table declares.
+    if (_nativeLibraryFailure && _utilsCore) {
+        parts.push(`\nMEASURED CAUSE — ${new _utilsCore.NativeLibraryLoadError(_nativeLibraryFailure, installHint).message}`);
+    }
+    else if (missing.length > 0) {
         parts.push(`\nMEASURED CAUSE — a system library the engine's prebuild loads is MISSING: ${names}.\n` +
             'The prebuild is present but its typelib cannot open its backing library, which GJS reports as ' +
             '`Unsupported type void, deriving from fundamental void` — a message that names nothing. ' +
             'This is a system package, not an npm one.');
-        const cmd = buildInstallCommand(detectPackageManager(), missing);
-        if (cmd)
-            parts.push(`Install it:\n  ${cmd}`);
-        else
-            parts.push(`Install ${names} with your system package manager (this host's manager was not recognised, so no command is suggested rather than a wrong one).`);
+        if (installHint)
+            parts.push(installHint);
     }
     // (2) No prebuild for this architecture — last because it is least actionable.
     // Read off the set `activateNativePrebuilds()` ACTUALLY put on the search paths:
     // a memoized cached-array read that cannot throw, and it names the per-target
     // sibling package really holding the artifact.
-    if (missing.length === 0) {
+    if (missing.length === 0 && !_nativeLibraryFailure) {
         const engine = activateNativePrebuilds().find((p) => p.name.startsWith('@gjsify/rolldown-native'));
         parts.push(engine
             ? `\nEvery declared system library resolves and ${engine.name}'s prebuild (${engine.prebuildsDir}) IS on ` +
@@ -255,24 +272,64 @@ export async function runWatch(finalOpts) {
     const output = finalOpts.output ?? {};
     return mod.watch({ ...finalOpts, output });
 }
+let _warnedNoWatchList = false;
+function warnNoNativeWatchList() {
+    if (_warnedNoWatchList)
+        return;
+    _warnedNoWatchList = true;
+    console.warn('[gjsify] this `@gjsify/rolldown-native` build reports no watch list: it predates ' +
+        '`addWatchFile`, so a file a plugin read itself (a stylesheet\u2019s `@import` chain, an ' +
+        'inlined `readFileSync`) cannot be declared as a build input. `gjsify test` will rebuild ' +
+        'the affected bundles on every run rather than trust a set it cannot see. Upgrade the ' +
+        'engine (it ships in the same release train as the CLI).');
+}
 /**
  * Run a bundle with the picked engine. Drop-in replacement for the
  * `rolldown(opts).write(opts.output)` flow used directly in build.ts.
  */
-export async function runBundle(finalOpts) {
+export async function runBundle(finalOpts, options = {}) {
     if (await shouldUseNative()) {
-        return await runNativeBundle(finalOpts);
+        return await runNativeBundle(finalOpts, options);
     }
     const rolldown = await loadNpmRolldown();
     const build = await rolldown(finalOpts);
     try {
-        return await build.write(finalOpts.output ?? {});
+        const output = await build.write(finalOpts.output ?? {});
+        if (options.onWatchFiles) {
+            options.onWatchFiles({ files: await build.watchFiles, reportedByEngine: true });
+        }
+        return output;
     }
     finally {
         await build.close();
     }
 }
 let _nativeProbe = null;
+/** Why the engine's library would not open, when `tryLoadNative()` measured it. */
+let _nativeLibraryFailure = null;
+let _utilsCore = null;
+/**
+ * Why the probe itself could not run, when that is the reason. Kept apart from
+ * "there is no engine" on purpose: `tryLoadNative()`'s bare `catch` cannot tell
+ * the two apart, and `diagnoseNativeEngine()` then answers a question nobody
+ * asked — it reports which system libraries resolve, and says the prebuild IS on
+ * girepository's search path, which is a positive claim about a measurement that
+ * never happened. This PR exists to make such a claim measurable, so a missing
+ * measurement is reported as one.
+ */
+let _utilsCoreError = null;
+async function utilsCore() {
+    if (_utilsCore === null) {
+        // `./native-library`, not `./core`: `core` re-exports `main-loop`, which
+        // holds a module-level singleton. The GJS bundle inlines utils already,
+        // so loading `core` off disk would give the process a SECOND copy of that
+        // singleton — inert today because only pure probe functions are read
+        // through this edge, and a trap the first time that stops being true.
+        const href = pathToFileURL(createRequire(import.meta.url).resolve('@gjsify/utils/native-library')).href;
+        _utilsCore = (await import(/* @vite-ignore */ href));
+    }
+    return _utilsCore;
+}
 export async function shouldUseNative() {
     const env = globalThis.process?.env ?? {};
     const choice = env.GJSIFY_BUNDLER;
@@ -282,7 +339,8 @@ export async function shouldUseNative() {
     if (choice === 'native') {
         const native = await tryLoadNative();
         if (!native) {
-            throw new Error('GJSIFY_BUNDLER=native but @gjsify/rolldown-native is not loadable (no prebuild for this architecture, or not running under GJS).');
+            throw new Error('GJSIFY_BUNDLER=native but @gjsify/rolldown-native is not loadable (no prebuild for this architecture, or not running under GJS).' +
+                (isGjs() ? `\n${diagnoseNativeEngine()}` : ''));
         }
         return true;
     }
@@ -375,7 +433,7 @@ async function tryLoadNative() {
                 // limitations and `findWorkspaceRoot`'s dependency on
                 // `discoverWorkspaces`, both of which can fail to map a
                 // sub-package dir up to the hoisted workspace root.
-                const bundleDir = path.dirname(new URL(import.meta.url).pathname);
+                const bundleDir = path.dirname(fileURLToPath(import.meta.url));
                 const resolvedFromNpm = resolveNpmPackage(specifier, { bundleUrl: import.meta.url });
                 const resolvedFromFs = resolvedFromNpm
                     ? null
@@ -399,6 +457,25 @@ async function tryLoadNative() {
             const mod = (await import(/* @vite-ignore */ target));
             if (!mod.hasNativeRolldown())
                 return null;
+            // The typelib resolved, which says nothing about its library: that
+            // opens at the first class access, and a missing system library
+            // (Homebrew json-glib on a Mac) would pass here and fail inside
+            // `new BundlerSession()` as the nameless "Unsupported type void" —
+            // past `diagnoseNativeEngine()`, which then never runs.
+            // Separated from the engine's own failure so that "the engine is
+            // absent" and "the measurement could not run" stay distinguishable
+            // at the one place that reports them.
+            let surface;
+            try {
+                surface = await utilsCore();
+            }
+            catch (err) {
+                _utilsCoreError = err;
+                return null;
+            }
+            _nativeLibraryFailure = surface.probeNativeLibrary('GjsifyRolldown');
+            if (_nativeLibraryFailure)
+                return null;
             return mod;
         }
         catch {
@@ -407,7 +484,7 @@ async function tryLoadNative() {
     })();
     return _nativeProbe;
 }
-async function runNativeBundle(finalOpts) {
+async function runNativeBundle(finalOpts, options = {}) {
     const native = await tryLoadNative();
     if (!native) {
         throw new Error('@gjsify/rolldown-native not loadable');
@@ -440,6 +517,20 @@ async function runNativeBundle(finalOpts) {
     }
     const result = await native.bundleWithPlugins(bundlerOpts, nativePlugins);
     reportNativeWarnings(result, finalOpts);
+    if (options.onWatchFiles) {
+        if (result.watchedFiles === undefined) {
+            // NOT a silent drop. A version-skewed engine has no `addWatchFile` on
+            // its plugin context, so nothing a plugin declares can reach the
+            // build's input set — and a caller judging freshness on that set
+            // would call a stale bundle current. Say so here, where the engine is
+            // in hand, and report `reportedByEngine: false` so the caller refuses.
+            warnNoNativeWatchList();
+            options.onWatchFiles({ files: [], reportedByEngine: false });
+        }
+        else {
+            options.onWatchFiles({ files: result.watchedFiles, reportedByEngine: true });
+        }
+    }
     // The native facade returns the BundleOutput shape but doesn't
     // write files — replicate `.write()` here so callers see the same
     // on-disk layout whether they used npm rolldown or native.

package/lib/cli-app.js

@@ -10,7 +10,7 @@
 // build`, and `gjsify run build:types → gjsify tsc → gjs tsc.gjs.mjs`), so on
 // CI's few cores the multiplier oversubscribes and the build thrashes. Letting
 // `gjsify run` dispatch the inner `gjsify <cmd>` in-process collapses two gjs
-// into one. See status/open-todos.md.
+// into one. See status/open-todos/README.md.
 //
 // This module MUST NOT execute anything at load time (no top-level
 // `parseAsync`) — `run.ts` imports it, and a top-level run would re-dispatch
@@ -18,7 +18,7 @@
 import yargs from 'yargs';
 import { classifyCliFailure } from './cli-fail.js';
 import { cliVersion } from './utils/publish-headers.js';
-import { buildCommand as build, clearCommand as clear, copyCommand as copy, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, shipCommand as ship, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, pruneCommand as prune, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, devCommand as dev, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
+import { buildCommand as build, clearCommand as clear, copyCommand as copy, envCommand as env, execCommand as exec, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, shipCommand as ship, dlxCommand as dlx, installCommand as install, linkCommand as link, unlinkCommand as unlink, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, pruneCommand as prune, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, devCommand as dev, debugCommand as debug, browseCommand as browse, webextCommand as webext, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 import { isBun, isDeno, isNode, gjsSystemVersion } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
@@ -93,9 +93,13 @@ export async function runCli(argv) {
         .wrap(cli.terminalWidth())
         .command(create.command, create.description, create.builder, create.handler)
         .command(install.command, install.description, install.builder, install.handler)
+        .command(link.command, link.description, link.builder, link.handler)
+        .command(unlink.command, unlink.description, unlink.builder, unlink.handler)
         .command(build.command, build.description, build.builder, build.handler)
         .command(clear.command, clear.description, clear.builder, clear.handler)
         .command(copy.command, copy.description, copy.builder, copy.handler)
+        .command(env.command, env.description, env.builder, env.handler)
+        .command(exec.command, exec.description, exec.builder, exec.handler)
         .command(test.command, test.description, test.builder, test.handler)
         .command(run.command, run.description, run.builder, run.handler)
         .command(dlx.command, dlx.description, dlx.builder, dlx.handler)
@@ -132,6 +136,7 @@ export async function runCli(argv) {
         .command(dev.command, dev.description, dev.builder, dev.handler)
         .command(debug.command, debug.description, debug.builder, debug.handler)
         .command(browse.command, browse.description, browse.builder, browse.handler)
+        .command(webext.command, webext.description, webext.builder, webext.handler)
         .demandCommand(1)
         .epilogue(`Running on ${runtimeLabel()}`)
         .help()

package/lib/commands/affected-classify.d.ts

@@ -1,4 +1,5 @@
 import { type Workspace } from '@gjsify/workspace';
+import type { ScriptReferrers } from './affected-script-refs.js';
 export interface ClassifyResult {
     /** Cannot decide precisely — caller should run full suite. */
     global: boolean;
@@ -13,4 +14,9 @@ export interface ClassifyResult {
     /** Diff was empty AND no triggers fired → CI can skip the whole job. */
     skipAll: boolean;
 }
-export declare function classifyAndExpand(workspaces: readonly Workspace[], changedFiles: readonly string[]): ClassifyResult;
+/**
+ * @param readersOf who reads a root `scripts/*` file. Omitted, a changed root script stays
+ *   `unmatched` and forces the full run — the behaviour before the lookup existed, and what
+ *   the command falls back to when it cannot list the tree.
+ */
+export declare function classifyAndExpand(workspaces: readonly Workspace[], changedFiles: readonly string[], readersOf?: ScriptReferrers): ClassifyResult;

package/lib/commands/affected-classify.js

@@ -49,8 +49,10 @@ const GLOBAL_TRIGGERS = [
  */
 const OTHER_WORKFLOW_INPUTS = [
     // Each sibling workflow's own definition. `main.yml` is deliberately absent: it
-    // is a GLOBAL_TRIGGER instead.
-    /^\.github\/workflows\/(deploy-docs|commitlint|release|release-cut|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image|cancel-pr-runs)\.yml$/,
+    // is a GLOBAL_TRIGGER instead. The three OS-suite workflows run unfiltered on every
+    // PR, so an edit to one is measured by that run; `webview2-probe.yml` is absent on
+    // purpose, being dispatch-only — nothing would measure an edit to it on the PR.
+    /^\.github\/workflows\/(deploy-docs|commitlint|release|release-cut|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image|cancel-pr-runs|macos-suites|windows-suites|gtk-os-suites)\.yml$/,
     // `prebuilds.yml`'s toolchain (#838): the QEMU-emulated build script and the
     // classifier deciding which native packages a prebuild run rebuilds. It is in
     // both of that workflow's `paths:` filters; `main.yml` builds no prebuild and
@@ -168,7 +170,51 @@ const SCRIPT_COUPLINGS = [
         why: 'tests/e2e/react-native-devtools is the only external observer of AppRegistry.runApplication',
     },
 ];
-export function classifyAndExpand(workspaces, changedFiles) {
+/** A root script whose readers can stand in for it (see `affected-script-refs.ts`). */
+const ROOT_SCRIPT = /^scripts\/[^/]+$/;
+function isResolvableScript(f) {
+    return (ROOT_SCRIPT.test(f) &&
+        !GLOBAL_TRIGGERS.some((re) => re.test(f)) &&
+        !SCRIPT_COUPLINGS.some((c) => c.match.test(f)));
+}
+/**
+ * Replace each changed root script by the files that read it, recursively through scripts
+ * that read scripts. Readers go back through IGNORE here and through GLOBAL / workspace
+ * mapping in the caller, so a reader this classifier does not model still forces the full
+ * run, and a script a GLOBAL_TRIGGER reads (`audit-runtimes.mjs`) stays in and fires it.
+ */
+function resolveRootScripts(files, readersOf) {
+    const out = new Set();
+    const queue = [];
+    for (const f of files) {
+        if (isResolvableScript(f))
+            queue.push(f);
+        else
+            out.add(f);
+    }
+    const seen = new Set();
+    while (queue.length > 0) {
+        const s = queue.shift();
+        if (seen.has(s))
+            continue;
+        seen.add(s);
+        for (const r of readersOf(s)) {
+            if (IGNORE.some((re) => re.test(r)))
+                continue;
+            if (isResolvableScript(r))
+                queue.push(r);
+            else
+                out.add(r);
+        }
+    }
+    return { files: [...out], scripts: seen.size };
+}
+/**
+ * @param readersOf who reads a root `scripts/*` file. Omitted, a changed root script stays
+ *   `unmatched` and forces the full run — the behaviour before the lookup existed, and what
+ *   the command falls back to when it cannot list the tree.
+ */
+export function classifyAndExpand(workspaces, changedFiles, readersOf) {
     const files = changedFiles.map((f) => f.replace(/\\/g, '/')).filter((f) => f.length > 0);
     if (files.length === 0) {
         return {
@@ -182,16 +228,26 @@ export function classifyAndExpand(workspaces, changedFiles) {
     }
     // Ignored files go FIRST, before the global-trigger check: ignore wins over
     // global, so `packages/infra/cli/README.md` must not force a full run.
-    const remaining = [];
+    let remaining = [];
     for (const f of files) {
         if (IGNORE.some((re) => re.test(f)))
             continue;
         remaining.push(f);
     }
+    // Every verdict below says when it was reached through a script's readers, so a
+    // surprising selection can be traced back to the lookup rather than the diff.
+    let note = '';
+    if (readersOf) {
+        const resolved = resolveRootScripts(remaining, readersOf);
+        if (resolved.scripts > 0) {
+            remaining = resolved.files;
+            note = `; ${resolved.scripts} root script(s) resolved to their readers`;
+        }
+    }
     if (remaining.length === 0) {
         return {
             global: false,
-            reason: 'ignored-only',
+            reason: 'ignored-only' + note,
             workspaces: [],
             runE2E: false,
             runIntegration: false,
@@ -204,7 +260,7 @@ export function classifyAndExpand(workspaces, changedFiles) {
             if (re.test(f)) {
                 return {
                     global: true,
-                    reason: `global-trigger ${re.source} matched ${f}`,
+                    reason: `global-trigger ${re.source} matched ${f}${note}`,
                     workspaces: workspaces.map((w) => w.name),
                     runE2E: true,
                     runIntegration: true,
@@ -254,7 +310,7 @@ export function classifyAndExpand(workspaces, changedFiles) {
     if (stillUnmatched.length > 0) {
         return {
             global: true,
-            reason: `unmatched files (${stillUnmatched.length}): ${stillUnmatched.slice(0, 3).join(', ')}${stillUnmatched.length > 3 ? '…' : ''}`,
+            reason: `unmatched files (${stillUnmatched.length}): ${stillUnmatched.slice(0, 3).join(', ')}${stillUnmatched.length > 3 ? '…' : ''}${note}`,
             workspaces: workspaces.map((w) => w.name),
             runE2E: true,
             runIntegration: true,
@@ -274,7 +330,7 @@ export function classifyAndExpand(workspaces, changedFiles) {
         const touchedIntegration = remaining.some((f) => f.startsWith('tests/integration/'));
         return {
             global: false,
-            reason: `test-only (${remaining.length} file(s) in ${only})`,
+            reason: `test-only (${remaining.length} file(s) in ${only})${note}`,
             workspaces: [only],
             // `|| couplingRunE2E`: this shortcut skips CLOSURE EXPANSION, and a
             // declared tier is not part of the closure. Dropping it here made a
@@ -323,7 +379,8 @@ export function classifyAndExpand(workspaces, changedFiles) {
     return {
         global: false,
         reason: `closure (${closure.size} ws from ${matched.size} seed(s))` +
-            (couplingSeeds.size > 0 ? `, ${couplingSeeds.size} via script-coupling` : ''),
+            (couplingSeeds.size > 0 ? `, ${couplingSeeds.size} via script-coupling` : '') +
+            note,
         workspaces: [...closure].sort(),
         runE2E,
         runIntegration,

package/lib/commands/affected-script-refs.d.ts

@@ -0,0 +1,20 @@
+/** Every file that names `scriptPath`, as repo-relative paths. */
+export type ScriptReferrers = (scriptPath: string) => readonly string[];
+/**
+ * The file-name pattern for a script: `adwaita-elements.mjs` is also read as
+ * `adwaita-elements.d.mts` (a TS import of the `.mjs` resolves to its declaration) and a
+ * `.d.mts` change is read through its `.mjs`. The leading boundary excludes `-` so
+ * `value-types.mjs` does not match `generate-value-types.mjs`.
+ */
+export declare function scriptNamePattern(scriptPath: string): RegExp;
+/**
+ * Build the reader lookup over `texts` (repo-relative path → raw content). Pure: the command
+ * feeds it `git ls-files`, the spec feeds it a fixture map.
+ */
+export declare function buildScriptReferrers(texts: ReadonlyMap<string, string>): ScriptReferrers;
+/**
+ * Every tracked text file under `rootDir`, for {@link buildScriptReferrers}. Throws when git
+ * cannot list the tree — the caller then classifies without the lookup, which is the old,
+ * conservative behaviour (a root script lands in `unmatched`).
+ */
+export declare function readTrackedTexts(rootDir: string): Map<string, string>;