fix(observability-map): make the corpus harness cover what it claims

CodeRabbit round on #4455, four findings in the mutation corpus.

The baseline scan ran in the describe callback body, which Vitest executes
during collection, where the suite's timeout option does not apply and a throw
has no test name to attach to. It now runs in beforeAll with its own timeout.
Collection of the enabled file drops from 9.7s to 3.7s, and the full corpus
passes in 282s with no --testTimeout flag.

readTree filtered with an inline copy of the scanner's file predicate, so the
corpus could materialize files scanDirectory never reads and still count them
towards the anti-vacuity thresholds. It uses the exported isScannableFile now.
No behaviour change today: the two predicates were identical.

The additive-coverage assertion reads no route tree and cost nothing, so
gating it behind OBS_MAP_MUTATION_CORPUS only hid a stale list from the run
people actually do. Moved next to the registry assertion.

merge-comma-expressions is labelled preserving but would have merged a
directive prologue into 'use client', foo(), which is no longer a directive.
No route has that shape today; the guard and its test are there so the label
stays true.

Author: 1stvamp

internal-packages/observability-map/src/mutationCorpus.test.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { scanDirectory } from "./scan.js";
+import { isScannableFile, scanDirectory } from "./scan.js";
 import { buildReport } from "./score.js";
 import { ADDITIVE_IDS, MUTATIONS, type Mutation } from "./mutations.js";
 import { CHECKS } from "./checks/index.js";
@@ -72,7 +72,9 @@ function readTree(dir: string): SourceFile[] {
       }
       continue;
     }
-    if (!entry.isFile() || !/\.tsx?$/.test(entry.name) || entry.name.endsWith(".d.ts")) continue;
+    // `scanDirectory`'s own predicate rather than a copy of it. A copy that drifts lets a mutation
+    // report files and sites the scanner never read, which is what the thresholds below are for.
+    if (!entry.isFile() || !isScannableFile(entry.name)) continue;
     take(join(dir, entry.name), entry.name);
   }
   return files;
@@ -218,6 +220,30 @@ describe("the corpus keeps up with the check registry", () => {
     );
     expect(missing).toEqual([]);
   });
+
+  // Ungated for the same reason as the sweep assertion above: it reads no route tree and costs
+  // nothing, so gating it would only hide a stale list from the run people actually do.
+  it("covers the additive direction, not only the subtractive one", () => {
+    // Every corpus entry once removed or restructured real signal, and none added fake signal. The
+    // two largest holes ever found here lived in that blind spot, so the class is asserted rather
+    // than left to whoever edits the list next.
+    const ids = new Set(MUTATIONS.map((m) => m.id));
+    expect(ADDITIVE_IDS.filter((id) => !ids.has(id))).toEqual([]);
+    expect(ADDITIVE_IDS.length).toBeGreaterThanOrEqual(8);
+  });
+});
+
+/**
+ * Ungated, because a `preserving` entry that changes behaviour is a false negative in the property
+ * the whole file exists to argue, and the shape is cheaper to state on a two-line fixture than to
+ * wait for a route to grow it.
+ */
+describe("a preserving mutation preserves what the route does", () => {
+  it("leaves a directive prologue alone when merging comma expressions", () => {
+    const merge = MUTATIONS.find((m) => m.id === "merge-comma-expressions")!;
+    const result = merge.apply("api.v1.a.tsx", '"use client";\nfoo();\nbar();\n');
+    expect(result?.source ?? "").not.toContain('"use client",');
+  });
 });
 
 const describeCorpus = ENABLED && existsSync(ROUTES) ? describe : describe.skip;
@@ -231,17 +257,17 @@ const describeCorpus = ENABLED && existsSync(ROUTES) ? describe : describe.skip;
 const ENTRY_TIMEOUT_MS = 120_000;
 
 describeCorpus("mutation corpus over the real route tree", { timeout: ENTRY_TIMEOUT_MS }, () => {
-  const files = ENABLED && existsSync(ROUTES) ? readTree(ROUTES) : [];
-  const baseline = ENABLED && existsSync(ROUTES) ? measure(files) : null;
+  let files: SourceFile[] = [];
+  let baseline: Measurement | null = null;
 
-  it("covers the additive direction, not only the subtractive one", () => {
-    // Every corpus entry once removed or restructured real signal, and none added fake signal. The
-    // two largest holes ever found here lived in that blind spot, so the class is asserted rather
-    // than left to whoever edits the list next.
-    const ids = new Set(MUTATIONS.map((m) => m.id));
-    expect(ADDITIVE_IDS.filter((id) => !ids.has(id))).toEqual([]);
-    expect(ADDITIVE_IDS.length).toBeGreaterThanOrEqual(8);
-  });
+  // In a hook rather than the suite body, which Vitest runs during collection where no test timeout
+  // applies and a throw has no test name to attach to. The baseline is the single most expensive
+  // step in the file, so it is the one that must be inside something that can be timed out and
+  // reported. `beforeAll` takes its own timeout.
+  beforeAll(() => {
+    files = readTree(ROUTES);
+    baseline = measure(files);
+  }, ENTRY_TIMEOUT_MS);
 
   it("has a baseline worth mutating", () => {
     expect(baseline).not.toBeNull();

internal-packages/observability-map/src/mutations.ts

@@ -821,6 +821,9 @@ export const MUTATIONS: Mutation[] = [
           const previous = statements[i - 1]!;
           const current = statements[i]!;
           if (!ts.isExpressionStatement(previous) || !ts.isExpressionStatement(current)) continue;
+          // A directive prologue is an ExpressionStatement, and `"use client", foo();` is no longer
+          // a directive. That is a behaviour change, which this entry claims not to make.
+          if (ts.isStringLiteral(previous.expression)) continue;
           if (source[previous.end - 1] !== ";") continue;
           edits.push({ start: previous.end - 1, end: current.getStart(), text: ", " });
         }

internal-packages/observability-map/src/scan.ts

@@ -1358,7 +1358,9 @@ export function scanFile(fileName: string, source: string): EntryPoint | null {
 
 const SOURCE_FILE = /\.tsx?$/;
 
-function isScannableFile(fileName: string): boolean {
+/** Exported so `mutationCorpus.test.ts` materializes exactly the files `scanDirectory` reads. Its
+ * anti-vacuity thresholds count files and sites the scanner never saw if the two predicates drift. */
+export function isScannableFile(fileName: string): boolean {
   return SOURCE_FILE.test(fileName) && !fileName.endsWith(".d.ts");
 }