@specific.dev/spectest 0.131.14 → 0.131.16

package/README.md

@@ -83,6 +83,28 @@ Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
 Use a local service definition or `serviceGroup()` wrapper; the repository’s
 `examples/google-pubsub` demonstrates this using public SDK APIs.
 
+## Next.js coverage (0.131.16)
+
+Use `coverage.next({ appDir: "ops", sourceRoot: "." })` in your Spectest
+service configuration to collect server and browser coverage. Keep Next's
+server and browser source maps in the runtime image. `appDir` is relative to
+the container working directory; `sourceRoot` identifies the repository
+directory represented by the build's source-map root.
+
+Standalone servers launched through Node wrappers can change working directory:
+the adapter preserves the launcher's generated dependency identity in children.
+Turbopack's generated image modules, including SVG data-URL wrappers, are
+excluded automatically wherever the asset lives. Authored asset and application
+sources are not excluded.
+
+For Next 16.4.3, the adapter also corrects a reproduced Turbopack Edge source-map
+path defect using Next's resolved build manifest (`appDir`, `distDir`, and
+`turbopack.root`). This happens while the collector reads a map, before it creates
+the coverage record. No application build-script workaround is required. The
+correction is scoped to that verified version and layout; correctly emitted maps
+and other versions retain normal source-map interpretation. Unknown source paths
+remain unresolved and cannot authorize subset selection.
+
 ## Supabase function coverage (0.122.0)
 
 `supabase({ dir: "supabase" })` automatically collects coverage for its edge

package/dist/coverage-next.js

@@ -9,15 +9,20 @@ export const NEXT_COVERAGE_HELPER_PATH = "/spectest/next-coverage.cjs";
 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 || ".");
+// Preloads run again in spawned Node processes. Carry the original runtime
+// root into children instead of interpreting appDir against each child's cwd.
+const root = process.env.SPECTEST_COVERAGE_ROOT || process.cwd();
+process.env.SPECTEST_COVERAGE_ROOT = root;
+const app = path.resolve(root, 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")); }
+let build;
+function manifest() { return build ||= 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);
+  return path.relative(root, file);
 }
 try {
   const file = launcher(manifest());
@@ -25,6 +30,55 @@ try {
     ...new Set([...JSON.parse(process.env.SPECTEST_COVERAGE_GENERATED_FILES || "[]"), file])
   ]);
 } catch {} // Capture reports a useful error; do not change application startup.
+
+// Next 16.4.3 gives its Edge chunker the offset from distDir to turbopack.root,
+// although the chunker's output root is distDir/server/edge. Recover the exact
+// serialized prefix from the build configuration, not from repository suffixes.
+// See docs/validation/next-coverage-20261102.md for the unmodified-build repro
+// and upstream implementation. Other versions/layouts keep normal map semantics.
+let edgePolicy;
+function edgeSourcePolicy() {
+  if (edgePolicy !== undefined) return edgePolicy;
+  edgePolicy = null;
+  try {
+    const version = JSON.parse(fs.readFileSync(require.resolve("next/package.json", {paths:[app]}), "utf8")).version;
+    if (version !== "16.4.3") return null;
+    const m = manifest(), config = m.config;
+    const buildRoot = config.turbopack && config.turbopack.root;
+    if (typeof m.appDir !== "string" || !path.isAbsolute(m.appDir) ||
+        typeof buildRoot !== "string" || !path.isAbsolute(buildRoot) ||
+        typeof config.distDir !== "string") return null;
+    const offset = path.relative(path.resolve(m.appDir, config.distDir), buildRoot);
+    if (!offset || !offset.split(path.sep).every(p => p === "..")) return null;
+    edgePolicy = {root:path.join(dist, "server/edge"), offset};
+  } catch {} // Unknown build metadata cannot authorize a source correction.
+  return edgePolicy;
+}
+exports.normalizeSourceMap = function(data, mapFile) {
+  const policy = edgeSourcePolicy();
+  if (!policy) return;
+  const relative = path.relative(policy.root, mapFile);
+  if (!relative.startsWith("chunks" + path.sep) || path.isAbsolute(relative) || relative.split(path.sep).includes("..")) return;
+  const prefix = path.relative(path.dirname(mapFile), policy.root).split(path.sep).join("/") + "/" + policy.offset.split(path.sep).join("/") + "/";
+  function visit(map, depth) {
+    if (!map || typeof map !== "object" || depth > 32 || map.sourceRoot) return;
+    if (Array.isArray(map.sections)) {
+      for (const section of map.sections) if (section && !section.url) visit(section.map, depth + 1);
+    }
+    if (!Array.isArray(map.sources)) return;
+    map.sources = map.sources.map(source => {
+      if (typeof source !== "string" || !source.startsWith(prefix)) return source;
+      const suffix = source.slice(prefix.length);
+      let decoded;
+      try { decoded = decodeURIComponent(suffix); } catch { return source; }
+      // Correctly emitted paths have two extra '..' components. Never rewrite
+      // those, absolute/virtual sources, escapes or another root's sources.
+      if (/[\\:\0?#]/.test(decoded) || decoded.split("/").some(p => !p || p === "." || p === "..")) return source;
+      return "turbopack:///[project]/" + suffix;
+    });
+  }
+  visit(data, 0);
+};
 if (require.main === module) {
   try {
     const m = manifest();
@@ -50,7 +104,9 @@ const GENERATED_SOURCES = [
     "*/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)",
+    "turbopack:///[project]/*.mjs (structured image object)",
+    "turbopack:///[project]/*.mjs (structured image object with data url)",
+    "*/app/*.mjs (structured image object)", // Older Next map identities.
 ];
 /** Server + browser coverage for a built Next app. Build-time maps are required;
  * enable native Next source maps and retain them in the runtime image.
@@ -85,7 +141,8 @@ export function next(options = {}) {
                 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, },
+                    SPECTEST_COVERAGE_SERVICE: info.key,
+                    SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER: NEXT_COVERAGE_HELPER_PATH, },
                 files: [...configured.files, { path: NEXT_COVERAGE_HELPER_PATH, content: NEXT_COVERAGE_HELPER }],
             };
         },

package/dist/coverage.js

@@ -339,9 +339,13 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   if (!bunRuntime) post("Debugger.enable", { maxScriptsCacheSize: 16 * 1024 * 1024 });
 
   const GENERATED = new Map();
+  // Generated names are service-root-relative unit identities, not paths
+  // relative to a wrapper's child process. Preserve that root through execs.
+  const generatedRoot = process.env.SPECTEST_COVERAGE_ROOT || process.cwd();
+  process.env.SPECTEST_COVERAGE_ROOT = generatedRoot;
   try {
     for (const file of JSON.parse(process.env.SPECTEST_COVERAGE_GENERATED_FILES || "[]")) {
-      GENERATED.set(url.pathToFileURL(path.resolve(file)).href, file);
+      GENERATED.set(url.pathToFileURL(path.resolve(generatedRoot, file)).href, file);
     }
   } catch (e) {}
   const generatedUnits = new Map();
@@ -349,6 +353,8 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     return "generated:" + process.env.SPECTEST_COVERAGE_SERVICE + ":" + file + "#" + crypto.createHash("sha256").update(text).digest("hex");
   }
   const SELF = url.pathToFileURL(__filename).href;
+  const SOURCE_MAP_ADAPTER = process.env.SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER;
+  const SOURCE_MAP_ADAPTER_URL = SOURCE_MAP_ADAPTER ? url.pathToFileURL(path.resolve(SOURCE_MAP_ADAPTER)).href : null;
   const SCRIPTS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_SCRIPTS_SUBDIR)});
   const MARKERS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_MARKERS_SUBDIR)});
   // V8 script ids identify a compiled script within this process. A URL
@@ -361,7 +367,7 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   fs.writeFileSync(path.join(dir, ".attached-" + (bunRuntime ? "bun" : "node")), "");
 
   function isApp(u) {
-    return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF;
+    return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF && u !== SOURCE_MAP_ADAPTER_URL;
   }
   function isDep(u) {
     return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") >= 0 && u !== SELF;
@@ -458,6 +464,10 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     } catch (e) {
       return null;
     }
+    // Framework policy runs before dependency attribution and before the final
+    // descriptor is hashed. The collector remains the sole owner of record IDs,
+    // deduplication, dump references and cleanup (including exit-time captures).
+    if (SOURCE_MAP_ADAPTER) require(SOURCE_MAP_ADAPTER).normalizeSourceMap(data, mapUrl ? url.fileURLToPath(mapUrl) : scriptPath);
     // A source inside node_modules is a dependency: its unit id rides
     // beside the map (\`sourceUnits[i]\`, null for the project's own), so
     // the control plane never has to know what node_modules is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.131.14",
+  "version": "0.131.16",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/coverage-next.test.ts

@@ -1,6 +1,7 @@
 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 { applyCoverageAdapters, resolveCoverageSourceOptions, attachCoverageSourceOptions, node, browser, NODE_COVERAGE_HOOK, NODE_COVERAGE_SCRIPTS_SUBDIR, NODE_COVERAGE_MARKERS_SUBDIR, type CoverageSourceContext } from "./coverage.js";
+import { createHash } from "node:crypto";
 import { applyCoverageDelta, encodeCoverageBundle } from "./harness/coverage.js";
 import { gunzipSync } from "node:zlib";
 import { promises as fs } from "node:fs";
@@ -18,6 +19,65 @@ function context(): CoverageSourceContext {
 }
 
 describe("Next adapter", () => {
+  test.each(["next", "node"])("%s preserves generated unit identity through children with different working directories", async (kind) => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "next-child-cov-"));
+    try {
+      const app = path.join(dir, "ops"), reports = path.join(dir, "reports");
+      const helper = path.join(dir, "next-coverage.cjs"), hook = path.join(dir, "coverage-hook.cjs");
+      for (const folder of ["ops/.next/server", "ops/.next/static", "elsewhere", `reports/${NODE_COVERAGE_SCRIPTS_SUBDIR}`, `reports/${NODE_COVERAGE_MARKERS_SUBDIR}`]) {
+        await fs.mkdir(path.join(dir, folder), {recursive:true});
+      }
+      await fs.writeFile(helper, NEXT_COVERAGE_HELPER);
+      await fs.writeFile(hook, NODE_COVERAGE_HOOK);
+      await fs.writeFile(path.join(app, ".next/required-server-files.json"), JSON.stringify({config:{output:"standalone"}}));
+      for (const folder of ["server", "static"]) await fs.writeFile(path.join(app, `.next/${folder}/a.js.map`), "{}");
+      const launcher = '// __NEXT_PRIVATE_STANDALONE_CONFIG next/dist/server/lib/start-server\nrequire("./authored.cjs");\n';
+      await fs.writeFile(path.join(app, "server.js"), launcher);
+      await fs.writeFile(path.join(app, "authored.cjs"), "globalThis.applicationRan = true;\n");
+      await fs.writeFile(path.join(app, "bridge.cjs"), `
+        const {execFileSync} = require("node:child_process");
+        execFileSync(process.execPath, [${JSON.stringify(path.join(app,"server.js"))}], {cwd:${JSON.stringify(path.join(dir,"elsewhere"))}, stdio:"inherit"});
+      `);
+      await fs.writeFile(path.join(dir, "wrapper.cjs"), `
+        const {execFileSync} = require("node:child_process");
+        execFileSync(process.execPath, [${JSON.stringify(path.join(app,"bridge.cjs"))}], {cwd:${JSON.stringify(app)}, stdio:"inherit"});
+      `);
+      const adapter = kind === "next" ? next({appDir:"ops"}) : node({generated:["ops/server.js"]});
+      const configured = applyCoverageAdapters("web", {image, coverage:{adapters:[adapter]}});
+      const env = {...process.env, ...configured.env,
+        SPECTEST_COVERAGE_DIR:reports,
+        ...(kind === "next" ? { SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER: helper } : {}),
+        NODE_OPTIONS: `${kind === "next" ? `--require ${helper} ` : ""}--require ${hook}`,
+      } as NodeJS.ProcessEnv;
+      const ctx: CoverageSourceContext = {
+        service:"web", signal:new AbortController().signal,
+        projectFiles:async()=>[], readProjectFile:async()=>null,
+        exec:async command=>({stdout:execFileSync("sh", ["-c", command.replaceAll(NEXT_COVERAGE_HELPER_PATH, helper)], {cwd:dir,env,stdio:["ignore","pipe","pipe"]}).toString(),stderr:""}),
+      };
+      const inventory = (await adapter.inventory!(ctx)).filter(unit=>unit.startsWith("generated:"));
+      expect(inventory).toHaveLength(1);
+      expect(inventory[0]).toMatch(/^generated:web:ops\/server.js#[a-f0-9]{64}$/);
+      execFileSync("node", [path.join(dir,"wrapper.cjs")], {cwd:dir,env,stdio:["ignore","pipe","pipe"]});
+      const dumps = await Promise.all((await fs.readdir(reports)).filter(n=>/^node-.*\.json$/.test(n)).map(async n=>JSON.parse(await fs.readFile(path.join(reports,n),"utf8"))));
+      const urls = dumps.flatMap(d=>d.result.map((s:{url:string})=>s.url));
+      const units = new Set(dumps.flatMap(d=>d.units ?? []).filter((unit:string)=>unit.startsWith("generated:")));
+      expect([...units]).toEqual(inventory);
+      expect(urls.some(url=>url.endsWith("/ops/server.js"))).toBe(false);
+      expect(urls.some(url=>url.endsWith("/ops/authored.cjs"))).toBe(true);
+      expect(urls.some(url=>url.endsWith("/wrapper.cjs"))).toBe(true);
+    } finally { await fs.rm(dir, {recursive:true,force:true}); }
+  });
+
+  test("image wrapper exclusions cover monorepo public assets and are archived on both report types", async () => {
+    const policies = await resolveCoverageSourceOptions([next({appDir:"ops"})], context());
+    const capture = attachCoverageSourceOptions({reports:[{name:"node-1.json"},{name:"browser.lcov"}]}, policies);
+    for (const report of capture.reports) {
+      expect(report.sourceOptions!.excludeSources).toContain("turbopack:///[project]/*.mjs (structured image object)");
+      expect(report.sourceOptions!.excludeSources).toContain("turbopack:///[project]/*.mjs (structured image object with data url)");
+      expect(report.sourceOptions!.excludeSources).not.toContain("*/public/*");
+    }
+  });
+
   test("one adapter configures both collectors, uses its declared source root, and owns only its reports", async () => {
     const adapter = next({sourceRoot:"packages"});
     const configured = applyCoverageAdapters("web", {image,coverage:{adapters:[adapter]}});
@@ -88,4 +148,164 @@ describe("Next adapter", () => {
       expect(probe).toThrow();
     } finally {await fs.rm(dir,{recursive:true,force:true});}
   });
+
+  test("generated image wrappers are excluded across asset locations without excluding authored modules", async () => {
+    const policies = await resolveCoverageSourceOptions([next()], context());
+    const patterns = policies[0]!.options!.excludeSources!;
+    // The wire contract treats only '*' as special (including '/').
+    const excluded = (source: string) => patterns.some(pattern => new RegExp("^" +
+      pattern.split("*").map(part => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$").test(source));
+    for (const folder of ["app", "ops/public", "packages/ui/assets", "src/images"]) {
+      for (const suffix of ["structured image object", "structured image object with data url"]) {
+        expect(excluded(`turbopack:///[project]/${folder}/invoice.svg.mjs (${suffix})`)).toBe(true);
+      }
+      expect(excluded(`turbopack:///[project]/${folder}/invoice.svg`)).toBe(false);
+      expect(excluded(`turbopack:///[project]/${folder}/image.mjs`)).toBe(false);
+    }
+    expect(excluded("turbopack:///[project]/ops/src/middleware.ts")).toBe(false);
+    expect(excluded("https://example.com/image.mjs (structured image object with data url)")).toBe(false);
+  });
+
+  test("a cwd-changing wrapper keeps launcher units consistent and Edge source records valid across captures", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "next-child-cov-"));
+    const reports = path.join(dir, "reports");
+    const helper = path.join(dir, "next-helper.cjs");
+    const hook = path.join(dir, "hook.cjs");
+    const adapter = next({ appDir: "ops" });
+    const config = adapter.configure!({ image }, { key: "web" });
+    const sourceText = "export function middleware() { return 42; }\n";
+    const source = "ops/src/middleware.ts";
+    const digest = (text: string) => createHash("sha256").update(text).digest("hex");
+    const env: NodeJS.ProcessEnv = { ...process.env, ...config.env, SPECTEST_COVERAGE_DIR: reports,
+      NODE_OPTIONS: `--require ${helper} --require ${hook}`,
+      SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER: helper };
+    delete env.SPECTEST_COVERAGE_ROOT;
+    const ctx = {
+      service: "web", reportDir: reports, signal: new AbortController().signal,
+      projectFiles: async () => [source],
+      readProjectFile: async (file: string) => file === source ? sourceText : null,
+      writeReport: (name: string, content: string) => fs.writeFile(path.join(reports, name), content),
+      async exec(command: string) {
+        const proc = Bun.spawn(["sh", "-c", command.replace(NEXT_COVERAGE_HELPER_PATH, helper)],
+          { cwd: dir, env: { ...env, NODE_OPTIONS: "" }, stdout: "pipe", stderr: "pipe" });
+        const stdout = await new Response(proc.stdout).text();
+        const stderr = await new Response(proc.stderr).text();
+        if (await proc.exited !== 0) throw new Error(stderr);
+        return { stdout, stderr };
+      },
+    };
+    try {
+      await fs.mkdir(path.join(dir, "ops/.next/server/edge/chunks"), { recursive: true });
+      await fs.mkdir(path.join(dir, "ops/.next/static"), { recursive: true });
+      await fs.mkdir(reports);
+      await fs.mkdir(path.join(dir, "node_modules/next"), { recursive: true });
+      await fs.writeFile(path.join(dir, "node_modules/next/package.json"), JSON.stringify({ version: "16.4.3" }));
+      await fs.writeFile(helper, NEXT_COVERAGE_HELPER);
+      await fs.writeFile(hook, NODE_COVERAGE_HOOK);
+      await fs.writeFile(path.join(dir, "ops/.next/required-server-files.json"), JSON.stringify({ appDir: "/build/ops", config: { output: "standalone", distDir: ".next", turbopack: { root: "/build" } } }));
+      await fs.writeFile(path.join(dir, "ops/.next/static/browser.js.map"), "{}");
+      const edge = path.join(dir, "ops/.next/server/edge/chunks/middleware.js");
+      await fs.writeFile(edge, "globalThis.edgeValue = 42;\n");
+      await fs.writeFile(edge + ".map", JSON.stringify({ version: 3, sections: [{ offset: { line: 0, column: 0 }, map: {
+        version: 3, sources: ["../../../ops/src/middleware.ts"], sourcesContent: [sourceText], mappings: "AAAA", names: [],
+      } }] }));
+      const launcher = '// __NEXT_PRIVATE_STANDALONE_CONFIG next/dist/server/lib/start-server\nrequire("./.next/server/edge/chunks/middleware.js");\n';
+      await fs.writeFile(path.join(dir, "ops/server.js"), launcher);
+      // Also exercise process.chdir before spawn, not just the spawn cwd option.
+      await fs.writeFile(path.join(dir, "wrapper.cjs"), `
+        process.chdir("ops");
+        require("node:child_process").execFileSync(process.execPath, ["server.js"], { cwd: process.cwd(), stdio: "inherit" });
+      `);
+      const run = () => execFileSync("node", ["wrapper.cjs"], { cwd: dir, env, stdio: ["ignore", "pipe", "pipe"] });
+      const unit = `generated:web:ops/server.js#${digest(launcher)}`;
+      let correctedId: string | undefined;
+      for (let capture = 0; capture < 2; capture++) {
+        run();
+        // The exit hook must already have written the final descriptor and ID,
+        // before harness metadata/capture executes or reads project files.
+        const rawRecords = await Promise.all((await fs.readdir(path.join(reports, "scripts")))
+          .map(async name => [name, await fs.readFile(path.join(reports, "scripts", name), "utf8")] as const));
+        await resolveCoverageSourceOptions([adapter], ctx);
+        await adapter.capture!(ctx);
+        const dumps = await Promise.all((await fs.readdir(reports)).filter(n => /^node-.*\.json$/.test(n))
+          .map(async n => JSON.parse(await fs.readFile(path.join(reports, n), "utf8"))));
+        expect(dumps.flatMap(d => d.units ?? [])).toContain(unit);
+        expect(dumps.flatMap(d => d.result).some(s => s.url.endsWith("/ops/server.js"))).toBe(false);
+        const executed = dumps.flatMap(d => d.result).find(s => s.url.endsWith("/middleware.js"));
+        expect(executed).toBeDefined();
+        if (capture === 0) {
+          correctedId = executed.spectestScript;
+          const text = await fs.readFile(path.join(reports, "scripts", `${correctedId}.json`), "utf8");
+          expect(digest(text).slice(0, 32)).toBe(correctedId);
+          const map = JSON.parse(text).spectestScript.sourceMap.data.sections[0].map;
+          expect(map.sources).toEqual(["turbopack:///[project]/ops/src/middleware.ts"]);
+          expect(map.sourcesContent).toBeUndefined();
+          expect(map.x_spectestSourceHashes).toBeUndefined();
+          expect(rawRecords.find(([name]) => name === `${correctedId}.json`)?.[1]).toBe(text);
+        } else {
+          // Node deduplicates the original record; the second capture must
+          // reference the corrected record archived with the first capture.
+          expect(executed.spectestScript).toBe(correctedId);
+          expect(await fs.readdir(path.join(reports, "scripts"))).toEqual([]);
+        }
+      }
+      expect(await adapter.inventory!(ctx)).toContain(unit);
+    } finally { await fs.rm(dir, { recursive: true, force: true }); }
+  });
+});
+
+describe("Next Edge build configuration", () => {
+  async function normalize({ appDir = "ops", distDir = ".next", buildApp = "/build/ops", buildRoot = "/build",
+    version = "16.4.3", source, sourceRoot, outside = false, indexed = false,
+  }: { appDir?: string; distDir?: string; buildApp?: string; buildRoot?: string; version?: string;
+    source: string; sourceRoot?: string; outside?: boolean; indexed?: boolean }) {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "next-map-config-"));
+    try {
+      const app = path.join(dir, appDir);
+      const dist = path.join(app, distDir);
+      const helper = path.join(dir, "helper.cjs");
+      await fs.mkdir(dist, { recursive: true });
+      await fs.mkdir(path.join(app, "node_modules/next"), { recursive: true });
+      await fs.writeFile(path.join(app, "node_modules/next/package.json"), JSON.stringify({ version }));
+      await fs.writeFile(path.join(dist, "required-server-files.json"), JSON.stringify({ appDir: buildApp,
+        config: { output: "standalone", distDir, turbopack: { root: buildRoot } } }));
+      await fs.writeFile(helper, NEXT_COVERAGE_HELPER);
+      const leaf = { version: 3, sources: [source], sourceRoot, names: [], mappings: "AAAA", ignoreList: [0] };
+      const map = indexed ? { version: 3, sections: [{ offset: { line: 2, column: 4 }, map: leaf }] } : leaf;
+      const script = `const map = ${JSON.stringify(map)};
+        require(${JSON.stringify(helper)}).normalizeSourceMap(map, ${JSON.stringify(path.join(dist, outside ? "server/chunks/a.js.map" : "server/edge/chunks/a.js.map"))});
+        process.stdout.write(JSON.stringify(map));`;
+      const result = JSON.parse(execFileSync("node", ["-e", script], { cwd: dir,
+        env: { ...process.env, NODE_OPTIONS: "", SPECTEST_COVERAGE_ROOT: dir,
+          SPECTEST_NEXT_COVERAGE_OPTIONS: JSON.stringify({ appDir, distDir }) } }).toString());
+      const resultLeaf = indexed ? result.sections[0].map : result;
+      expect(resultLeaf.ignoreList).toEqual([0]);
+      expect(resultLeaf.mappings).toBe("AAAA");
+      if (indexed) expect(result.sections[0].offset).toEqual({ line: 2, column: 4 });
+      return resultLeaf.sources[0];
+    } finally { await fs.rm(dir, { recursive: true, force: true }); }
+  }
+
+  test("uses the recorded build root and distDir independently of runtime relocation", async () => {
+    expect(await normalize({ source: "../../../ops/src/middleware.ts" }))
+      .toBe("turbopack:///[project]/ops/src/middleware.ts");
+    expect(await normalize({ appDir: ".", buildApp: "/build", source: "../../src/middleware.ts" }))
+      .toBe("turbopack:///[project]/src/middleware.ts");
+    expect(await normalize({ appDir: "deployed/web", buildApp: "/builder/packages/apps/web", buildRoot: "/builder/packages",
+      distDir: ".output", source: "../../../../apps/web/src/my%20middleware.ts", indexed: true }))
+      .toBe("turbopack:///[project]/apps/web/src/my%20middleware.ts");
+  });
+
+  test("preserves fixed maps, external sources, explicit roots and unknown producers", async () => {
+    for (const source of ["../../../../../ops/src/middleware.ts", "turbopack:///[project]/ops/src/middleware.ts",
+      "file:///build/ops/src/middleware.ts", "https://example.com/a.ts", "../../../%2e%2e/secret.ts",
+      "../../../ops/src/%ZZ.ts", "../../../C%3A/secret.ts", "../../../ops//middleware.ts"]) {
+      expect(await normalize({ source })).toBe(source);
+    }
+    const source = "../../../ops/src/middleware.ts";
+    for (const extra of [{ sourceRoot: "/build" }, { outside: true }, { version: "16.4.4" },
+      { buildRoot: "/another-root" }, { buildApp: "relative/app" }]) {
+      expect(await normalize({ source, ...extra })).toBe(source);
+    }
+  });
 });

package/src/coverage-next.ts

@@ -21,15 +21,20 @@ export const NEXT_COVERAGE_HELPER_PATH = "/spectest/next-coverage.cjs";
 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 || ".");
+// Preloads run again in spawned Node processes. Carry the original runtime
+// root into children instead of interpreting appDir against each child's cwd.
+const root = process.env.SPECTEST_COVERAGE_ROOT || process.cwd();
+process.env.SPECTEST_COVERAGE_ROOT = root;
+const app = path.resolve(root, 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")); }
+let build;
+function manifest() { return build ||= 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);
+  return path.relative(root, file);
 }
 try {
   const file = launcher(manifest());
@@ -37,6 +42,55 @@ try {
     ...new Set([...JSON.parse(process.env.SPECTEST_COVERAGE_GENERATED_FILES || "[]"), file])
   ]);
 } catch {} // Capture reports a useful error; do not change application startup.
+
+// Next 16.4.3 gives its Edge chunker the offset from distDir to turbopack.root,
+// although the chunker's output root is distDir/server/edge. Recover the exact
+// serialized prefix from the build configuration, not from repository suffixes.
+// See docs/validation/next-coverage-20261102.md for the unmodified-build repro
+// and upstream implementation. Other versions/layouts keep normal map semantics.
+let edgePolicy;
+function edgeSourcePolicy() {
+  if (edgePolicy !== undefined) return edgePolicy;
+  edgePolicy = null;
+  try {
+    const version = JSON.parse(fs.readFileSync(require.resolve("next/package.json", {paths:[app]}), "utf8")).version;
+    if (version !== "16.4.3") return null;
+    const m = manifest(), config = m.config;
+    const buildRoot = config.turbopack && config.turbopack.root;
+    if (typeof m.appDir !== "string" || !path.isAbsolute(m.appDir) ||
+        typeof buildRoot !== "string" || !path.isAbsolute(buildRoot) ||
+        typeof config.distDir !== "string") return null;
+    const offset = path.relative(path.resolve(m.appDir, config.distDir), buildRoot);
+    if (!offset || !offset.split(path.sep).every(p => p === "..")) return null;
+    edgePolicy = {root:path.join(dist, "server/edge"), offset};
+  } catch {} // Unknown build metadata cannot authorize a source correction.
+  return edgePolicy;
+}
+exports.normalizeSourceMap = function(data, mapFile) {
+  const policy = edgeSourcePolicy();
+  if (!policy) return;
+  const relative = path.relative(policy.root, mapFile);
+  if (!relative.startsWith("chunks" + path.sep) || path.isAbsolute(relative) || relative.split(path.sep).includes("..")) return;
+  const prefix = path.relative(path.dirname(mapFile), policy.root).split(path.sep).join("/") + "/" + policy.offset.split(path.sep).join("/") + "/";
+  function visit(map, depth) {
+    if (!map || typeof map !== "object" || depth > 32 || map.sourceRoot) return;
+    if (Array.isArray(map.sections)) {
+      for (const section of map.sections) if (section && !section.url) visit(section.map, depth + 1);
+    }
+    if (!Array.isArray(map.sources)) return;
+    map.sources = map.sources.map(source => {
+      if (typeof source !== "string" || !source.startsWith(prefix)) return source;
+      const suffix = source.slice(prefix.length);
+      let decoded;
+      try { decoded = decodeURIComponent(suffix); } catch { return source; }
+      // Correctly emitted paths have two extra '..' components. Never rewrite
+      // those, absolute/virtual sources, escapes or another root's sources.
+      if (/[\\:\0?#]/.test(decoded) || decoded.split("/").some(p => !p || p === "." || p === "..")) return source;
+      return "turbopack:///[project]/" + suffix;
+    });
+  }
+  visit(data, 0);
+};
 if (require.main === module) {
   try {
     const m = manifest();
@@ -69,7 +123,9 @@ const GENERATED_SOURCES = [
   "*/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)",
+  "turbopack:///[project]/*.mjs (structured image object)",
+  "turbopack:///[project]/*.mjs (structured image object with data url)",
+  "*/app/*.mjs (structured image object)", // Older Next map identities.
 ];
 
 /** Server + browser coverage for a built Next app. Build-time maps are required;
@@ -104,6 +160,7 @@ export function next(options: NextCoverageOptions = {}): CoverageAdapter {
           NODE_OPTIONS: `--require ${NEXT_COVERAGE_HELPER_PATH} ${configured.env!.NODE_OPTIONS}`,
           SPECTEST_NEXT_COVERAGE_OPTIONS: JSON.stringify(options),
           SPECTEST_COVERAGE_SERVICE: info.key,
+          SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER: NEXT_COVERAGE_HELPER_PATH,
         },
         files: [...configured.files!, { path: NEXT_COVERAGE_HELPER_PATH, content: NEXT_COVERAGE_HELPER }],
       };

package/src/coverage.test.ts

@@ -246,7 +246,9 @@ const hasNode = await new Promise<boolean>((resolve) => {
   p.on("exit", (code) => resolve(code === 0));
 });
 
-const SERVER_JS = "function tick() { return 1 }\nsetInterval(tick, 5); process.stdout.write('up\\n');\n";
+// Readiness must follow the first tick; otherwise a fast capture can win the
+// race against the timer and correctly report that tick has not run yet.
+const SERVER_JS = "function tick() { return 1 }\ntick(); setInterval(tick, 5); process.stdout.write('up\\n');\n";
 // A wrapper that spawns the real server as a child node process and
 // waits on it — what `pnpm exec`, `npm run` and the `tsx` binary do.
 // It takes its child down with it on SIGTERM, so the test leaves no
@@ -334,7 +336,7 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
       expect(fns.every((f) => f.some((_, i) => i % 3 === 2 && f[i]! > 0))).toBe(true);
       const rec = (await records(dir)).get(`file://${path.join(dir, "server.js")}`)!;
       expect(ranNames(dump, rec).sort()).toEqual(["", "tick"]);
-      expect(rec.lineLengths).toEqual([28, 51, 0]);
+      expect(rec.lineLengths).toEqual([28, 59, 0]);
       expect(rec.functions.map((f) => f[0])).toEqual(["", "tick"]);
       expect(rec.sourceMap).toBeNull();
       expect(dump.result[0]!.spectestScript).toBeDefined();

package/src/coverage.ts

@@ -517,9 +517,13 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   if (!bunRuntime) post("Debugger.enable", { maxScriptsCacheSize: 16 * 1024 * 1024 });
 
   const GENERATED = new Map();
+  // Generated names are service-root-relative unit identities, not paths
+  // relative to a wrapper's child process. Preserve that root through execs.
+  const generatedRoot = process.env.SPECTEST_COVERAGE_ROOT || process.cwd();
+  process.env.SPECTEST_COVERAGE_ROOT = generatedRoot;
   try {
     for (const file of JSON.parse(process.env.SPECTEST_COVERAGE_GENERATED_FILES || "[]")) {
-      GENERATED.set(url.pathToFileURL(path.resolve(file)).href, file);
+      GENERATED.set(url.pathToFileURL(path.resolve(generatedRoot, file)).href, file);
     }
   } catch (e) {}
   const generatedUnits = new Map();
@@ -527,6 +531,8 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     return "generated:" + process.env.SPECTEST_COVERAGE_SERVICE + ":" + file + "#" + crypto.createHash("sha256").update(text).digest("hex");
   }
   const SELF = url.pathToFileURL(__filename).href;
+  const SOURCE_MAP_ADAPTER = process.env.SPECTEST_COVERAGE_SOURCE_MAP_ADAPTER;
+  const SOURCE_MAP_ADAPTER_URL = SOURCE_MAP_ADAPTER ? url.pathToFileURL(path.resolve(SOURCE_MAP_ADAPTER)).href : null;
   const SCRIPTS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_SCRIPTS_SUBDIR)});
   const MARKERS = path.join(dir, ${JSON.stringify(NODE_COVERAGE_MARKERS_SUBDIR)});
   // V8 script ids identify a compiled script within this process. A URL
@@ -539,7 +545,7 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   fs.writeFileSync(path.join(dir, ".attached-" + (bunRuntime ? "bun" : "node")), "");
 
   function isApp(u) {
-    return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF;
+    return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF && u !== SOURCE_MAP_ADAPTER_URL;
   }
   function isDep(u) {
     return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") >= 0 && u !== SELF;
@@ -636,6 +642,10 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     } catch (e) {
       return null;
     }
+    // Framework policy runs before dependency attribution and before the final
+    // descriptor is hashed. The collector remains the sole owner of record IDs,
+    // deduplication, dump references and cleanup (including exit-time captures).
+    if (SOURCE_MAP_ADAPTER) require(SOURCE_MAP_ADAPTER).normalizeSourceMap(data, mapUrl ? url.fileURLToPath(mapUrl) : scriptPath);
     // A source inside node_modules is a dependency: its unit id rides
     // beside the map (\`sourceUnits[i]\`, null for the project's own), so
     // the control plane never has to know what node_modules is.