@specific.dev/spectest 0.119.4 → 0.119.5

package/dist/coverage-next.d.ts

@@ -0,0 +1,20 @@
+import { type CoverageAdapter, 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 declare const NEXT_COVERAGE_HELPER_PATH = "/spectest/next-coverage.cjs";
+export declare const NEXT_COVERAGE_HELPER: string;
+export interface NextBuildMetadata {
+    generated: string | null;
+    serverMaps: number;
+    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. */
+export declare function next(options?: NextCoverageOptions): CoverageAdapter;

package/dist/coverage-next.js

@@ -0,0 +1,106 @@
+// 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 } from "./coverage.js";
+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; }
+}
+`;
+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 = {}) {
+    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();
+    const metadata = (ctx) => {
+        let value = cache.get(ctx.service);
+        if (!value) {
+            value = ctx.exec(`NODE_OPTIONS= node ${NEXT_COVERAGE_HELPER_PATH}`).then(r => JSON.parse(r.stdout));
+            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/dist/coverage.d.ts

@@ -1,6 +1,7 @@
 import type { ServiceConfig } from "./index.js";
 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 declare const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
 /** The report `node()` writes when nothing has run yet on a branch. */
@@ -74,9 +75,21 @@ export interface CoverageCaptureContext {
     /** Aborts when the per-service capture budget runs out. */
     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
@@ -127,10 +140,17 @@ export declare const INVENTORY_REPORT = "inventory.units";
 export type ServiceCoverage = true | {
     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
  *  wrote (the program's own, a `command`'s). */
@@ -150,6 +170,19 @@ export declare function coverageAdapters(cov: ServiceCoverage | undefined): read
  * adapter names (`toJSON`), never as functions.
  */
 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<{
+    adapter: string;
+    ownsReport: (name: string) => boolean;
+    options: CoverageSourceOptions | undefined;
+}[]>;
+export declare function attachCoverageSourceOptions<T extends {
+    reports: {
+        name: string;
+        sourceOptions?: CoverageSourceOptions;
+    }[];
+}>(capture: T, policies: Awaited<ReturnType<typeof resolveCoverageSourceOptions>>): T;
 /** `env` with `value` appended to `name` (space-separated), or set. */
 export declare function appendEnvFlag(env: Readonly<Record<string, string>> | undefined, name: string, value: string): Record<string, string>;
 /** Env var the hook reads: the coverage directory inside the container. */
@@ -263,7 +296,7 @@ export declare function npmManifestUnit(projectPath: string, text: string): stri
  * Prints one `npm:<name>@<version>` per line.
  */
 export declare const NODE_INVENTORY_SCRIPT = "\"use strict\";\nconst fs = require(\"node:fs\"), path = require(\"node:path\");\nconst out = new Set();\nfunction isRealDir(p) { try { return fs.lstatSync(p).isDirectory(); } catch (e) { return false; } }\nfunction readPkg(d) {\n  try {\n    const j = JSON.parse(fs.readFileSync(path.join(d, \"package.json\"), \"utf8\"));\n    if (j && typeof j.name === \"string\" && j.name) out.add(\"npm:\" + j.name + (typeof j.version === \"string\" && j.version ? \"@\" + j.version : \"\"));\n  } catch (e) {}\n}\nfunction visit(d, depth) {\n  readPkg(d);\n  if (depth < 3) { const nested = path.join(d, \"node_modules\"); if (isRealDir(nested)) walkNm(nested, depth + 1); }\n}\nfunction walkNm(nm, depth) {\n  let names; try { names = fs.readdirSync(nm); } catch (e) { return; }\n  for (const n of names) {\n    if (n === \".bin\" || n === \".cache\" || n === \".modules.yaml\") continue;\n    if (n === \".pnpm\") {\n      let ps; try { ps = fs.readdirSync(path.join(nm, \".pnpm\")); } catch (e) { continue; }\n      for (const p of ps) { const inner = path.join(nm, \".pnpm\", p, \"node_modules\"); if (isRealDir(inner)) walkNm(inner, depth + 1); }\n      continue;\n    }\n    if (n.startsWith(\"@\")) {\n      let ss; try { ss = fs.readdirSync(path.join(nm, n)); } catch (e) { continue; }\n      for (const s of ss) { const d = path.join(nm, n, s); if (isRealDir(d)) visit(d, depth); }\n    } else { const d = path.join(nm, n); if (isRealDir(d)) visit(d, depth); }\n  }\n}\nlet d = process.cwd();\nfor (;;) {\n  const nm = path.join(d, \"node_modules\");\n  if (isRealDir(nm)) walkNm(nm, 0);\n  const up = path.dirname(d);\n  if (up === d) break;\n  d = up;\n}\nprocess.stdout.write(Array.from(out).sort().join(\"\\n\") + (out.size ? \"\\n\" : \"\"));\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. */
@@ -307,7 +340,7 @@ export declare 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 declare function browser(): CoverageAdapter;
+export declare function browser(options?: CoverageSourceOptions): CoverageAdapter;
 /**
  * Run `command` (via `sh -c`) in the container at every capture, so the
  * service writes a fresh report into `/spectest/coverage/`. The escape

package/dist/coverage.js

@@ -30,6 +30,7 @@ import { createHash } from "node:crypto";
 import { harvestAllBrowserCoverage, takeBrowserCoverageReport } from "./browser-coverage.js";
 import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR };
+export { next } from "./coverage-next.js";
 /** Where `node()` mounts its hook inside the container. */
 export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
 /** The report `node()` writes when nothing has run yet on a branch. */
@@ -58,10 +59,13 @@ export function validateCoverage(service, cov) {
     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") &&
@@ -69,7 +73,8 @@ export function validateCoverage(service, cov) {
     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 ?? []) {
             const ok = typeof a === "object" &&
                 a !== null &&
@@ -81,11 +86,16 @@ export function validateCoverage(service, cov) {
                 (a.explains === undefined ||
                     (Array.isArray(a.explains) &&
                         a.explains.every((e) => typeof e === "string"))) &&
-                ["configure", "load", "capture", "inventory"].every((k) => a[k] === undefined ||
+                ["configure", "load", "capture", "inventory", "ownsReport"].every((k) => a[k] === undefined ||
                     typeof a[k] === "function");
-            if (!ok) {
+            const sourceOptions = a?.sourceOptions;
+            const sourceShape = sourceOptions === undefined || (typeof a.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;
     }
@@ -117,19 +127,50 @@ export function applyCoverageAdapters(key, 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 } : {}),
     };
     return { ...out, coverage: wire };
 }
+function validateCoverageSourceOptions(service, options) {
+    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, ctx) {
+    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(capture, policies) {
+    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) {
     if (Object.prototype.hasOwnProperty.call(a, "toJSON"))
         return a;
     return Object.assign(Object.create(Object.getPrototypeOf(a)), a, {
-        toJSON: () => ({ adapter: a.name }),
+        toJSON: () => ({ adapter: a.name, ...(a.sourceOptions && typeof a.sourceOptions !== "function" ? { sourceOptions: a.sourceOptions } : {}) }),
     });
 }
 /** `env` with `value` appended to `name` (space-separated), or set. */
@@ -684,6 +725,8 @@ export function node(options = {}) {
     }
     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) {
@@ -883,9 +926,11 @@ export async function collectNodeReports(dir) {
  * 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() {
+export function browser(options = {}) {
     return {
         name: "browser",
+        ...(options.sourceRoot !== undefined || options.excludeSources !== undefined ? { sourceOptions: options } : {}),
+        ownsReport: name => name === "browser.lcov",
         reports: "delta",
         load(ctx) {
             ctx.collectBrowserScripts();

package/dist/daemon.js

@@ -34,7 +34,7 @@ import { ENVIRONMENT_CA_PATH as CA_PATH } from "./environment-ca.js";
 import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, validateServiceImage, normalizeServiceImage, proxy as makeProxyDecl, } from "./index.js";
 import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, walkProjectFiles, ENVIRONMENT_SERVICE, REACH_REPORT, READS_REPORT, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
-import { INVENTORY_REPORT, NODE_COVERAGE_MARKERS_SUBDIR, NODE_COVERAGE_SCRIPTS_SUBDIR, applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, } from "./coverage.js";
+import { INVENTORY_REPORT, NODE_COVERAGE_MARKERS_SUBDIR, NODE_COVERAGE_SCRIPTS_SUBDIR, applyCoverageAdapters, coverageAdapters, resolveCoverageSourceOptions, attachCoverageSourceOptions, coverageReportsMode, validateCoverage, } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, acquirePersistentDesktop, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
@@ -3427,6 +3427,24 @@ async function captureServiceCoverage(baseline = false) {
     // services' come from the ones that opted in, none included.
     const environment = captureEnvironmentCoverage(all, baseline);
     const captures = await Promise.all(services.map(async (svc) => {
+        let policies;
+        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 };
@@ -3439,12 +3457,21 @@ async function captureServiceCoverage(baseline = false) {
         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/dist/harness/browser-coverage.d.ts

@@ -37,6 +37,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>;
 }
 /** Decode one VLQ-encoded segment into its fields. */
 export declare function decodeVlq(segment: string): number[];

package/dist/harness/browser-coverage.js

@@ -180,6 +180,8 @@ export function decodeSourceMap(doc, depth = 0) {
             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)
@@ -199,6 +201,9 @@ export function decodeSourceMap(doc, depth = 0) {
     }
     const sourceRoot = typeof m.sourceRoot === "string" ? m.sourceRoot : undefined;
     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 = [];
     let src = 0;
     let line = 0;
@@ -231,7 +236,7 @@ export function decodeSourceMap(doc, depth = 0) {
     catch {
         return null;
     }
-    return { sources, lines };
+    return { sources, lines, ...(ignored !== undefined ? { ignored: new Set(ignored) } : {}) };
 }
 /**
  * Attribute generated line counts to original (file, line)s through the
@@ -247,7 +252,7 @@ export function mapToOriginal(map, generated) {
             continue;
         for (const seg of segs) {
             const file = map.sources[seg.src];
-            if (file === undefined || isForeignSource(file))
+            if (file === undefined || map.ignored?.has(seg.src) || isForeignSource(file))
                 continue;
             let lc = out.get(file);
             if (!lc) {

package/dist/harness/coverage.d.ts

@@ -21,6 +21,7 @@ export declare function coverageHostDir(workspace: string, service: string): str
 export interface CoverageReport {
     name: string;
     content: string;
+    sourceOptions?: import("../coverage.js").CoverageSourceOptions;
 }
 /** One service's capture: every report in its directory, verbatim. */
 export interface ServiceCoverageCapture {
@@ -34,6 +35,8 @@ export interface ServiceCoverageCapture {
     root?: string;
     /** Repository root of the service build/bundler workspace, when explicit. */
     sourceRoot?: string;
+    /** SDK-declared source exclusions, preserved for server-side derivation. */
+    excludeSources?: readonly string[];
     /** Set when the capture failed: the command failed, the directory was
      *  empty, no file held an `SF:` record, or the reports were too large.
      *  A case with an error here fails — a hole in the coverage data must

package/dist/harness/coverage.js

@@ -397,7 +397,7 @@ export function applyCoverageDelta(capture, mode, deltaReports) {
         const prev = prevByName.get(r.name) ?? new Map();
         prevByName.set(r.name, now);
         const restarted = [];
-        reports.push({ name: r.name, content: renderLcovCounts(subtractLcovCounts(now, prev, restarted)) });
+        reports.push({ ...r, content: renderLcovCounts(subtractLcovCounts(now, prev, restarted)) });
         if (restarted.length > 0) {
             console.warn(`[coverage] service "${capture.service}" report ${r.name}: counters dropped in ${restarted.length} file(s) (${restarted.slice(0, 3).join(", ")}) — a process restarted; those records count whole`);
         }

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export type { Desktop, DesktopApp, DesktopOptions } from "./desktop.js";
 import type { Desktop, DesktopApp, DesktopOptions } from "./desktop.js";
 export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 import type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
-export { type CoverageAdapter, type CoverageCaptureContext, type CoverageConfigureInfo, type CoverageLoadContext, type ServiceCoverage, } from "./coverage.js";
+export { type CoverageAdapter, type CoverageCaptureContext, type CoverageConfigureInfo, type CoverageSourceOptions, type CoverageSourceContext, type CoverageLoadContext, type ServiceCoverage, } from "./coverage.js";
 import { type ServiceCoverage } from "./coverage.js";
 export { ca } from "./environment-ca.js";
 export { certificate, dnsName, proxy, provides, lowerIngress, isWildcard, SELF_SERVICE_TOKEN, } from "./ingress.js";

package/dist/next.d.ts

@@ -0,0 +1,4 @@
+/** 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

@@ -0,0 +1,80 @@
+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) {
+    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() && entry.name.endsWith(".nft.json")) {
+                const trace = JSON.parse(await fs.readFile(file, "utf8"));
+                if (!Array.isArray(trace.files))
+                    throw new Error(`Invalid Next trace: ${file}`);
+                const scripts = [entry.name.slice(0, -".nft.json".length), ...trace.files];
+                const maps = [];
+                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));
+            }
+        }
+    }
+    await walk(distDir);
+}
+/** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.119.4",
+  "version": "0.119.5",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,6 +21,11 @@
       "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",