@specific.dev/spectest 0.86.2 → 0.88.0

package/dist/components/supabase.js

@@ -50,6 +50,7 @@
 // (`sb.url`, `sb.dbUrl`) embeds it — a mismatch errors at load.
 import { createHmac } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
+import { excludeAllBut, functionsReach } from "./supabase-functions-reach.js";
 import { readdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { serviceGroup, } from "../index.js";
@@ -137,6 +138,9 @@ function providerCredentials(providerName, declared, env) {
  * cache rides into the image as a layer — so at run time the worker resolves
  * those URLs locally and never reaches for the network.
  *
+ * The context is the module graph the functions can load (the functions
+ * directory and what its imports lead to, `functionsReach`), copied whole
+ * so a monorepo function's `../../packages/…` resolves at bundle time too.
  * One synthetic entrypoint imports every function, so the whole set is one
  * graph rather than one per function. Bundling is best-effort: a function that
  * fails to bundle (a type error, an import that only resolves at run time)
@@ -146,13 +150,13 @@ function providerCredentials(providerName, declared, env) {
 function functionsDockerfile(fnRelPath) {
     return `FROM ${IMAGES.functions}
 ENV DENO_DIR=${DENO_DIR}
-COPY ${fnRelPath} /warm/functions
+COPY . /warm/repo
 RUN set -eu; \
     : > /warm/all.ts; \
-    for d in /warm/functions/*/; do \
+    for d in /warm/repo/${fnRelPath}/*/; do \
       [ -f "$d/index.ts" ] || continue; \
       n=$(basename "$d"); \
-      printf 'import "./functions/%s/index.ts";\\n' "$n" >> /warm/all.ts; \
+      printf 'import "./repo/${fnRelPath}/%s/index.ts";\\n' "$n" >> /warm/all.ts; \
     done; \
     edge-runtime bundle --entrypoint /warm/all.ts --output /tmp/warm.eszip --quiet || true; \
     rm -rf /tmp/warm.eszip /warm
@@ -1247,6 +1251,10 @@ export function supabase(opts = {}) {
             ? `${REPO_MOUNT}/${fnDir.slice(root.length + 1)}`
             : `${REPO_MOUNT}/supabase/functions`;
     const migrationsPath = inDir("migrations");
+    // The directories the functions can load modules from: the functions
+    // directory and what its imports lead to (`supabase-functions-reach.ts`).
+    // The build context and the reach are narrowed to exactly these.
+    const fnReachDirs = withFunctions ? functionsReach(root, fnRelPath) : [];
     // ── config file (config.toml / config.json) ───────────────────────────
     // The CLI's own project config, mapped onto the stack. Read at build time:
     // the values become container config, so they must be in hand before the
@@ -1415,8 +1423,20 @@ export function supabase(opts = {}) {
             const realtimeHost = `realtime-dev.${g.key("realtime")}`;
             const parts = {};
             // ── db ──────────────────────────────────────────────────────────
+            // What the stack reads from the project: the Supabase folder
+            // (config.toml, migrations, seed, functions) and the mail templates,
+            // which may sit anywhere in the repo. Declared as inputs so a change
+            // to any of them is never taken as one that can affect no test; the
+            // migrations volume carries the folder too, but only when there is
+            // a migrations directory, and a config-only project must count as
+            // well.
+            const inputs = [
+                ...(opts.dir !== undefined && !opts.dir.startsWith("/") ? [opts.dir] : []),
+                ...templateBodies.map(([, spec]) => spec.path).filter((t) => !t.startsWith("/")),
+            ];
             const dbDef = {
                 image: { type: "registry", reference: opts.db?.image ?? IMAGES.db },
+                ...(inputs.length > 0 ? { inputs } : {}),
                 // `args` (not `command`): keep the image's docker-entrypoint.sh so it
                 // runs initdb + its baked init-scripts before starting.
                 args: [
@@ -1721,6 +1741,12 @@ export function supabase(opts = {}) {
                     image: {
                         type: "dockerfile",
                         content: functionsDockerfile(fnRelPath),
+                        // The root, narrowed to the module graph: only the functions
+                        // directory and what its imports lead to enter the context, so
+                        // a change anywhere else neither uploads nor counts as reaching
+                        // the functions.
+                        context: ".",
+                        exclude: excludeAllBut(fnReachDirs),
                     },
                     // The **project root**, mounted with the functions directory in its
                     // real position underneath. Mounting only `supabase/functions`
@@ -1729,8 +1755,10 @@ export function supabase(opts = {}) {
                     // (`../../../../packages/…`), and that only resolves if the
                     // directory sits where it sits in the repo. Read-only: the runtime
                     // only reads sources, and a function writing into its own directory
-                    // would be writing into the user's checkout.
-                    volumes: [{ source: projectRootPath(), target: REPO_MOUNT, readOnly: true }],
+                    // would be writing into the user's checkout. For the reach the
+                    // mount is exempt: what the functions can load is the module graph
+                    // above, which the build context already states.
+                    volumes: [{ source: projectRootPath(), target: REPO_MOUNT, readOnly: true, reachExempt: true }],
                     // Our router (see FUNCTIONS_MAIN_TS) sits outside that mount, so
                     // the project never has to carry a `main/` function of ours.
                     files: [{ path: "/home/deno/main/index.ts", content: FUNCTIONS_MAIN_TS }],

package/dist/daemon.js

@@ -24,12 +24,13 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { ENVIRONMENT_CA_PATH as CA_PATH } from "./environment-ca.js";
 import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, validateServiceImage, proxy as makeProxyDecl, } from "./index.js";
-import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, walkProjectFiles, ENVIRONMENT_SERVICE, REACH_REPORT, } from "./harness/coverage.js";
+import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, walkProjectFiles, ENVIRONMENT_SERVICE, REACH_REPORT, READS_REPORT, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
 import { INVENTORY_REPORT, NODE_COVERAGE_MARKERS_SUBDIR, NODE_COVERAGE_SCRIPTS_SUBDIR, applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
-import { acquirePersistentBrowser, mobileKey } from "./browser.js";
+import { acquirePersistentBrowser, acquirePersistentDesktop, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
+import { isDesktopApp } from "./desktop.js";
 // Pure ingress hostname matching, ported out of this file (see
 // harness/hostmatch.ts). Keeping ONE implementation is the point: the
 // exact-then-longest-suffix rule and the one-label certificate rule are
@@ -41,10 +42,10 @@ import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
-import { runWrapperRules } from "./harness/wrapper-rules.js";
+import { fsUsageDiagnostics, runWrapperRules } from "./harness/wrapper-rules.js";
 import { cpus } from "node:os";
 import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath, takeProjectReads } from "./project-files.js";
-import { projectReach, renderReach, renderReadsLcov } from "./harness/reach.js";
+import { compactReach, projectReach, renderReachRules, renderReadsLcov } from "./harness/reach.js";
 import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import { bindInstrumentationScope, createInstrumentationScope, runInstrumented, runUninstrumented, } from "./harness/instrumentation-scope.js";
 import { encodeRegistry } from "./harness/names-registry.js";
@@ -3584,7 +3585,9 @@ async function computeProjectReachInner(all) {
     const sources = [];
     for (const svc of all) {
         const src = {
-            volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source ? [v.source] : [])),
+            service: svc.name,
+            volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source && !v.reachExempt ? [v.source] : [])),
+            ...(svc.inputs && svc.inputs.length > 0 ? { inputs: [...svc.inputs] } : {}),
         };
         if (svc.image.type === "dockerfile") {
             try {
@@ -3603,29 +3606,33 @@ async function computeProjectReachInner(all) {
         }
         sources.push(src);
     }
-    return projectReach(files, sources);
+    const reach = projectReach(files, sources);
+    return { version: 1, sources, prefixes: compactReach(files, reach) };
 }
 /**
  * The synthetic `__environment__` capture: what the environment itself
- * knows — the project's reach (bring-up only) and the project files the
- * harness read through the SDK since the previous capture, as whole
- * lcov records. Present whenever some service opted in, so the two ride
- * the same bundle as the services' reports.
+ * knows — the project's reach as rules (bring-up only) and the project
+ * files the harness read through the SDK since the previous capture, as
+ * whole lcov records. Present on every capture of every project, coverage
+ * adapters or not: the reach is a property of the environment config,
+ * and it is what lets the control plane tell that a change to `site/**`
+ * can affect no test at all. When services opted in, the two ride the
+ * same bundle as their reports.
  */
 async function captureEnvironmentCoverage(all, baseline) {
     const reports = [];
     if (baseline) {
         try {
-            const reach = await computeProjectReach(all);
-            reports.push({ name: REACH_REPORT, content: renderReach(reach) });
-            console.log(`[coverage] project reach: ${reach.length} file(s) some build or volume can carry`);
+            const rules = await computeProjectReach(all);
+            reports.push({ name: REACH_REPORT, content: renderReachRules(rules) });
+            console.log(`[coverage] project reach: ${rules.sources.length} source(s), ${rules.prefixes.length} prefix(es) some build or volume can carry`);
         }
         catch (err) {
             console.warn(`[coverage] project reach not computed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     const reads = takeProjectReads();
-    reports.push({ name: "reads.lcov", content: renderReadsLcov(reads) });
+    reports.push({ name: READS_REPORT, content: renderReadsLcov(reads) });
     return { service: ENVIRONMENT_SERVICE, reports };
 }
 async function captureServiceCoverage(baseline = false) {
@@ -3639,8 +3646,8 @@ async function captureServiceCoverage(baseline = false) {
         byName.set(name, s);
     const all = [...byName.values()];
     const services = all.filter((s) => s.coverage !== undefined);
-    if (services.length === 0)
-        return [];
+    // The environment's own capture is unconditional (see above); the
+    // services' come from the ones that opted in, none included.
     const environment = captureEnvironmentCoverage(all, baseline);
     const captures = await Promise.all(services.map(async (svc) => {
         const { error, deltaReports } = await runCoverageAdapters(svc);
@@ -3748,6 +3755,7 @@ function newBrowserSession(testStart, idScope, frame = "browser", artifacts, nam
         record,
         recorder: {
             sessionId: record.sessionId,
+            frame,
             ...(name ? { sessionName: name } : {}),
             recordStep(step) {
                 if (closed)
@@ -3772,6 +3780,33 @@ function newBrowserSession(testStart, idScope, frame = "browser", artifacts, nam
         },
     };
 }
+/** Same desktop recording path for test runs and interactive evals. */
+function desktopOpener(start, scope, sessions, detaches, artifacts) {
+    const memo = new Map();
+    return async (app, options = {}) => {
+        if (!isDesktopApp(app))
+            throw new Error("ctx.desktop(app): pass ctx.svc.app from an electron() service");
+        const window = options.window ?? 0;
+        const key = JSON.stringify([app.endpoint, window]);
+        const existing = memo.get(key);
+        if (existing)
+            return existing;
+        const session = newBrowserSession(start, scope, "desktop", artifacts, window === 0 ? app.name : `${app.name} · window ${window + 1}`);
+        const { browser, detach, desktopChrome } = await acquirePersistentDesktop(app.endpoint, window, session.recorder);
+        session.record.desktopChrome = desktopChrome;
+        session.record.initialUrl = browser.url();
+        sessions.push(session);
+        detaches.push(async () => { await detach(); session.markClosed(); });
+        const close = browser.close.bind(browser);
+        browser.close = async () => {
+            await close();
+            if (memo.get(key) === browser)
+                memo.delete(key);
+        };
+        memo.set(key, browser);
+        return browser;
+    };
+}
 /** New terminal session bookkeeping for a single `ctx.terminal(...)` call. */
 function newTerminalSession(testStart, service, command, cols, rows, idScope) {
     const record = {
@@ -4643,6 +4678,7 @@ async function runOne(testCase) {
         openTerminal: recordedOpenTerminal,
         browser: trackedOpenBrowser,
         mobile: trackedOpenMobile,
+        desktop: desktopOpener(start, testCase.id, sessions, browserDetaches),
         mcp: openMcp,
         testName: testCase.name,
         parent,
@@ -5127,6 +5163,7 @@ async function evalCode(code, secrets) {
         openTerminal: evalOpenTerminal,
         browser: trackedOpenBrowser,
         mobile: trackedOpenMobile,
+        desktop: desktopOpener(start, "eval", sessions, browserDetaches, artifactCollector),
         mcp: openMcp,
         testName: "eval",
         parent: undefined,
@@ -5352,7 +5389,7 @@ async function runTypecheck() {
         return { status: "failed", errors: [], totalErrors: 0, durationMs, detail: "typecheck timed out" };
     }
     const { errors, total, suppressed } = parseTscOutput(res.stdout + res.stderr);
-    const wrapper = await runWrapperRulesReport(config);
+    const wrapper = [...(await runWrapperRulesReport(config)), ...(await rawFsReport())];
     const strip = ({ file, line, column, code, message }) => ({
         file,
         line,
@@ -5389,6 +5426,31 @@ async function runTypecheck() {
         ...(blocking.length > 0 ? { blocking } : {}),
     };
 }
+/**
+ * The raw-fs rule (`SPECTEST2003`, advisory) over the test tree: a test
+ * that opens a project file through `node:fs` hides a dependence from the
+ * subset selector. Textual, so it needs no compiler; best-effort.
+ */
+async function rawFsReport() {
+    const root = path.join(APP_DIR, "tests");
+    if (!existsSync(root))
+        return [];
+    try {
+        const files = await walkProjectFiles(root, ["node_modules"]);
+        const out = [];
+        for (const rel of files) {
+            if (!/\.(ts|tsx|js|jsx|mts|cts)$/.test(rel))
+                continue;
+            const text = await fs.readFile(path.join(root, rel), "utf8");
+            out.push(...fsUsageDiagnostics(path.join("tests", rel), text));
+        }
+        return out;
+    }
+    catch (err) {
+        console.warn(`[typecheck] raw fs rule threw: ${err?.message ?? err}`);
+        return [];
+    }
+}
 /**
  * The blocking rules, run against the BAKED compiler whatever the project
  * pins. Best-effort in every direction: an install that predates the API, a

package/dist/desktop-recorder.d.ts

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

package/dist/desktop-recorder.js

@@ -0,0 +1,30 @@
+// A late recorder cannot interpose on setters React cached during mounting.
+// Reconcile controls at action boundaries, without changing the app's DOM or
+// descriptors. Normal rrweb Input events win; synthesize only missing changes.
+export const DESKTOP_INPUT_SYNC_SCRIPT = String.raw `(() => {
+  if (window.__spectestSyncInputs) return;
+  const known = new WeakMap();
+  window.__spectestSyncInputs = (timestamp = Date.now()) => {
+    const rec = window.__spectestRec;
+    const events = window.__spectestRrwebEvents;
+    if (!rec?.mirror || !events) return;
+    const inputs = new Map();
+    for (const event of events) {
+      if (event.type === 3 && event.data?.source === 5) inputs.set(event.data.id, event.data);
+    }
+    for (const element of document.querySelectorAll('input, textarea, select')) {
+      const type = element.hasAttribute('data-rr-is-password') ? 'password' : element.type?.toLowerCase();
+      if (type === 'file' || element.closest('.rr-block, .rr-ignore')) continue;
+      const id = rec.mirror.getId(element);
+      if (!(id > 0)) continue;
+      const text = type === 'password' ? '*'.repeat(element.value.length) : element.value;
+      const isChecked = (type === 'checkbox' || type === 'radio') ? element.checked : false;
+      const current = { text, isChecked };
+      const previous = inputs.get(id) ?? known.get(element);
+      known.set(element, current);
+      if (!previous || (previous.text === text && previous.isChecked === isChecked)) continue;
+      events.push({ type: 3, data: { source: 5, id, text, isChecked }, timestamp });
+    }
+  };
+  window.__spectestSyncInputs();
+})();`;

package/dist/desktop.d.ts

@@ -0,0 +1,42 @@
+import type { Browser } from "./browser.js";
+export declare const DESKTOP_APP: unique symbol;
+/** An Electron service handle produced by electron(). */
+export interface DesktopApp {
+    readonly [DESKTOP_APP]: true;
+    readonly endpoint: string;
+    readonly name: string;
+}
+/** Real renderer window: user input, locators, assertions, and replay capture.
+ * close() closes this window only. Native OS dialogs are outside DOM replay. */
+export interface Desktop extends Browser {
+}
+/** Observed window configuration at the start of a replay session. */
+export interface DesktopChrome {
+    titleBarStyle: string;
+    frame: boolean;
+    trafficLightPosition: {
+        x: number;
+        y: number;
+    } | null;
+    titleBarOverlay: boolean | {
+        height?: number;
+        color?: string;
+        symbolColor?: string;
+    };
+    roundedCorners: boolean;
+    buttonVisibility: boolean | null;
+    titlebarArea?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface DesktopOptions {
+    /** Zero-based window creation order. Defaults to the first window.
+     * Open additional windows using the app UI before selecting them.
+     * A closed window keeps its index; other windows never change identity. */
+    window?: number;
+}
+export declare function desktopApp(endpoint: string, name: string): DesktopApp;
+export declare function isDesktopApp(value: unknown): value is DesktopApp;

package/dist/desktop.js

@@ -0,0 +1,10 @@
+export const DESKTOP_APP = Symbol.for("spectest.desktopApp");
+export function desktopApp(endpoint, name) {
+    return { [DESKTOP_APP]: true, endpoint, name };
+}
+export function isDesktopApp(value) {
+    return typeof value === "object" && value !== null &&
+        value[DESKTOP_APP] === true &&
+        typeof value.endpoint === "string" &&
+        typeof value.name === "string";
+}

package/dist/harness/coverage.d.ts

@@ -3,9 +3,12 @@ export declare const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
 /** The synthetic service the environment's own reports ride under: the
  *  project's reach (bring-up) and the project files the harness read. */
 export declare const ENVIRONMENT_SERVICE = "__environment__";
-/** The bring-up report listing the project's reach, one project-relative
- *  path per line (`harness/reach.ts`). */
-export declare const REACH_REPORT = "reach.paths";
+/** The bring-up report carrying the project's reach as rules plus a
+ *  compacted prefix list (`harness/reach.ts`, `ReachRules`). */
+export declare const REACH_REPORT = "reach.json";
+/** The per-capture report naming the project files the harness read
+ *  through the SDK since the previous capture, as whole lcov records. */
+export declare const READS_REPORT = "reads.lcov";
 /** Raw bytes of reports one service may ship per capture. Reports are
  *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
@@ -82,6 +85,9 @@ export declare function isUnitsReport(text: string): boolean;
 /** True when `text` is a report spectest stores: lcov, V8 JSON, a node()
  *  script record, or (by name) a `.units` list. */
 export declare function isWellFormedReport(text: string, name?: string): boolean;
+/** True when `text` is a `reach.json` document: a JSON object with a
+ *  `sources` array and a `prefixes` array. */
+export declare function isReachRules(text: string): boolean;
 /** True when a well-formed report names no source file at all (an lcov
  *  with no `SF:`, a V8 document with an empty `result`, a units list
  *  with no unit). */

package/dist/harness/coverage.js

@@ -36,9 +36,12 @@ export const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
 /** The synthetic service the environment's own reports ride under: the
  *  project's reach (bring-up) and the project files the harness read. */
 export const ENVIRONMENT_SERVICE = "__environment__";
-/** The bring-up report listing the project's reach, one project-relative
- *  path per line (`harness/reach.ts`). */
-export const REACH_REPORT = "reach.paths";
+/** The bring-up report carrying the project's reach as rules plus a
+ *  compacted prefix list (`harness/reach.ts`, `ReachRules`). */
+export const REACH_REPORT = "reach.json";
+/** The per-capture report naming the project files the harness read
+ *  through the SDK since the previous capture, as whole lcov records. */
+export const READS_REPORT = "reads.lcov";
 /** Raw bytes of reports one service may ship per capture. Reports are
  *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
@@ -89,12 +92,27 @@ export function isUnitsReport(text) {
 export function isWellFormedReport(text, name = "") {
     if (name.endsWith(".units"))
         return isUnitsReport(text);
+    if (name === REACH_REPORT)
+        return isReachRules(text);
     return isLcovShaped(text) || isV8CoverageJson(text) || isSpectestScriptRecord(text);
 }
+/** True when `text` is a `reach.json` document: a JSON object with a
+ *  `sources` array and a `prefixes` array. */
+export function isReachRules(text) {
+    try {
+        const v = JSON.parse(text);
+        return typeof v === "object" && v !== null && Array.isArray(v.sources) && Array.isArray(v.prefixes);
+    }
+    catch {
+        return false;
+    }
+}
 /** True when a well-formed report names no source file at all (an lcov
  *  with no `SF:`, a V8 document with an empty `result`, a units list
  *  with no unit). */
 export function isEmptyReport(text) {
+    if (isReachRules(text))
+        return false;
     if (isV8CoverageJson(text))
         return /"result"\s*:\s*\[\s*\]/.test(text);
     if (isSpectestScriptRecord(text))

package/dist/harness/reach.d.ts

@@ -12,6 +12,8 @@ export declare function compileDockerignore(text: string): Pattern[];
 export declare function isExcluded(patterns: Pattern[], rel: string): boolean;
 /** One service's contribution to the reach. */
 export interface ReachSource {
+    /** The service the source belongs to (for the shadow page's verdicts). */
+    service?: string;
     /** Build context directory, project-relative (`.` for the root); absent
      *  for a registry image. */
     context?: string;
@@ -23,6 +25,10 @@ export interface ReachSource {
     /** Volume sources, project-relative; an absolute source is not a
      *  project path and is skipped. */
     volumeSources?: string[];
+    /** The service's declared `inputs`: project files or directories it
+     *  consumes some other way (packaged at setup, read at load). A
+     *  directory covers its subtree. */
+    inputs?: string[];
 }
 /**
  * The project's reach: every project file (`files`, project-relative)
@@ -30,8 +36,33 @@ export interface ReachSource {
  * Dockerfiles the builds read. Sorted, unique.
  */
 export declare function projectReach(files: readonly string[], sources: readonly ReachSource[]): string[];
-/** The `reach.paths` report: one path per line. */
-export declare function renderReach(paths: readonly string[]): string;
+/** The `reach.json` report. Mirrors `reach::ReachRules` on the server. */
+export interface ReachRules {
+    version: 1;
+    /** Every service's contribution, as rules. */
+    sources: ReachSource[];
+    /** The current file reach, compacted: `dir/` for a directory every
+     *  project file of which is in the reach, a bare path for a file on its
+     *  own, `.` when the whole project is. */
+    prefixes: string[];
+}
+/**
+ * Compact a file reach against the project's file list: a directory
+ * whose every file is in the reach becomes one `dir/` prefix (the root
+ * becomes `.`), and a file whose directory is not wholly reached stays a
+ * path. Only directories that hold a project file exist here; an empty
+ * directory has nothing to be in or out of the reach.
+ */
+export declare function compactReach(files: readonly string[], reach: readonly string[]): string[];
+/** Is `path` (project-relative) in the reach the rules describe? The
+ *  compacted prefixes answer first; a path outside them is evaluated
+ *  against every source, so a file that did not exist when the prefixes
+ *  were computed gets the same answer the build would give. */
+export declare function reachContains(rules: ReachRules, path: string): boolean;
+/** The first source whose rules carry `path`, or `undefined`. */
+export declare function sourceOf(sources: readonly ReachSource[], path: string): ReachSource | undefined;
+/** The `reach.json` report text. */
+export declare function renderReachRules(rules: ReachRules): string;
 /** An lcov document that names `paths` as files with no line data —
  *  "whole" records, which the index reads as every line unknown, so any
  *  change to the file selects the case that read it. */

package/dist/harness/reach.js

@@ -4,14 +4,24 @@
 // a service's **build context** (so an image may carry it), it is the
 // **source of a volume** a service mounts, or a test **reads** it through
 // the SDK. The first two are known from the environment config before any
-// test runs; the harness computes their union here — the project's
-// **reach** — and ships it with the bring-up capture (`reach.paths`, one
-// project-relative path per line, under the synthetic `__environment__`
-// service). The subset selector then treats a changed file outside the
-// reach as one that cannot affect the suite: `site/**` behind a
+// test runs; the harness ships them with the bring-up capture as
+// **rules** (`reach.json`, under the synthetic `__environment__`
+// service): per service its context directory, the composed
+// `.dockerignore` text, the Dockerfile it reads and the volume sources it
+// mounts. Rules, not a file list: the control plane evaluates any changed
+// path against them, a file that did not exist at the base included, and
+// a project of ten thousand files ships a few lines. Beside the rules
+// rides a **compacted** view of the current file reach — a directory
+// every file of which is in the reach as one `dir/` prefix, the odd file
+// alone — which the control plane uses as a fast path and the shadow page
+// as the summary. The subset selector then treats a changed file outside
+// the reach as one that cannot affect the suite: `site/**` behind a
 // `.dockerignore`, `.github/**` outside every context. The third door is
 // recorded as it happens (`project-files.ts`, `takeProjectReads`).
 //
+// The rules are shipped for every project, coverage adapters or not: the
+// reach is a property of the environment config alone.
+//
 // The context of a build is what `docker build` would send: every file
 // under the context directory minus what the composed `.dockerignore`
 // (the project's own rules plus the service's `exclude`) matches, with
@@ -132,7 +142,7 @@ export function projectReach(files, sources) {
             if (rel)
                 out.add(rel);
         }
-        for (const v of s.volumeSources ?? []) {
+        for (const v of [...(s.volumeSources ?? []), ...(s.inputs ?? [])]) {
             if (v.startsWith("/"))
                 continue;
             const src = normRel(v);
@@ -144,9 +154,101 @@ export function projectReach(files, sources) {
     }
     return [...out].sort();
 }
-/** The `reach.paths` report: one path per line. */
-export function renderReach(paths) {
-    return paths.join("\n") + (paths.length ? "\n" : "");
+/**
+ * Compact a file reach against the project's file list: a directory
+ * whose every file is in the reach becomes one `dir/` prefix (the root
+ * becomes `.`), and a file whose directory is not wholly reached stays a
+ * path. Only directories that hold a project file exist here; an empty
+ * directory has nothing to be in or out of the reach.
+ */
+export function compactReach(files, reach) {
+    const inReach = new Set(reach);
+    // Per directory: how many project files live below it, how many of
+    // those the reach holds. "" is the root.
+    const total = new Map();
+    const hit = new Map();
+    const children = new Map();
+    const filesIn = new Map();
+    for (const f of files) {
+        const parts = f.split("/");
+        let dir = "";
+        for (let i = 0; i < parts.length; i += 1) {
+            total.set(dir, (total.get(dir) ?? 0) + 1);
+            if (inReach.has(f))
+                hit.set(dir, (hit.get(dir) ?? 0) + 1);
+            if (i === parts.length - 1) {
+                let list = filesIn.get(dir);
+                if (!list)
+                    filesIn.set(dir, (list = []));
+                list.push(f);
+            }
+            else {
+                const child = dir === "" ? parts[i] : `${dir}/${parts[i]}`;
+                let set = children.get(dir);
+                if (!set)
+                    children.set(dir, (set = new Set()));
+                set.add(child);
+                dir = child;
+            }
+        }
+    }
+    const out = [];
+    const walk = (dir) => {
+        const n = total.get(dir) ?? 0;
+        if (n > 0 && (hit.get(dir) ?? 0) === n) {
+            out.push(dir === "" ? "." : `${dir}/`);
+            return;
+        }
+        for (const f of filesIn.get(dir) ?? [])
+            if (inReach.has(f))
+                out.push(f);
+        for (const c of children.get(dir) ?? [])
+            walk(c);
+    };
+    walk("");
+    return out.sort();
+}
+/** Is `path` (project-relative) in the reach the rules describe? The
+ *  compacted prefixes answer first; a path outside them is evaluated
+ *  against every source, so a file that did not exist when the prefixes
+ *  were computed gets the same answer the build would give. */
+export function reachContains(rules, path) {
+    const p = normRel(path);
+    for (const pre of rules.prefixes) {
+        if (pre === "." || pre === p || (pre.endsWith("/") && p.startsWith(pre)))
+            return true;
+    }
+    return sourceOf(rules.sources, p) !== undefined;
+}
+/** The first source whose rules carry `path`, or `undefined`. */
+export function sourceOf(sources, path) {
+    const p = normRel(path);
+    for (const s of sources) {
+        if (s.context !== undefined) {
+            const ctx = normRel(s.context);
+            const prefix = ctx === "" ? "" : `${ctx}/`;
+            if (!prefix || p.startsWith(prefix)) {
+                const rel = p.slice(prefix.length);
+                if (rel === ".dockerignore" || rel === "Dockerfile" || !isExcluded(compileDockerignore(s.ignore ?? ""), rel))
+                    return s;
+            }
+        }
+        for (const e of s.extraFiles ?? [])
+            if (normRel(e) === p)
+                return s;
+        for (const v of [...(s.volumeSources ?? []), ...(s.inputs ?? [])]) {
+            if (v.startsWith("/"))
+                continue;
+            const src = normRel(v);
+            if (p === src || p.startsWith(`${src}/`))
+                return s;
+        }
+    }
+    return undefined;
+}
+/** The `reach.json` report text. */
+export function renderReachRules(rules) {
+    return JSON.stringify(rules);
 }
 /** An lcov document that names `paths` as files with no line data —
  *  "whole" records, which the index reads as every line unknown, so any