@specific.dev/spectest 0.119.4 → 0.119.5

package/src/coverage-next.test.ts

@@ -0,0 +1,132 @@
+import { describe, test, expect } from "bun:test";
+import { next, NEXT_COVERAGE_HELPER, NEXT_COVERAGE_HELPER_PATH, type NextBuildMetadata } from "./coverage-next.js";
+import { applyCoverageAdapters, resolveCoverageSourceOptions, attachCoverageSourceOptions, node, browser, type CoverageSourceContext } from "./coverage.js";
+import { withCoverage } from "./next.js";
+import { applyCoverageDelta, encodeCoverageBundle } from "./harness/coverage.js";
+import { gunzipSync } from "node:zlib";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const metadata: NextBuildMetadata = {generated:"server.js",serverMaps:1,browserMaps:1};
+const files = ["packages/dashboard/package.json", "packages/dashboard/app/page.tsx", "packages/shared/index.ts"];
+const image = {type:"dockerfile" as const,context:"packages",path:"Dockerfile"};
+function context(): CoverageSourceContext {
+  return {service:"web", signal:new AbortController().signal,
+    exec: async () => ({stdout:JSON.stringify(metadata),stderr:""}),
+    projectFiles:async()=>files, readProjectFile:async p=>p==="packages/dashboard/package.json" ? JSON.stringify({name:"fixture"}) : null};
+}
+
+describe("Next adapter", () => {
+  test("one adapter configures both collectors, uses its declared source root, and owns only its reports", async () => {
+    const adapter = next({sourceRoot:"packages"});
+    const configured = applyCoverageAdapters("web", {image,coverage:{adapters:[adapter]}});
+    expect(configured.env?.NODE_OPTIONS).toContain(`--require ${NEXT_COVERAGE_HELPER_PATH}`);
+    expect(configured.env?.NODE_OPTIONS).toContain("--require /spectest/coverage-hook.cjs");
+    expect(configured.files?.map(f=>f.path)).toEqual(["/spectest/coverage-hook.cjs",NEXT_COVERAGE_HELPER_PATH]);
+    let browserLoaded = false;
+    await adapter.load!({service:"web",collectBrowserScripts(){browserLoaded=true;}});
+    expect(browserLoaded).toBe(true);
+    const policies = await resolveCoverageSourceOptions([adapter],context());
+    expect(policies[0]!.options!.sourceRoot).toBe("packages");
+    const capture = attachCoverageSourceOptions({service:"web",reports:[
+      {name:"node-1.json",content:'{"result":[]}'}, {name:"browser.lcov",content:"TN:\n"},
+      {name:"other.lcov",content:"TN:\n"},
+    ]},policies);
+    expect(capture.reports[0]!.sourceOptions).toEqual(capture.reports[1]!.sourceOptions);
+    expect(capture.reports[2]!.sourceOptions).toBeUndefined();
+    const delta=applyCoverageDelta(capture,"cumulative",new Set());
+    expect(JSON.parse(gunzipSync(encodeCoverageBundle("case",[delta])).toString()).services[0].reports[1].sourceOptions.sourceRoot).toBe("packages");
+  });
+  test("sourceRoot defaults to the repository root and explicit roots are validated", async () => {
+    for (const sourceRoot of [null, "", "/app", "../app", "apps//web", "apps/./web", "C:\\app"]) {
+      expect(()=>next({sourceRoot} as any)).toThrow(/repository-relative/);
+    }
+    const ctx={...context(),image:{type:"registry" as const,reference:"web"}};
+    const policy=await resolveCoverageSourceOptions([next({sourceRoot:"apps/web"})],ctx);
+    expect(policy[0]!.options!.sourceRoot).toBe("apps/web");
+    for (const adapter of [next(), next({}), next({sourceRoot:undefined}), next({sourceRoot:"."})]) {
+      const policies = await resolveCoverageSourceOptions([adapter], context());
+      const capture = attachCoverageSourceOptions({reports:[{name:"node-1.json"},{name:"browser.lcov"}]}, policies);
+      expect(capture.reports.map(r => r.sourceOptions?.sourceRoot)).toEqual([".", "."]);
+      const configured = applyCoverageAdapters("web", {image, coverage:{adapters:[adapter]}});
+      expect(JSON.parse(configured.env!.SPECTEST_NEXT_COVERAGE_OPTIONS as string).sourceRoot).toBe(".");
+    }
+  });
+  test("node/browser options stay separate and duplicate report ownership is rejected", async () => {
+    const adapters=[node({sourceRoot:"server",excludeSources:["virtual://server/*"]}),browser({sourceRoot:"client"})];
+    const policies=await resolveCoverageSourceOptions(adapters,context());
+    const c=attachCoverageSourceOptions({reports:[{name:"node-1.json"},{name:"browser.lcov"}]},policies);
+    expect(c.reports[0]!.sourceOptions?.sourceRoot).toBe("server");
+    expect(c.reports[1]!.sourceOptions?.sourceRoot).toBe("client");
+    const duplicate=await resolveCoverageSourceOptions([next({sourceRoot:"packages"}),browser()],context());
+    expect(()=>attachCoverageSourceOptions({reports:[{name:"browser.lcov"}]},duplicate)).toThrow(/multiple adapters/);
+    expect(JSON.parse(JSON.stringify(applyCoverageAdapters("web",{image,coverage:{adapters}}))).coverage.adapters[1].sourceOptions.sourceRoot).toBe("client");
+  });
+  test("build helper preserves user settings and includes standalone maps", () => {
+    const c=withCoverage({output:"standalone",distDir:"build",experimental:{cpus:2},outputFileTracingIncludes:{"/*":["./assets/*"],"/api/*":["./data/*"]}}) as any;
+    expect(c.experimental).toEqual({cpus:2,serverSourceMaps:true});
+    expect(c.productionBrowserSourceMaps).toBe(true);
+    expect(c.outputFileTracingIncludes).toEqual({"/*":["./assets/*"],"/api/*":["./data/*"],"/**":["./build/server/**/*.map"]});
+  });
+  test("Webpack helper preserves hooks and disables dependency maps only", () => {
+    let called = false;
+    const config = withCoverage({ webpack(c: any) { called = true; return {...c, marker: true}; } });
+    const compiled = config.webpack({plugins: []});
+    expect(called).toBe(true);
+    expect(compiled.marker).toBe(true);
+    let loaderHook: (loader: any, module: any) => void;
+    compiled.plugins[0].apply({
+      hooks: {compilation: {tap(_name: string, f: Function) { f({}); }}},
+      webpack: {NormalModule: {getCompilationHooks() { return {
+        loader: {tap(_name: string, f: typeof loaderHook) { loaderHook = f; }},
+      }; }}},
+    });
+    for (const resource of ["/app/app/page.tsx", "/workspace/shared/index.ts", ""]) {
+      const loader = {sourceMap: true};
+      loaderHook!(loader, {resource});
+      expect(loader.sourceMap).toBe(true);
+    }
+    const dependency = {sourceMap: true};
+    loaderHook!(dependency, {resource: "/app/node_modules/next/dist/client/router.js"});
+    expect(dependency.sourceMap).toBe(false);
+  });
+  test("build hook retains traced maps and composes an existing compiler hook", async () => {
+    const dir=await fs.mkdtemp(path.join(os.tmpdir(),"next-trace-"));
+    try {
+      let called=false;
+      const config=withCoverage({compiler:{runAfterProductionCompile:async()=>{
+        called=true;
+        await fs.writeFile(path.join(dir,"page.js.map"),"{}");
+        await fs.writeFile(path.join(dir,"chunk.js.map"),"{}");
+        await fs.writeFile(path.join(dir,"page.js.nft.json"),JSON.stringify({version:1,files:["chunk.js","missing.js"]}));
+      }}});
+      await (config.compiler.runAfterProductionCompile as any)({projectDir:dir,distDir:dir});
+      expect(called).toBe(true);
+      expect(JSON.parse(await fs.readFile(path.join(dir,"page.js.nft.json"),"utf8")).files).toEqual(["chunk.js","missing.js","page.js.map","chunk.js.map"]);
+    } finally {await fs.rm(dir,{recursive:true,force:true});}
+  });
+  test("runtime probe distinguishes generated launcher from authored custom server and checks maps", async () => {
+    const dir=await fs.mkdtemp(path.join(os.tmpdir(),"next-cov-"));
+    const helper=path.join(dir,"helper.cjs");
+    try {
+      await fs.writeFile(helper,NEXT_COVERAGE_HELPER);
+      await fs.writeFile(path.join(dir,"package.json"),JSON.stringify({name:"fixture"}));
+      await fs.mkdir(path.join(dir,".next/server"),{recursive:true});
+      await fs.mkdir(path.join(dir,".next/static"),{recursive:true});
+      await fs.writeFile(path.join(dir,".next/required-server-files.json"),JSON.stringify({appDir:"/build",config:{output:"standalone",turbopack:{root:"/build"}}}));
+      await fs.writeFile(path.join(dir,".next/server/a.js.map"),JSON.stringify({sources:["turbopack:///[project]/app/page.tsx"]}));
+      await fs.writeFile(path.join(dir,".next/static/a.js.map"),JSON.stringify({sources:["app/client.tsx"]}));
+      await fs.writeFile(path.join(dir,"server.js"),"// authored custom server");
+      const probe=()=>JSON.parse(execFileSync("node",[helper],{cwd:dir,env:{...process.env,NODE_OPTIONS:"",SPECTEST_NEXT_COVERAGE_OPTIONS:"{}"},stdio:["ignore","pipe","pipe"]}).toString());
+      expect(probe().generated).toBeNull();
+      await fs.writeFile(path.join(dir,"server.js"),'process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = "{}"; require("next/dist/server/lib/start-server");');
+      expect(probe().generated).toBe("server.js");
+      expect(probe().serverMaps).toBe(1);
+      expect(probe().browserMaps).toBe(1);
+      await fs.rm(path.join(dir,".next/server/a.js.map"));
+      expect(probe).toThrow();
+    } finally {await fs.rm(dir,{recursive:true,force:true});}
+  });
+});

package/src/coverage-next.ts

@@ -0,0 +1,125 @@
+// 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 { node, browser, type CoverageAdapter, type CoverageSourceContext, type CoverageSourceOptions } from "./coverage.js";
+
+export interface NextCoverageOptions extends CoverageSourceOptions {
+  /** Repository-relative directory represented by the build's source-map root.
+   * Defaults to "." (repository root). Set explicitly for a nested build root. */
+  sourceRoot?: string;
+  /** Runtime app directory, relative to the container working directory. */
+  appDir?: string;
+  /** Next's build output directory, relative to appDir. Default: .next. */
+  distDir?: string;
+}
+
+export const NEXT_COVERAGE_HELPER_PATH = "/spectest/next-coverage.cjs";
+
+// Also preloaded before the Node hook. Only an identified standalone launcher
+// is generated: an authored server.js for a custom server remains application code.
+export const NEXT_COVERAGE_HELPER = String.raw`"use strict";
+const fs = require("node:fs"), path = require("node:path");
+const options = JSON.parse(process.env.SPECTEST_NEXT_COVERAGE_OPTIONS || "{}");
+const app = path.resolve(options.appDir || ".");
+const dist = path.resolve(app, options.distDir || ".next");
+function manifest() { return JSON.parse(fs.readFileSync(path.join(dist, "required-server-files.json"), "utf8")); }
+function launcher(m) {
+  const file = path.join(app, "server.js");
+  if (m.config.output !== "standalone" || !fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, "utf8");
+  if (!text.includes("__NEXT_PRIVATE_STANDALONE_CONFIG") || !text.includes("next/dist/server/lib/start-server")) return null;
+  return path.relative(process.cwd(), file);
+}
+try {
+  const file = launcher(manifest());
+  if (file) process.env.SPECTEST_COVERAGE_GENERATED_FILES = JSON.stringify([
+    ...new Set([...JSON.parse(process.env.SPECTEST_COVERAGE_GENERATED_FILES || "[]"), file])
+  ]);
+} catch {} // Capture reports a useful error; do not change application startup.
+if (require.main === module) {
+  try {
+    const m = manifest();
+    let serverMaps = 0, browserMaps = 0;
+    function walk(dir, server) {
+      if (!fs.existsSync(dir)) return;
+      for (const e of fs.readdirSync(dir, {withFileTypes:true})) {
+        const file = path.join(dir, e.name);
+        if (e.isDirectory()) walk(file, server);
+        else if (e.name.endsWith(".js.map")) {
+          if (server) serverMaps++; else browserMaps++;
+        }
+      }
+    }
+    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 withCoverage from @specific.dev/spectest/next in the test build and retain .next/server and .next/static maps when copying standalone output.");
+    process.stdout.write(JSON.stringify({generated:launcher(m), serverMaps, browserMaps}));
+  } catch (e) { console.error("Next coverage: " + e.message); process.exitCode = 1; }
+}
+`;
+
+export interface NextBuildMetadata {
+  generated: string | null;
+  serverMaps: number;
+  browserMaps: number;
+}
+
+const GENERATED_SOURCES = [
+  "webpack://*/", // Loader-only modules with an empty source identity.
+  "webpack://*/?*", // Loader-only modules without a resource path.
+  "webpack://*/external *", // Webpack external-module wrappers.
+  "*/data:* <text/javascript>", // Turbopack virtual modules, including action proxies.
+  "*/.next-internal/server/app/*/actions.js (server actions loader)",
+  "*/app/*--route-entry.js",
+  "*/app/*.mjs (structured image object)",
+];
+
+/** Server + browser coverage for a built Next app. Build-time maps are required;
+ * use withCoverage from @specific.dev/spectest/next in the Next configuration. */
+export function next(options: NextCoverageOptions = {}): CoverageAdapter {
+  const sourceRoot = options.sourceRoot === undefined ? "." : options.sourceRoot;
+  if (typeof sourceRoot !== "string" || !sourceRoot || /[\\:\0\r\n]/.test(sourceRoot) || (sourceRoot !== "." && sourceRoot.split("/").some(p => !p || p === "." || p === ".."))) throw new Error("coverage.next sourceRoot must be repository-relative (use \".\" for the repository root)");
+  options = { ...options, sourceRoot };
+  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 cache = new Map<string, Promise<NextBuildMetadata>>();
+  const metadata = (ctx: Pick<CoverageSourceContext, "service" | "exec">) => {
+    let value = cache.get(ctx.service);
+    if (!value) {
+      value = ctx.exec(`NODE_OPTIONS= node ${NEXT_COVERAGE_HELPER_PATH}`).then(r => JSON.parse(r.stdout) as NextBuildMetadata);
+      cache.set(ctx.service, value);
+      value.catch(() => cache.delete(ctx.service));
+    }
+    return value;
+  };
+  return {
+    name: "next", reports: "delta", explains: server.explains,
+    ownsReport: name => server.ownsReport!(name) || client.ownsReport!(name),
+    configure(svc, info) {
+      const configured = server.configure!(svc, info);
+      return { ...configured,
+        env: { ...configured.env,
+          NODE_OPTIONS: `--require ${NEXT_COVERAGE_HELPER_PATH} ${configured.env!.NODE_OPTIONS}`,
+          SPECTEST_NEXT_COVERAGE_OPTIONS: JSON.stringify(options),
+          SPECTEST_COVERAGE_SERVICE: info.key,
+        },
+        files: [...configured.files!, { path: NEXT_COVERAGE_HELPER_PATH, content: NEXT_COVERAGE_HELPER }],
+      };
+    },
+    load: client.load,
+    async sourceOptions(ctx) {
+      await metadata(ctx);
+      return { sourceRoot, excludeSources: [...GENERATED_SOURCES, ...(options.excludeSources ?? [])] };
+    },
+    async inventory(ctx) {
+      const m = await metadata(ctx);
+      return node({ generated: m.generated ? [m.generated] : [] }).inventory!(ctx);
+    },
+    async capture(ctx) {
+      await server.capture!(ctx);
+      await client.capture!(ctx);
+    },
+  };
+}

package/src/coverage.test.ts

@@ -59,6 +59,20 @@ describe("validateCoverage", () => {
       expect(() => validateCoverage("web", { adapters: [node()], sourceRoot })).toThrow();
     }
   });
+  test("source exclusions survive adapter configuration and wire serialization", () => {
+    const excludeSources = ["virtual:///compiler/*", "*/generated/[route]/loader.js"];
+    validateCoverage("web", { excludeSources });
+    const out = applyCoverageAdapters("web", { ...base, coverage: { adapters: [node(), browser()], excludeSources } });
+    expect(JSON.parse(JSON.stringify(out)).coverage.excludeSources).toEqual(excludeSources);
+    const configured = applyCoverageAdapters("web", { ...base, coverage: { adapters: [{
+      name: "compiler",
+      configure: service => ({ ...service, coverage: { ...service.coverage as object, excludeSources } }),
+    }] } });
+    expect(JSON.parse(JSON.stringify(configured)).coverage.excludeSources).toEqual(excludeSources);
+    for (const invalid of [null, "*", [1], [""], ["  "], ["bad\npath"], ["bad\0path"]]) {
+      expect(() => validateCoverage("web", { excludeSources: invalid })).toThrow();
+    }
+  });
   test("reports mode: cumulative unless declared; the shipped adapters write deltas", () => {
     expect(coverageReportsMode(undefined)).toBe("cumulative");
     expect(coverageReportsMode(true)).toBe("cumulative");
@@ -440,13 +454,14 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     const dir = await scratch();
     await fs.writeFile(path.join(dir, "main.js"), "globalThis.value = 1;\n");
     const leaf = { version: 3, sources: ["turbopack:///[project]/dashboard/page.ts", "webpack:///node_modules/pkg/a.js"],
-      sourcesContent: ["secret application source", "dependency source"], mappings: "AAAA,CCAA" };
+      ignoreList: [1], sourcesContent: ["secret application source", "dependency source"], mappings: "AAAA,CCAA" };
     await fs.writeFile(path.join(dir, "main.js.map"), JSON.stringify({ version: 3, sections: [
       { offset: { line: 0, column: 0 }, map: { version: 3, sections: [{ offset: { line: 0, column: 0 }, map: leaf }] } }
     ] }));
     expect(await runOnce(dir, "main.js")).toBe(0);
     const rec = (await records(dir)).get(`file://${path.join(dir, "main.js")}`)!;
     const text = JSON.stringify(rec.sourceMap);
+    expect(text).toContain('"ignoreList":[1]');
     expect(text).not.toContain("sourcesContent");
     expect(text).not.toContain("secret application source");
     expect(text).toContain('"x_spectestSourceUnits":[null,"npm:pkg"]');

package/src/coverage.ts

@@ -34,6 +34,7 @@ import { harvestAllBrowserCoverage, takeBrowserCoverageReport } from "./browser-
 
 import { COVERAGE_CONTAINER_DIR, type CoverageReportsMode } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR, type CoverageReportsMode };
+export { next, type NextCoverageOptions } from "./coverage-next.js";
 
 /** Where `node()` mounts its hook inside the container. */
 export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
@@ -110,9 +111,23 @@ export interface CoverageCaptureContext {
   signal: AbortSignal;
 }
 
+/** Source interpretation belongs to the adapter that produced each report. */
+export interface CoverageSourceOptions {
+  /** Repository-relative root corresponding to the report's source workspace. */
+  sourceRoot?: string;
+  /** Whole source identities; only `*` is special, including `/`. */
+  excludeSources?: readonly string[];
+}
+
+export type CoverageSourceContext = CoverageInventoryContext;
+
 export interface CoverageAdapter {
   /** Names the adapter in errors (`coverage adapter "node" on service …`). */
   name: string;
+  /** Archived on this adapter's reports; other adapters retain their own policy. */
+  sourceOptions?: CoverageSourceOptions | ((ctx: CoverageSourceContext) => Promise<CoverageSourceOptions>);
+  /** Required with sourceOptions, including reports written directly by a runtime. */
+  ownsReport?(name: string): boolean;
   /**
    * How the reports this adapter writes (through `ctx.writeReport`)
    * count: `"delta"` — what ran since the previous capture, the tool
@@ -167,10 +182,17 @@ export type ServiceCoverage =
   | {
       adapters?: readonly CoverageAdapter[];
       reports?: CoverageReportsMode;
-      /** Repository-relative root of this service's build/bundler workspace.
+      /** @deprecated Prefer adapter-owned sourceRoot.
+       * Repository-relative root of this service's build/bundler workspace.
        * For a monorepo built from packages/, set sourceRoot: "packages".
        * Paths are checked against the repository; no suffix guessing. */
       sourceRoot?: string;
+      /** @deprecated Prefer adapter-owned excludeSources.
+       * Reported source identities to omit from file coverage. `*` matches
+       * any characters, including `/`; everything else is literal. Use only
+       * for known generated/dependency sources, never missing application maps.
+       * Package unit coverage is retained. These rules are archived per capture. */
+      excludeSources?: readonly string[];
     };
 
 /** The `reports` mode of a `coverage` value, for the reports no adapter
@@ -192,10 +214,13 @@ export function validateCoverage(service: string, cov: unknown): void {
   const adapters = obj?.adapters;
   const reports = obj?.reports;
   const sourceRoot = obj?.sourceRoot;
+  const excludeSources = obj?.excludeSources;
   // `explains` is what `applyCoverageAdapters` adds for the wire; the
   // config is validated again after that, so it must pass here.
   const explains = obj?.explains;
-  const knownKeys = obj !== null && Object.keys(obj).every((k) => k === "adapters" || k === "reports" || k === "explains" || k === "sourceRoot");
+  const knownKeys = obj !== null && Object.keys(obj).every((k) => k === "adapters" || k === "reports" || k === "explains" || k === "sourceRoot" || k === "excludeSources");
+  const okExcludes = excludeSources === undefined || (Array.isArray(excludeSources) &&
+    excludeSources.every(p => typeof p === "string" && p.trim().length > 0 && !/[\0\r\n]/.test(p)));
   const okRoot = sourceRoot === undefined || (typeof sourceRoot === "string" &&
     (sourceRoot === "." || (sourceRoot.length > 0 && !sourceRoot.includes("\\") &&
       !sourceRoot.includes(":") && !sourceRoot.includes("\0") &&
@@ -203,7 +228,8 @@ export function validateCoverage(service: string, cov: unknown): void {
   const okReports = reports === undefined || reports === "delta" || reports === "cumulative";
   const okAdapters = adapters === undefined || Array.isArray(adapters);
   const okExplains = explains === undefined || (Array.isArray(explains) && explains.every((e) => typeof e === "string"));
-  if (obj !== null && knownKeys && okRoot && okReports && okAdapters && okExplains && (adapters !== undefined || reports !== undefined)) {
+  if (obj !== null && knownKeys && okRoot && okExcludes && okReports && okAdapters && okExplains &&
+      (adapters !== undefined || reports !== undefined || excludeSources !== undefined)) {
     for (const a of (adapters as unknown[] | undefined) ?? []) {
       const ok =
         typeof a === "object" &&
@@ -216,16 +242,20 @@ 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", "inventory"].every(
+        ["configure", "load", "capture", "inventory", "ownsReport"].every(
           (k) =>
             (a as Record<string, unknown>)[k] === undefined ||
             typeof (a as Record<string, unknown>)[k] === "function",
         );
-      if (!ok) {
+      const sourceOptions = (a as CoverageAdapter | null)?.sourceOptions;
+      const sourceShape = sourceOptions === undefined || (typeof (a as CoverageAdapter).ownsReport === "function" &&
+        (typeof sourceOptions === "function" || (typeof sourceOptions === "object" && sourceOptions !== null && !Array.isArray(sourceOptions))));
+      if (!ok || !sourceShape) {
         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)`,
         );
       }
+      if (sourceOptions !== undefined && typeof sourceOptions !== "function") validateCoverageSourceOptions(service, sourceOptions);
     }
     return;
   }
@@ -259,8 +289,10 @@ export function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc:
   // read it without knowing any adapter.
   const explains = [...new Set(adapters.flatMap((a) => a.explains ?? []))];
   const sourceRoot = typeof svc.coverage === "object" ? svc.coverage.sourceRoot : undefined;
+  const excludeSources = typeof out.coverage === "object" ? out.coverage.excludeSources : undefined;
   const wire = {
     ...(sourceRoot !== undefined ? { sourceRoot } : {}),
+    ...(excludeSources !== undefined ? { excludeSources } : {}),
     adapters: adapters.map((a) => withWireName(a)),
     ...(mode ? { reports: mode } : {}),
     ...(explains.length > 0 ? { explains } : {}),
@@ -268,10 +300,40 @@ export function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc:
   return { ...out, coverage: wire } as unknown as S;
 }
 
+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")) {
+    throw new Error(`service "${service}" has invalid adapter sourceOptions`);
+  }
+  validateCoverage(service, { adapters: [], ...options });
+}
+
+/** 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) {
+  return Promise.all(adapters.filter(a => a.sourceOptions !== undefined || a.ownsReport).map(async a => {
+    if (!a.ownsReport) throw new Error(`coverage adapter "${a.name}" needs ownsReport with sourceOptions`);
+    const options = typeof a.sourceOptions === "function" ? await a.sourceOptions(ctx) : a.sourceOptions;
+    if (a.sourceOptions !== undefined) validateCoverageSourceOptions(ctx.service, options);
+    return { adapter: a.name, ownsReport: a.ownsReport, options };
+  }));
+}
+
+export function attachCoverageSourceOptions<T extends { reports: { name: string; sourceOptions?: CoverageSourceOptions }[] }>(
+  capture: T, policies: Awaited<ReturnType<typeof resolveCoverageSourceOptions>>,
+): T {
+  for (const report of capture.reports) {
+    const matches = policies.filter(p => p.ownsReport(report.name));
+    if (matches.length > 1) throw new Error(`coverage report "${report.name}" belongs to multiple adapters: ${matches.map(p => p.adapter).join(", ")}`);
+    if (matches.length === 1) report.sourceOptions = matches[0]!.options;
+  }
+  return capture;
+}
+
 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 }),
+    toJSON: () => ({ adapter: a.name, ...(a.sourceOptions && typeof a.sourceOptions !== "function" ? { sourceOptions: a.sourceOptions } : {}) }),
   }) as CoverageAdapter;
 }
 
@@ -829,7 +891,7 @@ for (;;) {
 process.stdout.write(Array.from(out).sort().join("\\n") + (out.size ? "\\n" : ""));
 `;
 
-export interface NodeCoverageOptions {
+export interface NodeCoverageOptions extends CoverageSourceOptions {
   /** 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. */
@@ -847,6 +909,8 @@ export function node(options: NodeCoverageOptions = {}): CoverageAdapter {
   }
   return {
     name: "node",
+    ...(options.sourceRoot !== undefined || options.excludeSources !== undefined ? { sourceOptions: { sourceRoot: options.sourceRoot, excludeSources: options.excludeSources } } : {}),
+    ownsReport: name => isNodeDumpName(name) || name === NODE_COVERAGE_EMPTY_REPORT,
     reports: "delta",
     explains: NODE_EXPLAINS,
     async inventory(ctx) {
@@ -1054,9 +1118,11 @@ 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(): CoverageAdapter {
+export function browser(options: CoverageSourceOptions = {}): CoverageAdapter {
   return {
     name: "browser",
+    ...(options.sourceRoot !== undefined || options.excludeSources !== undefined ? { sourceOptions: options } : {}),
+    ownsReport: name => name === "browser.lcov",
     reports: "delta",
     load(ctx) {
       ctx.collectBrowserScripts();

package/src/daemon.ts

@@ -69,6 +69,8 @@ import {
   NODE_COVERAGE_SCRIPTS_SUBDIR,
   applyCoverageAdapters,
   coverageAdapters,
+  resolveCoverageSourceOptions,
+  attachCoverageSourceOptions,
   coverageReportsMode,
   validateCoverage,
   type CoverageAdapter,
@@ -4044,6 +4046,19 @@ async function captureServiceCoverage(baseline = false): Promise<ServiceCoverage
   const environment = captureEnvironmentCoverage(all, baseline);
   const captures = await Promise.all(
     services.map(async (svc): Promise<ServiceCoverageCapture> => {
+      let policies: Awaited<ReturnType<typeof resolveCoverageSourceOptions>>;
+      try {
+        policies = await resolveCoverageSourceOptions(coverageAdapters(svc.coverage), {
+          ...coverageCaptureContext(svc, AbortSignal.timeout(COVERAGE_CAPTURE_TIMEOUT_MS), new Set()),
+          projectFiles: () => walkProjectFiles(WORKSPACE),
+          async readProjectFile(p) {
+            try { return await fs.readFile(resolveProjectPath(p, { record: false }), "utf8"); }
+            catch { return null; }
+          },
+        });
+      } catch (err) {
+        return { service: svc.name, reports: [], error: `coverage source metadata: ${err instanceof Error ? err.message : String(err)}` };
+      }
       const { error, deltaReports } = await runCoverageAdapters(svc);
       if (error) return { service: svc.name, reports: [], error };
       if (baseline) {
@@ -4054,11 +4069,16 @@ async function captureServiceCoverage(baseline = false): Promise<ServiceCoverage
       if (baseline) {
         await fs.rm(path.join(coverageHostDir(WORKSPACE, svc.name), INVENTORY_REPORT), { force: true }).catch(() => {});
       }
+      try { attachCoverageSourceOptions(read, policies); }
+      catch (err) { read.error = `coverage source metadata: ${err instanceof Error ? err.message : String(err)}`; }
       const root = await coverageRoot(svc.name);
       if (root) read.root = root;
       if (typeof svc.coverage === "object" && svc.coverage.sourceRoot !== undefined) {
         read.sourceRoot = svc.coverage.sourceRoot;
       }
+      if (typeof svc.coverage === "object" && svc.coverage.excludeSources !== undefined) {
+        read.excludeSources = [...svc.coverage.excludeSources];
+      }
       // What ships is what ran during this capture, whatever the tool
       // counts: cumulative lcov is subtracted against the previous
       // capture (module memory, forks with the env); a delta adapter's

package/src/harness/browser-coverage.test.ts

@@ -48,6 +48,23 @@ describe("source maps", () => {
     expect(files.get("src/b.ts")!.get(5)).toBe(0);
   });
 
+  test("ignore metadata is local to each map section and standard metadata wins", () => {
+    const child = { version: 3, sources: ["src/a.ts", "virtual:///compiler/proxy"], mappings: "AAAA;ACAA", ignoreList: [1] };
+    const flat = decodeSourceMap(child)!;
+    expect([...mapToOriginal(flat, new Map([[1, 2], [2, 3]])).keys()]).toEqual(["src/a.ts"]);
+    const indexed = decodeSourceMap({ version: 3, sections: [
+      { offset: { line: 0, column: 0 }, map: child },
+      { offset: { line: 2, column: 0 }, map: { ...child, sources: ["virtual:///other", "src/b.ts"], ignoreList: [0] } },
+    ] })!;
+    expect([...mapToOriginal(indexed, new Map([[1, 2], [2, 3], [3, 4], [4, 5]])).keys()]).toEqual(["src/a.ts", "src/b.ts"]);
+    const legacy = { ...child, ignoreList: undefined, x_google_ignoreList: [1] };
+    expect([...mapToOriginal(decodeSourceMap(legacy)!, new Map([[2, 1]])).keys()]).toEqual([]);
+    expect([...mapToOriginal(decodeSourceMap({ ...legacy, ignoreList: [] })!, new Map([[2, 1]])).keys()]).toEqual(["virtual:///compiler/proxy"]);
+    for (const ignoreList of [null, [-1], [2], [0.5], ["1"]]) {
+      expect(decodeSourceMap({ ...child, ignoreList })).toBeNull();
+    }
+  });
+
   test("empty index maps are generated code; malformed maps remain unresolved", () => {
     expect(decodeSourceMap({ version: 3, sections: [] })).toEqual({ sources: [], lines: [] });
     expect(decodeSourceMap({ version: 3, sources: ["a"], mappings: "!!" })).toBeNull();

package/src/harness/browser-coverage.ts

@@ -91,6 +91,8 @@ export interface DecodedSourceMap {
   sources: string[];
   /** Segments per generated line (0-based), sorted by column. */
   lines: Segment[][];
+  /** Compiler-declared third-party/generated source indices. */
+  ignored?: Set<number>;
 }
 
 const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -195,6 +197,8 @@ export function decodeSourceMap(doc: unknown, depth = 0): DecodedSourceMap | nul
     sourceRoot?: unknown;
     mappings?: unknown;
     sections?: unknown;
+    ignoreList?: unknown;
+    x_google_ignoreList?: unknown;
   };
   if (m.sections !== undefined) {
     if (!Array.isArray(m.sections) || m.mappings !== undefined) return null;
@@ -212,6 +216,7 @@ export function decodeSourceMap(doc: unknown, depth = 0): DecodedSourceMap | nul
           i === line && segments.some(s => s.col >= column))) return null;
       const base = out.sources.length;
       for (const source of child.sources) out.sources.push(source);
+      for (const index of child.ignored ?? []) (out.ignored ??= new Set()).add(base + index);
       for (let i = 0; i < child.lines.length; i++) {
         const target = line + i;
         if (target > 1_000_000) return null;
@@ -230,6 +235,9 @@ export function decodeSourceMap(doc: unknown, depth = 0): DecodedSourceMap | nul
   const sources = m.sources.map((s) =>
     typeof s === "string" ? normalizeSourcePath(s, sourceRoot) : "",
   );
+  const ignored = m.ignoreList !== undefined ? m.ignoreList : m.x_google_ignoreList;
+  if (ignored !== undefined && (!Array.isArray(ignored) || ignored.some(i =>
+      !Number.isSafeInteger(i) || i < 0 || i >= sources.length))) return null;
   const lines: Segment[][] = [];
   let src = 0;
   let line = 0;
@@ -257,7 +265,7 @@ export function decodeSourceMap(doc: unknown, depth = 0): DecodedSourceMap | nul
   } catch {
     return null;
   }
-  return { sources, lines };
+  return { sources, lines, ...(ignored !== undefined ? { ignored: new Set(ignored as number[]) } : {}) };
 }
 
 /**
@@ -273,7 +281,7 @@ export function mapToOriginal(map: DecodedSourceMap, generated: LineCounts): Fil
     if (!segs || segs.length === 0) continue;
     for (const seg of segs) {
       const file = map.sources[seg.src];
-      if (file === undefined || isForeignSource(file)) continue;
+      if (file === undefined || map.ignored?.has(seg.src) || isForeignSource(file)) continue;
       let lc = out.get(file);
       if (!lc) {
         lc = new Map();

package/src/harness/coverage.test.ts

@@ -114,7 +114,7 @@ describe("readCoverageDir", () => {
 
 test("bundle round-trips and the ref summarises it", () => {
   const services = [
-    { service: "web", reports: [{ name: "lcov.info", content: "SF:/app/a.js\n" }] },
+    { service: "web", excludeSources: ["virtual:///compiler/*"], reports: [{ name: "lcov.info", content: "SF:/app/a.js\n" }] },
     { service: "api", reports: [], error: "no report" },
   ];
   const gz = encodeCoverageBundle("case-1", services);
@@ -193,10 +193,11 @@ describe("coverage delta", () => {
   test("applyCoverageDelta: cumulative reports are subtracted per service and name; delta and V8 reports pass", () => {
     resetCoverageDeltaMemory();
     const first = applyCoverageDelta(
-      { service: "api", reports: [{ name: "cov.lcov", content: boot }, { name: "node.lcov", content: later }, { name: "coverage-1.json", content: '{"result":[]}' }] },
+      { service: "api", excludeSources: ["virtual:///compiler/*"], reports: [{ name: "cov.lcov", content: boot }, { name: "node.lcov", content: later }, { name: "coverage-1.json", content: '{"result":[]}' }] },
       "cumulative",
       new Set(["node.lcov"]),
     );
+    expect(first.excludeSources).toEqual(["virtual:///compiler/*"]);
     // First capture: no previous, the whole boot set.
     expect(first.reports[0]!.content).toContain("SF:/app/a.py");
     expect(first.reports[0]!.content).toContain("SF:/app/b.py");