@specific.dev/spectest 0.86.2 → 0.88.0

package/dist/browser.d.ts

@@ -1,3 +1,4 @@
+import type { DesktopChrome } from "./desktop.js";
 import type { Wrapped } from "./inspect.js";
 import type { UrlPattern } from "./url-match.js";
 export type { UrlPattern } from "./url-match.js";
@@ -68,6 +69,7 @@ export interface BrowserSessionRecorder {
      * from the persisted events alone, with no replay bundle).
      */
     readonly sessionName?: string;
+    readonly frame?: "browser" | "mobile" | "desktop";
     /** Called for each drained chunk of rrweb events. */
     recordStep(step: BrowserSessionStep): void;
     /** Optional: called whenever `Browser.goto(url)` is invoked. */
@@ -342,6 +344,11 @@ export declare function acquirePersistentBrowser(name?: string, opts?: BrowserOp
  * session navigates to the app; an attach continues on the live page.
  */
 export declare function acquirePersistentMobileBackend(url: string, name: string, recorder: BrowserSessionRecorder | null, initScript?: string): Promise<PersistentBrowser>;
+/** Attach the shared locator/recorder backend to an actual Electron window.
+ * Never navigate, reload, emulate a viewport, or replace its renderer. */
+export declare function acquirePersistentDesktop(endpoint: string, windowIndex: number, recorder: BrowserSessionRecorder | null): Promise<PersistentBrowser & {
+    desktopChrome?: DesktopChrome;
+}>;
 export interface RecordableFields {
     url: string;
     selector: string;

package/dist/browser.js

@@ -1,8 +1,8 @@
 // Headless browser handle for tests. Thin wrapper around playwright-core
 // driving the guest's system Chromium (pipe transport — `chromium.launch`
-// with an explicit `executablePath`; `connectOverCDP` is off-limits, its
-// bundled `ws` client hangs under Bun). The wrapper keeps the public
-// surface stable (we swapped from Bun.WebView to Playwright without
+// with an explicit `executablePath`). Electron attaches to the app-owned
+// Chromium over CDP instead; its client also lives inside the VM. The wrapper
+// keeps the public surface stable (we swapped from Bun.WebView to Playwright without
 // changing tests) and routes every call through the recorder so browser
 // actions show up in a test's event log alongside exec/fetch/assertion
 // events. Playwright's client state (browser/context/page objects, the
@@ -32,6 +32,8 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { generateId } from "./ids.js";
+import { rawFetch } from "./harness/raw-fetch.js";
+import { DESKTOP_INPUT_SYNC_SCRIPT } from "./desktop-recorder.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
 import { capturePageStructure } from "./page-snapshot.js";
@@ -760,7 +762,7 @@ const PAGE_INIT_SCRIPT = RRWEB_BUNDLE
 // snapshot keeps steady-state steps (clicks/types on an unchanged page,
 // or navigations where `load` already fired) from bloating the stream
 // with redundant snapshots.
-function drainExpr(forceFullIfMissing) {
+function drainExpr(forceFullIfMissing, timestamp = Date.now()) {
     return `(function () {
   try {
     var rec = window.__spectestRec;
@@ -775,6 +777,9 @@ function drainExpr(forceFullIfMissing) {
       if (!hasFull) rec.takeFullSnapshot();
     }
   } catch (e) { /* recording inactive or DOM detached — drain what's there. */ }
+  if (typeof window.__spectestSyncInputs === "function") {
+    window.__spectestSyncInputs(${timestamp});
+  }
   var buf = window.__spectestRrwebEvents;
   if (!buf || !buf.length) return [];
   window.__spectestRrwebEvents = [];
@@ -1070,6 +1075,91 @@ export async function acquirePersistentMobileBackend(url, name, recorder, initSc
     }
     return { browser: backend, attached: existing !== undefined, detach };
 }
+/** Live CDP clients and window identities ride the harness snapshot. */
+const ELECTRON_APPS = new Map();
+/** Attach the shared locator/recorder backend to an actual Electron window.
+ * Never navigate, reload, emulate a viewport, or replace its renderer. */
+export async function acquirePersistentDesktop(endpoint, windowIndex, recorder) {
+    if (!Number.isInteger(windowIndex) || windowIndex < 0) {
+        throw new Error("ctx.desktop(): window must be a non-negative integer (creation order)");
+    }
+    let pending = ELECTRON_APPS.get(endpoint);
+    if (!pending) {
+        pending = (async () => {
+            const response = await rawFetch(new URL("/json/version", endpoint), {
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!response.ok)
+                throw new Error(`Electron debugger discovery failed: HTTP ${response.status}`);
+            const info = await response.json();
+            const websocket = new URL(info.webSocketDebuggerUrl);
+            websocket.host = new URL(endpoint).host;
+            const browser = await chromium.connectOverCDP(websocket.toString(), { timeout: 15_000 });
+            const context = browser.contexts()[0];
+            if (!context) {
+                await browser.close();
+                throw new Error("Electron has no renderer context");
+            }
+            const windows = context.pages().filter(page => !page.url().startsWith("devtools:"));
+            context.on("page", page => { if (!page.url().startsWith("devtools:"))
+                windows.push(page); });
+            browser.on("disconnected", () => { ELECTRON_APPS.delete(endpoint); });
+            return { browser, context, windows, holders: new Map() };
+        })();
+        ELECTRON_APPS.set(endpoint, pending);
+        pending.catch(() => { if (ELECTRON_APPS.get(endpoint) === pending)
+            ELECTRON_APPS.delete(endpoint); });
+    }
+    const app = await pending;
+    const deadline = Date.now() + 15_000;
+    while (!app.windows[windowIndex]) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new Error(`Electron window ${windowIndex} did not open`);
+        await app.context.waitForEvent("page", { timeout: remaining });
+    }
+    const page = app.windows[windowIndex];
+    if (page.isClosed())
+        throw new Error(`Electron window ${windowIndex} is closed; window indices retain creation order`);
+    await page.waitForLoadState("domcontentloaded");
+    // The main-process observer publishes only window presentation options.
+    // A popup created internally by Chromium might not pass through BrowserWindow.
+    await page.waitForFunction(() => Boolean(window.__spectestElectronChrome), null, { timeout: 3000 }).catch(() => { });
+    const desktopChrome = await page.evaluate(() => {
+        const chrome = window.__spectestElectronChrome;
+        if (!chrome)
+            return undefined;
+        const overlay = navigator.windowControlsOverlay;
+        return { ...chrome, ...(overlay?.visible ? { titlebarArea: overlay.getTitlebarAreaRect().toJSON() } : {}) };
+    });
+    let holder = app.holders.get(page);
+    const attached = holder !== undefined;
+    if (!holder) {
+        const cdp = await app.context.newCDPSession(page);
+        await cdp.send("Page.enable");
+        if (!PAGE_INIT_SCRIPT)
+            throw new Error("Electron replay recorder bundle is missing");
+        const init = `${PAGE_INIT_SCRIPT};\n${DESKTOP_INPUT_SYNC_SCRIPT}`;
+        await cdp.send("Page.addScriptToEvaluateOnNewDocument", { source: init });
+        // The app owns navigation and may already have loaded. Start on its live
+        // DOM, without losing drafts or replaying any application startup effects.
+        await page.evaluate(init);
+        const size = await page.evaluate(() => ({ width: innerWidth, height: innerHeight }));
+        holder = {
+            context: app.context, page, cdp, lastTitle: await page.title(),
+            recordingInstalled: true, device: null, width: size.width, height: size.height,
+            safeAreaInsets: null, initScripts: [],
+        };
+        app.holders.set(page, holder);
+        page.on("close", () => { app.holders.delete(page); });
+    }
+    await attachReset(holder);
+    const { backend, detach } = buildBackend(holder, recorder, {
+        persistent: false, ownsContext: false,
+        onDestroy: () => { app.holders.delete(page); },
+    });
+    return { browser: backend, attached, detach, desktopChrome };
+}
 /** True when a navigation failed on Chromium name resolution. */
 function isNameNotResolved(err) {
     return String(err?.message ?? err).includes("ERR_NAME_NOT_RESOLVED");
@@ -1183,15 +1273,16 @@ function buildBackend(holder, recorder, buildOpts) {
         return {
             sessionId: recorder.sessionId,
             sessionTimestamp: endT,
+            ...(recorder.frame ? { frame: recorder.frame } : {}),
             ...(recorder.sessionName ? { sessionName: recorder.sessionName } : {}),
         };
     }
-    async function drain(action) {
+    async function drain(action, timestamp = Date.now()) {
         if (!holder.recordingInstalled || !recorder || recordingEnded)
             return;
         try {
             const urlChanged = holder.page.url() !== lastDrainUrl;
-            const events = (await holder.page.evaluate(drainExpr(urlChanged)));
+            const events = (await holder.page.evaluate(drainExpr(urlChanged, timestamp)));
             lastDrainUrl = holder.page.url();
             if (Array.isArray(events) && events.length > 0) {
                 recorder.recordStep({
@@ -1232,7 +1323,7 @@ function buildBackend(holder, recorder, buildOpts) {
                 ...sessionFields(endT),
                 durationMs: endT - t,
             }, resv);
-            await drain(action);
+            await drain(action, endT);
             // Fold this page's V8 counters into the per-service totals now — a
             // navigation to another origin replaces the renderer and its
             // counters, so harvesting per op is what keeps them.
@@ -1269,7 +1360,7 @@ function buildBackend(holder, recorder, buildOpts) {
             }, resv);
             // Still try to drain — the failure itself may have produced
             // useful rrweb events (mutations from a half-loaded page, etc.).
-            await drain(action);
+            await drain(action, endT);
             throw err;
         }
     }
@@ -1525,7 +1616,8 @@ function buildBackend(holder, recorder, buildOpts) {
             // The context, not the page, holds the cookies and storage — closing
             // only the page would leave the next session signed in as this one.
             try {
-                await holder.context.close();
+                if (buildOpts.ownsContext !== false)
+                    await holder.context.close();
             }
             catch {
                 /* context already gone (browser died) */
@@ -1606,7 +1698,7 @@ function buildBackend(holder, recorder, buildOpts) {
             }, reserveBackdated(waitedMs));
             // Drain the rrweb the page buffered while the matcher waited into this
             // step's chunk, so `settledTarget` has bounds to seek into.
-            await drain(action);
+            await drain(action, endT);
             return seq;
         },
         pageOp(action, fields, fn, opts) {

package/dist/components/aws.d.ts

@@ -95,6 +95,14 @@ export interface LambdaOptions {
  */
 export declare function aws(opts?: AwsOptions): {
     setup?: (({ name, projectRoot }: ServiceSetupContext) => Promise<void>) | undefined;
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+    inputs?: string[] | undefined;
     image: {
         type: "registry";
         reference: string;
@@ -109,11 +117,4 @@ export declare function aws(opts?: AwsOptions): {
         source: string;
         target: string;
     }[];
-    ports: number[];
-    readyCheck: {
-        type: "http";
-        port: number;
-        path: string;
-        timeoutSecs: number;
-    };
 };

package/dist/components/aws.js

@@ -191,6 +191,12 @@ export function aws(opts = {}) {
             LAMBDA_DOCKER_NETWORK: SPECTEST_NETWORK,
         },
         volumes: [{ source: DOCKER_SOCKET, target: DOCKER_SOCKET }],
+        // Each lambda's code is packaged from the project at setup: no build
+        // context or volume carries it, so it is declared as an input and a
+        // change to it is never taken as one that can affect no test.
+        ...(Object.keys(lambdas).length > 0
+            ? { inputs: Object.values(lambdas).map((l) => l.source).filter((s) => typeof s === "string" && s.trim() !== "") }
+            : {}),
         ports: [AWS_PORT],
         readyCheck: {
             type: "http",

package/dist/components/electron-chrome.d.ts

@@ -0,0 +1 @@
+export declare const ELECTRON_CHROME_HOOK: string;

package/dist/components/electron-chrome.js

@@ -0,0 +1,76 @@
+// Runs before the application's main entry, like Playwright's Electron loader.
+// Observe constructor options; do not replace the app entry, preload, IPC, or OS.
+export const ELECTRON_CHROME_HOOK = String.raw `
+const electron = require('electron');
+const NativeBrowserWindow = electron.BrowserWindow;
+const WrappedBrowserWindow = new Proxy(NativeBrowserWindow, {
+  construct(Target, args, NewTarget) {
+    const win = Reflect.construct(Target, args, NewTarget);
+    const options = args[0] || {};
+    const chrome = {
+      titleBarStyle: options.titleBarStyle || 'default',
+      frame: options.frame !== false,
+      trafficLightPosition: options.trafficLightPosition || null,
+      titleBarOverlay: options.titleBarOverlay || false,
+      roundedCorners: options.roundedCorners !== false,
+      buttonVisibility: null,
+    };
+    const publish = () => {
+      if (win.isDestroyed() || win.webContents.isDestroyed()) return;
+      void win.webContents.executeJavaScript(
+        'window.__spectestElectronChrome = ' + JSON.stringify(chrome)
+      ).catch(() => {}); // A document can be replaced while this is in flight.
+    };
+    win.webContents.on('dom-ready', publish);
+    // Capture supported native setters too, without adding macOS APIs on Linux.
+    for (const [method, key] of [
+      ['setWindowButtonVisibility', 'buttonVisibility'],
+      ['setWindowButtonPosition', 'trafficLightPosition'],
+      ['setTitleBarOverlay', 'titleBarOverlay'],
+    ]) {
+      if (typeof win[method] !== 'function') continue;
+      const original = win[method];
+      win[method] = function(value) {
+        const result = original.call(this, value);
+        chrome[key] = value;
+        publish();
+        return result;
+      };
+    }
+    return win;
+  },
+});
+// Electron's own exports are non-configurable. Wrap module resolution instead
+// of modifying them; all other exports retain their original descriptors.
+const Module = require('node:module');
+const originalLoad = Module._load;
+const facades = new Map();
+Module._load = function(request, ...args) {
+  const exports = originalLoad.call(this, request, ...args);
+  if (request !== 'electron' && request !== 'electron/main') return exports;
+  if (!facades.has(exports)) {
+    const descriptors = Object.getOwnPropertyDescriptors(exports);
+    descriptors.BrowserWindow = { value: WrappedBrowserWindow, enumerable: true };
+    facades.set(exports, Object.defineProperties({}, descriptors));
+  }
+  return facades.get(exports);
+};
+// Electron's native ESM translator bypasses Module._load. Route ESM imports
+// through the same facade using Node's synchronous loader hooks when available.
+if (typeof Module.registerHooks === 'function') {
+  const source = 'import { createRequire } from "node:module";\n' +
+    'const electron = createRequire(' + JSON.stringify(__filename) + ')("electron");\n' +
+    'export default electron;\n' + Object.keys(electron)
+      .filter(key => /^[A-Za-z_$][\w$]*$/.test(key))
+      .map(key => 'export const ' + key + ' = electron.' + key + ';').join('\n');
+  const url = 'data:text/javascript,' + encodeURIComponent(source);
+  Module.registerHooks({
+    resolve(specifier, context, next) {
+      if ((specifier === 'electron' || specifier === 'electron/main') && context.conditions.includes('import')) {
+        return { url, shortCircuit: true };
+      }
+      return next(specifier, context);
+    },
+  });
+}
+`;

package/dist/components/electron.d.ts

@@ -0,0 +1,46 @@
+import { type DesktopApp } from "../desktop.js";
+export interface ElectronOptions {
+    /** Project-relative app directory; must contain package.json and Electron. */
+    appDir?: string;
+    /** Debian Node image tag, default 24-bookworm-slim. */
+    nodeVersion?: string;
+    /** Build the main/preload/renderer output; default npm run build. */
+    buildCommand?: string;
+    /** Dependency install command; defaults to npm ci when a lockfile exists. */
+    installCommand?: string;
+    /** App entry relative to /app, default . (package.json main). */
+    entry?: string;
+    env?: Record<string, string>;
+    dependsOn?: string[];
+}
+export declare const ELECTRON_LAUNCHER: string;
+/** Real Linux Electron under Xvfb, with a generated image and graphical replay.
+ * Like expo(), returns an app handle for the matching context method.
+ * Requires Linux-compatible application dependencies and binaries. */
+export declare function electron(options?: ElectronOptions): {
+    image: {
+        type: "dockerfile";
+        context: string;
+        exclude: string[];
+        content: string;
+    };
+    files: {
+        path: string;
+        content: string;
+    }[];
+    command: string;
+    env: {
+        SPECTEST_ELECTRON_ENTRY: string;
+    };
+    dependsOn: string[] | undefined;
+    ports: number[];
+    readyCheck: {
+        type: "http";
+        port: number;
+        path: string;
+        timeoutSecs: number;
+    };
+    helpers: ({ name }: {
+        name: string;
+    }) => DesktopApp;
+};

package/dist/components/electron.js

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolveProjectPath } from "../project-files.js";
+import { desktopApp } from "../desktop.js";
+import { ELECTRON_CHROME_HOOK } from "./electron-chrome.js";
+// Test-only debugger proxy: Electron binds its CDP socket to loopback. Forward
+// HTTP and WebSocket traffic from the VM to that socket, normalizing Host as
+// Chromium requires. It exposes no app-specific actions or state endpoints.
+export const ELECTRON_LAUNCHER = String.raw `
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+const require = createRequire('/app/package.json');
+const child = spawn(require('electron'), [
+  ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []),
+  '--disable-dev-shm-usage', '--remote-debugging-port=9222',
+  '-r', '/spectest-electron-chrome.cjs',
+  process.env.SPECTEST_ELECTRON_ENTRY || '.',
+], { cwd: '/app', stdio: 'inherit', env: process.env });
+const upstream = req => ({
+  host: '127.0.0.1', port: 9222, path: req.url, method: req.method,
+  headers: { ...req.headers, host: '127.0.0.1:9222' },
+});
+const server = http.createServer((req, res) => {
+  const proxy = http.request(upstream(req), response => {
+    res.writeHead(response.statusCode, response.headers);
+    response.pipe(res);
+  });
+  proxy.on('error', () => { res.writeHead(503); res.end('Electron debugger starting'); });
+  req.pipe(proxy);
+});
+server.on('upgrade', (req, socket, head) => {
+  const proxy = http.request(upstream(req));
+  proxy.on('upgrade', (response, remote, remoteHead) => {
+    socket.write('HTTP/1.1 101 Switching Protocols\r\n' +
+      Object.entries(response.headers).map(([k, v]) => k + ': ' + v).join('\r\n') + '\r\n\r\n');
+    if (remoteHead.length) socket.write(remoteHead);
+    if (head.length) remote.write(head);
+    socket.pipe(remote); remote.pipe(socket);
+    socket.on('error', () => remote.destroy());
+    remote.on('error', () => socket.destroy());
+    socket.on('close', () => remote.destroy());
+    remote.on('close', () => socket.destroy());
+  });
+  proxy.on('response', () => socket.destroy());
+  proxy.on('error', () => socket.destroy());
+  proxy.end();
+});
+server.listen(9223, '0.0.0.0');
+child.on('error', error => { console.error(error); process.exit(1); });
+child.on('exit', code => process.exit(code ?? 1));
+for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => child.kill(signal));
+`;
+/** Real Linux Electron under Xvfb, with a generated image and graphical replay.
+ * Like expo(), returns an app handle for the matching context method.
+ * Requires Linux-compatible application dependencies and binaries. */
+export function electron(options = {}) {
+    const appDir = options.appDir ?? ".";
+    const manifest = resolveProjectPath(`${appDir}/package.json`);
+    if (!existsSync(manifest))
+        throw new Error(`electron(): no package.json in ${appDir}`);
+    const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+    if (!pkg.dependencies?.electron && !pkg.devDependencies?.electron) {
+        throw new Error("electron(): declare electron in the app's dependencies or devDependencies");
+    }
+    const locked = existsSync(resolveProjectPath(`${appDir}/package-lock.json`));
+    const node = options.nodeVersion ?? "24-bookworm-slim";
+    if (!/^[\w.-]+$/.test(node))
+        throw new Error("electron(): invalid Node image tag");
+    const install = options.installCommand ?? (locked ? "npm ci" : "npm install");
+    const build = options.buildCommand ?? "npm run build";
+    if ([install, build].some(command => /[\r\n]/.test(command))) {
+        throw new Error("electron(): build/install commands must be single-line shell commands");
+    }
+    return {
+        image: {
+            type: "dockerfile",
+            context: appDir,
+            exclude: ["node_modules", "**/node_modules", "out", "test-results", ".data"],
+            content: `FROM node:${node}
+RUN apt-get update && apt-get install -y --no-install-recommends xvfb xauth libgtk-3-0 libnss3 libgbm1 libasound2 fonts-liberation ca-certificates && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY . .
+RUN ${install}
+RUN node node_modules/electron/install.js
+RUN ${build}
+`,
+        },
+        files: [
+            { path: "/spectest-electron.mjs", content: ELECTRON_LAUNCHER },
+            { path: "/spectest-electron-chrome.cjs", content: ELECTRON_CHROME_HOOK },
+        ],
+        command: "xvfb-run -a node /spectest-electron.mjs",
+        env: { ...options.env, SPECTEST_ELECTRON_ENTRY: options.entry ?? "." },
+        dependsOn: options.dependsOn,
+        ports: [9223],
+        readyCheck: { type: "http", port: 9223, path: "/json/version", timeoutSecs: 60 },
+        helpers: ({ name }) => desktopApp(`http://${name}.internal:9223`, name),
+    };
+}

package/dist/components/index.d.ts

@@ -14,3 +14,4 @@ export { apple, type AppleOptions } from "./apple.js";
 export { microsoft, type MicrosoftOptions } from "./microsoft.js";
 export { okta, type OktaOptions } from "./okta.js";
 export { replayFake, type ReplayFakeOptions, type ReplayMatch, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";
+export { electron, type ElectronOptions } from "./electron.js";

package/dist/components/index.js

@@ -23,3 +23,4 @@ export { apple } from "./apple.js";
 export { microsoft } from "./microsoft.js";
 export { okta } from "./okta.js";
 export { replayFake, } from "./replayFake.js";
+export { electron } from "./electron.js";

package/dist/components/supabase-functions-reach.d.ts

@@ -0,0 +1,18 @@
+/** Specifiers a source text imports, as written. */
+export declare function importSpecifiers(text: string): string[];
+/** Local targets an import map (`deno.json` `imports`, `import_map.json`)
+ *  names, as written: relative values, and root-relative `/…` ones. */
+export declare function importMapLocalTargets(text: string): string[];
+/**
+ * The directories, project-relative and sorted, that the functions under
+ * `fnRelPath` can load modules from: `fnRelPath` itself, and every
+ * directory a relative import or a local import-map entry leads to,
+ * transitively. `["."]` when the walk runs out of budget. A directory
+ * nested under another in the answer is dropped.
+ */
+export declare function functionsReach(root: string, fnRelPath: string): string[];
+/** The `exclude` list that narrows a root build context to `dirs`: drop
+ *  everything, then re-include each directory and its subtree, then drop
+ *  again what no context should carry (a re-included `packages/shared`
+ *  would otherwise bring its `node_modules` along). */
+export declare function excludeAllBut(dirs: readonly string[]): string[];

package/dist/components/supabase-functions-reach.js

@@ -0,0 +1,155 @@
+// What the edge functions can load from the project — the pure part.
+//
+// The edge runtime serves each function from the project root, mounted
+// whole so that a monorepo function's `../../packages/shared/mod.ts`
+// resolves where it sits. Whole is right for the runtime and wrong for
+// the reach: with the root in a build context and a volume, every file of
+// the project could "reach" the functions, and a change to `docs/` could
+// never skip a run. So the component works out the **module graph** the
+// functions can load, statically, and hands the build context and the
+// reach exactly that: the functions directory, and every directory a
+// relative import or a local import-map entry leads to, followed
+// transitively. Directories rather than files, so a sibling module a
+// dynamic `import()` picks at run time comes along.
+//
+// What it cannot see: a computed specifier that leaves the directories
+// found (`import(\`../../${x}/mod.ts\`)`), and a `Deno.readTextFile` of a
+// path outside them. Both are rare in a function, and both are the same
+// class of hole as a test reading the workspace through `node:fs`. A tree
+// too large to walk within the budget is answered with the whole project,
+// the safe side.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+/** Files the walk parses for imports. */
+const SOURCE_EXT = /\.(?:[mc]?[jt]sx?)$/;
+/** Names never walked into. */
+const SKIP = new Set(["node_modules", ".git", ".spectest", "dist", "build", ".next"]);
+/** The walk gives up past this many files and answers with the root. */
+const FILE_BUDGET = 20_000;
+const IMPORT_RE = /\b(?:import|export)\b[^;'"`]*?\bfrom\s*['"]([^'"]+)['"]|\bimport\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+/** Specifiers a source text imports, as written. */
+export function importSpecifiers(text) {
+    const out = [];
+    for (const m of text.matchAll(IMPORT_RE))
+        out.push(m[1] ?? m[2] ?? m[3] ?? "");
+    return out.filter((s) => s.length > 0);
+}
+/** Local targets an import map (`deno.json` `imports`, `import_map.json`)
+ *  names, as written: relative values, and root-relative `/…` ones. */
+export function importMapLocalTargets(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    const imports = parsed?.imports;
+    if (typeof imports !== "object" || imports === null)
+        return [];
+    return Object.values(imports).filter((v) => typeof v === "string" && (v.startsWith("./") || v.startsWith("../") || v.startsWith("/")));
+}
+function toPosix(p) {
+    return sep === "/" ? p : p.split(sep).join("/");
+}
+/**
+ * The directories, project-relative and sorted, that the functions under
+ * `fnRelPath` can load modules from: `fnRelPath` itself, and every
+ * directory a relative import or a local import-map entry leads to,
+ * transitively. `["."]` when the walk runs out of budget. A directory
+ * nested under another in the answer is dropped.
+ */
+export function functionsReach(root, fnRelPath) {
+    const rootAbs = resolve(root);
+    const dirs = new Set();
+    const queue = [resolve(rootAbs, fnRelPath)];
+    let budget = FILE_BUDGET;
+    const inRoot = (p) => p === rootAbs || p.startsWith(rootAbs + sep);
+    const enqueue = (target) => {
+        if (!inRoot(target) || !existsSync(target))
+            return;
+        let st;
+        try {
+            st = statSync(target);
+        }
+        catch {
+            return;
+        }
+        const dir = st.isDirectory() ? target : dirname(target);
+        if (![...dirs].some((d) => dir === d || dir.startsWith(d + sep)))
+            queue.push(dir);
+    };
+    const follow = (fromDir, spec) => {
+        if (spec.startsWith("./") || spec.startsWith("../"))
+            enqueue(resolve(fromDir, spec));
+        else if (spec.startsWith("/"))
+            enqueue(resolve(rootAbs, spec.slice(1)));
+    };
+    while (queue.length > 0) {
+        const dir = queue.shift();
+        if ([...dirs].some((d) => dir === d || dir.startsWith(d + sep)))
+            continue;
+        if (!existsSync(dir))
+            continue;
+        dirs.add(dir);
+        // Every file below it, parsed for what it imports.
+        const stack = [dir];
+        while (stack.length > 0) {
+            const d = stack.pop();
+            let entries;
+            try {
+                entries = readdirSync(d, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const e of entries) {
+                const p = join(d, e.name);
+                if (e.isDirectory()) {
+                    if (!SKIP.has(e.name))
+                        stack.push(p);
+                    continue;
+                }
+                if (!e.isFile())
+                    continue;
+                if (--budget < 0)
+                    return ["."];
+                if (e.name === "deno.json" || e.name === "import_map.json") {
+                    for (const t of importMapLocalTargets(safeRead(p)))
+                        follow(d, t.endsWith("/") ? t.slice(0, -1) : t);
+                    continue;
+                }
+                if (!SOURCE_EXT.test(e.name))
+                    continue;
+                for (const spec of importSpecifiers(safeRead(p)))
+                    follow(d, spec);
+            }
+        }
+    }
+    // Minimal, project-relative, sorted.
+    const rel = [...dirs].map((d) => (d === rootAbs ? "." : toPosix(relative(rootAbs, d))));
+    const minimal = rel.filter((d) => !rel.some((o) => o !== d && (o === "." || d.startsWith(o + "/"))));
+    return [...new Set(minimal)].sort();
+}
+function safeRead(p) {
+    try {
+        return readFileSync(p, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/** The `exclude` list that narrows a root build context to `dirs`: drop
+ *  everything, then re-include each directory and its subtree, then drop
+ *  again what no context should carry (a re-included `packages/shared`
+ *  would otherwise bring its `node_modules` along). */
+export function excludeAllBut(dirs) {
+    if (dirs.includes("."))
+        return [];
+    return ["**", ...dirs.flatMap((d) => [`!${d}`, `!${d}/**`]), ...REEXCLUDE];
+}
+/** Re-excluded after the re-includes: the names the default ignore drops. */
+const REEXCLUDE = ["**/node_modules/**", "**/.git/**", "**/.spectest/**", "**/__pycache__/**", "**/.venv/**"];
+// Keep `isAbsolute` referenced for callers that pass absolute fnRelPath by
+// mistake: the walk resolves it against the root either way.
+void isAbsolute;