@specific.dev/spectest 0.120.0 → 0.121.0

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)}` };
       }

package/src/index.ts

@@ -895,7 +895,11 @@ export interface ServiceGroupInput<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   H extends Record<string, any> = Record<string, never>,
   Primary extends keyof P & string = keyof P & string,
-> {
+> extends Partial<ServiceConfig> {
+  // ServiceConfig fields on the group override its primary container. This
+  // preserves the usual `{ ...component(), hostnames: [...] }` customization
+  // when a component expands to multiple services. Helpers/setup below are
+  // group hooks, not container overrides.
   /**
    * Build the group's member services, keyed by RELATIVE part name
    * (`db`, `auth`, …). Called at expansion time with the final naming
@@ -1127,14 +1131,17 @@ function expandServiceGroups(input: InputServicesMap): ServicesMap {
         );
       }
     }
+    const { primary: _primary, services: _services, helpers: _helpers,
+      setup: _setup, expectKey: _expectKey, [SERVICE_GROUP]: _marker,
+      ...primaryOverrides } = entry;
     for (const [part, svc] of Object.entries(parts)) {
       const finalKey = naming.key(part);
       claim(finalKey, owner);
       // Rewrite relative dependsOn to final keys; a spread keeps function
       // fields (helpers/setup) and the enumerable-symbol ingress decls.
-      const final: ServiceConfig = { ...svc };
-      if (svc.dependsOn?.length) {
-        final.dependsOn = svc.dependsOn.map((d) =>
+      const final: ServiceConfig = { ...svc, ...(part === entry.primary ? primaryOverrides : {}) };
+      if (final.dependsOn?.length) {
+        final.dependsOn = final.dependsOn.map((d) =>
           partKeys.has(d) ? naming.key(d) : d,
         );
       }