paperlint 3.1.0 → 3.1.1

package/scripts/coverage-config.test.ts

@@ -0,0 +1,406 @@
+/**
+ * The exclusions in `.c8rc.json` are CLAIMS about the excluded files, and each claim is checked
+ * here — otherwise an exclusion is the quiet way to make coverage go up.
+ *
+ *   - `typeOnly`: files with no runtime code. c8's `all` counts every line of a file no test
+ *     loaded, and a types-only module compiles to nothing, so it can never be "covered". The
+ *     claim is checked on the syntax tree: a file listed here that grows a function or a constant
+ *     fails this test and must leave the list.
+ *   - `evalOnly`: support for the PAID `*.eval.mjs` evaluations, which `npm test` never runs. The
+ *     claim is that nothing but an eval (or another eval-only module) imports them.
+ *
+ * The floor itself is pinned: lines, statements, functions and branches are all 100, `npm run
+ * coverage` checks them, and CI runs that script — lowering any of the three links fails here.
+ *
+ * Two more gates close the ways around a 100% threshold (owner's rule for #52):
+ *   - no measured source carries a coverage-ignore comment (`c8`/`v8`/`istanbul`/`node:coverage
+ *     ignore`) — an effect a test cannot reach is made injectable instead;
+ *   - the exclude list is PINNED: a new pattern fails here until this file names it, with its
+ *     reason, on purpose.
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { globSync, readFileSync } from "node:fs";
+import { dirname, join, matchesGlob, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// @ts-expect-error — js-yaml ships no types, and the package does not depend on @types/js-yaml
+import yaml from "js-yaml";
+import ts from "typescript";
+import { test } from "vitest";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const CONFIG = JSON.parse(readFileSync(join(ROOT, ".c8rc.json"), "utf8")) as {
+  lines: number;
+  statements: number;
+  functions: number;
+  branches: number;
+  excludeAfterRemap: boolean;
+  include: string[];
+  exclude: string[];
+  extension: string[];
+  typeOnly: string[];
+  evalOnly: string[];
+};
+
+const expand = (patterns: readonly string[]): string[] =>
+  patterns.flatMap((p) => globSync(p, { cwd: ROOT })).sort();
+
+/** Statements that emit JavaScript — anything but interfaces, type aliases and type-only imports/exports. */
+export function runtimeStatements(fileName: string, source: string): string[] {
+  const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest);
+  return sf.statements
+    .filter(
+      (s) =>
+        !ts.isInterfaceDeclaration(s) &&
+        !ts.isTypeAliasDeclaration(s) &&
+        !(ts.isImportDeclaration(s) && s.importClause?.isTypeOnly) &&
+        !(ts.isExportDeclaration(s) && s.isTypeOnly),
+    )
+    .map((s) => ts.SyntaxKind[s.kind]);
+}
+
+/** Every relative module specifier a source imports, statically or with `import("…")`. */
+export function importedPaths(fileName: string, source: string): string[] {
+  const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest);
+  const found: string[] = [];
+  const visit = (node: ts.Node): void => {
+    const spec = ts.isImportDeclaration(node)
+      ? node.moduleSpecifier
+      : ts.isCallExpression(node) &&
+          node.expression.kind === ts.SyntaxKind.ImportKeyword
+        ? node.arguments[0]
+        : undefined;
+    if (spec && ts.isStringLiteral(spec) && spec.text.startsWith("."))
+      found.push(resolve(dirname(fileName), spec.text));
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return found;
+}
+
+test("the named exclusion lists are part of c8's exclude, and match files", () => {
+  for (const list of [CONFIG.typeOnly, CONFIG.evalOnly]) {
+    assert.deepEqual(
+      list.filter((p) => !CONFIG.exclude.includes(p)),
+      [],
+    );
+    assert.ok(expand(list).length >= list.length);
+  }
+});
+
+test("runtimeStatements tells a types-only module from one with code", () => {
+  assert.deepEqual(
+    [
+      runtimeStatements(
+        "a.ts",
+        'import type { X } from "./x";\nexport type Y = X;\ninterface Z {}\n',
+      ),
+      runtimeStatements("b.ts", "export type Y = 1;\nexport const y = 1;\n"),
+    ],
+    [[], ["FirstStatement"]],
+  );
+});
+
+test("every typeOnly exclusion has no runtime code", () => {
+  const offenders = expand(CONFIG.typeOnly)
+    .map(
+      (f) =>
+        [f, runtimeStatements(f, readFileSync(join(ROOT, f), "utf8"))] as const,
+    )
+    .filter(([, rt]) => rt.length > 0);
+  assert.deepEqual(offenders, []);
+});
+
+test("every evalOnly exclusion is imported only by an eval or another evalOnly module", () => {
+  const evalOnly = new Set(expand(CONFIG.evalOnly).map((f) => join(ROOT, f)));
+  const sources = globSync("**/*.{mjs,ts}", {
+    cwd: ROOT,
+    exclude: (p) => p === "node_modules" || p === "dist" || p === "coverage",
+  });
+  const importers = sources.flatMap((f) => {
+    const abs = join(ROOT, f);
+    return importedPaths(abs, readFileSync(abs, "utf8"))
+      .filter((target) => evalOnly.has(target))
+      .map(() => f);
+  });
+  const outsiders = importers.filter(
+    (f) => !f.endsWith(".eval.mjs") && !evalOnly.has(join(ROOT, f)),
+  );
+  assert.deepEqual(
+    { outsiders, anyImporter: importers.length > 0 },
+    {
+      outsiders: [],
+      anyImporter: true,
+    },
+  );
+});
+
+/** Every tracked file c8 could load as code — the extensions it is configured to measure. */
+function trackedSources(): string[] {
+  const r = spawnSync("git", ["ls-files", "-z"], {
+    cwd: ROOT,
+    encoding: "utf8",
+  });
+  assert.equal(r.status, 0, r.stderr);
+  return r.stdout
+    .split("\0")
+    .filter((f) => CONFIG.extension.some((x) => f.endsWith(x)))
+    .sort();
+}
+const isIncluded = (f: string): boolean =>
+  CONFIG.include.some((p) => matchesGlob(f, p));
+const isExcluded = (f: string): boolean =>
+  CONFIG.exclude.some((p) => matchesGlob(f, p));
+const isMeasured = (f: string): boolean => isIncluded(f) && !isExcluded(f);
+
+/** The files c8 measures: `include` globs, the configured extensions, minus every `exclude`. */
+function measuredFiles(): string[] {
+  return [...new Set(CONFIG.include.flatMap((p) => globSync(p, { cwd: ROOT })))]
+    .filter((f) => CONFIG.extension.some((x) => f.endsWith(x)))
+    .filter((f) => !CONFIG.exclude.some((x) => matchesGlob(f, x)))
+    .sort();
+}
+
+/**
+ * The text of every comment in a JS/TS source, read off the parsed tree — not by grep, which
+ * cannot tell a comment from a string or a regex. Every comment is trivia around a token — leading
+ * the token after it, or trailing the one before it on the same line — so the comment ranges
+ * around every token (end-of-file included) are all of them.
+ */
+export function comments(fileName: string, source: string): string[] {
+  const sf = ts.createSourceFile(
+    fileName,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    fileName.endsWith(".ts") ? ts.ScriptKind.TS : ts.ScriptKind.JS,
+  );
+  const found = new Map<number, string>();
+  const visit = (node: ts.Node): void => {
+    if (ts.isJSDoc(node)) return; // its text is the comment already collected before its node
+    const kids = node.getChildren(sf);
+    if (kids.length > 0) return kids.forEach(visit);
+    for (const r of [
+      ...(ts.getLeadingCommentRanges(source, node.pos) ?? []),
+      ...(ts.getTrailingCommentRanges(source, node.end) ?? []),
+    ])
+      found.set(r.pos, source.slice(r.pos, r.end));
+  };
+  visit(sf);
+  return [...found.entries()].sort(([a], [b]) => a - b).map(([, text]) => text);
+}
+
+const IGNORE = /\b(?:c8|v8|istanbul|node:coverage)\s+ignore\b/;
+
+test("comments() finds comments and only comments — before a closing brace, in a template, at the end", () => {
+  assert.deepEqual(
+    comments(
+      "a.ts",
+      [
+        'const s = "/* c8 ignore next */";',
+        "const r = /x\\/y/; // v8 ignore",
+        "const t = `${1 /* in a template */}`;",
+        "try {",
+        "  f();",
+        "  /* c8 ignore start */",
+        "} catch {}",
+        "/* at the end */",
+      ].join("\n"),
+    ),
+    [
+      "// v8 ignore",
+      "/* in a template */",
+      "/* c8 ignore start */",
+      "/* at the end */",
+    ],
+  );
+});
+
+test("no measured source carries a coverage-ignore comment", () => {
+  const files = measuredFiles();
+  // The scan covers exactly what c8 measures: the same set, derived from the tracked files.
+  assert.deepEqual(files, trackedSources().filter(isMeasured));
+  assert.ok(files.length > 0);
+  const offenders = files.filter((f) =>
+    comments(f, readFileSync(join(ROOT, f), "utf8")).some((c) =>
+      IGNORE.test(c),
+    ),
+  );
+  assert.deepEqual(offenders, []);
+});
+
+test("the floor is 100 on all four measures, and the script that checks it cannot loosen it", () => {
+  assert.deepEqual(
+    [CONFIG.lines, CONFIG.statements, CONFIG.functions, CONFIG.branches],
+    [100, 100, 100, 100],
+  );
+  const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")) as {
+    scripts: Record<string, string>;
+  };
+  // Pinned whole: c8's command-line flags override .c8rc.json, so `--lines 50` or `--exclude "**"`
+  // added here would bypass every threshold and the pinned exclude list below.
+  assert.equal(
+    pkg.scripts["coverage"],
+    'NODE_OPTIONS="--import=./test/coverage-src.mjs $NODE_OPTIONS" c8 --check-coverage npm test --',
+  );
+});
+
+/** The gates job and the one step of it that runs coverage, read from the parsed workflow. */
+interface Step {
+  readonly run?: string;
+  readonly if?: unknown;
+  readonly "continue-on-error"?: unknown;
+}
+interface Job {
+  readonly if?: unknown;
+  readonly "continue-on-error"?: unknown;
+  readonly steps?: readonly Step[];
+}
+export function coverageSteps(
+  workflow: string,
+): { job: string; definition: Job; step: Step }[] {
+  const ci = yaml.load(workflow) as { jobs: Record<string, Job> };
+  return Object.entries(ci.jobs).flatMap(([job, definition]) =>
+    (definition.steps ?? [])
+      .filter((step) => (step.run ?? "").trim().startsWith("npm run coverage"))
+      .map((step) => ({ job, definition, step })),
+  );
+}
+
+const DRAFT_GATE =
+  "github.event_name != 'pull_request' || github.event.pull_request.draft == false";
+
+/** Why CI's coverage step would not fail the run on a coverage drop — empty when it would. */
+export function coverageStepHoles(workflow: string): string[] {
+  const found = coverageSteps(workflow);
+  if (found.length !== 1)
+    return [
+      `expected one step running \`npm run coverage\`, found ${String(found.length)}`,
+    ];
+  const [{ job, definition, step }] = found as [(typeof found)[number]];
+  return [
+    ...(job === "gates" ? [] : [`the step is in job ${job}, not gates`]),
+    ...(definition.if === DRAFT_GATE
+      ? []
+      : [
+          `job ${job} runs if ${JSON.stringify(definition.if)}, not only the draft gate`,
+        ]),
+    ...("continue-on-error" in definition
+      ? [`job ${job} has continue-on-error`]
+      : []),
+    ...(step.if === undefined
+      ? []
+      : [`the step has if: ${JSON.stringify(step.if)}`]),
+    ...("continue-on-error" in step ? ["the step has continue-on-error"] : []),
+    ...(step.run?.trim() === "npm run coverage -- --no-skip"
+      ? []
+      : [
+          `the step runs ${JSON.stringify(step.run)}, not \`npm run coverage -- --no-skip\``,
+        ]),
+  ];
+}
+
+test("CI runs the coverage step in the gates job, unconditionally past the draft gate, and fails on it", () => {
+  const ci = readFileSync(join(ROOT, ".github", "workflows", "ci.yml"), "utf8");
+  assert.deepEqual(coverageStepHoles(ci), []);
+});
+
+test("coverageStepHoles names every way to keep CI green over a coverage drop", () => {
+  const wf = (step: string, jobIf = DRAFT_GATE, job = "gates") =>
+    [
+      "jobs:",
+      `  ${job}:`,
+      `    if: ${JSON.stringify(jobIf)}`,
+      "    steps:",
+      "      - name: coverage",
+      `        run: npm run coverage -- --no-skip${step}`,
+    ].join("\n");
+  assert.deepEqual(
+    [
+      coverageStepHoles(wf("")),
+      coverageStepHoles(wf("\n        continue-on-error: true")),
+      coverageStepHoles(wf("\n        if: false")),
+      coverageStepHoles(wf("", "false")),
+      coverageStepHoles(wf("", DRAFT_GATE, "other")),
+      coverageStepHoles("jobs:\n  gates:\n    steps: []\n"),
+    ],
+    [
+      [],
+      ["the step has continue-on-error"],
+      ["the step has if: false"],
+      ['job gates runs if "false", not only the draft gate'],
+      ["the step is in job other, not gates"],
+      ["expected one step running `npm run coverage`, found 0"],
+    ],
+  );
+});
+
+test("dist/ is excluded BEFORE source maps: a direct load is not a second copy of src/", () => {
+  // With `true`, a dist/ file remapped through its source map lands under src/ and escapes the
+  // `dist/**` exclude — measured: the extract-pdf-facts shim, spawned without NODE_OPTIONS, added a
+  // column-shifted duplicate of every function in the src/ modules it imported.
+  assert.equal(CONFIG.excludeAfterRemap, false);
+});
+
+test("the exclude list is exactly the justified set", () => {
+  assert.deepEqual(CONFIG.exclude, [
+    // tests themselves
+    "**/*.harness.mjs",
+    "**/*.test.*",
+    // PAID LLM evaluations, never run by `npm test`
+    "**/*.eval.mjs",
+    // skill sources vigiles compiles into SKILL.md
+    "**/*.spec.ts",
+    // type declarations
+    "**/*.d.ts",
+    "**/*.d.mts",
+    // inputs the tests read
+    "**/fixtures/**",
+    // build output (the coverage run resolves it to src/ — test/coverage-src.mjs)
+    "dist/**",
+    // test support
+    "test/**",
+    // not sources: dependencies, the report itself
+    "node_modules/**",
+    "coverage/**",
+    // typeOnly — checked above to hold no runtime code
+    ...CONFIG.typeOnly,
+    // evalOnly — checked above to be imported only by evals
+    ...CONFIG.evalOnly,
+    // dated research records kept as evidence for the skills' prose and the prior-art notes
+    "skills/**/repro/**",
+    "skills/**/references/**",
+    "docs/prior-art/repro/**",
+    // the test runner's own configuration, read by vitest, not code the package runs
+    "vitest.config.ts",
+  ]);
+  assert.deepEqual(CONFIG.include, [
+    "bin/**",
+    "src/**/*.ts",
+    "lib/**",
+    "eslint-rules/**",
+    "hooks/**",
+    "skills/**",
+    "scripts/**",
+    "eslint.config.mjs",
+  ]);
+  assert.deepEqual(CONFIG.typeOnly, [
+    "src/types.ts",
+    "src/ports/*.ts",
+    "src/domain/page-layout.ts",
+    "src/domain/paths.ts",
+  ]);
+  assert.deepEqual(CONFIG.evalOnly, [
+    "lib/skill-eval-kit.mjs",
+    "lib/skill-eval-fixture.mjs",
+    "lib/trigger-ledger.mjs",
+  ]);
+});
+
+test("every tracked source is either measured or excluded by a pattern named above", () => {
+  // A new directory outside `include` would otherwise be invisible to c8 and to this file alike.
+  assert.deepEqual(
+    trackedSources().filter((f) => !isIncluded(f) && !isExcluded(f)),
+    [],
+  );
+});

package/scripts/eslint-report-guard.test.mjs

@@ -0,0 +1,48 @@
+/**
+ * The report guard's listing: a file entry without `messages`, a warning, and a message with no
+ * rule (ESLint's own parse errors carry `ruleId: null`). The zero-file refusal and the pass-through
+ * are driven end to end by `action.harness.mjs`.
+ */
+import assert from "node:assert/strict";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { test } from "vitest";
+import { useTempDir } from "../test/support.mjs";
+import { guard } from "./eslint-report-guard.mjs";
+
+test("warnings and rule-less messages are listed; a file with no messages counts as linted", () => {
+  const report = join(useTempDir("report-guard-"), "report.json");
+  writeFileSync(
+    report,
+    JSON.stringify([
+      {
+        filePath: "a.md",
+        messages: [
+          {
+            severity: 1,
+            line: 2,
+            column: 3,
+            ruleId: "paper/x",
+            message: "soft",
+          },
+          {
+            severity: 2,
+            line: 1,
+            column: 1,
+            ruleId: null,
+            message: "Parsing error",
+          },
+        ],
+      },
+      { filePath: "b.md" },
+    ]),
+  );
+  assert.deepEqual(guard(report, 1), {
+    code: 1,
+    lines: [
+      "warning a.md:2:3  paper/x  soft",
+      "error a.md:1:1  (no rule)  Parsing error",
+      "\nlinted 2 file(s) · 2 finding(s) · 1 error(s) · 1 warning(s)",
+    ],
+  });
+});

package/scripts/harness-api.frozen.json

@@ -13,11 +13,9 @@
     "eslint-rules/tex-build.harness.mjs",
     "fixtures/real-markdown-paper/real-markdown-paper.harness.mjs",
     "lib/agent-cli-version.harness.mjs",
-    "lib/mutation-driver.harness.mjs",
     "lib/paper-config.harness.mjs",
     "lib/skill-trigger-cases.harness.mjs",
     "scripts/check.harness.mjs",
-    "scripts/mutation-batteries-frozen.harness.mjs",
     "scripts/rules-are-content-only.harness.mjs",
     "scripts/rules-see-files.harness.mjs",
     "skills/analyze-sibling-paper/analyze-sibling-paper.harness.mjs",

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

@@ -21,8 +21,16 @@ export declare function judge(o: {
   unexplained: readonly string[];
   frozen: Counts;
 }): string[];
-export declare function checkFrozen(root?: string): Promise<{
+export declare function checkFrozen(
+  root?: string,
+  options?: { lint?: (cwd: string) => Promise<unknown[]> },
+): Promise<{
   problems: string[];
   frozen: Counts;
   counts: Counts;
 }>;
+export declare function main(options?: {
+  check?: () => Promise<{ problems: string[]; frozen: Counts; counts: Counts }>;
+  log?: (line: string) => void;
+  err?: (line: string) => void;
+}): Promise<number>;

package/scripts/layer-legacy-frozen.mjs

@@ -12,7 +12,7 @@
  * `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:
+ * a list that may only shrink:
  *
  *   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;
@@ -34,6 +34,7 @@
  *
  * Run: `node scripts/layer-legacy-frozen.mjs` (also part of `npm run check`)
  */
+import { isMain } from "../skills/paper-pipeline/scripts/consumer.mjs";
 import { readFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -114,12 +115,16 @@ export function judge({ counts, unexplained, frozen }) {
 }
 
 /** Lint `src/` with the repository's configuration and run the whole check. */
-export async function checkFrozen(root = ROOT) {
+export async function checkFrozen(
+  root = ROOT,
+  { lint = (cwd) => new ESLint({ cwd }).lintFiles(["src/**/*.ts"]) } = {},
+) {
   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.
+  // ESLint itself THROWS when the glob matches nothing ("No files matching 'src/**/*.ts' were
+  // found") or only ignored files — measured. An empty result from any other linter (or a
+  // configuration that lets it through) must not tally nothing and report every frozen file fixed.
+  const raw = await lint(root);
   if (raw.length === 0)
     return {
       problems: ["src/**/*.ts matched no file — nothing was counted."],
@@ -134,19 +139,31 @@ export async function checkFrozen(root = ROOT) {
   return { problems: judge({ ...t, frozen }), frozen, counts: t.counts };
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
-  const { problems, counts } = await checkFrozen(ROOT);
+/**
+ * The gate: exit 1 naming every problem, or 0 with the count of what stays frozen. `check` is
+ * injected so a test can hand it problems without planting suppressions in real source.
+ */
+export async function main({
+  check = () => checkFrozen(ROOT),
+  log = console.log,
+  err = console.error,
+} = {}) {
+  const { problems, counts } = await check();
   if (problems.length) {
-    console.error(
+    err(
       `🔴 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);
+    for (const p of problems) err(`   ${p}`);
+    return 1;
   }
   const n = Object.values(counts)
     .flatMap((r) => Object.values(r))
     .reduce((s, v) => s + v, 0);
-  console.log(
+  log(
     `✓ ${String(Object.keys(counts).length)} legacy files, ${String(n)} frozen layer exemptions, none new, none grown (#76)`,
   );
+  return 0;
 }
+
+// `isMain`, not a comparison with `file://${argv[1]}`: that is false through a symlink (consumer.mjs).
+if (isMain(import.meta.url)) process.exit(await main());