@specific.dev/spectest 0.119.7 → 0.120.1

package/dist/coverage-javascript.d.ts

@@ -0,0 +1 @@
+export declare const JAVASCRIPT_GENERATED_SOURCES: readonly ["webpack/bootstrap", "*/webpack/bootstrap", "webpack/runtime/*", "*/webpack/runtime/*", "webpack://*/", "webpack://*/?*", "webpack://*/external *"];

package/dist/coverage-javascript.js

@@ -0,0 +1,11 @@
+// Bundler-generated source identities shared by browser and Node coverage.
+// Do not match arbitrary webpack:// sources: those include authored modules.
+export const JAVASCRIPT_GENERATED_SOURCES = [
+    "webpack/bootstrap",
+    "*/webpack/bootstrap",
+    "webpack/runtime/*",
+    "*/webpack/runtime/*",
+    "webpack://*/", // Loader-only modules with an empty source identity.
+    "webpack://*/?*", // Loader-only modules without a resource path.
+    "webpack://*/external *", // Webpack external-module wrappers.
+];

package/dist/coverage-next.d.ts

@@ -16,5 +16,6 @@ export interface NextBuildMetadata {
     browserMaps: number;
 }
 /** Server + browser coverage for a built Next app. Build-time maps are required;
- * use withCoverage from @specific.dev/spectest/next in the Next configuration. */
+ * enable native Next source maps and retain them in the runtime image.
+ * Configure this adapter only in Spectest; the application needs no SDK dependency. */
 export declare function next(options?: NextCoverageOptions): CoverageAdapter;

package/dist/coverage-next.js

@@ -1,6 +1,7 @@
 // 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 { JAVASCRIPT_GENERATED_SOURCES } from "./coverage-javascript.js";
 import { node, browser } from "./coverage.js";
 export const NEXT_COVERAGE_HELPER_PATH = "/spectest/next-coverage.cjs";
 // Also preloaded before the Node hook. Only an identified standalone launcher
@@ -40,22 +41,20 @@ 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 withCoverage from @specific.dev/spectest/next in the test build and retain .next/server and .next/static maps when copying standalone output.");
+    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}));
   } catch (e) { console.error("Next coverage: " + e.message); process.exitCode = 1; }
 }
 `;
 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. */
+ * enable native Next source maps and retain them in the runtime image.
+ * Configure this adapter only in Spectest; the application needs no SDK dependency. */
 export function next(options = {}) {
     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 === "..")))
@@ -77,6 +76,7 @@ export function next(options = {}) {
         return value;
     };
     return {
+        defaultExcludeSources: JAVASCRIPT_GENERATED_SOURCES,
         name: "next", reports: "delta", explains: server.explains,
         ownsReport: name => server.ownsReport(name) || client.ownsReport(name),
         configure(svc, info) {

package/dist/coverage.d.ts

@@ -88,7 +88,9 @@ export interface CoverageAdapter {
     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. */
+    /** Generated scaffolding excluded in addition to explicit or legacy source policy. */
+    defaultExcludeSources?: readonly string[];
+    /** Required with sourceOptions/defaultExcludeSources, including runtime reports. */
     ownsReport?(name: string): boolean;
     /**
      * How the reports this adapter writes (through `ctx.writeReport`)
@@ -172,7 +174,7 @@ export declare function coverageAdapters(cov: ServiceCoverage | undefined): read
 export declare function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc: S): S;
 /** Resolve adapter policies once per capture. Invalid/overlapping ownership is
  * an error, so one adapter cannot silently reinterpret another's reports. */
-export declare function resolveCoverageSourceOptions(adapters: readonly CoverageAdapter[], ctx: CoverageSourceContext): Promise<{
+export declare function resolveCoverageSourceOptions(adapters: readonly CoverageAdapter[], ctx: CoverageSourceContext, fallback?: CoverageSourceOptions): Promise<{
     adapter: string;
     ownsReport: (name: string) => boolean;
     options: CoverageSourceOptions | undefined;

package/dist/coverage.js

@@ -27,6 +27,7 @@
 //   import * as coverage from "@specific.dev/spectest/coverage";
 //   coverage: { adapters: [coverage.node(), coverage.browser()] }
 import { createHash } from "node:crypto";
+import { JAVASCRIPT_GENERATED_SOURCES } from "./coverage-javascript.js";
 import { harvestAllBrowserCoverage, takeBrowserCoverageReport } from "./browser-coverage.js";
 import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR };
@@ -89,13 +90,17 @@ export function validateCoverage(service, cov) {
                 ["configure", "load", "capture", "inventory", "ownsReport"].every((k) => a[k] === undefined ||
                     typeof a[k] === "function");
             const sourceOptions = a?.sourceOptions;
+            const defaults = a?.defaultExcludeSources;
+            const defaultShape = defaults === undefined || typeof a.ownsReport === "function";
             const sourceShape = sourceOptions === undefined || (typeof a.ownsReport === "function" &&
                 (typeof sourceOptions === "function" || (typeof sourceOptions === "object" && sourceOptions !== null && !Array.isArray(sourceOptions))));
-            if (!ok || !sourceShape) {
+            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)`);
             }
             if (sourceOptions !== undefined && typeof sourceOptions !== "function")
                 validateCoverageSourceOptions(service, sourceOptions);
+            if (defaults !== undefined)
+                validateCoverageSourceOptions(service, { excludeSources: defaults });
         }
         return;
     }
@@ -146,13 +151,22 @@ function validateCoverageSourceOptions(service, 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, ctx) {
-    return Promise.all(adapters.filter(a => a.sourceOptions !== undefined || a.ownsReport).map(async (a) => {
+export async function resolveCoverageSourceOptions(adapters, ctx, fallback) {
+    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`);
-        const options = typeof a.sourceOptions === "function" ? await a.sourceOptions(ctx) : a.sourceOptions;
+        let options = typeof a.sourceOptions === "function" ? await a.sourceOptions(ctx) : a.sourceOptions;
         if (a.sourceOptions !== undefined)
             validateCoverageSourceOptions(ctx.service, options);
+        if (a.defaultExcludeSources !== undefined) {
+            validateCoverageSourceOptions(ctx.service, { excludeSources: a.defaultExcludeSources });
+            // Defaults must not discard the source root/exclusions of older configs.
+            // Explicit adapter options still replace that service-level fallback.
+            options ??= fallback;
+            if (options !== undefined)
+                validateCoverageSourceOptions(ctx.service, options);
+            options = { ...options, excludeSources: [...new Set([...a.defaultExcludeSources, ...(options?.excludeSources ?? [])])] };
+        }
         return { adapter: a.name, ownsReport: a.ownsReport, options };
     }));
 }
@@ -170,7 +184,7 @@ function withWireName(a) {
     if (Object.prototype.hasOwnProperty.call(a, "toJSON"))
         return a;
     return Object.assign(Object.create(Object.getPrototypeOf(a)), a, {
-        toJSON: () => ({ adapter: a.name, ...(a.sourceOptions && typeof a.sourceOptions !== "function" ? { sourceOptions: a.sourceOptions } : {}) }),
+        toJSON: () => ({ adapter: a.name, ...(a.defaultExcludeSources ? { defaultExcludeSources: a.defaultExcludeSources } : {}), ...(a.sourceOptions && typeof a.sourceOptions !== "function" ? { sourceOptions: a.sourceOptions } : {}) }),
     });
 }
 /** `env` with `value` appended to `name` (space-separated), or set. */
@@ -725,6 +739,7 @@ export function node(options = {}) {
     }
     return {
         name: "node",
+        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,
         reports: "delta",
@@ -929,6 +944,7 @@ export async function collectNodeReports(dir) {
 export function browser(options = {}) {
     return {
         name: "browser",
+        defaultExcludeSources: JAVASCRIPT_GENERATED_SOURCES,
         ...(options.sourceRoot !== undefined || options.excludeSources !== undefined ? { sourceOptions: options } : {}),
         ownsReport: name => name === "browser.lcov",
         reports: "delta",

package/dist/daemon.js

@@ -3300,7 +3300,10 @@ async function captureServiceCoverage(baseline = false) {
                         return null;
                     }
                 },
-            });
+            }, typeof svc.coverage === "object" ? {
+                sourceRoot: svc.coverage.sourceRoot,
+                excludeSources: svc.coverage.excludeSources,
+            } : undefined);
         }
         catch (err) {
             return { service: svc.name, reports: [], error: `coverage source metadata: ${err instanceof Error ? err.message : String(err)}` };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.119.7",
+  "version": "0.120.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,11 +21,6 @@
       "bun": "./src/coverage.ts",
       "default": "./dist/coverage.js"
     },
-    "./next": {
-      "types": "./dist/next.d.ts",
-      "bun": "./src/next.ts",
-      "default": "./dist/next.js"
-    },
     "./browser": {
       "types": "./dist/browser.d.ts",
       "bun": "./src/browser.ts",

package/src/coverage-javascript.ts

@@ -0,0 +1,11 @@
+// Bundler-generated source identities shared by browser and Node coverage.
+// Do not match arbitrary webpack:// sources: those include authored modules.
+export const JAVASCRIPT_GENERATED_SOURCES = [
+  "webpack/bootstrap",
+  "*/webpack/bootstrap",
+  "webpack/runtime/*",
+  "*/webpack/runtime/*",
+  "webpack://*/", // Loader-only modules with an empty source identity.
+  "webpack://*/?*", // Loader-only modules without a resource path.
+  "webpack://*/external *", // Webpack external-module wrappers.
+] as const;

package/src/coverage-next.test.ts

@@ -1,7 +1,6 @@
 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";
@@ -30,6 +29,9 @@ describe("Next adapter", () => {
     expect(browserLoaded).toBe(true);
     const policies = await resolveCoverageSourceOptions([adapter],context());
     expect(policies[0]!.options!.sourceRoot).toBe("packages");
+    expect(policies[0]!.options!.excludeSources).toContain("*/webpack/runtime/*");
+    expect(policies[0]!.options!.excludeSources).toContain("*/.next-internal/server/app/*/actions.js (server actions loader)");
+    expect(policies[0]!.options!.excludeSources!.some(p => p.includes("temporal"))).toBe(false);
     const capture = attachCoverageSourceOptions({service:"web",reports:[
       {name:"node-1.json",content:'{"result":[]}'}, {name:"browser.lcov",content:"TN:\n"},
       {name:"other.lcov",content:"TN:\n"},
@@ -64,53 +66,6 @@ describe("Next adapter", () => {
     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 and untraced Edge 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.mkdir(path.join(dir,"server/edge"),{recursive:true});
-        await fs.writeFile(path.join(dir,"server/edge/middleware.js.map"),"{}");
-        await fs.writeFile(path.join(dir,"next-server.js.nft.json"),JSON.stringify({version:1,files:["runtime.js"]}));
-        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,"next-server.js.nft.json"),"utf8")).files).toEqual(["runtime.js","server/edge/middleware.js.map"]);
-      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");

package/src/coverage-next.ts

@@ -1,6 +1,7 @@
 // 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 { JAVASCRIPT_GENERATED_SOURCES } from "./coverage-javascript.js";
 import { node, browser, type CoverageAdapter, type CoverageSourceContext, type CoverageSourceOptions } from "./coverage.js";
 
 export interface NextCoverageOptions extends CoverageSourceOptions {
@@ -52,7 +53,7 @@ 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 withCoverage from @specific.dev/spectest/next in the test build and retain .next/server and .next/static maps when copying standalone output.");
+    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}));
   } catch (e) { console.error("Next coverage: " + e.message); process.exitCode = 1; }
 }
@@ -65,9 +66,6 @@ export interface NextBuildMetadata {
 }
 
 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",
@@ -75,7 +73,8 @@ const GENERATED_SOURCES = [
 ];
 
 /** Server + browser coverage for a built Next app. Build-time maps are required;
- * use withCoverage from @specific.dev/spectest/next in the Next configuration. */
+ * enable native Next source maps and retain them in the runtime image.
+ * Configure this adapter only in Spectest; the application needs no SDK dependency. */
 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)");
@@ -95,6 +94,7 @@ export function next(options: NextCoverageOptions = {}): CoverageAdapter {
     return value;
   };
   return {
+    defaultExcludeSources: JAVASCRIPT_GENERATED_SOURCES,
     name: "next", reports: "delta", explains: server.explains,
     ownsReport: name => server.ownsReport!(name) || client.ownsReport!(name),
     configure(svc, info) {

package/src/coverage.test.ts

@@ -22,9 +22,12 @@ import {
   isNodeDumpName,
   node,
   resetNodeCoverageMemory,
+  resolveCoverageSourceOptions,
+  attachCoverageSourceOptions,
   validateCoverage,
   type CoverageCaptureContext,
 } from "./coverage.js";
+import { JAVASCRIPT_GENERATED_SOURCES } from "./coverage-javascript.js";
 import type { ServiceConfig } from "./index.js";
 import { foldBrowserCoverage } from "./browser-coverage.js";
 
@@ -109,7 +112,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" }, { adapter: "browser" }],
+      adapters: [{ adapter: "node", defaultExcludeSources: [...JAVASCRIPT_GENERATED_SOURCES] }, { adapter: "browser", defaultExcludeSources: [...JAVASCRIPT_GENERATED_SOURCES] }],
       explains: [...NODE_EXPLAINS],
     });
   });
@@ -614,3 +617,46 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     expect((await fs.readdir(dir)).filter((n) => n.endsWith(".json"))).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
   });
 });
+
+
+describe("JavaScript generated-source defaults", () => {
+  const ctx = {
+    service: "app", signal: new AbortController().signal,
+    exec: async () => ({stdout: "", stderr: ""}),
+    projectFiles: async () => [], readProjectFile: async () => null,
+  };
+  test("defaults are archived only on owned reports and preserve legacy policy", async () => {
+    const legacy = {sourceRoot: "packages", excludeSources: ["virtual:///generated/*"]};
+    const policies = await resolveCoverageSourceOptions([node(), browser()], ctx, legacy);
+    const captured = attachCoverageSourceOptions({reports: [
+      {name: "node-1.json"}, {name: "browser.lcov"}, {name: "other.lcov"},
+    ]}, policies);
+    for (const report of captured.reports.slice(0, 2) as any[]) {
+      expect(report.sourceOptions.sourceRoot).toBe("packages");
+      expect(report.sourceOptions.excludeSources).toContain("*/webpack/bootstrap");
+      expect(report.sourceOptions.excludeSources).toContain("*/webpack/runtime/*");
+      expect(report.sourceOptions.excludeSources).toContain("virtual:///generated/*");
+      expect(report.sourceOptions.excludeSources.some((p: string) => p.includes("temporal"))).toBe(false);
+      expect(report.sourceOptions.excludeSources.some((p: string) => p.includes("server actions loader"))).toBe(false);
+    }
+    expect((captured.reports[2] as any).sourceOptions).toBeUndefined();
+  });
+  test("explicit user policy replaces legacy policy and extends defaults without duplicates", async () => {
+    const user = {sourceRoot: "workflows", excludeSources: [
+      "*/webpack/runtime/*", "*/temporal/workflows/index-autogenerated-entrypoint.cjs",
+    ]};
+    for (const adapter of [node(user), browser(user)]) {
+      const [policy] = await resolveCoverageSourceOptions([adapter], ctx, {
+        sourceRoot: "old", excludeSources: ["old/*"],
+      });
+      expect(policy!.options!.sourceRoot).toBe("workflows");
+      expect(policy!.options!.excludeSources).toContain(user.excludeSources[1]!);
+      expect(policy!.options!.excludeSources).not.toContain("old/*");
+      expect(policy!.options!.excludeSources!.filter(p => p === "*/webpack/runtime/*")).toHaveLength(1);
+    }
+  });
+  test("default policy requires report ownership and valid source patterns", () => {
+    expect(() => validateCoverage("app", {adapters: [{name: "bad", defaultExcludeSources: ["generated/*"]}]})).toThrow();
+    expect(() => validateCoverage("app", {adapters: [{name: "bad", ownsReport: () => true, defaultExcludeSources: [""]}]})).toThrow();
+  });
+});

package/src/coverage.ts

@@ -28,6 +28,7 @@
 //   coverage: { adapters: [coverage.node(), coverage.browser()] }
 
 import { createHash } from "node:crypto";
+import { JAVASCRIPT_GENERATED_SOURCES } from "./coverage-javascript.js";
 
 import type { ServiceConfig } from "./index.js";
 import { harvestAllBrowserCoverage, takeBrowserCoverageReport } from "./browser-coverage.js";
@@ -126,7 +127,9 @@ export interface CoverageAdapter {
   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. */
+  /** Generated scaffolding excluded in addition to explicit or legacy source policy. */
+  defaultExcludeSources?: readonly string[];
+  /** Required with sourceOptions/defaultExcludeSources, including runtime reports. */
   ownsReport?(name: string): boolean;
   /**
    * How the reports this adapter writes (through `ctx.writeReport`)
@@ -248,14 +251,17 @@ export function validateCoverage(service: string, cov: unknown): void {
             typeof (a as Record<string, unknown>)[k] === "function",
         );
       const sourceOptions = (a as CoverageAdapter | null)?.sourceOptions;
+      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) {
+      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)`,
         );
       }
       if (sourceOptions !== undefined && typeof sourceOptions !== "function") validateCoverageSourceOptions(service, sourceOptions);
+      if (defaults !== undefined) validateCoverageSourceOptions(service, { excludeSources: defaults });
     }
     return;
   }
@@ -310,11 +316,19 @@ 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) {
-  return Promise.all(adapters.filter(a => a.sourceOptions !== undefined || a.ownsReport).map(async a => {
+export async function resolveCoverageSourceOptions(adapters: readonly CoverageAdapter[], ctx: CoverageSourceContext, fallback?: CoverageSourceOptions) {
+  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`);
-    const options = typeof a.sourceOptions === "function" ? await a.sourceOptions(ctx) : a.sourceOptions;
+    let options = typeof a.sourceOptions === "function" ? await a.sourceOptions(ctx) : a.sourceOptions;
     if (a.sourceOptions !== undefined) validateCoverageSourceOptions(ctx.service, options);
+    if (a.defaultExcludeSources !== undefined) {
+      validateCoverageSourceOptions(ctx.service, { excludeSources: a.defaultExcludeSources });
+      // Defaults must not discard the source root/exclusions of older configs.
+      // Explicit adapter options still replace that service-level fallback.
+      options ??= fallback;
+      if (options !== undefined) validateCoverageSourceOptions(ctx.service, options);
+      options = { ...options, excludeSources: [...new Set([...a.defaultExcludeSources, ...(options?.excludeSources ?? [])])] };
+    }
     return { adapter: a.name, ownsReport: a.ownsReport, options };
   }));
 }
@@ -333,7 +347,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.sourceOptions && typeof a.sourceOptions !== "function" ? { sourceOptions: a.sourceOptions } : {}) }),
+    toJSON: () => ({ adapter: a.name, ...(a.defaultExcludeSources ? { defaultExcludeSources: a.defaultExcludeSources } : {}), ...(a.sourceOptions && typeof a.sourceOptions !== "function" ? { sourceOptions: a.sourceOptions } : {}) }),
   }) as CoverageAdapter;
 }
 
@@ -909,6 +923,7 @@ export function node(options: NodeCoverageOptions = {}): CoverageAdapter {
   }
   return {
     name: "node",
+    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,
     reports: "delta",
@@ -1121,6 +1136,7 @@ export async function collectNodeReports(dir: string): Promise<NodeReportStats>
 export function browser(options: CoverageSourceOptions = {}): CoverageAdapter {
   return {
     name: "browser",
+    defaultExcludeSources: JAVASCRIPT_GENERATED_SOURCES,
     ...(options.sourceRoot !== undefined || options.excludeSources !== undefined ? { sourceOptions: options } : {}),
     ownsReport: name => name === "browser.lcov",
     reports: "delta",

package/src/daemon.ts

@@ -3894,7 +3894,10 @@ async function captureServiceCoverage(baseline = false): Promise<ServiceCoverage
             try { return await fs.readFile(resolveProjectPath(p, { record: false }), "utf8"); }
             catch { return null; }
           },
-        });
+        }, typeof svc.coverage === "object" ? {
+          sourceRoot: svc.coverage.sourceRoot,
+          excludeSources: svc.coverage.excludeSources,
+        } : undefined);
       } catch (err) {
         return { service: svc.name, reports: [], error: `coverage source metadata: ${err instanceof Error ? err.message : String(err)}` };
       }

package/dist/next.d.ts

@@ -1,4 +0,0 @@
-/** Build-time companion for coverage.next(). Import this lightweight module in
- * next.config; it does not load the Spectest harness or require Next at runtime.
- * Apply only in the test build if production should not expose source maps. */
-export declare function withCoverage<T extends object>(config: T): T;

package/dist/next.js

@@ -1,93 +0,0 @@
-import { promises as fs } from "node:fs";
-import path from "node:path";
-/** Keep each traced script's map alongside it in standalone output. Turbopack
- * versions that do not apply outputFileTracingIncludes still emit these traces
- * before runAfterProductionCompile. No source files or generated code change. */
-async function includeTracedMaps(distDir) {
-    const traces = [];
-    const serverMaps = [];
-    async function walk(dir) {
-        for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
-            const file = path.join(dir, entry.name);
-            if (entry.isDirectory() && entry.name !== "cache" && entry.name !== "standalone")
-                await walk(file);
-            else if (entry.isFile()) {
-                if (entry.name.endsWith(".nft.json"))
-                    traces.push(file);
-                if (entry.name.endsWith(".js.map") && file.startsWith(path.join(distDir, "server") + path.sep))
-                    serverMaps.push(file);
-            }
-        }
-    }
-    await walk(distDir);
-    for (const file of traces) {
-        const dir = path.dirname(file);
-        const trace = JSON.parse(await fs.readFile(file, "utf8"));
-        if (!Array.isArray(trace.files))
-            throw new Error(`Invalid Next trace: ${file}`);
-        const scripts = [path.basename(file).slice(0, -".nft.json".length), ...trace.files];
-        // Edge bundles are copied through middleware-manifest, not NFT traces.
-        // The server trace is always copied into standalone output; retain
-        // their maps there without changing the middleware's executable files.
-        const maps = file === path.join(distDir, "next-server.js.nft.json")
-            ? serverMaps.map(map => path.relative(dir, map)) : [];
-        for (const script of scripts) {
-            if (typeof script !== "string" || !script.endsWith(".js"))
-                continue;
-            const map = script + ".map";
-            try {
-                if ((await fs.stat(path.resolve(dir, map))).isFile())
-                    maps.push(map);
-            }
-            catch (e) {
-                if (e.code !== "ENOENT")
-                    throw e;
-            }
-        }
-        trace.files = [...new Set([...trace.files, ...maps])];
-        await fs.writeFile(file, JSON.stringify(trace));
-    }
-}
-/** Build-time companion for coverage.next(). Import this lightweight module in
- * next.config; it does not load the Spectest harness or require Next at runtime.
- * Apply only in the test build if production should not expose source maps. */
-export function withCoverage(config) {
-    const c = config;
-    const distDir = c.distDir ?? ".next";
-    const includes = c.outputFileTracingIncludes ?? {};
-    return {
-        ...config,
-        productionBrowserSourceMaps: true,
-        turbopack: c.turbopack ?? {},
-        webpack(webpackConfig, context) {
-            const configured = c.webpack ? c.webpack(webpackConfig, context) : webpackConfig;
-            configured.plugins ??= [];
-            configured.plugins.push({
-                apply(compiler) {
-                    compiler.hooks.compilation.tap("SpectestCoverage", (compilation) => {
-                        compiler.webpack.NormalModule.getCompilationHooks(compilation).loader.tap("SpectestCoverage", (loader, module) => {
-                            // Keep dependencies identifiable as dependencies. Chaining a
-                            // package's published maps can replace node_modules provenance
-                            // with ambiguous paths such as ../../src/client/router.ts.
-                            if (/[\\/]node_modules[\\/]/.test(module.resource ?? ""))
-                                loader.sourceMap = false;
-                        });
-                    });
-                },
-            });
-            return configured;
-        },
-        experimental: { ...c.experimental, serverSourceMaps: true },
-        compiler: {
-            ...c.compiler,
-            async runAfterProductionCompile(metadata) {
-                await c.compiler?.runAfterProductionCompile?.(metadata);
-                await includeTracedMaps(metadata.distDir);
-            },
-        },
-        outputFileTracingIncludes: {
-            ...includes,
-            "/**": [...(includes["/**"] ?? []), `./${distDir}/server/**/*.map`],
-        },
-    };
-}

package/src/next.ts

@@ -1,85 +0,0 @@
-import { promises as fs } from "node:fs";
-import path from "node:path";
-
-/** Keep each traced script's map alongside it in standalone output. Turbopack
- * versions that do not apply outputFileTracingIncludes still emit these traces
- * before runAfterProductionCompile. No source files or generated code change. */
-async function includeTracedMaps(distDir: string): Promise<void> {
-  const traces: string[] = [];
-  const serverMaps: string[] = [];
-  async function walk(dir: string): Promise<void> {
-    for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
-      const file = path.join(dir, entry.name);
-      if (entry.isDirectory() && entry.name !== "cache" && entry.name !== "standalone") await walk(file);
-      else if (entry.isFile()) {
-        if (entry.name.endsWith(".nft.json")) traces.push(file);
-        if (entry.name.endsWith(".js.map") && file.startsWith(path.join(distDir, "server") + path.sep)) serverMaps.push(file);
-      }
-    }
-  }
-  await walk(distDir);
-  for (const file of traces) {
-    const dir = path.dirname(file);
-    const trace = JSON.parse(await fs.readFile(file, "utf8"));
-    if (!Array.isArray(trace.files)) throw new Error(`Invalid Next trace: ${file}`);
-    const scripts = [path.basename(file).slice(0, -".nft.json".length), ...trace.files];
-    // Edge bundles are copied through middleware-manifest, not NFT traces.
-    // The server trace is always copied into standalone output; retain
-    // their maps there without changing the middleware's executable files.
-    const maps = file === path.join(distDir, "next-server.js.nft.json")
-      ? serverMaps.map(map => path.relative(dir, map)) : [];
-    for (const script of scripts) {
-      if (typeof script !== "string" || !script.endsWith(".js")) continue;
-      const map = script + ".map";
-      try { if ((await fs.stat(path.resolve(dir, map))).isFile()) maps.push(map); }
-      catch (e) { if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e; }
-    }
-    trace.files = [...new Set([...trace.files, ...maps])];
-    await fs.writeFile(file, JSON.stringify(trace));
-  }
-}
-
-/** Build-time companion for coverage.next(). Import this lightweight module in
- * next.config; it does not load the Spectest harness or require Next at runtime.
- * Apply only in the test build if production should not expose source maps. */
-export function withCoverage<T extends object>(config: T): T {
-  const c = config as Record<string, any>;
-  const distDir = c.distDir ?? ".next";
-  const includes = c.outputFileTracingIncludes ?? {};
-  return {
-    ...config,
-    productionBrowserSourceMaps: true,
-    turbopack: c.turbopack ?? {},
-    webpack(webpackConfig: any, context: any) {
-      const configured = c.webpack ? c.webpack(webpackConfig, context) : webpackConfig;
-      configured.plugins ??= [];
-      configured.plugins.push({
-        apply(compiler: any) {
-          compiler.hooks.compilation.tap("SpectestCoverage", (compilation: any) => {
-            compiler.webpack.NormalModule.getCompilationHooks(compilation).loader.tap(
-              "SpectestCoverage", (loader: any, module: any) => {
-                // Keep dependencies identifiable as dependencies. Chaining a
-                // package's published maps can replace node_modules provenance
-                // with ambiguous paths such as ../../src/client/router.ts.
-                if (/[\\/]node_modules[\\/]/.test(module.resource ?? "")) loader.sourceMap = false;
-              },
-            );
-          });
-        },
-      });
-      return configured;
-    },
-    experimental: { ...c.experimental, serverSourceMaps: true },
-    compiler: {
-      ...c.compiler,
-      async runAfterProductionCompile(metadata: { projectDir: string; distDir: string }) {
-        await c.compiler?.runAfterProductionCompile?.(metadata);
-        await includeTracedMaps(metadata.distDir);
-      },
-    },
-    outputFileTracingIncludes: {
-      ...includes,
-      "/**": [...(includes["/**"] ?? []), `./${distDir}/server/**/*.map`],
-    },
-  };
-}