@specific.dev/spectest 0.131.21 → 0.132.0

package/src/coverage-next.ts

@@ -1,10 +1,13 @@
 // Next policy lives in the SDK. The collector/indexer only see ordinary
 // Node/browser reports and generic, report-scoped source metadata.
 import path from "node:path";
+import { NEXT_CHANGE_RULES, type ChangeRule } from "./change-rules.js";
 import { JAVASCRIPT_GENERATED_SOURCES } from "./coverage-javascript.js";
 import { node, browser, type CoverageAdapter, type CoverageSourceContext, type CoverageSourceOptions } from "./coverage.js";
 
 export interface NextCoverageOptions extends CoverageSourceOptions {
+  /** Replace this adapter's defaults, or false to disable them. */
+  changeRules?: readonly ChangeRule[] | false;
   /** Repository-relative directory represented by the build's source-map root.
    * Defaults to "." (repository root). Set explicitly for a nested build root. */
   sourceRoot?: string;
@@ -108,7 +111,10 @@ if (require.main === module) {
     walk(path.join(dist, "server"), true);
     walk(path.join(dist, "static"), false);
     if (!serverMaps || !browserMaps) throw new Error("Next coverage needs server and browser .js.map files in the runtime image. Enable productionBrowserSourceMaps and experimental.serverSourceMaps in Next config, and copy .next/server and .next/static maps into the runtime image, including Edge maps.");
-    process.stdout.write(JSON.stringify({generated:launcher(m), serverMaps, browserMaps}));
+    const appRoot = typeof m.relativeAppDir === "string" ? m.relativeAppDir :
+      (typeof m.appDir === "string" && typeof m.config.turbopack?.root === "string" ? path.relative(m.config.turbopack.root, m.appDir) : "");
+    process.stdout.write(JSON.stringify({generated:launcher(m), serverMaps, browserMaps,
+      pageExtensions:m.config.pageExtensions || ["tsx","ts","jsx","js"], appRoot}));
   } catch (e) { console.error("Next coverage: " + e.message); process.exitCode = 1; }
 }
 `;
@@ -117,6 +123,8 @@ export interface NextBuildMetadata {
   generated: string | null;
   serverMaps: number;
   browserMaps: number;
+  pageExtensions?: string[];
+  appRoot?: string;
 }
 
 const GENERATED_SOURCES = [
@@ -138,7 +146,7 @@ export function next(options: NextCoverageOptions = {}): CoverageAdapter {
   for (const [key, value] of Object.entries({ appDir: options.appDir, distDir: options.distDir })) {
     if (value !== undefined && (!value || path.posix.isAbsolute(value) || value.split("/").some(p => p === "..") || /[\\\0\r\n]/.test(value))) throw new Error(`coverage.next ${key} must be a relative runtime directory`);
   }
-  const server = node(), client = browser();
+  const server = node({ sourceRoot, changeRules: options.changeRules === undefined ? NEXT_CHANGE_RULES : options.changeRules }), client = browser();
   const cache = new Map<string, Promise<NextBuildMetadata>>();
   const metadata = (ctx: Pick<CoverageSourceContext, "service" | "exec">) => {
     let value = cache.get(ctx.service);
@@ -151,7 +159,25 @@ export function next(options: NextCoverageOptions = {}): CoverageAdapter {
   };
   return {
     defaultExcludeSources: JAVASCRIPT_GENERATED_SOURCES,
-    name: "next", reports: "delta", explains: server.explains,
+    name: "next", reports: "delta", explains: server.explains, changeRules: server.changeRules?.map(rule => ({...rule, root: rule.root ?? sourceRoot})),
+    ...(options.changeRules === undefined ? { async resolveChangeRules(ctx: CoverageSourceContext) {
+      const m = await metadata(ctx);
+      const extensions = m.pageExtensions ?? ["tsx", "ts", "jsx", "js"];
+      if (!Array.isArray(extensions) || extensions.some(ext => typeof ext !== "string" || !ext || /[^a-zA-Z0-9._-]/.test(ext))) throw new Error("invalid Next pageExtensions metadata");
+      const appRoot = m.appRoot || ".";
+      if (appRoot !== "." && (appRoot.includes("\\") || appRoot.split("/").some(part => !part || part === "." || part === ".."))) throw new Error("invalid Next app root metadata");
+      const root = path.posix.join(sourceRoot, appRoot);
+      // Remove the static conventional route allowance; the build's extensions
+      // determine which files are actually routes (including custom test-like names).
+      const rules = NEXT_CHANGE_RULES.filter(rule => !/^(pages|src\/pages|app|src\/app)\//.test(rule.pattern));
+      const routes = extensions.flatMap(ext => [
+        ...["pages", "src/pages"].map(dir => ({root,pattern:`${dir}/**/*.${ext}`,action:"coverage" as const})),
+        ...["app", "src/app"].flatMap(dir => ["page", "route"].map(name => ({root,pattern:`${dir}/**/${name}.${ext}`,action:"coverage" as const}))),
+      ]);
+      // Shared entries still require full runs, even when they are also routes.
+      const full = rules.filter(rule => rule.action === "full" && rule.pattern !== "**/migrations/**");
+      return [...rules.map(rule => ({...rule,root:rule.root ?? sourceRoot})), ...routes, ...full.map(rule => ({...rule,root:rule.root ?? sourceRoot}))];
+    }} : {}),
     ownsReport: name => server.ownsReport!(name) || client.ownsReport!(name),
     configure(svc, info) {
       const configured = server.configure!(svc, info);

package/src/coverage-rust.test.ts

@@ -5,6 +5,8 @@ import { execFileSync } from "node:child_process";
 import path from "node:path";
 import os from "node:os";
 import { rust } from "./coverage-rust";
+import { resolveCoverageSourceOptions, serviceChangePolicy } from "./coverage";
+import { evaluateChangePolicy } from "./change-rules";
 import { captureCoverageTarget } from "./harness/coverage-target";
 import { encodeCoverageBundle } from "./harness/coverage";
 
@@ -72,3 +74,35 @@ test.skipIf(!installedTools)("Rust real LLVM reports capture live and exited pro
     expect((await capture()).error).toContain("without a final report");
   } finally { child?.kill(); await fs.rm(root, { recursive: true, force: true }); }
 }, 30000);
+
+
+test("Rust workspace rules discover crate-local tests and binaries without running Cargo", async () => {
+  const files = [
+    "workspace/Cargo.toml", "workspace/crates/a/Cargo.toml", "workspace/crates/b/Cargo.toml",
+    "workspace/crates/a/tests/fixture/Cargo.toml", "outside/Cargo.toml",
+  ];
+  const context = {service:"rust", signal:AbortSignal.timeout(1000),
+    projectFiles:async()=>files,readProjectFile:async()=>null,
+    exec:async()=>{throw new Error("crate policy must not execute Cargo");}};
+  for (const explicitRoot of [true, false]) {
+    const adapter = rust(explicitRoot ? {sourceRoot:"workspace"} : {});
+    const svc = {coverage:{sourceRoot:"workspace",adapters:[adapter]}};
+    await resolveCoverageSourceOptions([adapter],context,{sourceRoot:"workspace"});
+    const policy = serviceChangePolicy(svc,{requireResolved:true});
+    for (const crate of ["a","b"]) {
+      const root = `workspace/crates/${crate}`;
+      for (const file of ["tests/integration.rs", "tests/data.json", "benches/perf.rs"]) expect(evaluateChangePolicy(policy,`${root}/${file}`)).toBe("ignore");
+      for (const file of ["src/lib.rs", "src/tests.rs", "examples/server.rs"]) expect(evaluateChangePolicy(policy,`${root}/${file}`)).toBe("coverage");
+      expect(evaluateChangePolicy(policy,`${root}/src/bin/server.rs`)).toBe("full");
+      expect(evaluateChangePolicy(policy,`${root}/src/bin/README.md`)).toBe("ignore");
+    }
+    expect(evaluateChangePolicy(policy,"workspace/crates/a/tests/fixture/src/bin/main.rs")).toBe("ignore");
+    expect(evaluateChangePolicy(policy,"workspace/not-a-crate/tests/helper.rs")).toBe("coverage");
+    expect(evaluateChangePolicy(policy,"workspace/not-a-crate/benches/data.json")).toBeUndefined();
+    expect(evaluateChangePolicy(policy,"outside/tests/helper.rs")).toBeUndefined();
+  }
+  for (const changeRules of [false, []] as const) {
+    const adapter = rust({changeRules});
+    expect(adapter.resolveChangeRules).toBeUndefined();
+  }
+});

package/src/coverage-rust.ts

@@ -1,9 +1,11 @@
+import { RUST_CHANGE_RULES, COMMON_CHANGE_RULES, validateChangeRules, type ChangeRule } from "./change-rules.js";
 import { promises as fs, readFileSync } from "node:fs";
 import path from "node:path";
 import { connect } from "node:net";
 import type { CoverageAdapter, CoverageSourceOptions } from "./coverage.js";
 
 export interface RustCoverageOptions extends CoverageSourceOptions {
+  changeRules?: readonly ChangeRule[] | false;
   /** Only for idle command containers where no Rust process has run yet. */
   allowEmpty?: boolean;
   /** Compiler workspace directory, when different from the runtime workdir.
@@ -50,6 +52,8 @@ export async function flushCoverageSockets(dir: string, prefix: string, signal:
  * The helper exports cumulative per-process LCOV before exit and on request;
  * no compiler tools or binaries need to be copied out of terminated pods. */
 export function rust(options: RustCoverageOptions = {}): CoverageAdapter {
+  const rules = options.changeRules === undefined ? RUST_CHANGE_RULES : options.changeRules;
+  if (rules !== false) validateChangeRules(rules);
   const { sourceRoot, excludeSources, llvmCov, llvmProfdata, ignoreFilenameRegex, buildRoot } = options;
   if (buildRoot !== undefined && (!buildRoot.startsWith("/") || buildRoot === "/" || /[\0\r\n]/.test(buildRoot) || buildRoot.split("/").includes(".."))) throw new Error("Rust buildRoot must be an absolute compiler workspace directory");
   for (const value of [llvmCov, llvmProfdata, ignoreFilenameRegex]) {
@@ -57,6 +61,24 @@ export function rust(options: RustCoverageOptions = {}): CoverageAdapter {
   }
   return {
     name: "rust", reports: "cumulative",
+    changeRules: rules === false ? [] : rules.map(rule => ({...rule})),
+    ...(options.changeRules === undefined ? { async resolveChangeRules(ctx) {
+      const root = sourceRoot ?? ctx.sourceRoot ?? ".";
+      const prefix = root === "." ? "" : root + "/";
+      const files = await ctx.projectFiles();
+      const crates = [...new Set(files.filter(file =>
+        file.startsWith(prefix) && (file === "Cargo.toml" || file.endsWith("/Cargo.toml"))
+      ).map(file => path.posix.dirname(file)))].sort();
+      // A workspace can contain many packages; their canonical test directories
+      // are relative to each Cargo.toml, not just the adapter's source root.
+      // Test fixture packages stay ignored even when they contain binary targets.
+      return [
+        ...RUST_CHANGE_RULES.map(rule => ({...rule,root:rule.root ?? root})),
+        ...crates.map(root => ({root,pattern:"src/bin/**",action:"full" as const})),
+        ...crates.flatMap(root => ["tests/**", "benches/**"].map(pattern => ({root,pattern,action:"ignore" as const}))),
+        ...COMMON_CHANGE_RULES.map(rule => ({...rule,root})),
+      ];
+    }} satisfies Partial<CoverageAdapter> : {}),
     sourceOptions: { ...(sourceRoot !== undefined ? { sourceRoot } : {}), ...(excludeSources ? { excludeSources } : {}) },
     ownsReport: name => /^rust-.*\.lcov$/.test(name),
     configure: service => ({ ...service, env: { ...service.env,

package/src/coverage.test.ts

@@ -12,6 +12,7 @@ import {
   NODE_COVERAGE_MARKERS_SUBDIR,
   NODE_COVERAGE_SOCKET_PREFIX,
   NODE_EXPLAINS,
+  NODE_CHANGE_RULES,
   NODE_INVENTORY_SCRIPT,
   npmManifestUnit,
   applyCoverageAdapters,
@@ -112,7 +113,7 @@ describe("applyCoverageAdapters", () => {
     expect(typeof list[0]?.capture).toBe("function");
     expect(typeof list[1]?.load).toBe("function");
     expect(JSON.parse(JSON.stringify(out)).coverage).toEqual({
-      adapters: [{ adapter: "node", defaultExcludeSources: [...JAVASCRIPT_GENERATED_SOURCES] }, { adapter: "browser", defaultExcludeSources: [...JAVASCRIPT_GENERATED_SOURCES] }],
+      adapters: [{ adapter: "node", changeRules: NODE_CHANGE_RULES, defaultExcludeSources: [...JAVASCRIPT_GENERATED_SOURCES] }, { adapter: "browser", changeRules: NODE_CHANGE_RULES, defaultExcludeSources: [...JAVASCRIPT_GENERATED_SOURCES] }],
       explains: [...NODE_EXPLAINS],
     });
   });

package/src/coverage.ts

@@ -29,6 +29,8 @@
 
 import { createHash } from "node:crypto";
 import { JAVASCRIPT_GENERATED_SOURCES } from "./coverage-javascript.js";
+import { NODE_CHANGE_RULES, BROWSER_CHANGE_RULES, resolveChangePolicy, validateChangeRules, compileChangePolicy, type ChangeRule, type ChangePolicy } from "./change-rules.js";
+export * from "./change-rules.js";
 
 import type { ServiceConfig } from "./index.js";
 import { harvestAllBrowserCoverage, takeBrowserCoverageReport } from "./browser-coverage.js";
@@ -80,13 +82,17 @@ export interface CoverageLoadContext {
  * of the manifests that declare them (see {@link CoverageAdapter.inventory}).
  */
 export interface CoverageInventoryContext {
+  /** Effective repository-relative source root for build-specific policy resolution. */
+  sourceRoot?: string;
+  /** Selection overrides of the owning service, forwarded by container wrappers. */
+  changeRules?: readonly ChangeRule[] | false;
   /** The services-map key. */
   service: string;
   /** Run a shell command (`sh -c`) inside the container. Rejects on a
    *  non-zero exit with the command's output in the message. */
   exec(command: string): Promise<{ stdout: string; stderr: string }>;
-  /** Every file of the uploaded project, project-relative, `/`-separated,
-   *  `node_modules`, `.git` and the like skipped. */
+  /** Project-relative files; inventory calls omit paths ignored by effective
+   * change policy, as well as node_modules, .git and other upload exclusions. */
   projectFiles(): Promise<string[]>;
   /** One project file's text (project-relative path); `null` when absent. */
   readProjectFile(path: string): Promise<string | null>;
@@ -127,6 +133,12 @@ export type CoverageSourceContext = CoverageInventoryContext;
 export interface CoverageAdapter {
   /** Names the adapter in errors (`coverage adapter "node" on service …`). */
   name: string;
+  /** Ordered default rules; service rules are explicit overrides. */
+  changeRules?: readonly ChangeRule[];
+  /** Resolve build-specific rules once evidence is available; replaces static defaults. */
+  resolveChangeRules?(ctx: CoverageSourceContext): Promise<readonly ChangeRule[]>;
+  /** Wrappers retain separate policy groups for each nested adapter. */
+  changeRuleGroups?: readonly (readonly ChangeRule[])[];
   /** Archived on this adapter's reports; other adapters retain their own policy. */
   sourceOptions?: CoverageSourceOptions | ((ctx: CoverageSourceContext) => Promise<CoverageSourceOptions>);
   /** Generated scaffolding excluded in addition to explicit or legacy source policy. */
@@ -251,19 +263,23 @@ export function validateCoverage(service: string, cov: unknown): void {
         ((a as CoverageAdapter).explains === undefined ||
           (Array.isArray((a as CoverageAdapter).explains) &&
             ((a as CoverageAdapter).explains as unknown[]).every((e) => typeof e === "string"))) &&
-        ["configure", "load", "capture", "collect", "inventory", "ownsReport"].every(
+        ["configure", "load", "capture", "collect", "inventory", "ownsReport", "resolveChangeRules"].every(
           (k) =>
             (a as Record<string, unknown>)[k] === undefined ||
             typeof (a as Record<string, unknown>)[k] === "function",
         );
       const sourceOptions = (a as CoverageAdapter | null)?.sourceOptions;
+      const changeRules = (a as CoverageAdapter | null)?.changeRules;
+      const groups = (a as CoverageAdapter | null)?.changeRuleGroups;
+      if (changeRules !== undefined) validateChangeRules(changeRules);
+      if (groups !== undefined) { if (!Array.isArray(groups)) throw new Error("invalid changeRuleGroups"); for (const group of groups) validateChangeRules(group); }
       const defaults = (a as CoverageAdapter | null)?.defaultExcludeSources;
       const defaultShape = defaults === undefined || typeof (a as CoverageAdapter).ownsReport === "function";
       const sourceShape = sourceOptions === undefined || (typeof (a as CoverageAdapter).ownsReport === "function" &&
         (typeof sourceOptions === "function" || (typeof sourceOptions === "object" && sourceOptions !== null && !Array.isArray(sourceOptions))));
       if (!ok || !sourceShape || !defaultShape) {
         throw new Error(
-          `service "${service}" has an invalid coverage adapter — an adapter is \`{ name, reports?, explains?, configure?, load?, capture?, inventory? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`,
+          `service "${service}" has an invalid coverage adapter — an adapter is \`{ name, reports?, explains?, changeRules?, configure?, load?, capture?, inventory? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`,
         );
       }
       if (sourceOptions !== undefined && typeof sourceOptions !== "function") validateCoverageSourceOptions(service, sourceOptions);
@@ -291,6 +307,7 @@ export function coverageAdapters(cov: ServiceCoverage | undefined): readonly Cov
 export function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc: S): S {
   validateCoverage(key, svc.coverage);
   const adapters = coverageAdapters(svc.coverage);
+  serviceChangePolicy(svc); // Validate even uncovered services; never enables collection.
   if (adapters.length === 0) return svc;
   let out: ServiceConfig = svc;
   for (const a of adapters) {
@@ -312,6 +329,41 @@ export function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc:
   return { ...out, coverage: wire } as unknown as S;
 }
 
+/** Resolve service policy without requiring coverage to be enabled. */
+const RESOLVED_CHANGE_RULES = new Map<NonNullable<CoverageAdapter["resolveChangeRules"]>, readonly ChangeRule[]>();
+export async function resolveAdapterChangeRules(adapter: CoverageAdapter, ctx: CoverageSourceContext): Promise<void> {
+  if (!adapter.resolveChangeRules) return;
+  const rules = await adapter.resolveChangeRules(ctx);
+  validateChangeRules(rules);
+  const before = RESOLVED_CHANGE_RULES.get(adapter.resolveChangeRules);
+  if (before && JSON.stringify(before) !== JSON.stringify(rules)) throw new Error(`adapter ${adapter.name} resolved inconsistent change rules across runtimes`);
+  RESOLVED_CHANGE_RULES.set(adapter.resolveChangeRules, rules.map(rule => ({...rule})));
+}
+export function serviceChangePolicy(svc: Pick<ServiceConfig, "coverage" | "changeRules">, options: {requireResolved?: boolean} = {}): ChangePolicy {
+  const adapters = coverageAdapters(svc.coverage).map(adapter => {
+    if (!adapter.resolveChangeRules || svc.changeRules === false) return adapter;
+    const rules = RESOLVED_CHANGE_RULES.get(adapter.resolveChangeRules);
+    if (!rules && options.requireResolved) {
+      // An unused declared image has no runtime metadata. Archive a conservative
+      // fallback, so its source cannot gain ignore/coverage exceptions.
+      const fallbackRoot = typeof adapter.sourceOptions === "object" ? adapter.sourceOptions.sourceRoot : undefined;
+      const serviceRoot = typeof svc.coverage === "object" ? svc.coverage.sourceRoot : undefined;
+      const roots = new Set([...(adapter.changeRules ?? []), ...(adapter.changeRuleGroups ?? []).flat()].map(rule => rule.root ?? fallbackRoot ?? serviceRoot ?? "."));
+      if (!roots.size) roots.add(fallbackRoot ?? serviceRoot ?? ".");
+      return {...adapter, changeRuleGroups:[], changeRules:[...roots].map(root => ({root,pattern:"**",action:"full" as const}))};
+    }
+    return rules ? {...adapter,changeRules:rules} : adapter;
+  });
+  return resolveChangePolicy(svc, adapters);
+}
+
+/** Inventory fingerprints must not turn ignored fixture manifests into changes.
+ * Installed runtime dependency inventories remain independent of project files. */
+export function inventoryProjectFiles(svc: Pick<ServiceConfig, "coverage" | "changeRules">, files: readonly string[]): string[] {
+  const action = compileChangePolicy(serviceChangePolicy(svc, {requireResolved:true}));
+  return files.filter(file => action(file) !== "ignore");
+}
+
 function validateCoverageSourceOptions(service: string, options: unknown): asserts options is CoverageSourceOptions {
   if (!options || typeof options !== "object" || Array.isArray(options) ||
       !Object.keys(options).every(k => k === "sourceRoot" || k === "excludeSources")) {
@@ -323,6 +375,9 @@ function validateCoverageSourceOptions(service: string, options: unknown): asser
 /** Resolve adapter policies once per capture. Invalid/overlapping ownership is
  * an error, so one adapter cannot silently reinterpret another's reports. */
 export async function resolveCoverageSourceOptions(adapters: readonly CoverageAdapter[], ctx: CoverageSourceContext, fallback?: CoverageSourceOptions) {
+  await Promise.all(adapters.map(a => resolveAdapterChangeRules(a, {
+    ...ctx, sourceRoot: (typeof a.sourceOptions === "object" ? a.sourceOptions.sourceRoot : undefined) ?? fallback?.sourceRoot ?? ".",
+  })));
   return Promise.all(adapters.filter(a => a.sourceOptions !== undefined || a.defaultExcludeSources !== undefined || a.ownsReport).map(async a => {
     if (!a.ownsReport) throw new Error(`coverage adapter "${a.name}" needs ownsReport with sourceOptions`);
     let options = typeof a.sourceOptions === "function" ? await a.sourceOptions(ctx) : a.sourceOptions;
@@ -353,7 +408,7 @@ export function attachCoverageSourceOptions<T extends { reports: { name: string;
 function withWireName(a: CoverageAdapter): CoverageAdapter {
   if (Object.prototype.hasOwnProperty.call(a, "toJSON")) return a;
   return Object.assign(Object.create(Object.getPrototypeOf(a) as object | null), a, {
-    toJSON: () => ({ adapter: a.name, ...(a.defaultExcludeSources ? { defaultExcludeSources: a.defaultExcludeSources } : {}), ...(a.sourceOptions && typeof a.sourceOptions !== "function" ? { sourceOptions: a.sourceOptions } : {}) }),
+    toJSON: () => ({ adapter: a.name, ...(a.changeRules ? {changeRules: a.changeRules} : {}), ...(a.changeRuleGroups ? {changeRuleGroups: a.changeRuleGroups} : {}), ...(a.defaultExcludeSources ? { defaultExcludeSources: a.defaultExcludeSources } : {}), ...(a.sourceOptions && typeof a.sourceOptions !== "function" ? { sourceOptions: a.sourceOptions } : {}) }),
   }) as CoverageAdapter;
 }
 
@@ -973,6 +1028,8 @@ process.stdout.write(Array.from(out).sort().join("\\n") + (out.size ? "\\n" : ""
 `;
 
 export interface NodeCoverageOptions extends CoverageSourceOptions {
+  /** Replace this adapter's defaults, or false to disable them. */
+  changeRules?: readonly ChangeRule[] | false;
   /** Generated runtime entrypoints, relative to the service working directory.
    * Track their exact contents as units rather than inventing repository lines.
    * A content change changes the inventory and invalidates dependent tests. */
@@ -980,6 +1037,11 @@ export interface NodeCoverageOptions extends CoverageSourceOptions {
 }
 
 export function node(options: NodeCoverageOptions = {}): CoverageAdapter {
+  const policy = options.changeRules === undefined ? NODE_CHANGE_RULES : options.changeRules;
+  if (policy !== false) validateChangeRules(policy);
+  if (options.sourceRoot !== undefined || options.excludeSources !== undefined) {
+    validateCoverageSourceOptions("node", { sourceRoot: options.sourceRoot, excludeSources: options.excludeSources });
+  }
   if (options.generated !== undefined && (!Array.isArray(options.generated) || options.generated.some(p => typeof p !== "string"))) {
     throw new Error("coverage.node generated must be a list of relative files");
   }
@@ -990,6 +1052,7 @@ export function node(options: NodeCoverageOptions = {}): CoverageAdapter {
   }
   return {
     name: "node",
+    changeRules: policy === false ? [] : policy.map(rule => ({...rule})),
     defaultExcludeSources: JAVASCRIPT_GENERATED_SOURCES,
     ...(options.sourceRoot !== undefined || options.excludeSources !== undefined ? { sourceOptions: { sourceRoot: options.sourceRoot, excludeSources: options.excludeSources } } : {}),
     ownsReport: name => isNodeDumpName(name) || name === NODE_COVERAGE_EMPTY_REPORT,
@@ -1204,11 +1267,17 @@ export async function collectNodeReports(dir: string): Promise<NodeReportStats>
  * harvested first, and only this service's totals are taken and cleared. Nothing ran ⇒
  * an lcov with no records, which is a report saying so.
  */
-export function browser(options: CoverageSourceOptions = {}): CoverageAdapter {
+export interface BrowserCoverageOptions extends CoverageSourceOptions {
+  changeRules?: readonly ChangeRule[] | false;
+}
+export function browser(options: BrowserCoverageOptions = {}): CoverageAdapter {
+  const rules = options.changeRules === undefined ? BROWSER_CHANGE_RULES : options.changeRules;
+  if (rules !== false) validateChangeRules(rules);
   return {
     name: "browser",
+    changeRules: rules === false ? [] : rules.map(rule => ({...rule})),
     defaultExcludeSources: JAVASCRIPT_GENERATED_SOURCES,
-    ...(options.sourceRoot !== undefined || options.excludeSources !== undefined ? { sourceOptions: options } : {}),
+    ...(options.sourceRoot !== undefined || options.excludeSources !== undefined ? { sourceOptions: {sourceRoot: options.sourceRoot, excludeSources: options.excludeSources} } : {}),
     ownsReport: name => name === "browser.lcov",
     reports: "delta",
     load(ctx) {

package/src/daemon.ts

@@ -72,6 +72,8 @@ import {
   NODE_COVERAGE_SCRIPTS_SUBDIR,
   applyCoverageAdapters,
   coverageAdapters,
+  serviceChangePolicy,
+  inventoryProjectFiles,
   resolveCoverageSourceOptions,
   attachCoverageSourceOptions,
   coverageReportsMode,
@@ -123,7 +125,7 @@ import { evaluateChecked } from "./harness/eval-typecheck.js";
 import type { WrapperDiagnostic } from "./harness/wrapper-rules.js";
 import { cpus, tmpdir } from "node:os";
 import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath, takeProjectReads } from "./project-files.js";
-import { compactReach, projectReach, renderReachRules, renderReadsLcov, type ReachRules, type ReachSource } from "./harness/reach.js";
+import { compactReach, environmentReachSource, projectReach, renderReachRules, renderReadsLcov, type ReachRules, type ReachSource } from "./harness/reach.js";
 import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import {
   bindInstrumentationScope,
@@ -1382,7 +1384,7 @@ async function runServiceBuild(
     if (remote) {
       buildArgs = ["buildx", "build", "--builder", remote.builder,
         "--progress=plain", "--metadata-file", metadataPath,
-        "--output", shadowOutput(remoteReference!), ...argFlags,
+        "--output", shadowOutput(remoteReference!, remote), ...argFlags,
         "-f", dfPath, contextDir];
     } else if (useLocal) {
       // The in-VM builder is BuildKit's containerd worker on this VM's
@@ -1470,7 +1472,7 @@ async function runServiceBuild(
       const immutable = `${remoteReference!.split(":result")[0]}@${digest}`;
       const pullStarted = Date.now();
       const pulled = await shxStream("docker", ["pull", immutable], undefined, undefined, () => {});
-      await shadowTiming(name, "pull-unpack", pullStarted, { digest, ok: pulled.code === 0, lazy: false });
+      await shadowTiming(name, "pull-unpack", pullStarted, { digest, ok: pulled.code === 0, lazy: remote.imageFormat === "nydus-v6", imageFormat: remote.imageFormat ?? "oci-zstd" });
       if (pulled.code !== 0) return { ok: false, log: pulled.stderr };
       const tagged = await docker(["tag", immutable, tag]);
       if (tagged.code !== 0) return { ok: false, log: tagged.stderr };
@@ -3793,7 +3795,7 @@ async function writeCoverageInventory(svc: NamedService): Promise<string | undef
       }
       return { stdout: r.stdout, stderr: r.stderr };
     },
-    projectFiles: () => walkProjectFiles(WORKSPACE),
+    projectFiles: async () => inventoryProjectFiles(svc, await walkProjectFiles(WORKSPACE)),
     async readProjectFile(p: string) {
       // Not recorded as a read: an inventory fingerprinting every
       // manifest is bookkeeping, not the suite depending on the files.
@@ -3846,11 +3848,13 @@ async function computeProjectReach(all: NamedService[]): Promise<ReachRules> {
 
 async function computeProjectReachInner(all: NamedService[]): Promise<ReachRules> {
   const files = await walkProjectFiles(WORKSPACE, [".git"]);
-  const sources: ReachSource[] = [];
+  const sources: ReachSource[] = [environmentReachSource(ENVIRONMENT_SERVICE)];
   const owners = new Map(componentBuildTasks(all).map(t => [t.name, t.owner]));
   for (const svc of imageTasks(all)) {
+    const changePolicy = serviceChangePolicy(svc, {requireResolved: true});
     const src: ReachSource = {
       service: owners.get(svc.name) ?? svc.name,
+      changePolicy,
       volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source && !v.reachExempt ? [v.source] : [])),
       ...(svc.inputs && svc.inputs.length > 0 ? { inputs: [...svc.inputs] } : {}),
     };
@@ -3870,7 +3874,7 @@ async function computeProjectReachInner(all: NamedService[]): Promise<ReachRules
     sources.push(src);
   }
   const reach = projectReach(files, sources);
-  return { version: 1, sources, prefixes: compactReach(files, reach) };
+  return { version: 2, sources, prefixes: compactReach(files, reach) };
 }
 
 /**
@@ -3915,7 +3919,6 @@ async function captureServiceCoverage(baseline = false): Promise<ServiceCoverage
   });
   // 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): Promise<ServiceCoverageCapture> => {
       let policies: Awaited<ReturnType<typeof resolveCoverageSourceOptions>>;
@@ -3967,6 +3970,7 @@ async function captureServiceCoverage(baseline = false): Promise<ServiceCoverage
       try {
         return await adapter.collect!({
           ...coverageCaptureContext(svc, signal, new Set()),
+          changeRules: svc.changeRules,
           projectFiles: () => walkProjectFiles(WORKSPACE),
           async readProjectFile(p) {
             try { return await fs.readFile(resolveProjectPath(p, { record: false }), "utf8"); }
@@ -3977,7 +3981,8 @@ async function captureServiceCoverage(baseline = false): Promise<ServiceCoverage
         return [{ service: `${svc.name}/${adapter.name}`, reports: [], error: String(error) }];
       }
     })));
-  return [...captures, ...components.flat(), await environment];
+  // Freeze build-dependent policy only after all direct and nested adapters resolved it.
+  return [...captures, ...components.flat(), await captureEnvironmentCoverage(all, baseline)];
 }
 
 /** Per-Browser rrweb session shipped to the control plane. */
@@ -6074,7 +6079,7 @@ export function harnessMethods(state: RouteState): MethodTable {
   return {
     health: async () => ({
       ok: true,
-      capabilities: ["prepared-images-v1", "shadow-builder-v1"],
+      capabilities: ["prepared-images-v1", "shadow-builder-v1", "shadow-nydus-v1"],
       // Optional discovery: old SDKs omit this field and are never sent the
       // new method. Check the loaded project, including after warm restore.
       setupInteractive: typeof loaded?.project.interactive?.seed === "function",

package/src/harness/component-images.test.ts

@@ -1,6 +1,9 @@
 import { expect, test } from "bun:test";
 import { canonicalImageReference, componentBuildTasks, isComponentImageTask, isDigestReference, kubernetesImages } from "./component-images";
 import { validateServiceImage, type BuildImage } from "../index";
+import { node, rust, serviceChangePolicy } from "../coverage";
+import { evaluateChangePolicy } from "../change-rules";
+import { projectReach } from "./reach";
 
 test("services and Kubernetes share all Dockerfile build options without a type discriminator", () => {
   const image: BuildImage & { reference: string } = {
@@ -51,6 +54,45 @@ test("component image tasks are recognised by name and services are not", () =>
   expect(isComponentImageTask("spectest-image")).toBe(false);
 });
 
+test("image tasks retain each adapter policy and context without granting permissions to sibling images", () => {
+  const images = kubernetesImages([
+    { reference: "app/api:1", context: "packages/api", content: "FROM node:24",
+      coverage: { adapters: [node({ sourceRoot: "packages/api" })] } },
+    { reference: "app/worker:1", context: "crates/worker", content: "FROM rust:1",
+      coverage: { adapters: [rust({ sourceRoot: "crates/worker" })] },
+      changeRules: [{ root: "crates/worker", pattern: "generated/**", action: "ignore" }] },
+    { reference: "app/uncovered:1", context: "packages/uncovered", content: "FROM scratch" },
+  ]);
+  const tasks = componentBuildTasks([{ name: "cluster", image: "k3s:latest", imageBuilds: images.builds }]);
+  const [api, worker, uncovered] = tasks;
+  expect(api.coverage).toBeDefined();
+  expect(api.image).not.toHaveProperty("coverage");
+  expect(worker.image).not.toHaveProperty("changeRules");
+  expect(evaluateChangePolicy(serviceChangePolicy(api), "packages/api/main.ts")).toBe("coverage");
+  expect(evaluateChangePolicy(serviceChangePolicy(api), "crates/worker/main.rs")).toBeUndefined();
+  expect(evaluateChangePolicy(serviceChangePolicy(worker), "crates/worker/src/main.rs")).toBe("coverage");
+  expect(evaluateChangePolicy(serviceChangePolicy(worker), "crates/worker/generated/build.rs")).toBe("ignore");
+  expect(evaluateChangePolicy(serviceChangePolicy(uncovered), "packages/uncovered/main.ts")).toBeUndefined();
+  expect(evaluateChangePolicy(serviceChangePolicy(uncovered), "packages/uncovered/CLAUDE.md")).toBe("ignore");
+  const sources = tasks.map(task => ({ context: task.image.context }));
+  expect(projectReach(["packages/api/main.ts", "docs/outside.md"], sources)).toEqual(["packages/api/main.ts"]);
+  const serialized = JSON.parse(JSON.stringify(images.builds));
+  expect(serialized[0].coverage.adapters[0].changeRules).toBeDefined();
+  expect(serialized[1].changeRules[0].action).toBe("ignore");
+});
+
+test("cluster overrides reach its image tasks unless an image specializes them", () => {
+  const images = kubernetesImages([
+    { reference: "app/a:1", content: "FROM scratch" },
+    { reference: "app/b:1", content: "FROM scratch", changeRules: false },
+  ]);
+  const tasks = componentBuildTasks([{ name: "cluster", image: "k3s:latest", imageBuilds: images.builds,
+    changeRules: [{ pattern: "**/*.md", action: "full" as const }] }]);
+  expect(evaluateChangePolicy(serviceChangePolicy(tasks[0]), "README.md")).toBe("full");
+  expect(evaluateChangePolicy(serviceChangePolicy(tasks[1]), "README.md")).toBeUndefined();
+  expect(() => kubernetesImages([{ reference: "bad:1", content: "FROM scratch", changeRules: [{}] as never }])).toThrow();
+});
+
 test("only a full sha256 digest reference is immutable", () => {
   const digest = "a".repeat(64);
   expect(isDigestReference(`postgres@sha256:${digest}`)).toBe(true);

package/src/harness/component-images.ts

@@ -1,7 +1,13 @@
 import { createHash } from "node:crypto";
 import type { BuildImage, ComponentImageBuild, ServiceConfig } from "../index.js";
+import { validateChangeRules, type ChangeRule } from "../change-rules.js";
 
-export type KubernetesImage = string | (BuildImage & { reference: string; coverage?: import("../coverage.js").ServiceCoverage });
+export type KubernetesImage = string | (BuildImage & {
+  reference: string;
+  coverage?: import("../coverage.js").ServiceCoverage;
+  /** Override change-selection defaults for this image's own build context. */
+  changeRules?: readonly ChangeRule[] | false;
+});
 
 /** containerd/CRI use fully qualified names, including the default tag. */
 export function canonicalImageReference(reference: string): string {
@@ -51,8 +57,13 @@ export function kubernetesImages(images: readonly KubernetesImage[]): { pulls: s
     seen.set(reference, identity);
     if (typeof image === "string") pulls.push(image);
     else {
-      const { coverage: _coverage, ...build } = image;
-      builds.push({ reference, image: image.coverage === undefined ? image : build });
+      const { coverage, changeRules, ...build } = image;
+      if (changeRules !== undefined && changeRules !== false) validateChangeRules(changeRules);
+      builds.push({ reference,
+        image: coverage === undefined && changeRules === undefined ? image : build,
+        ...(coverage === undefined ? {} : { coverage }),
+        ...(changeRules === undefined ? {} : { changeRules }),
+      });
     }
   }
   return { pulls, builds };
@@ -74,6 +85,12 @@ export function componentBuildTasks<T extends ServiceConfig & { name: string }>(
     owner: svc.name,
     reference: build.reference,
     image: build.image,
+    ...(build.coverage === undefined ? {} : { coverage: build.coverage }),
+    // An image may specialize the cluster's explicit overrides. Each task
+    // keeps its own context and adapter source root; policies never leak to
+    // another image merely because the same cluster runs both.
+    ...(build.changeRules !== undefined || svc.changeRules !== undefined
+      ? { changeRules: build.changeRules ?? svc.changeRules } : {}),
   })));
 }
 

package/src/harness/coverage-target.ts

@@ -3,12 +3,14 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { attachCoverageSourceOptions, coverageAdapters, coverageReportsMode, resolveCoverageSourceOptions,
-  type CoverageCaptureContext, type CoverageInventoryContext, type ServiceCoverage } from "../coverage.js";
+  inventoryProjectFiles, type CoverageCaptureContext, type CoverageInventoryContext, type ServiceCoverage } from "../coverage.js";
+import type { ChangeRule } from "../change-rules.js";
 import { applyCoverageDelta, readCoverageDir, type ServiceCoverageCapture } from "./coverage.js";
 
 export async function captureCoverageTarget(options: {
   context: CoverageCaptureContext & CoverageInventoryContext;
   coverage: ServiceCoverage;
+  changeRules?: readonly ChangeRule[] | false;
   root: string;
   baseline: boolean;
   inventoryAvailable?: boolean;
@@ -39,7 +41,8 @@ export async function captureCoverageTarget(options: {
     }
     if (baseline && options.inventoryAvailable !== false) {
       const units = new Set<string>();
-      for (const adapter of adapters) for (const unit of await adapter.inventory?.(context) ?? []) units.add(unit);
+      const inventoryContext = {...context, projectFiles: async () => inventoryProjectFiles({coverage,changeRules:options.changeRules}, await context.projectFiles())};
+      for (const adapter of adapters) for (const unit of await adapter.inventory?.(inventoryContext) ?? []) units.add(unit);
       await context.writeReport("inventory.units", [...units].sort().join("\n"));
     }
     ctx.signal.throwIfAborted();