@specific.dev/spectest 0.131.20 → 0.132.0

package/src/browser-image-loading.test.ts

@@ -0,0 +1,51 @@
+import { expect, test } from "bun:test";
+import { readRaw } from "./inspect.js";
+import { openBrowser } from "./browser.js";
+
+const available = !!(Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"));
+const png = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=", "base64");
+
+for (const late of [false, true]) {
+  test.skipIf(!available)(`SDK recording preserves cookie-protected cross-origin images (${late ? "late" : "initial"})`, async () => {
+    const imageRequests: string[] = [];
+    const images = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch(request) {
+      // The SDK also fetches assets for replay. Count actual <img> requests
+      // separately so the regression catches recorder-induced image reloads.
+      if (request.headers.get("sec-fetch-dest") === "image") imageRequests.push(request.headers.get("cookie") ?? "");
+      if (!request.headers.get("cookie")?.includes("image_session=allowed")) return new Response("", { status: 401 });
+      return new Response(png, { headers: { "content-type": "image/png", "cache-control": "no-store" } });
+    } });
+    const page = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch() {
+      return new Response(`<!doctype html><body><script>
+        document.cookie = 'image_session=allowed; path=/';
+        window.loads = 0; window.errors = 0; window.changes = [];
+        window.addImage = () => {
+          const img = document.createElement('img'); img.id = 'subject';
+          new MutationObserver(records => window.changes.push(...records.map(r => r.attributeName)))
+            .observe(img, {attributes:true, attributeFilter:['crossorigin']});
+          img.onload = () => window.loads++; img.onerror = () => window.errors++;
+          img.src = ${JSON.stringify(images.url.href)}; document.body.append(img);
+        };
+        ${late ? "" : "window.addImage();"}
+      </script>`, { headers: { "content-type": "text/html" } });
+    } });
+    const browser = await openBrowser({ recorder: { sessionId: `image-${late}`, recordStep() {} } });
+    try {
+      await browser.goto(page.url.href);
+      if (late) await browser.evaluate("Insert image after recording starts", "window.addImage()");
+      // Wait through load and recorder callbacks, including asynchronous retries.
+      await browser.evaluate("Allow image capture to finish", "new Promise(resolve => setTimeout(resolve, 500))");
+      const state = await browser.evaluate("Inspect live image", `({
+        attr: document.querySelector('#subject').getAttribute('crossorigin'),
+        width: document.querySelector('#subject').naturalWidth,
+        loads: window.loads, errors: window.errors, changes: window.changes,
+        recording: !!window.__spectestRrwebInit
+      })`);
+      expect(readRaw(state)).toEqual({ attr: null, width: 1, loads: 1, errors: 0, changes: [], recording: true });
+      expect(imageRequests).toEqual(["image_session=allowed"]);
+    } finally {
+      await browser.close();
+      page.stop(true); images.stop(true);
+    }
+  }, 15000);
+}

package/src/browser.ts

@@ -672,7 +672,8 @@ async function applySafeAreaInsets(
 
 // Vendored `@rrweb/record` UMD bundle (rrweb 2.x), BUILT FROM OUR FORK by
 // `scripts/rrweb-record/build.sh` (specific-dev/rrweb, branch `spectest` =
-// the `rrweb@2.1.0` tag + upstream PR 1802). Never copy the npm dist over
+// the `rrweb@2.1.0` tag + upstream PR 1802 + non-mutating image capture).
+// Never copy the npm dist over
 // it: upstream's `@rrweb/utils` lists `querySelector` as an accessor, so its
 // pristine-prototype test always fails and `record()` appends an <iframe>
 // to every document — measured at ~1 s per navigation (see the top-frame
@@ -766,7 +767,8 @@ const RRWEB_BOOTSTRAP = `
       // CSS (what next/font emits), so it's a no-op for most apps; the
       // url()-based fonts are handled by the inliner below instead. All
       // degrade gracefully — an asset that can't be read is skipped,
-      // never fatal to recording.
+      // never fatal to recording. Our fork never changes a live image's
+      // crossorigin attribute to retry a failed canvas read.
       inlineStylesheet: true,
       collectFonts: true,
       inlineImages: true,

package/src/change-rules.fixtures.json

@@ -0,0 +1,35 @@
+[
+ {"pattern":"**/*.ts","path":"helper.ts","matches":true},
+ {"pattern":"**/*.ts","path":"a/b/helper.ts","matches":true},
+ {"pattern":"*.ts","path":"a/helper.ts","matches":false},
+ {"pattern":"src/**","path":"src/a/b.ts","matches":true},
+ {"pattern":"src","path":"src/a.ts","matches":false},
+ {"pattern":"app/\\[id\\]/page.tsx","path":"app/[id]/page.tsx","matches":true},
+ {"pattern":"app/[[]id]/page.tsx","path":"app/[id]/page.tsx","matches":true},
+ {"pattern":"app/[id]/page.tsx","path":"app/[id]/page.tsx","matches":false},
+ {"pattern":"app/[id]/page.tsx","path":"app/i/page.tsx","matches":true},
+ {"pattern":"app/(shop)/\\[...slug\\]/page.tsx","path":"app/(shop)/[...slug]/page.tsx","matches":true},
+ {"pattern":"a?b.ts","path":"a😀b.ts","matches":true},
+ {"pattern":"a?b.ts","path":"a/b.ts","matches":false},
+ {"pattern":"[!a].ts","path":"b.ts","matches":true},
+ {"pattern":"[!a].ts","path":"a.ts","matches":false},
+ {"pattern":"[!a].ts","path":"/.ts","matches":false},
+ {"pattern":"[a-c].ts","path":"b.ts","matches":true},
+ {"pattern":"[a-c].ts","path":"d.ts","matches":false},
+ {"pattern":"[😀-🙏].ts","path":"😂.ts","matches":true},
+ {"pattern":"**/*.md","path":"a/line\nbreak.md","matches":true},
+ {"pattern":"file.ts","path":"file.ts\n","matches":false},
+ {"pattern":"!odd#name:foo+.ts","path":"!odd#name:foo+.ts","matches":true},
+ {"pattern":" leading space.ts","path":" leading space.ts","matches":true},
+ {"pattern":"file\\*.ts","path":"file*.ts","matches":true},
+ {"pattern":"*.{ts,js}","path":"a.ts","matches":false},
+ {"pattern":"a/[z-a]","invalid":true},
+ {"pattern":"a/[.-0]","invalid":true},
+ {"pattern":"a/[abc","invalid":true},
+ {"pattern":"a/[]","invalid":true},
+ {"pattern":"a/\\","invalid":true},
+ {"pattern":"foo**bar.ts","invalid":true},
+ {"pattern":"../secret","invalid":true},
+ {"pattern":"/absolute","invalid":true},
+ {"pattern":"a//b","invalid":true}
+]

package/src/change-rules.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from "bun:test";
+import fixtures from "./change-rules.fixtures.json";
+import { compileChangeGlob, matchesChangeGlob, evaluateChangePolicy, resolveChangePolicy, COMMON_CHANGE_RULES, NODE_CHANGE_RULES, NEXT_CHANGE_RULES, type ChangeRule } from "./change-rules.js";
+import { node, next, bun, browser, rust, command, applyCoverageAdapters, serviceChangePolicy, defineAdapter, resolveCoverageSourceOptions, inventoryProjectFiles } from "./coverage.js";
+const image = {type: "registry" as const, reference: "node:24"};
+const action = (adapter: ReturnType<typeof node>, path: string) => evaluateChangePolicy(serviceChangePolicy({coverage:{adapters:[adapter]}}), path);
+describe("portable change glob", () => {
+  for (const fixture of fixtures) test(JSON.stringify(fixture.pattern) + " " + (fixture.path ?? "invalid"), () => {
+    if (fixture.invalid) expect(() => compileChangeGlob(fixture.pattern)).toThrow();
+    else expect(matchesChangeGlob(fixture.pattern, fixture.path!)).toBe(fixture.matches!);
+  });
+});
+describe("change rule defaults and overrides", () => {
+  test("documentation defaults work without coverage, with false opt-out", () => {
+    const svc = applyCoverageAdapters("db", {image});
+    expect(svc).toEqual({image});
+    for (const path of ["AGENTS.md", "nested/CLAUDE.md", "notes.MD", "a/readme.markdown"]) expect(evaluateChangePolicy(serviceChangePolicy(svc), path)).toBe("ignore");
+    expect(evaluateChangePolicy(serviceChangePolicy({changeRules:false}), "AGENTS.md")).toBeUndefined();
+    expect(evaluateChangePolicy(serviceChangePolicy(svc), "app.mdx")).toBeUndefined();
+  });
+  test("JS test patterns, configuration and roots", () => {
+    for (const adapter of [node(), bun(), browser(), next()]) {
+      for (const path of ["src/math.test.ts", "src/math.spec.tsx", "src/math_test.mjs", "src/math_spec.cts", "src/a.test-d.ts", "src/a.cy.tsx", "__tests__/helper.json", "__mocks__/fetch.ts", "__snapshots__/a.snap", "tests/helper.ts", "jest.config.ts", "vitest.config.mjs"]) expect(action(adapter, path)).toBe("ignore");
+      for (const path of ["src/a.ts", "src/a.jsx", "src/a.mts"]) expect(action(adapter, path)).toBe("coverage");
+      for (const path of ["migrations/001.ts", "webpack.config.ts", "tsconfig.json", ".env.local"]) expect(action(adapter, path)).toBe("full");
+    }
+    expect(action(node({sourceRoot:"packages/api"}), "packages/api/test/a.ts")).toBe("ignore");
+    expect(action(node({sourceRoot:"packages/api"}), "packages/other/a.ts")).toBeUndefined();
+    expect(action(bun(), "bunfig.toml")).toBe("full");
+  });
+  test("Next specializations survive any adapter ordering", () => {
+    for (const adapters of [[next(),node(),browser()],[browser(),node(),next()]]) {
+      const policy = serviceChangePolicy({coverage:{adapters}});
+      for (const path of ["app/layout.tsx", "app/error.tsx", "proxy.ts", "instrumentation-client.ts", "mdx-components.tsx", "pages/_app.tsx", "next.config.mjs", "app/content.mdx"]) expect(evaluateChangePolicy(policy,path)).toBe("full");
+      for (const path of ["app/hello/page.tsx", "app/api/new/route.ts", "pages/a.test.tsx"]) expect(evaluateChangePolicy(policy,path)).toBe("coverage");
+    }
+  });
+  test("Rust defaults distinguish tests, build inputs and production", () => {
+    for (const path of ["tests/integration.rs", "benches/perf.rs"]) expect(action(rust(),path)).toBe("ignore");
+    for (const path of ["src/lib.rs", "src/tests.rs", "examples/server.rs"]) expect(action(rust(),path)).toBe("coverage");
+    for (const path of ["Cargo.toml", "Cargo.lock", "build.rs", ".cargo/config.toml", "rust-toolchain.toml", "src/bin/server.rs"]) expect(action(rust(),path)).toBe("full");
+  });
+  test("service rules are ordered final overrides and adapter options replace defaults", () => {
+    const rules: ChangeRule[] = [{pattern:"**/*.ts",action:"ignore"}, {pattern:"migrations/**",action:"full"}, {pattern:String.raw`migrations/\[seed\].ts`,action:"coverage"}];
+    const svc = applyCoverageAdapters("api", {image,coverage:{adapters:[node()]},changeRules:rules});
+    const twice = applyCoverageAdapters("api", svc);
+    for (const configured of [svc,twice]) {
+      const policy = serviceChangePolicy(configured);
+      expect(evaluateChangePolicy(policy,"a.ts")).toBe("ignore");
+      expect(evaluateChangePolicy(policy,"migrations/a.ts")).toBe("full");
+      expect(evaluateChangePolicy(policy,"migrations/[seed].ts")).toBe("coverage");
+      expect(JSON.parse(JSON.stringify(configured)).changeRules).toEqual(rules);
+      expect(JSON.parse(JSON.stringify(policy))).toEqual(policy);
+    }
+    for (const factory of [node,next,browser,bun,rust]) {
+      expect(action(factory({changeRules:false}),"src/a.ts")).toBeUndefined();
+      expect(action(factory({changeRules:[{pattern:"**/*.go",action:"coverage"}]}),"src/a.go")).toBe("coverage");
+    }
+    expect(Object.isFrozen(NODE_CHANGE_RULES)).toBe(true);
+    expect(Object.isFrozen(NEXT_CHANGE_RULES)).toBe(true);
+    expect(Object.isFrozen(COMMON_CHANGE_RULES)).toBe(true);
+  });
+  test("dynamic source roots need explicit policies; wrappers retain independent groups", () => {
+    const dynamic = defineAdapter({name:"dynamic",ownsReport:()=>true,sourceOptions:async()=>({sourceRoot:"runtime"}),changeRules:[{pattern:"**/*.ts",action:"coverage" as const}]});
+    expect(()=>serviceChangePolicy({coverage:{adapters:[dynamic]}})).toThrow();
+    const policy = serviceChangePolicy({coverage:{adapters:[{...dynamic,changeRules:dynamic.changeRules!.map(r=>({...r,root:"src"}))}]}});
+    expect(evaluateChangePolicy(policy,"src/a.ts")).toBe("coverage");
+    const nested = resolveChangePolicy({},[{changeRuleGroups:[[{root:"app",pattern:"**/*.ts",action:"coverage"}],[{root:"app",pattern:"shared.ts",action:"full"}]]}]);
+    expect(evaluateChangePolicy(nested,"app/shared.ts")).toBe("full");
+    expect(action(command("collect"),"src/a.ts")).toBeUndefined();
+  });
+  test("Spectest execution files stay active while nearby Markdown is ignored", () => {
+    const policy = serviceChangePolicy({coverage:{adapters:[node()]}});
+    expect(evaluateChangePolicy(policy,"spectest/helper.test.ts")).toBe("full");
+    expect(evaluateChangePolicy(policy,"spectest/tests/__mocks__/helper.ts")).toBe("coverage");
+    expect(evaluateChangePolicy(policy,"spectest/tests/AGENTS.md")).toBe("ignore");
+    expect(evaluateChangePolicy(policy,"migrations/README.md")).toBe("ignore");
+    expect(action(rust(),"src/bin/README.md")).toBe("ignore");
+  });
+  test("Next capture freezes configured route extensions and rejects divergent runtimes", async () => {
+    const adapter = next();
+    const svc = {coverage:{adapters:[adapter]}};
+    const missing = serviceChangePolicy(svc,{requireResolved:true});
+    expect(evaluateChangePolicy(missing,"pages/README.md")).toBe("full");
+    expect(evaluateChangePolicy(missing,"src/a.test.ts")).toBe("full");
+    const nested = next({sourceRoot:"apps/web"});
+    const unknownNested = serviceChangePolicy({coverage:{adapters:[nested]}},{requireResolved:true});
+    expect(evaluateChangePolicy(unknownNested,"apps/web/a.ts")).toBe("full");
+    expect(evaluateChangePolicy(unknownNested,"other/a.ts")).toBeUndefined();
+    const context = (extensions: string[], appRoot = "") => ({service:"web",signal:new AbortController().signal,
+      projectFiles:async()=>[],readProjectFile:async()=>null,
+      exec:async()=>({stdout:JSON.stringify({generated:null,serverMaps:1,browserMaps:1,pageExtensions:extensions,appRoot}),stderr:""})});
+    await resolveCoverageSourceOptions([adapter],context(["tsx","md"]));
+    const policy = serviceChangePolicy(svc,{requireResolved:true});
+    expect(evaluateChangePolicy(policy,"pages/a.md")).toBe("coverage");
+    expect(evaluateChangePolicy(policy,"pages/a.test.tsx")).toBe("coverage");
+    expect(evaluateChangePolicy(policy,"pages/a.test.ts")).toBe("ignore");
+    expect(evaluateChangePolicy(policy,"app/new/page.md")).toBe("coverage");
+    expect(evaluateChangePolicy(policy,"app/new/README.md")).toBe("ignore");
+    expect(evaluateChangePolicy(policy,"migrations/README.md")).toBe("ignore");
+    expect(evaluateChangePolicy(policy,"pages/_app.tsx")).toBe("full");
+    await expect(resolveCoverageSourceOptions([adapter],{...context(["ts"]),service:"other"})).rejects.toThrow("inconsistent change rules");
+    const ordinary = next();
+    await resolveCoverageSourceOptions([ordinary],context(["tsx"],"web"));
+    const ordinaryPolicy = serviceChangePolicy({coverage:{adapters:[ordinary]}},{requireResolved:true});
+    expect(evaluateChangePolicy(ordinaryPolicy,"web/pages/a.test.tsx")).toBe("coverage");
+    expect(evaluateChangePolicy(ordinaryPolicy,"web/pages/README.md")).toBe("ignore");
+  });
+  test("ignored fixture manifests cannot change a Node inventory, explicit overrides can", async () => {
+    const adapter = node();
+    const svc = {coverage:{adapters:[adapter]}};
+    const files = ["package.json","__tests__/fixture/package.json"];
+    const inventory = (version: string, changeRules?: ChangeRule[]) => adapter.inventory!({service:"app",signal:new AbortController().signal,
+      projectFiles:async()=>inventoryProjectFiles({...svc,changeRules},files),
+      readProjectFile:async file=>JSON.stringify({name:file,dependencies:{dependency:file.startsWith("__tests__") ? version : "1"}}),
+      exec:async()=>({stdout:"",stderr:""})});
+    expect(await inventory("1")).toEqual(await inventory("2"));
+    const override: ChangeRule[] = [{pattern:"__tests__/**",action:"coverage"}];
+    expect(await inventory("1",override)).not.toEqual(await inventory("2",override));
+  });
+  test("malformed declarations cannot silently broaden selection", () => {
+    for (const rule of [{pattern:"**/*.ts",action:"wat"},{pattern:"../file",action:"ignore"},{pattern:"**",action:"ignore",root:"/absolute"},{pattern:"**",action:"ignore",extra:true}]) expect(()=>serviceChangePolicy({changeRules:[rule] as any})).toThrow();
+    expect(()=>serviceChangePolicy({changeRules:null as any})).toThrow();
+  });
+});

package/src/change-rules.ts

@@ -0,0 +1,147 @@
+/** Portable source-change policy, evaluated identically by the SDK and controller.
+ * Globs match whole root-relative paths: *, ?, [], [!], ** and backslash escapes.
+ * Braces/extglobs have no special meaning. Directory rules explicitly use /**. */
+export type ChangeAction = "coverage" | "full" | "ignore";
+export interface ChangeRule { root?: string; pattern: string; action: ChangeAction }
+export interface ResolvedChangeRule extends ChangeRule { root: string }
+export interface ChangePolicy { defaults: readonly (readonly ResolvedChangeRule[])[]; overrides: readonly ResolvedChangeRule[] }
+export interface ChangeRuleAdapter {
+  changeRules?: readonly ChangeRule[];
+  /** Wrappers preserve independent nested adapter policies, including roots. */
+  changeRuleGroups?: readonly (readonly ChangeRule[])[];
+  sourceOptions?: { sourceRoot?: string } | ((...args: any[]) => unknown);
+}
+export interface ChangeRuleService {
+  /** Explicit rules override all defaults. false disables defaults. */
+  changeRules?: readonly ChangeRule[] | false;
+  coverage?: boolean | { sourceRoot?: string };
+}
+const literal = (c: string) => /[\\^$.*+?()[\]{}|/]/u.test(c) ? `\\${c}` : c;
+const classLiteral = (c: string) => ["\\", "[", "]", "^", "-"].includes(c) ? `\\${c}` : c;
+export function compileChangeGlob(pattern: string): RegExp {
+  if (!pattern || pattern.includes("\0") || pattern.startsWith("/") || pattern.split("/").some(p => p === "" || p === "." || p === "..")) throw new Error("change-rule pattern must be a nonempty relative glob without traversal");
+  const chars = [...pattern]; let out = "";
+  for (let i = 0; i < chars.length; i++) {
+    const c = chars[i]!;
+    if (c === "\\") {
+      const next = chars[++i];
+      if (next === undefined || next === "/") throw new Error("invalid glob escape");
+      out += literal(next);
+    } else if (c === "*") {
+      if (chars[i + 1] === "*") {
+        i++;
+        if ((i > 1 && chars[i - 2] !== "/") || (i + 1 < chars.length && chars[i + 1] !== "/")) throw new Error("** must occupy a whole path segment");
+        if (chars[i + 1] === "/") { i++; out += "(?:[\\s\\S]*/)?"; } else out += "[\\s\\S]*";
+      } else out += "[^/]*";
+    } else if (c === "?") out += "[^/]";
+    else if (c === "[") {
+      let negate = false; if (chars[i + 1] === "!") { negate = true; i++; }
+      const members: { c: string; escaped: boolean }[] = [];
+      let closed = false;
+      while (++i < chars.length) {
+        let ch = chars[i]!;
+        if (ch === "]") { closed = true; break; }
+        let escaped = false;
+        if (ch === "\\") { ch = chars[++i]!; escaped = true; if (ch === undefined) throw new Error("invalid class escape"); }
+        if (ch === "/") throw new Error("glob classes cannot match separators");
+        members.push({ c: ch, escaped });
+      }
+      if (!closed || !members.length) throw new Error("unterminated or empty glob class");
+      let body = "";
+      for (let j = 0; j < members.length; j++) {
+        const m = members[j]!;
+        if (members[j + 1]?.c === "-" && !members[j + 1]!.escaped && members[j + 2]) {
+          const end = members[j + 2]!;
+          if (m.c.codePointAt(0)! > end.c.codePointAt(0)! || (m.c.codePointAt(0)! <= 47 && end.c.codePointAt(0)! >= 47)) throw new Error("invalid glob range");
+          body += `${classLiteral(m.c)}-${classLiteral(end.c)}`; j += 2;
+        } else body += classLiteral(m.c);
+      }
+      // Prefix slash in a negated class so it remains segment-scoped.
+      out += `[${negate ? "^/" : ""}${body}]`;
+    } else out += literal(c);
+  }
+  return new RegExp(`^(?:${out})$(?![\\s\\S])`, "u");
+}
+export function matchesChangeGlob(pattern: string, path: string): boolean { return compileChangeGlob(pattern).test(path); }
+export function validateChangeRules(value: unknown): asserts value is readonly ChangeRule[] {
+  if (!Array.isArray(value)) throw new Error("changeRules must be an array or false");
+  for (const rule of value) {
+    if (!rule || typeof rule !== "object" || Array.isArray(rule) || !Object.keys(rule).every(k => ["root", "pattern", "action"].includes(k)) || typeof rule.pattern !== "string" || !["coverage", "full", "ignore"].includes(rule.action)) throw new Error("invalid change rule");
+    if (rule.root !== undefined && (typeof rule.root !== "string" || (rule.root !== "." && (!rule.root || rule.root.includes("\\") || rule.root.includes("\0") || rule.root.split("/").some((p: string) => !p || p === "." || p === ".."))))) throw new Error("change-rule root must be repository-relative");
+    compileChangeGlob(rule.pattern);
+  }
+}
+const freeze = (rules: ChangeRule[]): readonly ChangeRule[] => Object.freeze(rules.map(r => Object.freeze(r)));
+export const COMMON_CHANGE_RULES = freeze(["**/*.md", "**/*.markdown", "**/*.MD", "**/*.MARKDOWN"].map(pattern => ({ pattern, action: "ignore" })));
+const extensions = ["js", "jsx", "mjs", "cjs", "ts", "tsx", "mts", "cts"];
+const full = (pattern: string): ChangeRule => ({pattern, action: "full"});
+const ignore = (pattern: string): ChangeRule => ({pattern, action: "ignore"});
+const coverage = (pattern: string): ChangeRule => ({pattern, action: "coverage"});
+export const JAVASCRIPT_CHANGE_RULES = freeze([
+  ...extensions.map(ext => coverage(`**/*.${ext}`)),
+  full("**/migrations/**"),
+  ...extensions.flatMap(ext => [full(`**/*.config.${ext}`), full(`**/.babelrc.${ext}`), full(`**/.pnp.${ext}`), full(`**/.pnp.loader.${ext}`)]),
+  ...["**/tsconfig*.json", "**/jsconfig*.json", "**/.babelrc", "**/.babelrc.json", "**/.swcrc", "**/.env", "**/.env.*"].map(full),
+  ...extensions.flatMap(ext => [ignore(`**/test.${ext}`), ignore(`**/spec.${ext}`)]),
+  ...extensions.flatMap(ext => [".test", ".spec", "_test", "_spec", ".test-d", ".spec-d", ".cy"].map(suffix => ignore(`**/*${suffix}.${ext}`))),
+  ...["**/__tests__/**", "**/__mocks__/**", "**/__snapshots__/**", "test/**", "tests/**", "e2e/**", "cypress/**", "playwright/**"].map(ignore),
+  ...[...extensions, "json"].flatMap(ext => ["jest", "vitest", "playwright", "cypress"].map(tool => ignore(`**/${tool}.config.${ext}`))),
+  ...COMMON_CHANGE_RULES,
+]);
+export const NODE_CHANGE_RULES = JAVASCRIPT_CHANGE_RULES;
+export const BROWSER_CHANGE_RULES = JAVASCRIPT_CHANGE_RULES;
+export const BUN_CHANGE_RULES = freeze([...NODE_CHANGE_RULES, full("**/bunfig.toml")]);
+const sharedNext = ["layout", "template", "error", "global-error", "loading", "not-found", "default", "forbidden", "unauthorized", "middleware", "proxy", "instrumentation", "instrumentation-client", "mdx-components", "_app", "_document", "_error"];
+export const NEXT_CHANGE_RULES = freeze([
+  ...JAVASCRIPT_CHANGE_RULES,
+  // Pages-router files are routes even if their names resemble unit tests.
+  ...["pages", "src/pages"].flatMap(root => extensions.map(ext => coverage(`${root}/**/*.${ext}`))),
+  ...["app", "src/app"].flatMap(root => extensions.flatMap(ext => [coverage(`${root}/**/page.${ext}`), coverage(`${root}/**/route.${ext}`)])),
+  full("**/*.mdx"), full("**/*.MDX"),
+  ...extensions.flatMap(ext => sharedNext.map(name => full(`**/${name}.${ext}`))),
+]);
+export const RUST_CHANGE_RULES = freeze([
+  coverage("**/*.rs"), ignore("tests/**"), ignore("benches/**"),
+  ...["**/Cargo.toml", "**/Cargo.lock", "**/.cargo/config", "**/.cargo/config.toml", "**/rust-toolchain", "**/rust-toolchain.toml", "**/build.rs", "src/bin/**"].map(full),
+  ...COMMON_CHANGE_RULES,
+]);
+export function resolveChangePolicy(service: ChangeRuleService, adapters: readonly ChangeRuleAdapter[] = []): ChangePolicy {
+  if (service.changeRules !== undefined && service.changeRules !== false) validateChangeRules(service.changeRules);
+  const serviceRoot = typeof service.coverage === "object" ? service.coverage.sourceRoot ?? "." : ".";
+  const resolve = (rules: readonly ChangeRule[], root: string): ResolvedChangeRule[] => {
+    validateChangeRules(rules); const out = rules.map(r => ({ ...r, root: r.root ?? root })); validateChangeRules(out); return out;
+  };
+  const defaults: ResolvedChangeRule[][] = service.changeRules === false ? [] : [resolve([{pattern:"spectest/**",action:"full"}, {pattern:"spectest/tests/**",action:"coverage"}, ...COMMON_CHANGE_RULES], ".")];
+  if (service.changeRules !== false) for (const adapter of adapters) {
+    const groups = [...(adapter.changeRules ? [adapter.changeRules] : []), ...(adapter.changeRuleGroups ?? [])];
+    const root = typeof adapter.sourceOptions === "object" ? adapter.sourceOptions.sourceRoot ?? serviceRoot : serviceRoot;
+    for (const group of groups) {
+      if (typeof adapter.sourceOptions === "function" && group.some(r => r.root === undefined)) throw new Error("dynamic sourceOptions requires explicit change-rule roots");
+      defaults.push(resolve(group, root));
+    }
+  }
+  return { defaults, overrides: resolve(service.changeRules || [], serviceRoot) };
+}
+/** Compile once for scans over a source tree; regexes carry no mutable flags. */
+export function compileChangePolicy(policy: ChangePolicy): (path: string) => ChangeAction | undefined {
+  const compile = (rules: readonly ResolvedChangeRule[]) => rules.map(r => ({...r, regex:compileChangeGlob(r.pattern)}));
+  const defaults = policy.defaults.map(compile), overrides = compile(policy.overrides);
+  const groupAction = (rules: ReturnType<typeof compile>, path: string) => {
+    let result: ChangeAction | undefined;
+    for (const r of rules) {
+      const rel = r.root === "." ? path : path === r.root ? "" : path.startsWith(r.root + "/") ? path.slice(r.root.length + 1) : undefined;
+      if (rel !== undefined && r.regex.test(rel)) result = r.action;
+    }
+    return result;
+  };
+  const rank = {ignore: 1, coverage: 2, full: 3};
+  return path => {
+    const override = groupAction(overrides, path); if (override) return override;
+    let result: ChangeAction | undefined;
+    for (const rules of defaults) { const action = groupAction(rules,path); if (action && (!result || rank[action] > rank[result])) result = action; }
+    return result;
+  };
+}
+export function evaluateChangePolicy(policy: ChangePolicy, path: string): ChangeAction | undefined {
+  return compileChangePolicy(policy)(path);
+}

package/src/components/k3s-coverage.test.ts

@@ -158,3 +158,35 @@ test("collection bounds parallel targets and shares lazy discovery for command a
     expect(commands.filter(command => command.includes("capture-probe"))).toHaveLength(11);
   } finally { await fs.rm(root, { recursive: true, force: true }); }
 }, 10000);
+
+test("nested inventory uses cluster overrides unless an image supplies its own", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "k3s-policy-inventory-"));
+  try {
+    const id = "c".repeat(16);
+    const dir = path.join(root, ".pods", id);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, ".instance.json"), JSON.stringify({ id, image: image.reference, container: "api", namespace: "app", root: "/app" }));
+    await fs.writeFile(path.join(dir, "app.lcov"), "TN:\n");
+    const adapter: CoverageAdapter = { name: "manifest", async inventory(ctx) {
+      return (await ctx.projectFiles()).map(file => `manifest:${file}`);
+    } };
+    const pod = { metadata: { name: "api", annotations: { "spectest.dev/coverage": JSON.stringify({ instances: [id] }) } },
+      status: { containerStatuses: [{ name: "api", state: { running: {} } }] } };
+    const ctx = { service: "k8s", reportDir: root, signal: AbortSignal.timeout(5000),
+      changeRules: [{ pattern: "**/fixtures/**", action: "ignore" as const }],
+      projectFiles: async () => ["app/package.json", "app/fixtures/package.json"],
+      readProjectFile: async () => null, writeReport: async () => {},
+      exec: async () => ({ stdout: JSON.stringify({ items: [pod] }), stderr: "" }),
+    };
+    const capture = async (restoreFixture: boolean) => {
+      const bridge = k3sCoverage([{ ...image, coverage: { adapters: [adapter] },
+        ...(restoreFixture ? { changeRules: [{ pattern: "**/fixtures/**", action: "full" as const }] } : {}),
+      }]);
+      const [result] = await bridge.adapter().collect!(ctx, true);
+      expect(result.error).toBeUndefined();
+      return result.reports.find(report => report.name === "inventory.units")?.content;
+    };
+    expect(await capture(false)).toBe("manifest:app/package.json");
+    expect(await capture(true)).toBe("manifest:app/fixtures/package.json\nmanifest:app/package.json");
+  } finally { await fs.rm(root, { recursive: true, force: true }); }
+});

package/src/components/k3s-coverage.ts

@@ -33,12 +33,12 @@ export interface K3sCoverageDependencies {
 /** One component-owned bridge; runtime adapters remain unaware of Kubernetes. */
 export function k3sCoverage(images: readonly KubernetesImage[]) {
   const declarations = images.flatMap(image => typeof image === "string" || image.coverage === undefined ? [] : [{
-    reference: canonicalImageReference(image.reference), coverage: image.coverage,
+    reference: canonicalImageReference(image.reference), coverage: image.coverage, changeRules: image.changeRules,
   }]);
   for (const image of declarations) {
     const adapters = coverageAdapters(image.coverage);
     if (adapters.some(adapter => adapter.load || adapter.collect)) throw new Error("k3s image coverage accepts container adapters; put browser coverage on the cluster service");
-    applyCoverageAdapters(image.reference, { image: { type: "registry", reference: image.reference }, coverage: image.coverage });
+    applyCoverageAdapters(image.reference, { image: { type: "registry", reference: image.reference }, coverage: image.coverage, changeRules: image.changeRules });
   }
   const metadata = new Map<string, ImageInfo>();
   const service = (cluster: string, reference: string) => `${cluster}/image-${hash(reference)}`;
@@ -136,7 +136,7 @@ export function k3sCoverage(images: readonly KubernetesImage[]) {
         // adapter's functions would otherwise disappear from JSON.stringify.
         toJSON() { return { adapter: "k3s-containers", images: declarations.map(image => ({
           reference: image.reference,
-          config: applyCoverageAdapters(image.reference, { image: { type: "registry", reference: image.reference }, coverage: image.coverage }),
+          config: applyCoverageAdapters(image.reference, { image: { type: "registry", reference: image.reference }, coverage: image.coverage, changeRules: image.changeRules }),
         })) }; },
         async collect(ctx, baseline) {
           const root = path.join(ctx.reportDir, ".pods");
@@ -176,7 +176,7 @@ export function k3sCoverage(images: readonly KubernetesImage[]) {
               }
             }
             const captured = await captureCoverageTarget({
-              coverage: declaration.coverage, root: instance.root, baseline,
+              coverage: declaration.coverage, changeRules: declaration.changeRules ?? ctx.changeRules, root: instance.root, baseline,
               inventoryAvailable: baseline && adapters.some(a => a.inventory) ? !!await livePod() : false,
               counterKey: `${service(ctx.service, instance.image)}/${id}`,
               context: { ...ctx, service: service(ctx.service, instance.image), reportDir: dir,

package/src/components/supabase-coverage.ts

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import type { CoverageAdapter } from "../coverage.js";
+import { COMMON_CHANGE_RULES, NODE_CHANGE_RULES, type ChangeRule } from "../change-rules.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 
 // Drain all work even on failure: no writes may outlive the capture boundary.
@@ -21,6 +22,17 @@ export function supabaseFunctionsCoverage(functionRoot: string): CoverageAdapter
     name: "supabase-functions",
     reports: "delta",
     sourceOptions: { sourceRoot: "." },
+    // Ordinary modules follow callers, including shared modules outside the
+    // functions directory. Concrete reach still limits which paths this
+    // service owns. Directory-discovered entrypoints remain in the inventory.
+    changeRules: [
+      ...["**/deno.json", "**/deno.jsonc", "**/deno.lock", "**/import_map.json"].map(pattern => ({ pattern, action: "full" as const })),
+      ...NODE_CHANGE_RULES,
+      ...["config.toml", "config.json"].map(pattern => ({ root: path.posix.dirname(functionRoot), pattern, action: "full" as const })),
+      // Migration directory conventions in the JS preset must not make
+      // incidental Markdown defeat the shared documentation default.
+      ...COMMON_CHANGE_RULES,
+    ] satisfies ChangeRule[],
     ownsReport: name => name.startsWith("edge-") || name.startsWith("edge-scripts/"),
     async inventory(ctx) {
       // Functions are discovered by directory, not by an import in user code.

package/src/components/supabase-dir.test.ts

@@ -11,6 +11,9 @@ import { join } from "node:path";
 import { google } from "./google.js";
 import { supabase } from "./supabase.js";
 import type { ServiceConfig, ServicesMap } from "../index.js";
+import { serviceChangePolicy } from "../coverage.js";
+import { evaluateChangePolicy } from "../change-rules.js";
+import { reachContains } from "../harness/reach.js";
 
 let root: string;
 const prevWorkspace = process.env.SPECTEST_WORKSPACE;
@@ -93,6 +96,29 @@ function expand(stack: ReturnType<typeof supabase>, name = "supabase"): Services
 const svc = (parts: ServicesMap, key: string): ServiceConfig => parts[key] as ServiceConfig;
 
 describe("supabase({ dir })", () => {
+  test("database reach follows an alternate directory while preserving runtime Markdown templates", () => {
+    mkdirSync(join(root, "custom/backend/migrations"), { recursive: true });
+    writeFileSync(join(root, "custom/invite[en].md"), "Welcome {{ .Token }}");
+    const parts = expand(supabase({
+      dir: "custom/backend",
+      configOverrides: { auth: { email: { template: { invite: { content_path: "custom/invite[en].md" } } } } },
+    }));
+    const db = svc(parts, "db");
+    expect(db.inputs).toEqual([
+      "custom/backend/config.toml", "custom/backend/config.json", "custom/backend/migrations", "custom/backend/seed.sql", "custom/invite[en].md",
+    ]);
+    expect(db.volumes?.[0]).toMatchObject({ source: join(root, "custom/backend"), reachExempt: true });
+    const reach = { version: 1, sources: [{ inputs: [...db.inputs!] }], prefixes: [] };
+    expect(reachContains(reach, "custom/backend/migrations/new.sql")).toBe(true);
+    expect(reachContains(reach, "custom/backend/functions/new/index.ts")).toBe(false);
+    expect(reachContains(reach, "supabase/config.toml")).toBe(false);
+    const policy = serviceChangePolicy(db);
+    expect(evaluateChangePolicy(policy, "custom/backend/migrations/notes.md")).toBe("ignore");
+    expect(evaluateChangePolicy(policy, "custom/invite[en].md")).toBe("full");
+    expect(evaluateChangePolicy(policy, "custom/invitee.md")).toBe("ignore");
+    expect(evaluateChangePolicy(policy, "custom/backend/config.json")).toBe("full");
+  });
+
   test("overrides hook addresses without moving migrations or leaking env references", () => {
     const stack = supabase({
       dir: "supabase",

package/src/components/supabase-functions-reach.test.ts

@@ -6,6 +6,10 @@ import { join } from "node:path";
 import { excludeAllBut, functionsReach, importMapLocalTargets, importSpecifiers } from "./supabase-functions-reach.js";
 import { serviceDockerignore } from "../harness/build-context.js";
 import { projectReach, reachContains } from "../harness/reach.js";
+import { inventoryProjectFiles, serviceChangePolicy } from "../coverage.js";
+import { evaluateChangePolicy } from "../change-rules.js";
+import type { ServiceConfig } from "../index.js";
+import { supabaseFunctionsCoverage } from "./supabase-coverage.js";
 
 let root: string;
 
@@ -71,6 +75,31 @@ describe("parsers", () => {
 });
 
 describe("supabase() wiring", () => {
+  test("ignored test fixtures do not change inventory while actual function config and discovery do", async () => {
+    const adapter = supabaseFunctionsCoverage("supabase/functions");
+    const service = { coverage: { adapters: [adapter] } };
+    const files: Record<string, string> = {
+      "supabase/functions/hello/index.ts": "Deno.serve(() => new Response());",
+      "supabase/functions/hello/deno.json": '{"imports":{}}',
+      "supabase/functions/__tests__/fixture/deno.json": '{"imports":{}}',
+      "supabase/functions/__tests__/fixture/package.json": '{"dependencies":{}}',
+    };
+    const inventory = () => adapter.inventory!({ service: "edge", signal: AbortSignal.timeout(1000),
+      projectFiles: async () => inventoryProjectFiles(service, Object.keys(files)),
+      readProjectFile: async p => files[p] ?? null,
+      exec: async () => { throw new Error("inventory should only read project metadata"); },
+    });
+    const baseline = await inventory();
+    files["supabase/functions/__tests__/fixture/deno.json"] = '{"imports":{"x":"./fixture.ts"}}';
+    files["supabase/functions/__tests__/fixture/package.json"] = '{"dependencies":{"x":"2"}}';
+    expect(await inventory()).toEqual(baseline);
+    files["supabase/functions/hello/deno.json"] = '{"imports":{"x":"./helper.ts"}}';
+    const configured = await inventory();
+    expect(configured).not.toEqual(baseline);
+    files["supabase/functions/new/index.ts"] = "Deno.serve(() => new Response());";
+    expect(await inventory()).not.toEqual(configured);
+  });
+
   test("the functions image context is the module graph, and the root mount is reach-exempt", async () => {
     const prev = process.env.SPECTEST_WORKSPACE;
     process.env.SPECTEST_WORKSPACE = root;
@@ -83,7 +112,18 @@ describe("supabase() wiring", () => {
       expect(fn.image.exclude?.slice(0, 9)).toEqual(["**", "!lib/db", "!lib/db/**", "!packages/shared/src", "!packages/shared/src/**", "!packages/util", "!packages/util/**", "!supabase/functions", "!supabase/functions/**"]);
       expect(fn.image.exclude?.at(-1)).toBe("**/.venv/**");
       expect(fn.volumes?.[0]).toMatchObject({ source: root, reachExempt: true });
-      expect((parts.db as { inputs?: readonly string[] }).inputs).toEqual(["supabase"]);
+      const db = parts.db as ServiceConfig;
+      expect(db.inputs).toEqual(["supabase/config.toml", "supabase/config.json", "supabase/migrations", "supabase/seed.sql"]);
+      const dbRules = serviceChangePolicy(db);
+      expect(evaluateChangePolicy(dbRules, "supabase/migrations/002.sql")).toBe("full");
+      expect(evaluateChangePolicy(dbRules, "supabase/config.json")).toBe("full");
+      expect(evaluateChangePolicy(dbRules, "supabase/seed.sql")).toBe("full");
+      expect(evaluateChangePolicy(dbRules, "supabase/migrations/AGENTS.md")).toBe("ignore");
+      expect(projectReach(["supabase/functions/hello/index.ts", "supabase/functions/hello/index_test.ts"], [{ inputs: [...db.inputs!] }])).toEqual([]);
+      const fnRules = serviceChangePolicy(parts.functions as ServiceConfig);
+      expect(evaluateChangePolicy(fnRules, "packages/shared/src/new-helper.ts")).toBe("coverage");
+      expect(evaluateChangePolicy(fnRules, "supabase/functions/hello/index_test.ts")).toBe("ignore");
+      expect(evaluateChangePolicy(fnRules, "supabase/functions/deno.json")).toBe("full");
       const sources = [
         { context: fn.image.context, ignore: serviceDockerignore(null, fn.image.exclude) },
         { inputs: [...(parts.db as { inputs: string[] }).inputs] },

package/src/components/supabase-migrations.test.ts

@@ -41,7 +41,7 @@ test("hundreds of sorted migrations and a seed use one exec without reading SQL
   for (let i = 558; i >= 0; i--) writeFileSync(join(root, "migrations", `${String(i).padStart(4, "0")}.sql`), "select 1");
   writeFileSync(join(root, "migrations", "ignored.txt"), "not SQL");
   const services = parts(root);
-  expect(services.db!.volumes).toContainEqual({ source: root, target: "/spectest/supabase", readOnly: true });
+  expect(services.db!.volumes).toContainEqual({ source: root, target: "/spectest/supabase", readOnly: true, reachExempt: true });
   const calls: { service: string; command: string[]; opts?: ExecOpts }[] = [];
   await services.migrations!.setup!({
     exec: async (service: string, command: string[], opts?: ExecOpts) => {