@terpjs/eslint-boundaries 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@terpjs/eslint-boundaries",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Terp frontend boundary rules (as data) + the ESLint adapter: no cross-module imports, no package internals, design-token-only styling (no style/className/module stylesheets), token-styled components for raw HTML tags, router-only in-app links, generated-client-only, and browser XSS/navigation sink bans. Strict-only (no modes); governed opt-outs via terp-allow markers + the escape-hatch budget ratchet (terp-boundaries-budget).",
+  "main": "./src/index.js",
+  "bin": {
+    "terp-boundaries-budget": "./src/budget.js",
+    "terp-boundaries-lint": "./src/findings.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./spec": "./src/spec.js",
+    "./layouts": "./src/layouts.js",
+    "./budget": "./src/budget.js",
+    "./findings": "./src/findings.js"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "eslint": ">=9"
+  },
+  "dependencies": {
+    "typescript-eslint": "^8.20.0"
+  },
+  "devDependencies": {
+    "@terp/spec": "github:AITT-NL/terp-spec#v0.12.0",
+    "eslint": "^9.18.0",
+    "vitest": "^3.0.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AITT-NL/terp-framework.git",
+    "directory": "packages/frontend/eslint-boundaries"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/budget.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * The escape-hatch budget ratchet — the frontend analog of the backend's governed
+ * `# arch-allow-*` budget (design §8): `terp-allow-*` marker counts in the app-authored
+ * surface (`src/modules/**`) must match the checked-in `escape-hatch-budget.json` **exactly**.
+ * A marker that rose needs a justified budget bump in the same change; one that dropped must
+ * be lowered to lock in the win; an unbudgeted marker must be added with a justified count.
+ * This keeps every boundary opt-out visible, greppable, and governed.
+ *
+ * Run it standalone or in CI (`terp-boundaries-budget [budget-path]`); the app lint
+ * command (`terp-boundaries-lint`) runs the same {@link checkBudget} in-process, so the
+ * ratchet can never be skipped by a failing lint. It exits non-zero on any drift.
+ * `--format json` additionally publishes the drift as a findings envelope on stdout,
+ * attributed to `frontend/escape-hatch` (see ./findings.js).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+import { BOUNDARY_SPEC } from "./spec.js";
+import { knownMarkerNames, parseAllowMarkers } from "./index.js";
+
+const MODULE_FILE_RE = /\.(?:ts|tsx)$/;
+
+/** The `review-by:<YYYY-MM-DD>` metadata token in a marker's reason (the Terp
+ * Standard's escape-hatch contract): when the exception must be re-justified.
+ * The tokens are a convention, not a gate — a reason without one is never
+ * rejected — but the spec says a toolchain SHOULD surface *expired* dates. */
+const REVIEW_BY_RE = /review-by:\s*(\d{4}-\d{2}-\d{2})/g;
+
+/** A strictly valid calendar date from a `YYYY-MM-DD` token, else null — a
+ * malformed date (2026-13-45) is not a well-formed token and never fires. */
+function parsedReviewDate(value) {
+  const [year, month, day] = value.split("-").map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  const roundTrips =
+    date.getUTCFullYear() === year &&
+    date.getUTCMonth() === month - 1 &&
+    date.getUTCDate() === day;
+  return roundTrips ? date : null;
+}
+
+/** Every `src/modules/**` TypeScript file under *root*, recursively. */
+function moduleFiles(root) {
+  const modulesRoot = path.join(root, "src", "modules");
+  if (!fs.existsSync(modulesRoot)) {
+    return [];
+  }
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (MODULE_FILE_RE.test(entry.name)) {
+        files.push(full);
+      }
+    }
+  };
+  walk(modulesRoot);
+  return files;
+}
+
+/** Actual `terp-allow-<rule>` marker counts across the app-authored surface. */
+export function countMarkers(root) {
+  const counts = {};
+  for (const file of moduleFiles(root)) {
+    for (const marker of parseAllowMarkers(fs.readFileSync(file, "utf-8"))) {
+      const name = `${BOUNDARY_SPEC.allowMarkerPrefix}${marker.rule}`;
+      counts[name] = (counts[name] ?? 0) + 1;
+    }
+  }
+  return counts;
+}
+
+/** Compare actual marker counts to the budget; return human-readable problems (empty = clean).
+ *
+ * A marker (or budget key) that names no rule with a governed opt-out — a typo, a
+ * stale name, or the governance rule's own name — is refused outright: an unknown
+ * marker can never be budgeted into legitimacy. A marker reason MAY carry the spec's
+ * `review-by:<YYYY-MM-DD>` metadata token; one whose date has passed is surfaced as a
+ * problem naming the marker's own file:line (re-justify the exception or remove it —
+ * a long-lived opt-out is never silently eternal). Reasons without the token are never
+ * rejected. *today* is injectable for tests; the default is the real current date.
+ */
+export function checkBudget(root, budgetPath, today = new Date()) {
+  let raw;
+  try {
+    raw = fs.readFileSync(budgetPath, "utf-8");
+  } catch {
+    return [`budget file not found: ${budgetPath}; create it (e.g. '{}') to govern opt-outs`];
+  }
+  let budget;
+  try {
+    budget = JSON.parse(raw);
+  } catch (error) {
+    return [`budget is not valid JSON: ${error.message}`];
+  }
+  if (
+    budget === null ||
+    typeof budget !== "object" ||
+    Array.isArray(budget) ||
+    !Object.values(budget).every((count) => Number.isInteger(count))
+  ) {
+    return ["budget must be a JSON object mapping each 'terp-allow-*' marker to an integer count"];
+  }
+  const actual = countMarkers(root);
+  const known = knownMarkerNames();
+  const problems = [];
+  const isGoverned = (name) =>
+    name.startsWith(BOUNDARY_SPEC.allowMarkerPrefix) &&
+    known.has(name.slice(BOUNDARY_SPEC.allowMarkerPrefix.length));
+  for (const name of [...new Set([...Object.keys(budget), ...Object.keys(actual)])].sort()) {
+    if (!isGoverned(name)) {
+      problems.push(
+        `'${name}' names no rule with a governed opt-out; remove the marker/budget entry ` +
+          "(opt-out markers name the Terp Standard catalog rule)",
+      );
+    }
+  }
+  for (const [name, count] of Object.entries(budget)) {
+    if (!isGoverned(name)) {
+      continue;
+    }
+    const used = actual[name] ?? 0;
+    if (used < count) {
+      problems.push(
+        `marker '${name}' dropped to ${used} (budget ${count}); lower the budget to lock in the win`,
+      );
+    } else if (used > count) {
+      problems.push(
+        `marker '${name}' rose to ${used} (budget ${count}); justify the bump in the same change`,
+      );
+    }
+  }
+  for (const [name, used] of Object.entries(actual)) {
+    if (isGoverned(name) && !(name in budget)) {
+      problems.push(`unbudgeted marker '${name}' used ${used} time(s); add it with a justified count`);
+    }
+  }
+  // Date-only comparison (like the backend checker): a review-by dated today
+  // is due, not yet passed.
+  const deadline = Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate());
+  for (const file of moduleFiles(root)) {
+    const relative = path.relative(root, file).split(path.sep).join("/");
+    for (const marker of parseAllowMarkers(fs.readFileSync(file, "utf-8"))) {
+      if (marker.reason === null) {
+        continue;
+      }
+      for (const match of marker.reason.matchAll(REVIEW_BY_RE)) {
+        const reviewBy = parsedReviewDate(match[1]);
+        if (reviewBy !== null && reviewBy.getTime() < deadline) {
+          problems.push(
+            `marker '${BOUNDARY_SPEC.allowMarkerPrefix}${marker.rule}' at ${relative}:${marker.line} ` +
+              `has a passed review date (review-by:${match[1]}); re-justify the exception ` +
+              "with a new review-by date or remove the marker",
+          );
+        }
+      }
+    }
+  }
+  return problems;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  // `--format json` additionally publishes the drift as a findings envelope on stdout
+  // (attributed to `frontend/escape-hatch`), so a driving tool joins the budget verdict
+  // to the Terp Standard catalog without parsing prose. Humans keep reading stderr.
+  let format = "text";
+  const formatIndex = args.indexOf("--format");
+  if (formatIndex !== -1) {
+    const value = args[formatIndex + 1];
+    if (value !== "json") {
+      console.error(`escape-hatch-budget: unsupported --format ${value ?? "(missing)"}; expected json`);
+      process.exit(2);
+    }
+    format = "json";
+    args.splice(formatIndex, 2);
+  }
+  const root = process.cwd();
+  const budgetPath = args[0] ?? path.join(root, "escape-hatch-budget.json");
+  const problems = checkBudget(root, budgetPath);
+  if (format === "json") {
+    const relative = path.relative(root, budgetPath).split(path.sep).join("/");
+    const budgetFile = relative === "" ? budgetPath.split(path.sep).join("/") : relative;
+    console.log(
+      JSON.stringify({
+        terp_findings: 1,
+        tool: "terp-boundaries-budget",
+        rules: ["frontend/escape-hatch"],
+        findings: problems.map((problem) => ({
+          rule: "frontend/escape-hatch",
+          path: budgetFile,
+          message: problem,
+        })),
+        unattributed: [],
+      }),
+    );
+  }
+  if (problems.length > 0) {
+    for (const problem of problems) {
+      console.error(`escape-hatch-budget: ${problem}`);
+    }
+    process.exit(1);
+  }
+}
+
+// Run main() only when invoked as a CLI (directly or via the npm bin symlink), not on import.
+const entry = process.argv[1] ? pathToFileURL(fs.realpathSync(process.argv[1])).href : "";
+if (entry === import.meta.url) {
+  main();
+}

package/src/budget.test.js

@@ -0,0 +1,207 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { checkBudget, countMarkers } from "./budget.js";
+
+// The frontend analog of the backend budget-ratchet tests: actual `terp-allow-*` marker counts
+// must match the checked-in escape-hatch-budget.json exactly — a rise, a drop, and an
+// unbudgeted marker are each reported, and a missing/invalid budget fails closed.
+
+const roots = [];
+const scratchRoot = path.resolve("node_modules/.cache/terp-budget-tests");
+let rootCounter = 0;
+
+function appRoot(files, budget) {
+  const root = path.join(scratchRoot, `case-${rootCounter++}`);
+  fs.rmSync(root, { recursive: true, force: true });
+  fs.mkdirSync(root, { recursive: true });
+  roots.push(root);
+  for (const [relative, text] of Object.entries(files)) {
+    const full = path.join(root, "src", "modules", relative);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, text);
+  }
+  if (budget !== undefined) {
+    fs.writeFileSync(path.join(root, "escape-hatch-budget.json"), budget);
+  }
+  return root;
+}
+
+function check(root) {
+  return checkBudget(root, path.join(root, "escape-hatch-budget.json"));
+}
+
+const MARKED = "// terp-allow-token-styled-elements: measured host quirk\nexport const W = 1;\n";
+
+afterEach(() => {
+  for (const root of roots.splice(0)) {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+describe("countMarkers", () => {
+  it("counts markers per rule across the module surface", () => {
+    const root = appRoot({ "a/x.tsx": MARKED, "b/y.tsx": MARKED });
+    expect(countMarkers(root)).toEqual({ "terp-allow-token-styled-elements": 2 });
+  });
+
+  it("counts custom terp rule markers for the same budget ratchet", () => {
+    const marked = "// terp-allow-no-unsafe-target-blank: vendor opener handshake\nexport const W = 1;\n";
+    const root = appRoot({ "a/x.tsx": marked });
+    expect(countMarkers(root)).toEqual({ "terp-allow-no-unsafe-target-blank": 1 });
+  });
+
+  it("is empty for an app with no modules directory", () => {
+    const root = path.join(scratchRoot, `case-${rootCounter++}`);
+    fs.rmSync(root, { recursive: true, force: true });
+    fs.mkdirSync(root, { recursive: true });
+    roots.push(root);
+    expect(countMarkers(root)).toEqual({});
+  });
+});
+
+describe("checkBudget", () => {
+  it("passes when usage matches the budget exactly", () => {
+    const root = appRoot({ "a/x.tsx": MARKED }, '{ "terp-allow-token-styled-elements": 1 }');
+    expect(check(root)).toEqual([]);
+  });
+
+  it("fails when a marker rose above its budget", () => {
+    const root = appRoot(
+      { "a/x.tsx": MARKED, "b/y.tsx": MARKED },
+      '{ "terp-allow-token-styled-elements": 1 }',
+    );
+    expect(check(root).join("\n")).toMatch(/rose to 2/);
+  });
+
+  it("fails when a marker dropped below its budget (lock in the win)", () => {
+    const root = appRoot({}, '{ "terp-allow-token-styled-elements": 1 }');
+    expect(check(root).join("\n")).toMatch(/dropped to 0/);
+  });
+
+  it("fails on an unbudgeted marker", () => {
+    const root = appRoot({ "a/x.tsx": MARKED }, "{}");
+    expect(check(root).join("\n")).toMatch(/unbudgeted marker/);
+  });
+
+  it("fails closed on a missing budget file", () => {
+    const root = appRoot({ "a/x.tsx": MARKED });
+    expect(check(root).join("\n")).toMatch(/budget file not found/);
+  });
+
+  it("fails closed on invalid budget JSON", () => {
+    const root = appRoot({}, "not json");
+    expect(check(root).join("\n")).toMatch(/not valid JSON/);
+  });
+
+  it("fails closed on a non-object budget", () => {
+    const root = appRoot({}, '["terp-allow-x"]');
+    expect(check(root).join("\n")).toMatch(/must be a JSON object/);
+  });
+
+  it("refuses a marker or budget key that names no governed rule", () => {
+    // A typo, a stale name, or the governance rule's own name can never be
+    // budgeted into legitimacy — refused on both sides of the ledger.
+    const marked = "// terp-allow-made-up-rule: stale\nexport const W = 1;\n";
+    const root = appRoot(
+      { "a/x.tsx": marked },
+      '{ "terp-allow-made-up-rule": 1, "terp-allow-escape-hatch": 1 }',
+    );
+    const problems = check(root).join("\n");
+    expect(problems).toMatch(/'terp-allow-made-up-rule' names no rule with a governed opt-out/);
+    expect(problems).toMatch(/'terp-allow-escape-hatch' names no rule with a governed opt-out/);
+  });
+
+  it("does not count marker-shaped text inside a string literal", () => {
+    const viaString = 'export const doc = "// terp-allow-token-styled-elements: in a string";\n';
+    const root = appRoot({ "a/x.tsx": viaString }, "{}");
+    expect(countMarkers(root)).toEqual({});
+    expect(check(root)).toEqual([]);
+  });
+
+  it("surfaces an expired review-by date on the marker's own file:line", () => {
+    // The spec's escape-hatch contract: a reason MAY carry review-by:<YYYY-MM-DD>;
+    // a toolchain SHOULD surface expired dates — so a long-lived opt-out is
+    // re-justified on schedule instead of staying silently eternal.
+    const marked =
+      "// terp-allow-token-styled-elements: host quirk owner:web ticket:APP-9 review-by:2026-01-31\n" +
+      "export const W = 1;\n";
+    const root = appRoot({ "a/x.tsx": marked }, '{ "terp-allow-token-styled-elements": 1 }');
+    const budgetPath = path.join(root, "escape-hatch-budget.json");
+    const problems = checkBudget(root, budgetPath, new Date("2026-02-01T12:00:00Z"));
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toMatch(/'terp-allow-token-styled-elements' at src\/modules\/a\/x\.tsx:1/);
+    expect(problems[0]).toMatch(/review-by:2026-01-31/);
+    expect(problems[0]).toMatch(/re-justify/);
+    // Due today = not yet passed; a future date is simply fine.
+    expect(checkBudget(root, budgetPath, new Date("2026-01-31T23:59:00Z"))).toEqual([]);
+  });
+
+  it("treats review-by as a convention, not a gate", () => {
+    // Reasons without the token are never rejected (the spec's MUST NOT), and
+    // a malformed date is not a well-formed token — neither fires, ever.
+    const marked =
+      "// terp-allow-token-styled-elements: no token here\nexport const A = 1;\n";
+    const broken =
+      "// terp-allow-token-styled-elements: review-by:2020-13-45 broken\n" +
+      "// terp-allow-token-styled-elements: review-by:someday prose\n" +
+      "export const B = 1;\n";
+    const root = appRoot(
+      { "a/x.tsx": marked, "b/y.tsx": broken },
+      '{ "terp-allow-token-styled-elements": 3 }',
+    );
+    const budgetPath = path.join(root, "escape-hatch-budget.json");
+    expect(checkBudget(root, budgetPath, new Date("2030-01-01T00:00:00Z"))).toEqual([]);
+  });
+});
+
+describe("terp-boundaries-budget --format json (the findings envelope)", () => {
+  const BUDGET_BIN = fileURLToPath(new URL("./budget.js", import.meta.url));
+
+  function runBin(root, args = []) {
+    return spawnSync(process.execPath, [BUDGET_BIN, ...args], { cwd: root, encoding: "utf8" });
+  }
+
+  it("attributes drift to frontend/escape-hatch on stdout; humans keep stderr", () => {
+    const root = appRoot({ "a/x.tsx": MARKED }, "{}");
+    const run = runBin(root, ["--format", "json"]);
+    expect(run.status).toBe(1);
+    const envelope = JSON.parse(run.stdout);
+    expect(envelope.terp_findings).toBe(1);
+    expect(envelope.tool).toBe("terp-boundaries-budget");
+    expect(envelope.rules).toEqual(["frontend/escape-hatch"]);
+    expect(envelope.findings).toHaveLength(1);
+    expect(envelope.findings[0].rule).toBe("frontend/escape-hatch");
+    expect(envelope.findings[0].path).toBe("escape-hatch-budget.json");
+    expect(envelope.findings[0].message).toMatch(/unbudgeted marker/);
+    expect(run.stderr).toMatch(/unbudgeted marker/);
+  });
+
+  it("publishes an empty findings list when the budget matches (exit 0)", () => {
+    const root = appRoot({ "a/x.tsx": MARKED }, '{ "terp-allow-token-styled-elements": 1 }');
+    const run = runBin(root, ["--format", "json"]);
+    expect(run.status).toBe(0);
+    const envelope = JSON.parse(run.stdout);
+    expect(envelope.rules).toEqual(["frontend/escape-hatch"]);
+    expect(envelope.findings).toEqual([]);
+  });
+
+  it("still reads a positional budget path alongside the flag", () => {
+    const root = appRoot({ "a/x.tsx": MARKED });
+    fs.writeFileSync(path.join(root, "other-budget.json"), "{}");
+    const run = runBin(root, ["--format", "json", "other-budget.json"]);
+    expect(run.status).toBe(1);
+    expect(JSON.parse(run.stdout).findings[0].path).toBe("other-budget.json");
+  });
+
+  it("refuses an unsupported format (fail closed, exit 2)", () => {
+    const root = appRoot({}, "{}");
+    const run = runBin(root, ["--format", "yaml"]);
+    expect(run.status).toBe(2);
+    expect(run.stderr).toMatch(/unsupported --format/);
+  });
+});

package/src/corpus-harness.js

@@ -0,0 +1,75 @@
+/**
+ * The frontend corpus harness: lint a Terp Standard corpus case into spec-shaped
+ * findings, exactly as an app's own boundary lint would see it.
+ *
+ * Shared by the certification test (corpus.test.js) and the scorecard emitter
+ * (scorecard.js), so the two can never apply different corpus semantics. The spec
+ * is resolved as a declared dependency (@terp/spec, ADR 0082) by the CALLER —
+ * this module takes paths, never resolves the spec itself.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { ESLint } from "eslint";
+
+import terpBoundaries, { LAYOUT_CONTRACT_FILE, catalogRuleId } from "./index.js";
+
+/** Every file below *caseDir*, recursively. */
+export function caseFiles(caseDir) {
+  const files = [];
+  const walk = (dir) => {
+    for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, item.name);
+      if (item.isDirectory()) walk(full);
+      else files.push(full);
+    }
+  };
+  walk(caseDir);
+  return files;
+}
+
+/**
+ * A case that ships a `layout-contract.json` at its root has opted into that layout
+ * contract (exactly as a real app does, ADR 0079). The harness lints with virtual file
+ * paths, so the rule's on-disk upward search cannot see the case's config; it is passed
+ * through the rule's `contract` option instead — the same activation, spelled explicitly.
+ */
+export function caseLayoutContract(caseDir) {
+  const file = path.join(caseDir, LAYOUT_CONTRACT_FILE);
+  if (!fs.existsSync(file)) return null;
+  const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  return typeof parsed.contract === "string" ? parsed.contract : null;
+}
+
+/** Lint a corpus case into spec-shaped findings (`findings.schema.json`): rule/path/line/message. */
+export async function lintCaseFindings(caseDir) {
+  const contract = caseLayoutContract(caseDir);
+  const overrideConfig =
+    contract === null
+      ? terpBoundaries
+      : [
+          ...terpBoundaries,
+          {
+            files: ["**/modules/**/*.{ts,tsx}"],
+            rules: { "terp/layout-contract": ["error", { contract }] },
+          },
+        ];
+  const eslint = new ESLint({ overrideConfigFile: true, overrideConfig });
+  const findings = [];
+  for (const file of caseFiles(caseDir)) {
+    if (!/\.tsx?$/.test(file)) continue; // config carriers (layout-contract.json) are not linted
+    // Resolve under the cwd so the config's `files` globs match the module path.
+    const filePath = path.resolve(path.relative(caseDir, file));
+    const [result] = await eslint.lintText(fs.readFileSync(file, "utf8"), { filePath });
+    findings.push(
+      ...result.messages.map((message) => ({
+        rule: catalogRuleId(message),
+        path: path.relative(caseDir, file).split(path.sep).join("/"),
+        line: message.line,
+        message: message.message,
+      })),
+    );
+  }
+  return findings;
+}

package/src/corpus.test.js

@@ -0,0 +1,92 @@
+/**
+ * The ESLint adapter is held to the Terp Standard's violation corpus (ADR 0080).
+ *
+ * `spec/corpus/frontend/<rule>/` holds violating and compliant sample module files — the
+ * executable meaning of each frontend catalog entry. This test lints every case with the real
+ * boundary config and applies the corpus contract in terms of the **stack-neutral catalog id**
+ * (findings are attributed through the adapter's published {@link catalogRuleId} mapping, never
+ * the raw ESLint rule id — several catalog rules share a core rule id):
+ *
+ * - every `violation-*` case produces at least one finding attributed to the entry's catalog id;
+ * - every `compliant-*` case is completely clean (no messages at all).
+ *
+ * The same corpus certifies any future stack's adapter (e.g. a Svelte realisation of
+ * BOUNDARY_SPEC). The backend half lives in `tests/architecture/test_spec_corpus.py`.
+ */
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { lintCaseFindings } from "./corpus-harness.js";
+
+// The spec is a declared dependency (@terp/spec, ADR 0082), never a repo-relative path —
+// inside the monorepo it resolves to the workspace member; after a repo split, to the pin.
+const SPEC_ROOT = path.dirname(
+  createRequire(import.meta.url).resolve("@terp/spec/package.json"),
+);
+const CATALOG = path.join(SPEC_ROOT, "catalog", "frontend");
+const CORPUS = path.join(SPEC_ROOT, "corpus", "frontend");
+
+const entries = fs
+  .readdirSync(CATALOG)
+  .filter((name) => name.endsWith(".json"))
+  .map((name) => JSON.parse(fs.readFileSync(path.join(CATALOG, name), "utf8")))
+  .filter((entry) => entry.corpus);
+
+async function lintCase(caseDir) {
+  return (await lintCaseFindings(caseDir)).map((finding) => finding.rule);
+}
+
+describe("frontend corpus (spec/corpus/frontend)", () => {
+  for (const entry of entries) {
+    const rule = entry.id.split("/")[1];
+    const ruleDir = path.join(CORPUS, rule);
+    for (const caseName of fs.readdirSync(ruleDir).sort()) {
+      if (caseName.startsWith("violation-")) {
+        it(`${rule}/${caseName} is attributed to ${entry.id}`, async () => {
+          expect(await lintCase(path.join(ruleDir, caseName))).toContain(entry.id);
+        });
+      } else {
+        it(`${rule}/${caseName} is completely clean`, async () => {
+          expect(await lintCase(path.join(ruleDir, caseName))).toEqual([]);
+        });
+      }
+    }
+  }
+});
+
+describe("findings round-trip (spec/findings.schema.json)", () => {
+  // The reference adapter's output, rendered as spec findings, must validate against the
+  // published finding format (ADR 0081) — the contract a Level 2 checker is certified on.
+  const schema = JSON.parse(
+    fs.readFileSync(path.join(SPEC_ROOT, "findings.schema.json"), "utf8"),
+  );
+  const item = schema.items;
+  const rulePattern = new RegExp(item.properties.rule.pattern);
+
+  it("every violation-case finding conforms to the published finding format", async () => {
+    const findings = [];
+    for (const entry of entries) {
+      const ruleDir = path.join(CORPUS, entry.id.split("/")[1]);
+      for (const caseName of fs.readdirSync(ruleDir).sort()) {
+        if (!caseName.startsWith("violation-")) continue;
+        findings.push(...(await lintCaseFindings(path.join(ruleDir, caseName))));
+      }
+    }
+    expect(findings.length).toBeGreaterThan(0);
+    for (const finding of findings) {
+      for (const field of item.required) expect(finding).toHaveProperty(field);
+      for (const field of Object.keys(finding)) {
+        expect(Object.keys(item.properties)).toContain(field); // additionalProperties: false
+      }
+      expect(finding.rule).toMatch(rulePattern); // attributed to a catalog id, never a tool id
+      expect(finding.path).not.toContain("\\"); // forward slashes, relative to the tree root
+      expect(Number.isInteger(finding.line)).toBe(true);
+      expect(finding.line).toBeGreaterThanOrEqual(item.properties.line.minimum);
+      expect(finding.message.trim()).not.toBe("");
+    }
+  });
+});