paperlint 2.0.0

package/scripts/harness-api.test.ts

@@ -0,0 +1,175 @@
+/**
+ * What makes a file a HARNESS. A `*.harness.*` file tests the agent surface, so it drives it through
+ * vigiles: it imports `runHook`, `runHarnessTest` or `runEval` from `vigiles` (or a `vigiles/…`
+ * entry point). Anything else is a plain unit test and is named `*.test.ts`, run by vitest.
+ *
+ * The rule is read from the file's IMPORTS, parsed with the TypeScript compiler — not from its
+ * folder and not from a text search: a comment or a string that mentions `runHook` is not an import,
+ * and `src/cli.harness.mjs` calls a function of rpp's own that happens to be called `runHook`.
+ *
+ * Harnesses that predate the rule and import none of the three are frozen in
+ * `harness-api.frozen.json` (issue #77). That list only shrinks: an entry that now imports the API,
+ * or that no longer exists, has to leave it.
+ */
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { test } from "vitest";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const FROZEN: readonly string[] = (
+  JSON.parse(
+    readFileSync(join(ROOT, "scripts", "harness-api.frozen.json"), "utf8"),
+  ) as { harnesses: string[] }
+).harnesses;
+
+/** vigiles' agent-testing API — what a harness exists to call. */
+export const AGENT_API = new Set(["runHook", "runHarnessTest", "runEval"]);
+
+const isHarnessName = (path: string): boolean =>
+  /\.harness\.[cm]?[jt]s$/.test(basename(path));
+
+const fromVigiles = (spec: ts.Expression | undefined): boolean =>
+  spec !== undefined &&
+  ts.isStringLiteral(spec) &&
+  (spec.text === "vigiles" || spec.text.startsWith("vigiles/"));
+
+/** Names bound by `import { a, b as c } from "vigiles…"` — the EXPORTED names, a and b. */
+function staticNames(node: ts.Node): string[] {
+  if (!ts.isImportDeclaration(node) || !fromVigiles(node.moduleSpecifier))
+    return [];
+  const named = node.importClause?.namedBindings;
+  if (!named || !ts.isNamedImports(named)) return [];
+  return named.elements.map((e) => (e.propertyName ?? e.name).text);
+}
+
+/** Names destructured from `await import("vigiles…")`: `const { runHook } = await import(…)`. */
+function dynamicNames(node: ts.Node): string[] {
+  if (!ts.isVariableDeclaration(node) || !node.initializer) return [];
+  if (!ts.isObjectBindingPattern(node.name)) return [];
+  const init = ts.isAwaitExpression(node.initializer)
+    ? node.initializer.expression
+    : node.initializer;
+  const isImport =
+    ts.isCallExpression(init) &&
+    init.expression.kind === ts.SyntaxKind.ImportKeyword &&
+    fromVigiles(init.arguments[0]);
+  if (!isImport) return [];
+  return node.name.elements.map((e) => {
+    const key = e.propertyName ?? e.name;
+    return ts.isIdentifier(key) ? key.text : "";
+  });
+}
+
+/** Does this source import at least one of vigiles' agent-testing functions? */
+export function importsAgentApi(fileName: string, source: string): boolean {
+  const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest);
+  let found = false;
+  const visit = (node: ts.Node): void => {
+    if (
+      [...staticNames(node), ...dynamicNames(node)].some((n) =>
+        AGENT_API.has(n),
+      )
+    )
+      found = true;
+    if (!found) ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return found;
+}
+
+/** Harness-named files, among `paths`, that import none of the API and are not frozen. */
+export function misnamed(
+  files: ReadonlyMap<string, string>,
+  frozen: readonly string[],
+): string[] {
+  return [...files]
+    .filter(([p]) => isHarnessName(p) && !frozen.includes(p))
+    .filter(([p, src]) => !importsAgentApi(p, src))
+    .map(([p]) => p);
+}
+
+/** Frozen entries that must leave: gone from the tree, or now importing the API. */
+export function mustLeave(
+  files: ReadonlyMap<string, string>,
+  frozen: readonly string[],
+): string[] {
+  return frozen.filter((f) => {
+    const src = files.get(f);
+    return src === undefined || importsAgentApi(f, src);
+  });
+}
+
+/** Every harness-named file git knows about (tracked, or new and not ignored), with its source. */
+function harnessesOnDisk(): Map<string, string> {
+  const listed = execFileSync(
+    "git",
+    ["ls-files", "--cached", "--others", "--exclude-standard"],
+    { cwd: ROOT, encoding: "utf8" },
+  )
+    .split("\n")
+    .filter(isHarnessName);
+  return new Map(
+    listed.map((p) => [p, readFileSync(join(ROOT, p), "utf8")] as const),
+  );
+}
+
+test("every harness imports vigiles' agent-testing API, or is on the frozen list", () => {
+  // Guards: the rule on the real tree — a new plain test named `*.harness.*` turns this red.
+  assert.deepEqual(misnamed(harnessesOnDisk(), FROZEN), []);
+});
+
+test("the frozen list only shrinks", () => {
+  // Guards: a renamed, deleted or converted harness must leave the list, or it stops meaning anything.
+  assert.deepEqual(mustLeave(harnessesOnDisk(), FROZEN), []);
+});
+
+test("both halves, on planted files", () => {
+  const plain = 'import assert from "node:assert";\nassert.ok(true);\n';
+  const real = 'import { runHook } from "vigiles";\nrunHook("true", {});\n';
+  const files = new Map([
+    ["skills/x/x.harness.ts", plain],
+    ["src/y.harness.mjs", real],
+    [
+      "hooks/h.harness.mjs",
+      'const { runEval } = await import("vigiles/eval");\n',
+    ],
+    ["src/z.test.ts", plain],
+  ]);
+  // Guards: the fire half — a plain test named as a harness fails EVEN inside skills/.
+  assert.deepEqual(misnamed(files, []), ["skills/x/x.harness.ts"]);
+  // Guards: a file that is on the list but now imports the API has to leave it.
+  assert.deepEqual(mustLeave(files, ["src/y.harness.mjs"]), [
+    "src/y.harness.mjs",
+  ]);
+  // Guards: an entry whose file is gone has to leave it.
+  assert.deepEqual(mustLeave(files, ["gone.harness.mjs"]), [
+    "gone.harness.mjs",
+  ]);
+});
+
+test("an import is what counts — not a mention, not a same-named local function", () => {
+  // Guards: a comment and a string naming runHook do not make a harness.
+  const mention =
+    '// runHook\nconst s = "runHarnessTest";\nimport { x } from "vigiles";\n';
+  assert.equal(importsAgentApi("a.harness.mjs", mention), false);
+  // Guards: rpp's own `runHook` (src/cli.ts) is not vigiles'.
+  assert.equal(
+    importsAgentApi(
+      "b.harness.mjs",
+      'import { runHook } from "../src/cli.ts";\n',
+    ),
+    false,
+  );
+  // Guards: an aliased import still counts by the name vigiles exports.
+  assert.equal(
+    importsAgentApi(
+      "c.harness.mjs",
+      'import { runHook as hook } from "vigiles";\n',
+    ),
+    true,
+  );
+});

package/scripts/layer-legacy-frozen.d.mts

@@ -0,0 +1,28 @@
+/** Types for `layer-legacy-frozen.mjs`, for its TypeScript test. */
+export interface Suppressed {
+  readonly filePath: string;
+  readonly suppressedMessages?: readonly {
+    readonly ruleId: string | null;
+    readonly line: number;
+    readonly suppressions?: readonly { readonly justification?: string }[];
+  }[];
+}
+export type Counts = Record<string, Record<string, number>>;
+export declare const FROZEN_FILE: string;
+export declare const LAYER_RULES: readonly string[];
+export declare const NO_LEGACY_UNDER: readonly string[];
+export declare const LEGACY: RegExp;
+export declare function tally(results: readonly Suppressed[]): {
+  counts: Counts;
+  unexplained: string[];
+};
+export declare function judge(o: {
+  counts: Counts;
+  unexplained: readonly string[];
+  frozen: Counts;
+}): string[];
+export declare function checkFrozen(root?: string): Promise<{
+  problems: string[];
+  frozen: Counts;
+  counts: Counts;
+}>;

package/scripts/layer-legacy-frozen.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * layer-legacy-frozen.mjs — the legacy exemptions from `src/`'s layer rules may only SHRINK.
+ *
+ * `src/` is hexagonal on two axes (src/CLAUDE.md): who may know whom, and where effects may be
+ * written. The flat `src/*.ts` files predate both. Each site in them that still breaks a rule
+ * carries a directive naming the debt:
+ *
+ *   // eslint-disable-next-line boundaries/dependencies -- legacy I/O, moves behind a port in #76
+ *   // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
+ *
+ * `reportUnusedDisableDirectives: "error"` already makes a directive that suppresses nothing a lint
+ * error, so a fixed site must drop its comment. What that cannot stop is a NEW directive: a new file,
+ * or a new import in an old one, silenced the same way. This check freezes the per-file counts, in
+ * the shape `mutation-batteries-frozen.mjs` gives the mutation batteries:
+ *
+ *   1. a file carrying a legacy suppression that is not in the frozen list fails — a new exemption;
+ *   2. a listed file with no legacy suppression left fails — the list must shrink with the code;
+ *   3. a count that grew fails;
+ *   4. a count that shrank fails until the recorded number is lowered — otherwise a fixed site
+ *      leaves room for a different one to be silenced later.
+ *
+ * Plus two refusals the frozen list cannot express: no file under `src/domain/`, `src/ports/` or
+ * `src/adapters/` may carry one at all (those folders were written under the rules, so there is no
+ * legacy there to hold), and a layer finding silenced WITHOUT naming #76 is not a legacy site but
+ * an unexplained exemption.
+ *
+ * ── COUNTED FROM ESLINT'S OWN REPORT, NOT FROM THE SOURCE TEXT ─────────────────────────────
+ * The unit is a SUPPRESSED FINDING, read from `LintResult.suppressedMessages[].suppressions[]`:
+ * the linter itself says which finding a directive silenced and with what justification. A
+ * comment that only looks like a directive, or one on a line with nothing to silence, cannot be
+ * counted by construction — and a range directive (`/* eslint-disable … *\/` around a multi-line
+ * import) counts exactly what it silences.
+ *
+ * Run: `node scripts/layer-legacy-frozen.mjs` (also part of `npm run check`)
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ESLint } from "eslint";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const FROZEN_FILE = join("scripts", "layer-legacy.frozen.json");
+
+/** The rules that enforce the layers. A suppression of any other rule is not this check's business. */
+export const LAYER_RULES = ["boundaries/dependencies", "no-restricted-globals"];
+
+/** Where a legacy suppression may never appear: the folders written under the rules. */
+export const NO_LEGACY_UNDER = ["src/domain/", "src/ports/", "src/adapters/"];
+
+/** The justification every legacy directive carries — `I/O` or `layer`, then the issue. */
+export const LEGACY = /^legacy (I\/O|layer), moves behind a port in #76$/;
+
+/**
+ * Per file, per rule: how many layer findings a legacy directive suppressed. Pure: takes ESLint's
+ * results (`filePath` relative to the repository, POSIX separators) and returns the tally plus
+ * every layer suppression that is not a legacy one.
+ */
+export function tally(results) {
+  const counts = {};
+  const unexplained = [];
+  for (const r of results)
+    for (const m of r.suppressedMessages ?? []) {
+      if (!LAYER_RULES.includes(m.ruleId ?? "")) continue;
+      const why = (m.suppressions ?? []).map((s) => s.justification ?? "");
+      if (!why.some((j) => LEGACY.test(j.trim()))) {
+        unexplained.push(
+          `${r.filePath}:${String(m.line)}: ${String(m.ruleId)} is silenced with "${why.join(" | ")}" — a layer exemption must say "legacy I/O|layer, moves behind a port in #76", or the site must be fixed.`,
+        );
+        continue;
+      }
+      const file = (counts[r.filePath] ??= {});
+      file[m.ruleId] = (file[m.ruleId] ?? 0) + 1;
+    }
+  return { counts, unexplained };
+}
+
+/** Compare the tally with the frozen list. Pure. `frozen` is `{ path: { rule: count } }`. */
+export function judge({ counts, unexplained, frozen }) {
+  const problems = [...unexplained];
+  for (const [f, rules] of Object.entries(counts)) {
+    if (NO_LEGACY_UNDER.some((d) => f.startsWith(d)))
+      problems.push(
+        `${f}: carries a legacy layer exemption, and nothing under ${NO_LEGACY_UNDER.join(", ")} may — those folders are written under the rules. Fix the site (src/CLAUDE.md).`,
+      );
+    else if (!(f in frozen))
+      problems.push(
+        `${f}: a new legacy layer exemption is not accepted (#76). A module that needs the world is a new *.io.ts in the adapter of the program it talks to; an app file takes a port.`,
+      );
+    for (const [rule, got] of Object.entries(rules)) {
+      const want = frozen[f]?.[rule];
+      if (want === undefined) {
+        if (f in frozen)
+          problems.push(
+            `${f}: ${String(got)} legacy ${rule} suppression(s), frozen at 0 — no new exemptions in existing files (#76).`,
+          );
+      } else if (got > want)
+        problems.push(
+          `${f}: ${String(got)} legacy ${rule} suppressions, frozen at ${String(want)} — no new exemptions in existing files (#76).`,
+        );
+      else if (got < want)
+        problems.push(
+          `${f}: ${String(got)} legacy ${rule} suppressions, frozen at ${String(want)} — lower it to ${String(got)} in ${FROZEN_FILE} (the list must shrink with the code).`,
+        );
+    }
+  }
+  for (const [f, rules] of Object.entries(frozen))
+    for (const [rule, want] of Object.entries(rules))
+      if (!counts[f]?.[rule])
+        problems.push(
+          `${f}: no legacy ${rule} suppression left (frozen at ${String(want)}) — remove it from ${FROZEN_FILE}.`,
+        );
+  return problems;
+}
+
+/** Lint `src/` with the repository's configuration and run the whole check. */
+export async function checkFrozen(root = ROOT) {
+  const data = JSON.parse(readFileSync(join(root, FROZEN_FILE), "utf8"));
+  const frozen = data.files ?? {};
+  const eslint = new ESLint({ cwd: root });
+  const raw = await eslint.lintFiles(["src/**/*.ts"]);
+  // Guards: a glob that matched nothing tallies nothing and reports every frozen file as fixed.
+  if (raw.length === 0)
+    return {
+      problems: ["src/**/*.ts matched no file — nothing was counted."],
+      frozen,
+      counts: {},
+    };
+  const results = raw.map((r) => ({
+    ...r,
+    filePath: relative(root, r.filePath).split(sep).join("/"),
+  }));
+  const t = tally(results);
+  return { problems: judge({ ...t, frozen }), frozen, counts: t.counts };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const { problems, counts } = await checkFrozen(ROOT);
+  if (problems.length) {
+    console.error(
+      `🔴 legacy layer exemptions are frozen and may only shrink (#76) — ${String(problems.length)} problem(s):`,
+    );
+    for (const p of problems) console.error(`   ${p}`);
+    process.exit(1);
+  }
+  const n = Object.values(counts)
+    .flatMap((r) => Object.values(r))
+    .reduce((s, v) => s + v, 0);
+  console.log(
+    `✓ ${String(Object.keys(counts).length)} legacy files, ${String(n)} frozen layer exemptions, none new, none grown (#76)`,
+  );
+}

package/scripts/layer-legacy-frozen.test.ts

@@ -0,0 +1,115 @@
+/**
+ * The legacy-exemption ratchet (`layer-legacy-frozen.mjs`): each of its refusals fires on a planted
+ * case and stays silent on the matching clean one. The inputs are ESLint's own result shape, so the
+ * tally is tested on what the linter reports, not on source text.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { judge, tally, type Suppressed } from "./layer-legacy-frozen.mjs";
+
+const IO = "legacy I/O, moves behind a port in #76";
+const LAYER = "legacy layer, moves behind a port in #76";
+
+/** One file's result with a suppressed finding per `[rule, justification]`. */
+const result = (filePath: string, ...s: [string, string][]): Suppressed => ({
+  filePath,
+  suppressedMessages: s.map(([ruleId, justification], i) => ({
+    ruleId,
+    line: i + 1,
+    suppressions: [{ justification }],
+  })),
+});
+
+const BUILD = result(
+  "src/build.ts",
+  ["boundaries/dependencies", IO],
+  ["boundaries/dependencies", LAYER],
+  ["no-restricted-globals", IO],
+);
+const FROZEN = {
+  "src/build.ts": { "boundaries/dependencies": 2, "no-restricted-globals": 1 },
+};
+
+const problemsOf = (results: Suppressed[], frozen = FROZEN) =>
+  judge({ ...tally(results), frozen });
+
+test("counts per file and rule, and a tally equal to the frozen list is clean", () => {
+  assert.deepEqual(tally([BUILD]).counts, FROZEN);
+  assert.deepEqual(problemsOf([BUILD]), []);
+});
+
+test("a legacy suppression in a file the list does not name is a new exemption", () => {
+  const p = problemsOf([
+    BUILD,
+    result("src/new.ts", ["boundaries/dependencies", IO]),
+  ]);
+  assert.equal(p.length, 1);
+  assert.match(p[0] ?? "", /^src\/new\.ts: a new legacy layer exemption/);
+});
+
+test("a count that grew fails, and so does a rule the file was not frozen with", () => {
+  const grown = result(
+    "src/build.ts",
+    ["boundaries/dependencies", IO],
+    ["boundaries/dependencies", IO],
+    ["boundaries/dependencies", IO],
+    ["no-restricted-globals", IO],
+  );
+  assert.match(
+    problemsOf([grown]).join("\n"),
+    /3 legacy boundaries\/dependencies suppressions, frozen at 2/,
+  );
+  const newRule = judge({
+    ...tally([BUILD]),
+    frozen: { "src/build.ts": { "boundaries/dependencies": 2 } },
+  });
+  assert.match(
+    newRule.join("\n"),
+    /no-restricted-globals suppression\(s\), frozen at 0/,
+  );
+});
+
+test("a count that shrank fails until the frozen number is lowered, and a fixed file must leave", () => {
+  const shrunk = result(
+    "src/build.ts",
+    ["boundaries/dependencies", IO],
+    ["no-restricted-globals", IO],
+  );
+  assert.match(problemsOf([shrunk]).join("\n"), /lower it to 1/);
+  assert.match(
+    problemsOf([]).join("\n"),
+    /src\/build\.ts: no legacy boundaries\/dependencies suppression left/,
+  );
+});
+
+test("no file inside the new folders may carry one, even if someone froze it", () => {
+  for (const f of [
+    "src/domain/x.ts",
+    "src/ports/x.ts",
+    "src/adapters/banal/x.ts",
+  ]) {
+    const p = problemsOf([BUILD, result(f, ["boundaries/dependencies", IO])], {
+      ...FROZEN,
+      [f]: { "boundaries/dependencies": 1 },
+    });
+    assert.equal(p.length, 1, p.join("\n"));
+    assert.match(p[0] ?? "", /written under the rules/);
+  }
+});
+
+test("a layer finding silenced without naming #76 is reported; other rules' suppressions are not counted", () => {
+  const r = result(
+    "src/build.ts",
+    ["boundaries/dependencies", IO],
+    ["boundaries/dependencies", LAYER],
+    ["no-restricted-globals", IO],
+    ["boundaries/dependencies", "temporary"],
+    ["@typescript-eslint/no-explicit-any", "#49: replace with a real type"],
+  );
+  const p = problemsOf([r]);
+  assert.equal(p.length, 1, p.join("\n"));
+  assert.match(
+    p[0] ?? "",
+    /src\/build\.ts:4: boundaries\/dependencies is silenced with "temporary"/,
+  );
+});

package/scripts/layer-legacy.frozen.json

@@ -0,0 +1,50 @@
+{
+  "issue": "https://github.com/zernie/research-paper-pipeline/issues/76",
+  "why": "Legacy src/*.ts files that still do I/O or import an adapter or a tool package directly. May only shrink: fix a site, delete its directive, lower the count here (delete the file entry at zero). A new file may not appear. Counted from ESLint suppressedMessages by scripts/layer-legacy-frozen.mjs, part of npm run check.",
+  "files": {
+    "src/build-engine.ts": {
+      "boundaries/dependencies": 2,
+      "no-restricted-globals": 2
+    },
+    "src/build.ts": {
+      "boundaries/dependencies": 5,
+      "no-restricted-globals": 2
+    },
+    "src/doctor.ts": {
+      "boundaries/dependencies": 2,
+      "no-restricted-globals": 1
+    },
+    "src/engine.ts": {
+      "boundaries/dependencies": 2,
+      "no-restricted-globals": 1
+    },
+    "src/hooks-settings.ts": {
+      "boundaries/dependencies": 1
+    },
+    "src/init.ts": {
+      "boundaries/dependencies": 4,
+      "no-restricted-globals": 6
+    },
+    "src/link-skills.ts": {
+      "boundaries/dependencies": 1
+    },
+    "src/new-paper.ts": {
+      "boundaries/dependencies": 1
+    },
+    "src/pdf-facts.ts": {
+      "boundaries/dependencies": 3,
+      "no-restricted-globals": 1
+    },
+    "src/structure.ts": {
+      "boundaries/dependencies": 1,
+      "no-restricted-globals": 1
+    },
+    "src/tex-requirements.ts": {
+      "boundaries/dependencies": 2
+    },
+    "src/toolchain.ts": {
+      "boundaries/dependencies": 3,
+      "no-restricted-globals": 2
+    }
+  }
+}