test(comments): no plan code lands in the code again

planCodes.contract.test.ts scans every tracked text file and every new one not yet added (comments, docstrings, test titles, lint messages alike) for an epic or roadmap code (`E28`, `E9.5`, `R14`) and for a sprint or review round cited on its own (`(S6)`, `S3e2`, `round 4`, `deep-review`). Not `E2E`, not a ruff rule family (`E4/E7/E9`), not a TV episode (`S2 · E5`, a test episode titled "E1"), not `S3h` (the media-card decision docs/DESIGN.md is headed by). Markdown and the Alembic migrations keep their history and are not scanned. One sweep test rather than an ESLint rule plus a ruff one: the codes sat in Python, TS, CSS, shell, TOML, YAML and lint messages, and no single linter reads all of them. Seen red on a planted backend/app file (all three plan-code lines named, its allowed line not). audit_metrics.py counts epic codes by the same definition (it used to miss `E9.5` and `R6`), and CLAUDE.md's "comment the why" rule names the test.
2026-10-05 00:19:39 +02:00
parent 4aaaaa7860
commit 4e71723a07
3 changed files with 67 additions and 4 deletions
@@ -0,0 +1,59 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+// The code says WHY; the plan that produced it stays in the private ops repo. A comment that cites
+// `E28 review J4`, `(R6 S3b)` or `deep-review round 5` names a document no reader of this repo has,
+// so the citation is noise at best, and at worst a rule that only makes sense next to the plan. All
+// of them were taken out at once (2026-10-04); this keeps new ones out of every tracked text file and
+// every new one not yet added (comments, docstrings, test titles, lint messages alike).
+//
+// Not scanned: Markdown (the docs and the changelog keep a decision's date and its epic as history)
+// and the Alembic migrations (each one is a dated record of what changed).
+
+const REPO = new URL("../../../", import.meta.url);
+const SKIPPED =
+  /\.(md|webp|png|jpe?g|ico|woff2?)$|^backend\/alembic\/versions\/|package-lock\.json$/;
+// the guard itself, and the metric that counts epics by the same definition
+const ALLOWED = new Set([
+  "frontend/src/lib/planCodes.contract.test.ts",
+  "scripts/audit_metrics.py",
+]);
+const PLAN_CODES = [
+  // an epic (`E28`, `E9.5`) or an older roadmap item (`R14`) — not `E2E`, not a ruff rule family
+  // (`E4/E7/E9`), not a TV episode (`S2 · E5`, a test show's episode titled "E1")
+  /(?<!S\d{1,2}\s?·?\s?)(?<![/"])\b(?:E\d{1,2}(?:\.\d+)?|R\d{1,2})\b(?![/"E])/,
+  // a sprint cited on its own (`(S6)`, `S3e2`) or a review round (`round 4`, `deep-review`) — not
+  // `S3h`, the media-card decision docs/DESIGN.md is headed by and the design lab labels
+  /\(S\d{1,2}[a-z]?\d?\)|\bS(?!3h\b)\d{1,2}[a-z]\d?\b|\b[Rr]ound[ -]\d|deep-review/,
+];
+
+function tracked(): string[] {
+  const out = execFileSync(
+    "git",
+    ["ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+    {
+      cwd: REPO,
+      encoding: "utf-8",
+    },
+  );
+  // a file deleted but not yet staged is still listed
+  return out
+    .split("\0")
+    .filter((f) => f && !SKIPPED.test(f) && !ALLOWED.has(f) && existsSync(new URL(f, REPO)));
+}
+
+describe("plan codes", () => {
+  it("are not cited in the code", () => {
+    const files = tracked();
+    expect(files.length).toBeGreaterThan(1000); // a scan that reads nothing is green over nothing
+    const hits = files.flatMap((f) =>
+      readFileSync(new URL(f, REPO), "utf-8")
+        .split("\n")
+        .flatMap((line, i) =>
+          PLAN_CODES.some((re) => re.test(line)) ? [`${f}:${i + 1}: ${line.trim()}`] : [],
+        ),
+    );
+    expect(hits).toEqual([]);
+  });
+});