@specific.dev/spectest 0.120.0 → 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.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
@@ -46,9 +47,6 @@ if (require.main === module) {
 }
 `;
 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",
@@ -78,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.120.0",
+  "version": "0.120.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

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

@@ -29,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"},

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 {
@@ -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",
@@ -96,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)}` };
       }