paperlint 7.2.0 → 8.0.0

package/skills/paper-pipeline/scripts/population-map.harness.mjs

@@ -1,135 +0,0 @@
-/**
- * population-map.harness.mjs — the population gate, made visible to the metric, plus the layer
- * its own self-test cannot reach. `npx vigiles test .claude/skills/paper-pipeline/scripts/population-map.harness.mjs`.
- *
- * 🔴 SCOPE NARROWED 2026-08-26. Two findings out of four (`untied`, `undeclared`) moved to ESLint
- * rules — `paper/population-untied` and `paper/population-undeclared`, tests for them in
- * `eslint-rules/paper-registry.harness.mjs`. Two remain here: `stale` and `badref`, both are about
- * THE REGISTRY ITSELF (`repro/populations.tsv`), both have no address in the paper, and so cannot be expressed by ESLint,
- * which reports only to the linted file.
- *
- * The findings themselves are planted in `population-map.test.mjs` (vitest; until #52 a
- * self-test script this harness spawned). This file keeps what only the command shows: finding
- * paper.md and repro/populations.tsv, and `--flags-only` staying silent on a clean paper — the
- * wiring the CI step actually invokes.
- */
-import assert from "node:assert/strict";
-import { execFileSync } from "node:child_process";
-import {
-  mkdtempSync,
-  mkdirSync,
-  writeFileSync,
-  rmSync,
-  realpathSync,
-} from "node:fs";
-import { tmpdir } from "node:os";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { consumerRoot } from "./consumer.mjs";
-const HERE = dirname(fileURLToPath(import.meta.url));
-
-const ROOT = consumerRoot();
-const SCRIPT = join(HERE, "population-map.mjs");
-const tmp = realpathSync(mkdtempSync(join(tmpdir(), "popmap-harness-")));
-
-/** Run a node script; never throws on a non-zero exit. */
-function run(argv) {
-  try {
-    return {
-      code: 0,
-      out: execFileSync("node", argv, {
-        cwd: ROOT,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"],
-      }),
-    };
-  } catch (e) {
-    return { code: e.status ?? 1, out: (e.stdout || "") + (e.stderr || "") };
-  }
-}
-
-/** A paper dir carrying `body`, and optionally a population registry. */
-function paper(name, body, tsv) {
-  const d = join(tmp, name);
-  mkdirSync(join(d, "repro"), { recursive: true });
-  writeFileSync(
-    join(d, "paper.md"),
-    `## Abstract\n\n${body}\n\n## References\n\n[1] x.\n`,
-  );
-  if (tsv !== undefined)
-    writeFileSync(join(d, "repro", "populations.tsv"), tsv);
-  return d;
-}
-
-const REG = [
-  "id\tprinted\trelation\trelated_to\tgloss",
-  "broad\t1,921\troot\t\tthe corpus",
-  "census\t134\tdisjoint\tbroad\ta separate sample",
-].join("\n");
-
-// ── 2. the CLI finds the paper and the registry, and fires on a stale registry row ─────
-// 🔴 FIXTURE REWRITTEN 2026-08-26. Before that it planted an UNLINKED POPULATION, and that
-// finding moved to `paper/population-untied` — meaning the old «dirty» input became clean, and
-// the block would silently stop checking the argv → findings() wiring while staying green. Exactly that
-// class of failure this file was written for.
-{
-  const dirty = paper(
-    "cli-stale",
-    "The resolver ran over all 1,921 repositories at pinned commits.",
-    REG,
-  );
-  const r = run([SCRIPT, dirty, "--flags-only"]);
-  assert.match(
-    r.out,
-    /134 \(census\) is declared and the body no longer prints it/,
-    "the CLI did not report a stale registry row — the self-test proves findings() sees it, so what " +
-      "is broken is the path from argv to findings():\n" +
-      r.out,
-  );
-}
-
-// ── 3. …and says NOTHING when every declared population is printed ──────────────────────
-// The direction that matters more. A gate that fires on a paper which already obeys the rule gets
-// muted the same week, and a muted gate is indistinguishable from an absent one.
-{
-  const clean = paper(
-    "cli-clean",
-    "The resolver ran over all 1,921 repositories at pinned commits, and a census of 134\nrepositories is a separate sample from those 1,921, overlapping in seven.",
-    REG,
-  );
-  const r = run([SCRIPT, clean, "--flags-only"]);
-  assert.equal(
-    r.out.trim(),
-    "",
-    "--flags-only printed something about a paper whose registry matches its body:\n" +
-      r.out,
-  );
-}
-
-// ── 4. KNOWN GAP, asserted so it stays visible ─────────────────────────────────────────
-// 🔴 A paper with NO repro/populations.tsv exits 0 in silence, which reads as a pass for
-// draft-paper. So a paper that never declared its populations scores
-// identically to one that declared them and tied every one. Absence is invisible again — the same
-// shape artifact-coverage.mjs was written to close for the released bundle.
-//
-// This asserts the CURRENT behaviour. When population-map learns to say "this paper has no
-// registry", this assertion flips and must be updated; writing the gap down is how it stops being
-// mistaken for coverage.
-{
-  const bare = paper(
-    "cli-no-registry",
-    "We measured 1,921 repositories and a census of 134 repositories.",
-    undefined,
-  );
-  const r = run([SCRIPT, bare, "--flags-only"]);
-  assert.equal(
-    r.out.trim(),
-    "",
-    "population-map now says something about a paper with no registry — good; update this assertion",
-  );
-}
-
-rmSync(tmp, { recursive: true, force: true });
-console.log(
-  "✓ population-map: self-test owned (7 cases), CLI wiring fires on a stale row and stays quiet, 1 known gap recorded",
-);

package/skills/paper-pipeline/scripts/population-map.mjs

@@ -1,188 +0,0 @@
-#!/usr/bin/env node
-/**
- * population-map.mjs — does the population registry keep its link to the body of the paper?
- *
- * (Before 2026-08-26 this file answered the question "can the reader tell WHICH SET each number
- *  counts" in full; half of the answer now lives in ESLint rules — see below.)
- *
- *   node population-map.mjs <paper-dir>              report
- *   node population-map.mjs <paper-dir> --flags-only for hooks and pre-commit
- *
- * 🔴 WHY THIS EXISTS. `papers/CLAUDE.md` has carried this as writing rule #3 since 2026-08-05:
- *
- *     "A number arrives together with what it counts, and out of what. […] If two numbers come
- *      from different experiments — say so IN THE SAME SENTENCE."
- *
- * It was written after a cold reader gave up tracking the abstract's populations halfway through.
- * It is prose. Nothing enforced it. On 2026-08-06 the author read the finished paper and said he
- * could not follow his own §4 — and the cause was not the count of measurements, it was that §4
- * moves between TWO SAMPLES THAT BARELY OVERLAP (a targeted census of 134 repositories and a broad
- * corpus of 1,921; seven repositories are in both) and never says so. §4.1's rate and §4.3's rate
- * read as if one replicated the other. They cannot: they are different populations.
- *
- * That is this repository's own thesis turned on its own manuscript — a rule written in a rules
- * file, with no mechanism behind it, that therefore did nothing for a year of edits. So the rule
- * gets a leg.
- *
- * 🔴 TWO OF THE FOUR FINDINGS MOVED INTO ESLint RULES ON 2026-08-26. What is left here is only
- * what speaks about THE REGISTRY ITSELF, not about the paper:
- *
- *   stale    a registry row for a quantity the body NO LONGER PRINTS. The registry shrinks together
- *            with the paper and does not rot.
- *   badref   a row points at a `related_to` that is not a row anywhere.
- *
- * Both are inseparable from the file `repro/populations.tsv` and HAVE NO ADDRESS IN THE PAPER:
- * `stale` by definition speaks about a number that is not in the paper, and `badref` about two
- * fields of one TSV row. An ESLint rule can only report into the file being linted, so moving them
- * would mean pointing a finger at the paper while talking about a different file.
- *
- * MOVED INTO `eslint-rules/paper-registry.mjs` (the rules `paper/population-untied` and
- * `paper/population-undeclared`):
- *   untied      — a population is not named IN THE SAME SENTENCE as the one it is derived from;
- *   undeclared  — a number is printed in the shape of a population, and no registry row declares it.
- * Both speak about a place IN THE PAPER, and for them the registry is configuration, exactly like a
- * venue profile for `pdf/profile`. Parity was proved before the deletion (the real paper + 17
- * fixtures), the write-up is in `the author's private research notes`.
- *
- * Advisory.
- */
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { headings as mdHeadings, requireMarkdown } from "#lib/markdown";
-import { isMain } from "./consumer.mjs";
-
-// Markup is parsed with a parser (`CLAUDE.md`, 2026-08-11). We fail rather than degrade: without
-// the body boundaries `bodyOf()` would return an empty string, and out of an empty string this
-// check concludes "not a single registry number is printed", that is, ALL rows stale — a confident
-// list of findings about a paper nobody read.
-requireMarkdown();
-
-/** The body is everything before the bibliography; appendices sit after it in this paper and are
- *  not under the page limit, so a relation stated only there does not reach the reader who stops
- *  at the References. That asymmetry is the whole point of checking the body separately. */
-export function bodyOf(md) {
-  const stripped = md.replace(/<!--[\s\S]*?-->/g, "");
-  // 2026-08-11: both body boundaries come from the parser. `/^##\s+References\s*$/m` opened and
-  // closed the body on hashes at the start of a line — including hashes inside a ```-block, and this
-  // paper quotes whole chunks of other people's papers. The `-1` convention and the `< 0`
-  // comparisons are left as they were.
-  const at = (re) => {
-    const h = mdHeadings(stripped).find(
-      (x) => x.depth === 2 && re.test(x.text),
-    );
-    return h ? h.offset : -1;
-  };
-  const cut = at(/^References$/u);
-  const start = at(/^Abstract$/u);
-  return stripped.slice(start < 0 ? 0 : start, cut < 0 ? stripped.length : cut);
-}
-
-const asLiteral = (n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-/** A printed quantity, not a substring of a longer one: 189 must not match inside 1,189 or 1893.
- *  The trailing guard must still allow ORDINARY PUNCTUATION after the number — "of the 1,921, we
- *  could enumerate 189" and a sentence-final "...over all 1,921." are both the number being
- *  printed. Forbidding any following `.` or `,` silently loses exactly the positions a summary
- *  figure lands in; only a DIGIT after the separator makes it part of a longer quantity. */
-const printed = (n) => new RegExp(`(?<![\\d,.])${asLiteral(n)}(?!\\d|[,.]\\d)`);
-
-export function parseRegistry(tsv) {
-  const rows = [];
-  for (const line of tsv.split("\n")) {
-    if (!line.trim() || line.startsWith("#")) continue;
-    const [id, print, relation, relatedTo, gloss] = line
-      .split("\t")
-      .map((c) => c.trim()); // split yields strings; a missing column is `undefined` in the destructuring
-    if (!id || id === "id") continue;
-    rows.push({ id, print, relation, relatedTo, gloss });
-  }
-  return rows;
-}
-
-export function findings(md, tsv) {
-  const body = bodyOf(md);
-  const reg = parseRegistry(tsv);
-  const byId = new Map(reg.map((r) => [r.id, r]));
-  const out = [];
-
-  for (const row of reg) {
-    // A row with no printed quantity has nothing to look for in the body. It used to reach
-    // `printed(undefined)` and crash the checker; it is a defect of the TSV, reported as one.
-    if (!row.print) {
-      out.push({ kind: "incomplete", row });
-      continue;
-    }
-    const appears = printed(row.print).test(body);
-    if (!appears) {
-      // A registry row for a quantity the body no longer prints. Same discipline as the
-      // grandfathered numbers list: the registry shrinks when the paper does, and never rots.
-      if (row.relation !== "retired") out.push({ kind: "stale", row });
-      continue;
-    }
-    if (row.relation === "root" || row.relation === "external") continue;
-    // The order is preserved from the original: `untied` was computed AFTER this check and moved
-    // into `paper/population-untied`; the dangling reference stayed here because it is about a TSV
-    // row.
-    if (!byId.get(row.relatedTo)) out.push({ kind: "badref", row });
-  }
-  return out;
-}
-
-/* Importable above this line; the CLI only runs when this file is the entry point, so the tests
- * can exercise findings() without the argv handling firing. */
-if (!isMain(import.meta.url)) {
-  // imported — nothing to do
-} else main();
-
-function main() {
-  const args = process.argv.slice(2);
-  const dir = args.find((a) => !a.startsWith("--"));
-  const flagsOnly = args.includes("--flags-only");
-  if (!dir) {
-    console.error("usage: node population-map.mjs <paper-dir> [--flags-only]");
-    process.exit(0);
-  }
-
-  const paperPath = ["paper.md", "draft.md"]
-    .map((f) => join(dir, f))
-    .find(existsSync);
-  const regPath = join(dir, "repro", "populations.tsv");
-  // Same silent-skip class as artifact-coverage.mjs — see the note there (measured 2026-08-25).
-  if (!paperPath || !existsSync(regPath)) {
-    const why = !paperPath
-      ? "no paper.md/draft.md — this checker reads markdown only, a .tex paper is NOT covered"
-      : `no registry at ${regPath}`;
-    console.error(`⏭️  population map SKIPPED for ${dir} — ${why}.`);
-    process.exit(0);
-  }
-
-  const found = findings(
-    readFileSync(paperPath, "utf8"),
-    readFileSync(regPath, "utf8"),
-  );
-
-  if (!found.length) {
-    if (!flagsOnly)
-      console.log(
-        "population map: the registry matches the body — no stale rows, no dangling related_to.",
-      );
-    process.exit(0);
-  }
-
-  console.log(`population map — ${found.length} finding(s) in ${paperPath}`);
-  for (const f of found) {
-    if (f.kind === "stale") {
-      console.log(
-        `  ·  ${f.row.print} (${f.row.id}) is declared and the body no longer prints it — drop the row or mark it retired`,
-      );
-    } else if (f.kind === "badref") {
-      console.log(
-        `  🔴 ${f.row.id} says it relates to "${f.row.relatedTo}", which is not a row in populations.tsv`,
-      );
-    } else {
-      console.log(
-        `  🔴 ${f.row.id} has no printed quantity — the row cannot be checked against the body`,
-      );
-    }
-  }
-  process.exit(0);
-}

package/skills/paper-pipeline/scripts/population-map.test.mjs

@@ -1,154 +0,0 @@
-/**
- * population-map.mjs — the registry's own findings (`stale`, `badref`), planted in both directions,
- * and the command around them. Until #52 the seven cases below were `population-map.selftest.mjs`,
- * a script the harness spawned and whose "N passed" line it parsed; they are vitest cases now.
- *
- * 🔴 ONE CASE WAS DELETED BEFORE THE MOVE, NOT MOVED, and that is worth remembering: it ran a
- * HAND-COPIED COPY of the checker's regex over a string. A change to the real `printed()` cannot
- * touch such a test by construction. The property is pinned by behaviour instead (case 6).
- */
-import assert from "node:assert/strict";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { test } from "vitest";
-import { runNode, useTempDir, writeTree } from "../../../test/support.ts";
-import { bodyOf, findings } from "./population-map.mjs";
-
-const SCRIPT = join(
-  dirname(fileURLToPath(import.meta.url)),
-  "population-map.mjs",
-);
-const doc = (bodyLines) =>
-  `## Abstract\n\n${bodyLines}\n\n## References\n\n[1] x.\n`;
-const kinds = (md, reg) =>
-  findings(md, reg).map((f) => `${f.kind}:${f.row.print}`);
-const REG = [
-  "id\tprinted\trelation\trelated_to\tgloss",
-  "broad\t1,921\troot\t\tthe corpus",
-  "sub\t1,836\tsubset\tbroad\tthose it could read",
-].join("\n");
-const HEAD = "id\tprinted\trelation\trelated_to\tgloss\n";
-
-// 1. The direction that matters more: a checker firing on a paper that already obeys gets muted.
-test("a registry that matches the body is silent", () => {
-  assert.deepEqual(
-    kinds(
-      doc(
-        "The resolver ran over all 1,921 repositories, and read 1,836 of them.",
-      ),
-      REG,
-    ),
-    [],
-  );
-});
-
-// 2. A row for a quantity the paper no longer prints is a claim nobody can check.
-test("a stale registry row fires", () => {
-  assert.deepEqual(
-    kinds(doc("The resolver ran over all 1,921 repositories."), REG),
-    ["stale:1,836"],
-  );
-});
-
-// 3. `retired` is what keeps a set declared after it was cut from the paper.
-test("a retired row does not fire", () => {
-  assert.deepEqual(
-    kinds(
-      doc("The resolver ran over all 1,921 repositories, and read 1,836."),
-      `${REG}\ngold\t7,310\tretired\t\ta public gold set`,
-    ),
-    [],
-  );
-});
-
-// 4. A relation pointing at an id that is not a row — a defect of the TSV alone.
-test("a dangling related_to fires", () => {
-  assert.deepEqual(
-    kinds(
-      doc("We read 1,836 repositories."),
-      `${HEAD}sub\t1,836\tsubset\tnosuch\tx`,
-    ),
-    ["badref:1,836"],
-  );
-});
-
-// 5. A row whose number is absent is `stale`, never also `badref`.
-test("a row that is absent is stale, not badref", () => {
-  assert.deepEqual(
-    kinds(doc("Nothing numeric here."), `${HEAD}sub\t1,836\tsubset\tnosuch\tx`),
-    ["stale:1,836"],
-  );
-});
-
-// 6. `printed()` boundaries through behaviour: 189 is not printed inside 1,189.
-test('189 is not "printed" inside 1,189', () => {
-  assert.deepEqual(
-    kinds(
-      doc("A follow-up read covered 1,189 records, of all 1,921."),
-      `${HEAD}broad\t1,921\troot\t\tthe corpus\nspread\t189\tsubset\tbroad\tenumerable`,
-    ),
-    ["stale:189"],
-  );
-});
-
-// 7. The body stops at the bibliography; with no Abstract it starts at the top, with no
-//    References it runs to the end.
-test("bodyOf: from Abstract to References, or the whole text when either is missing", () => {
-  assert.deepEqual(
-    [
-      bodyOf(doc("nothing here")).includes("[1] x."),
-      bodyOf("pre\n\n## References\n\n[1] x.\n"),
-      bodyOf("## Abstract\n\nall of it\n"),
-    ],
-    [false, "pre\n\n", "## Abstract\n\nall of it\n"],
-  );
-});
-
-test("a registry row with no printed quantity is reported, not a crash", () => {
-  assert.deepEqual(
-    findings(doc("x"), `${HEAD}short\n`).map((f) => [f.kind, f.row.id]),
-    [["incomplete", "short"]],
-  );
-});
-
-// ── the command ─────────────────────────────────────────────────────────────────────────
-const root = useTempDir("population-map-");
-const paper = (name, body, tsv) =>
-  writeTree(join(root, name), {
-    "paper.md": doc(body),
-    ...(tsv === undefined ? {} : { "repro/populations.tsv": tsv }),
-  });
-
-test("the command: usage, a paper without markdown, a clean registry, and every finding kind", () => {
-  assert.deepEqual(runNode(SCRIPT, []), {
-    status: 0,
-    stdout: "",
-    stderr: "usage: node population-map.mjs <paper-dir> [--flags-only]\n",
-  });
-  const tex = writeTree(join(root, "tex"), { "paper.tex": "x" });
-  assert.match(
-    runNode(SCRIPT, [tex]).stderr,
-    /population map SKIPPED for .* — no paper\.md\/draft\.md — this checker reads markdown only/,
-  );
-  const clean = paper(
-    "clean",
-    "All 1,921 of them.",
-    `${HEAD}broad\t1,921\troot\t\tx`,
-  );
-  assert.equal(
-    runNode(SCRIPT, [clean]).stdout,
-    "population map: the registry matches the body — no stale rows, no dangling related_to.\n",
-  );
-  assert.equal(runNode(SCRIPT, [clean, "--flags-only"]).stdout, "");
-  const bad = paper(
-    "bad",
-    "We read 1,836.",
-    `${HEAD}sub\t1,836\tsubset\tnosuch\tx\nold\t7,310\tsubset\tsub\tx\nshort\n`,
-  );
-  assert.deepEqual(runNode(SCRIPT, [bad]).stdout.split("\n").slice(1), [
-    '  🔴 sub says it relates to "nosuch", which is not a row in populations.tsv',
-    "  ·  7,310 (old) is declared and the body no longer prints it — drop the row or mark it retired",
-    "  🔴 short has no printed quantity — the row cannot be checked against the body",
-    "",
-  ]);
-});