@terpjs/eslint-boundaries 0.1.0

package/src/findings.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * The machine-readable boundary lint — the frontend analog of `terp check --format json`.
+ *
+ * `terp-boundaries-lint` runs the app's own ESLint config (the flat config in the cwd,
+ * exactly what `eslint .` would load) **and** the escape-hatch budget ratchet (the same
+ * check `terp-boundaries-budget` runs) in one command, and publishes one **findings
+ * envelope** on stdout:
+ *
+ *   { "terp_findings": 1, "tool": "@terp/eslint-boundaries",
+ *     "rules": ["frontend/<rule>", …],          // every catalog rule this run evaluated
+ *     "not_applicable": ["frontend/<rule>", …], // opt-in rules this app has not enabled
+ *     "findings": [{ rule, path, line, message }, …],   // spec findings.schema.json shape
+ *     "unattributed": [{ path, line, message, reported_as }, …] }
+ *
+ * `rules` is the evaluated-rule inventory ({@link catalogRuleIds}, minus the opt-in
+ * rules listed under `not_applicable` — today `frontend/layout-contract` when the app
+ * has no checked-in layout-contract.json, so a consumer never renders an unenforced
+ * rule as passing). `findings` are the reported messages attributed to their
+ * stack-neutral catalog ids through the adapter's published {@link catalogRuleId}
+ * mapping, plus any budget drift attributed to `frontend/escape-hatch`. A message
+ * outside the boundary (another configured rule, a parse error) lands in
+ * `unattributed` — surfaced, never dropped. The human-readable report goes to stderr,
+ * so `npm run lint` failures stay legible while a driving tool (the Studio's gate, a
+ * CI annotator) parses stdout.
+ *
+ * Both halves ALWAYS run — a boundary violation cannot skip the budget ratchet the way
+ * an `eslint . && terp-boundaries-budget` chain could — and the exit code is the
+ * combined verdict (non-zero when either half failed). An optional positional argument
+ * names the budget file (default `escape-hatch-budget.json`, as the budget bin). *
+ * `--format check-report` prints the Terp Standard **check report** instead
+ * (`app-check-report.schema.json`: the same inventory and findings, self-described with
+ * `spec_version`, the checker identity, and the run verdict) — still exactly one JSON
+ * document on stdout. The default stays the legacy `terp_findings` envelope, a published
+ * seam (ADR 0083) existing consumers parse strictly. */
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+import { ESLint } from "eslint";
+
+import { checkBudget } from "./budget.js";
+import { activeLayoutContract, catalogRuleId, catalogRuleIds } from "./index.js";
+import { SPEC_VERSION } from "./spec.js";
+
+/** This package's own version — the `checker.version` a check report carries. */
+const PACKAGE_VERSION = JSON.parse(
+  fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+
+/**
+ * Render a findings envelope as the Terp Standard **check report**
+ * (`app-check-report.schema.json`, printed by `--format check-report`): the same
+ * inventory and findings, self-described with the spec version the rule ids resolve
+ * against, the checker identity, and the run verdict — so a consumer joins per-rule
+ * verdicts to the catalog without knowing this toolchain. `unattributed.reported_as`
+ * is omitted (never null) per the schema; `ok` covers the standard's own findings
+ * (the process exit code stays the combined verdict, unattributed errors included).
+ */
+export function asCheckReport(envelope) {
+  return {
+    terp_check_report: 1,
+    spec_version: SPEC_VERSION,
+    checker: { tool: envelope.tool, version: PACKAGE_VERSION },
+    ok: envelope.findings.length === 0,
+    rules: envelope.rules,
+    not_applicable: envelope.not_applicable,
+    findings: envelope.findings,
+    unattributed: envelope.unattributed.map(({ path: file, line, message, reported_as }) => ({
+      path: file,
+      ...(Number.isInteger(line) && line >= 1 ? { line } : {}),
+      message,
+      ...(typeof reported_as === "string" && reported_as !== "" ? { reported_as } : {}),
+    })),
+  };
+}
+
+/**
+ * Render lint *results* (ESLint result objects) as the findings envelope plus the
+ * human report lines. Paths are cwd-relative with `/` separators on every OS — the
+ * envelope is a machine contract, not display text.
+ *
+ * Options mirror what the bin derives from the app checkout: `layoutContract`
+ * (is the opt-in slot-typed contract active? default: the same upward
+ * `layout-contract.json` search the ESLint rule performs from *cwd*),
+ * `budgetProblems` (escape-hatch budget drift, appended as
+ * `frontend/escape-hatch` findings) and `budgetFile` (the path those findings cite).
+ */
+export function renderEnvelope(results, cwd = process.cwd(), options = {}) {
+  const {
+    layoutContract = activeLayoutContract(cwd) !== null,
+    budgetProblems = [],
+    budgetFile = "escape-hatch-budget.json",
+  } = options;
+  const findings = [];
+  const unattributed = [];
+  const human = [];
+  for (const result of results) {
+    const relative = path.relative(cwd, result.filePath).split(path.sep).join("/");
+    const file = relative === "" ? result.filePath.split(path.sep).join("/") : relative;
+    for (const message of result.messages) {
+      const rule = catalogRuleId(message);
+      const line = Number.isInteger(message.line) && message.line > 0 ? message.line : 1;
+      if (rule === null) {
+        unattributed.push({
+          path: file,
+          line,
+          message: message.message,
+          reported_as: message.ruleId ?? null,
+        });
+      } else {
+        findings.push({ rule, path: file, line, message: message.message });
+      }
+      human.push(
+        `${file}:${line}:${message.column ?? 1}  ${message.message}  [${rule ?? message.ruleId ?? "parse"}]`,
+      );
+    }
+  }
+  for (const problem of budgetProblems) {
+    findings.push({ rule: "frontend/escape-hatch", path: budgetFile, message: problem });
+    human.push(`${budgetFile}  ${problem}  [frontend/escape-hatch]`);
+  }
+  // An opt-in rule the app has not enabled is published as not-applicable — never
+  // silently kept in `rules`, where "evaluated, zero findings" would read as passing.
+  const notApplicable = layoutContract ? [] : ["frontend/layout-contract"];
+  return {
+    envelope: {
+      terp_findings: 1,
+      tool: "@terp/eslint-boundaries",
+      rules: catalogRuleIds().filter((id) => !notApplicable.includes(id)),
+      not_applicable: notApplicable,
+      findings,
+      unattributed,
+    },
+    human,
+  };
+}
+
+async function main() {
+  const cwd = process.cwd();
+  const args = process.argv.slice(2);
+  // `--format check-report` prints the Terp Standard check report
+  // (app-check-report.schema.json) instead of the legacy terp_findings envelope —
+  // still exactly ONE JSON document on stdout, so strict consumers keep a single
+  // parse. The default stays the legacy envelope (a published seam, ADR 0083).
+  let format = "findings";
+  const formatIndex = args.indexOf("--format");
+  if (formatIndex !== -1) {
+    const value = args[formatIndex + 1];
+    if (value !== "findings" && value !== "check-report") {
+      process.stderr.write(
+        `terp-boundaries-lint: unsupported --format ${value ?? "(missing)"}; ` +
+          "expected findings or check-report\n",
+      );
+      process.exit(2);
+    }
+    format = value;
+    args.splice(formatIndex, 2);
+  }
+  const budgetPath = args[0] ?? path.join(cwd, "escape-hatch-budget.json");
+  // The app's own config and ignore set, with the same cache the plain CLI used
+  // (`--cache --cache-location node_modules/.cache/eslint/`).
+  const eslint = new ESLint({ cache: true, cacheLocation: "node_modules/.cache/eslint/" });
+  const results = await eslint.lintFiles(["."]);
+  // The ratchet runs regardless of the lint verdict — both halves always report.
+  const budgetProblems = checkBudget(cwd, budgetPath);
+  const relativeBudget = path.relative(cwd, budgetPath).split(path.sep).join("/");
+  const { envelope, human } = renderEnvelope(results, cwd, {
+    budgetProblems,
+    budgetFile: relativeBudget === "" ? budgetPath.split(path.sep).join("/") : relativeBudget,
+  });
+  if (human.length > 0) {
+    process.stderr.write(
+      `${human.join("\n")}\n${human.length} problem(s); the findings envelope is on stdout.\n`,
+    );
+  }
+  const document = format === "check-report" ? asCheckReport(envelope) : envelope;
+  process.stdout.write(`${JSON.stringify(document)}\n`);
+  const errors =
+    results.reduce((sum, result) => sum + result.errorCount, 0) + budgetProblems.length;
+  process.exitCode = errors > 0 ? 1 : 0;
+}
+
+// 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().catch((error) => {
+    // The lint could not run at all (no config, ESLint crash) — distinct from "ran and failed".
+    console.error(String(error));
+    process.exitCode = 2;
+  });
+}

package/src/findings.test.js

@@ -0,0 +1,346 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ESLint } from "eslint";
+import { afterEach, describe, expect, it } from "vitest";
+
+import terpBoundaries, { catalogRuleIds } from "./index.js";
+import { asCheckReport, renderEnvelope } from "./findings.js";
+import { SPEC_VERSION } from "./spec.js";
+
+// The machine-readable boundary lint (the frontend analog of `terp check --format json`):
+// the findings envelope publishes the evaluated-rule inventory + findings attributed to
+// stack-neutral catalog ids, humans keep stderr, and the exit code stays the verdict.
+
+const SPEC_ROOT = path.dirname(
+  createRequire(import.meta.url).resolve("@terp/spec/package.json"),
+);
+const FINDINGS_BIN = fileURLToPath(new URL("./findings.js", import.meta.url));
+
+const roots = [];
+const scratchRoot = path.resolve("node_modules/.cache/terp-findings-tests");
+let rootCounter = 0;
+
+function appRoot(files) {
+  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, relative);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, text);
+  }
+  return root;
+}
+
+afterEach(() => {
+  for (const root of roots.splice(0)) {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+async function lintModule(text) {
+  const eslint = new ESLint({ overrideConfigFile: true, overrideConfig: terpBoundaries });
+  const filePath = path.resolve("src/modules/sample/View.tsx");
+  return eslint.lintText(text, { filePath });
+}
+
+describe("catalogRuleIds (the evaluated-rule inventory)", () => {
+  it("matches the Terp Standard frontend catalog exactly, both directions", () => {
+    // The inventory can't lie: every catalog entry is evaluated, and no evaluated id
+    // outlives its catalog entry (the same parity discipline as test_spec_catalog).
+    const catalogued = fs
+      .readdirSync(path.join(SPEC_ROOT, "catalog", "frontend"))
+      .filter((name) => name.endsWith(".json"))
+      .map((name) => `frontend/${name.replace(/\.json$/, "")}`)
+      .sort();
+    expect(catalogRuleIds()).toEqual(catalogued);
+  });
+});
+
+describe("renderEnvelope", () => {
+  it("attributes findings to catalog ids and publishes the inventory", async () => {
+    const results = await lintModule(
+      'export function View() {\n  return <button style={{ color: "#fff" }}>x</button>;\n}\n',
+    );
+    const { envelope, human } = renderEnvelope(results, path.resolve("."), {
+      layoutContract: true,
+    });
+    expect(envelope.terp_findings).toBe(1);
+    expect(envelope.tool).toBe("@terp/eslint-boundaries");
+    expect(envelope.rules).toEqual(catalogRuleIds());
+    expect(envelope.not_applicable).toEqual([]);
+    const rules = envelope.findings.map((finding) => finding.rule);
+    expect(rules).toContain("frontend/token-styled-elements");
+    expect(rules).toContain("frontend/no-inline-styling");
+    expect(envelope.unattributed).toEqual([]);
+    expect(human.length).toBe(envelope.findings.length);
+  });
+
+  it("publishes an un-opted-in layout contract as not_applicable, never as passing", async () => {
+    // The opt-in rule is inert without a checked-in layout-contract.json; keeping it
+    // in `rules` would let a consumer render "evaluated, zero findings" = green for a
+    // rule that never ran. It moves to `not_applicable` instead.
+    const results = await lintModule("export const view = 1;\n");
+    const { envelope } = renderEnvelope(results, path.resolve("."), { layoutContract: false });
+    expect(envelope.not_applicable).toEqual(["frontend/layout-contract"]);
+    expect(envelope.rules).toEqual(
+      catalogRuleIds().filter((id) => id !== "frontend/layout-contract"),
+    );
+  });
+
+  it("appends budget drift as frontend/escape-hatch findings", () => {
+    const { envelope, human } = renderEnvelope([], path.resolve("."), {
+      layoutContract: true,
+      budgetProblems: ["unbudgeted marker 'terp-allow-no-eval' used 1 time(s)"],
+      budgetFile: "escape-hatch-budget.json",
+    });
+    expect(envelope.findings).toEqual([
+      {
+        rule: "frontend/escape-hatch",
+        path: "escape-hatch-budget.json",
+        message: "unbudgeted marker 'terp-allow-no-eval' used 1 time(s)",
+      },
+    ]);
+    expect(human).toHaveLength(1);
+  });
+
+  it("emits spec-shaped findings (findings.schema.json), separator-stable", async () => {
+    const schema = JSON.parse(
+      fs.readFileSync(path.join(SPEC_ROOT, "findings.schema.json"), "utf8"),
+    );
+    const item = schema.items;
+    const results = await lintModule("export const x = fetch('/api');\n");
+    const { envelope } = renderEnvelope(results, path.resolve("."));
+    expect(envelope.findings.length).toBeGreaterThan(0);
+    for (const finding of envelope.findings) {
+      expect(Object.keys(finding).sort()).toEqual(["line", "message", "path", "rule"]);
+      expect(finding.rule).toMatch(new RegExp(item.properties.rule.pattern));
+      expect(finding.path).toBe("src/modules/sample/View.tsx");
+      expect(finding.path).not.toContain("\\");
+      expect(Number.isInteger(finding.line)).toBe(true);
+      expect(finding.line).toBeGreaterThanOrEqual(1);
+    }
+  });
+
+  it("surfaces a non-boundary message as unattributed, never dropped", async () => {
+    // A parse error has no boundary attribution; it must stay visible in the envelope.
+    const results = await lintModule("export const = broken(\n");
+    const { envelope } = renderEnvelope(results, path.resolve("."));
+    expect(envelope.findings).toEqual([]);
+    expect(envelope.unattributed.length).toBeGreaterThan(0);
+    for (const entry of envelope.unattributed) {
+      expect(Object.keys(entry).sort()).toEqual(["line", "message", "path", "reported_as"]);
+      expect(entry.line).toBeGreaterThanOrEqual(1);
+    }
+  });
+});
+
+describe("terp-boundaries-lint (the bin)", () => {
+  const config =
+    'import terpBoundaries from "@terpjs/eslint-boundaries";\n' +
+    'export default [{ ignores: ["node_modules/**"] }, ...terpBoundaries];\n';
+
+  function runBin(root) {
+    return spawnSync(process.execPath, [FINDINGS_BIN], { cwd: root, encoding: "utf8" });
+  }
+
+  it("publishes the envelope on stdout, humans on stderr, verdict as exit code", () => {
+    const root = appRoot({
+      "package.json": '{ "type": "module" }',
+      "eslint.config.js": config,
+      "escape-hatch-budget.json": "{}",
+      "src/modules/sample/View.tsx": "export function View() {\n  return <button>x</button>;\n}\n",
+    });
+    const run = runBin(root);
+    expect(run.status).toBe(1);
+    const envelope = JSON.parse(run.stdout);
+    expect(envelope.terp_findings).toBe(1);
+    expect(envelope.findings.map((finding) => finding.rule)).toContain(
+      "frontend/token-styled-elements",
+    );
+    expect(envelope.findings[0].path).toBe("src/modules/sample/View.tsx");
+    expect(run.stderr).toMatch(/problem/);
+  });
+
+  it("stays green (exit 0) with an empty findings list on a clean app", () => {
+    const root = appRoot({
+      "package.json": '{ "type": "module" }',
+      "eslint.config.js": config,
+      "escape-hatch-budget.json": "{}",
+      "src/modules/sample/View.tsx": "export const view = 1;\n",
+    });
+    const run = runBin(root);
+    expect(run.status).toBe(0);
+    const envelope = JSON.parse(run.stdout);
+    expect(envelope.findings).toEqual([]);
+    expect(envelope.unattributed).toEqual([]);
+    // No layout-contract.json: the opt-in rule is not applicable, never "passing".
+    expect(envelope.not_applicable).toEqual(["frontend/layout-contract"]);
+    expect(envelope.rules).toEqual(
+      catalogRuleIds().filter((id) => id !== "frontend/layout-contract"),
+    );
+  });
+
+  it("reports budget drift even when the boundary lint fails (both halves always run)", () => {
+    // The regression the merged bin exists for: with `eslint . && terp-boundaries-budget`
+    // a boundary violation short-circuited the ratchet, hiding budget drift from the run.
+    const root = appRoot({
+      "package.json": '{ "type": "module" }',
+      "eslint.config.js": config,
+      "escape-hatch-budget.json": "{}",
+      "src/modules/sample/View.tsx":
+        "// terp-allow-no-eval: measured host quirk\n" +
+        "export function View() {\n  return <button>x</button>;\n}\n",
+    });
+    const run = runBin(root);
+    expect(run.status).toBe(1);
+    const rules = JSON.parse(run.stdout).findings.map((finding) => finding.rule);
+    expect(rules).toContain("frontend/token-styled-elements"); // the lint half
+    expect(rules).toContain("frontend/escape-hatch"); // the ratchet half, not skipped
+  });
+
+  it("fails closed on a missing budget file, attributed to frontend/escape-hatch", () => {
+    const root = appRoot({
+      "package.json": '{ "type": "module" }',
+      "eslint.config.js": config,
+      "src/modules/sample/View.tsx": "export const view = 1;\n",
+    });
+    const run = runBin(root);
+    expect(run.status).toBe(1);
+    const envelope = JSON.parse(run.stdout);
+    expect(envelope.findings).toHaveLength(1);
+    expect(envelope.findings[0].rule).toBe("frontend/escape-hatch");
+    expect(envelope.findings[0].message).toMatch(/budget file not found/);
+  });
+
+  it("includes layout-contract in the inventory when the app has opted in", () => {
+    const root = appRoot({
+      "package.json": '{ "type": "module" }',
+      "eslint.config.js": config,
+      "escape-hatch-budget.json": "{}",
+      "layout-contract.json": '{ "contract": "standard" }',
+      "src/modules/sample/View.tsx": "export const view = 1;\n",
+    });
+    const run = runBin(root);
+    expect(run.status).toBe(0);
+    const envelope = JSON.parse(run.stdout);
+    expect(envelope.rules).toEqual(catalogRuleIds());
+    expect(envelope.not_applicable).toEqual([]);
+  });
+});
+
+describe("the check report (--format check-report, app-check-report.schema.json)", () => {
+  const config =
+    'import terpBoundaries from "@terpjs/eslint-boundaries";\n' +
+    'export default [{ ignores: ["node_modules/**"] }, ...terpBoundaries];\n';
+
+  function runBin(root, args) {
+    return spawnSync(process.execPath, [FINDINGS_BIN, ...args], { cwd: root, encoding: "utf8" });
+  }
+
+  it("asCheckReport self-describes the envelope in the spec's report shape", async () => {
+    const schema = JSON.parse(
+      fs.readFileSync(path.join(SPEC_ROOT, "app-check-report.schema.json"), "utf8"),
+    );
+    const results = await lintModule("export const x = fetch('/api');\n");
+    const { envelope } = renderEnvelope(results, path.resolve("."), { layoutContract: true });
+    const report = asCheckReport(envelope);
+    expect(report.terp_check_report).toBe(1);
+    // The certified spec version rides every report. Shape only here — the
+    // equality lock against the pinned @terp/spec lives in the framework gate
+    // (test_check_json.py), because certification runs THIS suite against
+    // candidate spec releases whose version is allowed to be newer.
+    expect(report.spec_version).toMatch(/^\d+\.\d+\.\d+$/);
+    expect(report.checker.tool).toBe("@terp/eslint-boundaries");
+    expect(report.checker.version).toMatch(/^\d+\.\d+\.\d+$/);
+    expect(report.ok).toBe(false);
+    expect(report.rules).toEqual(catalogRuleIds());
+    expect(Object.keys(report).sort()).toEqual(
+      Object.keys(schema.properties).sort().filter((key) => key !== "error"),
+    );
+    const itemProperties = new Set(Object.keys(schema.properties.findings.items.properties));
+    for (const finding of report.findings) {
+      expect(finding.rule).toMatch(
+        new RegExp(schema.properties.findings.items.properties.rule.pattern),
+      );
+      for (const key of Object.keys(finding)) {
+        expect(itemProperties.has(key)).toBe(true);
+      }
+    }
+  });
+
+  it("omits a null reported_as instead of publishing it (the schema forbids null)", async () => {
+    const results = await lintModule("export const = broken(\n");
+    const { envelope } = renderEnvelope(results, path.resolve("."));
+    const report = asCheckReport(envelope);
+    expect(report.unattributed.length).toBeGreaterThan(0);
+    for (const entry of report.unattributed) {
+      expect("reported_as" in entry).toBe(false);
+      expect(Object.keys(entry).sort()).toEqual(["line", "message", "path"]);
+    }
+  });
+
+  it("the bin prints exactly one check-report document under --format check-report", () => {
+    const root = appRoot({
+      "package.json": '{ "type": "module" }',
+      "eslint.config.js": config,
+      "escape-hatch-budget.json": "{}",
+      "src/modules/sample/View.tsx": "export function View() {\n  return <button>x</button>;\n}\n",
+    });
+    const run = runBin(root, ["--format", "check-report"]);
+    expect(run.status).toBe(1);
+    const report = JSON.parse(run.stdout); // strict single-document parse
+    expect(report.terp_check_report).toBe(1);
+    expect(report.spec_version).toBe(SPEC_VERSION);
+    expect(report.ok).toBe(false);
+    expect(report.findings.map((finding) => finding.rule)).toContain(
+      "frontend/token-styled-elements",
+    );
+    expect(report.not_applicable).toEqual(["frontend/layout-contract"]);
+  });
+
+  it("keeps the default format as the legacy terp_findings envelope", () => {
+    const root = appRoot({
+      "package.json": '{ "type": "module" }',
+      "eslint.config.js": config,
+      "escape-hatch-budget.json": "{}",
+      "src/modules/sample/View.tsx": "export const view = 1;\n",
+    });
+    const run = runBin(root, []);
+    expect(run.status).toBe(0);
+    const envelope = JSON.parse(run.stdout);
+    expect(envelope.terp_findings).toBe(1);
+    expect("terp_check_report" in envelope).toBe(false);
+  });
+
+  it("refuses an unsupported format (fail closed, exit 2)", () => {
+    const root = appRoot({
+      "package.json": '{ "type": "module" }',
+      "eslint.config.js": config,
+      "escape-hatch-budget.json": "{}",
+      "src/modules/sample/View.tsx": "export const view = 1;\n",
+    });
+    const run = runBin(root, ["--format", "yaml"]);
+    expect(run.status).toBe(2);
+    expect(run.stderr).toMatch(/unsupported --format/);
+  });
+
+  it("still reads a positional budget path alongside the flag", () => {
+    const root = appRoot({
+      "package.json": '{ "type": "module" }',
+      "eslint.config.js": config,
+      "custom-budget.json": "{}",
+      "src/modules/sample/View.tsx": "export const view = 1;\n",
+    });
+    const run = runBin(root, ["--format", "check-report", "custom-budget.json"]);
+    expect(run.status).toBe(0);
+    const report = JSON.parse(run.stdout);
+    expect(report.ok).toBe(true);
+    expect(report.rules).toContain("frontend/escape-hatch");
+  });
+});