paperlint 2.0.1 → 3.0.0

package/skills/verify-citations/SKILL.md

@@ -4,7 +4,7 @@ description: Verify every citation is a real work with correct metadata, and tha
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Agent]
 ---
 
-<!-- vigiles:sha256:f35db5aec55b4691 compiled from skills/verify-citations/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:2bb9f6f1233094cf compiled from skills/verify-citations/SKILL.md.spec.ts -->
 
 # verify-citations — every cite real, the delta explicit
 
@@ -136,6 +136,15 @@ any `false` (fabrication)** — `unresolvable` alone is advisory and does NOT fa
 narrowed-false philosophy. API responses are cached to `scripts/.cite-cache.json` (gitignored) so re-runs are
 cheap and deterministic.
 
+## 5a. Both checks run on every `paperlint build`
+
+`npx paperlint build` runs `verify-cites` and `bib-authors` over the paper's bibliography after the PDF is
+built and records the verdicts, with the SHA-256 of the bibliography it checked, in
+`<paper>/_build/references.json`. `paperlint lint` reads that record offline: `paper/cite-exists` and
+`paper/author-list` report a failing entry on its own line, `paper/refs-fresh` says when the bibliography
+changed since, and `paper/refs-checked` warns when nothing was recorded or the build had no network. The
+step never fails the build. Run the scripts by hand (below) to read a single verdict in full.
+
 ## 5b. The author-list gate — `scripts/bib-authors.mjs`
 
 `verify-cites.mjs` answers *"does this citation exist, and does the id point at it?"*. There is a second

package/skills/verify-citations/SKILL.md.spec.ts

@@ -152,6 +152,15 @@ any \`false\` (fabrication)** — \`unresolvable\` alone is advisory and does NO
 narrowed-false philosophy. API responses are cached to \`scripts/.cite-cache.json\` (gitignored) so re-runs are
 cheap and deterministic.
 
+## 5a. Both checks run on every \`paperlint build\`
+
+\`npx paperlint build\` runs \`verify-cites\` and \`bib-authors\` over the paper's bibliography after the PDF is
+built and records the verdicts, with the SHA-256 of the bibliography it checked, in
+\`<paper>/_build/references.json\`. \`paperlint lint\` reads that record offline: \`paper/cite-exists\` and
+\`paper/author-list\` report a failing entry on its own line, \`paper/refs-fresh\` says when the bibliography
+changed since, and \`paper/refs-checked\` warns when nothing was recorded or the build had no network. The
+step never fails the build. Run the scripts by hand (below) to read a single verdict in full.
+
 ## 5b. The author-list gate — \`scripts/bib-authors.mjs\`
 
 \`verify-cites.mjs\` answers *"does this citation exist, and does the id point at it?"*. There is a second

package/skills/verify-citations/scripts/bib-authors.mjs

@@ -192,7 +192,7 @@ function bibTextFrom(target) {
  * Only three fields are needed (type, key, author, title, booktitle/journal), and a full
  * BibTeX grammar would be a second thing to maintain. Brace-depth counting is enough and
  * is exercised by the colocated test. */
-function parseBib(text) {
+export function parseBib(text) {
   const out = [];
   const re = /@(\w+)\s*\{\s*([^,\s]+)\s*,/g;
   let m;
@@ -289,7 +289,7 @@ export function claimsPublished(e) {
 
 /* ---------- DBLP ---------- */
 
-async function dblpHits(title) {
+export async function dblpHits(title) {
   const url = `${DBLP}/?q=${encodeURIComponent(title)}&format=json&h=6`;
   // Per-request timeout: a check that hangs is indistinguishable from a check that is dead,
   // and this one runs 25+ requests. Measured 2026-08-24: a single unbounded query stalled the
@@ -335,23 +335,31 @@ export function compare(ourSurnames, theirSurnames) {
   return { missing, extra, orderDiffers };
 }
 
-function die(msg) {
-  console.error(`bib-authors: ${msg}`);
-  process.exit(2);
-}
-
-async function main() {
-  const args = process.argv.slice(2).filter((a) => a !== "--json");
-  const asJson = process.argv.includes("--json");
-  if (!args[0])
-    die("usage: bib-authors.mjs <paper-dir|file.bib|file.tex> [--json]");
-
-  const { text, file, markdown } = bibTextFrom(args[0]);
-  const parsed = markdown ? parseMarkdownRefs(text) : parseBib(text);
-  const entries = parsed.filter((e) => e.title && e.author);
+/**
+ * The comparison over parsed entries, the network behind `lookup` (DBLP by default). Returns the
+ * buckets main() prints and `paperlint build` records: `findings` (the author list differs from
+ * the published version's), `matched` (compared, equal), `skipped` (not applicable), `unchecked`
+ * (the lookup FAILED — never a pass). An entry in none of them was a preprint entry, which may
+ * carry preprint metadata.
+ *
+ * @param lookup  title → DBLP-shaped hits; throws on a failed request (`retryable` for a 429)
+ * @param pause   ms → a promise; DBLP asks for gentle clients. A test passes `() => {}`.
+ */
+export async function checkAuthors(
+  parsed,
+  {
+    lookup = dblpHits,
+    pause = (ms) =>
+      new Promise((r) => {
+        setTimeout(r, ms);
+      }),
+  } = {},
+) {
   const findings = [];
   const skipped = []; // legitimately not applicable
   const unchecked = []; // we FAILED to check — must never be reported as a pass
+  const matched = []; // compared against the published record, and equal
+  const entries = parsed.filter((e) => e.title && e.author);
 
   for (const e of parsed.filter((x) => x.unparsed)) {
     skipped.push({
@@ -377,7 +385,7 @@ async function main() {
     let hits = null;
     for (let attempt = 0; attempt < 3 && hits === null; attempt++) {
       try {
-        hits = await dblpHits(e.title.replace(/[{}]/g, ""));
+        hits = await lookup(e.title.replace(/[{}]/g, ""));
       } catch (err) {
         const last = attempt === 2;
         if (last)
@@ -385,10 +393,7 @@ async function main() {
             key: e.key,
             why: `DBLP lookup failed: ${err.message}`,
           });
-        else
-          await new Promise((r) => {
-            setTimeout(r, 1500 * (attempt + 1));
-          });
+        else await pause(1500 * (attempt + 1));
       }
     }
     if (hits === null) continue;
@@ -408,7 +413,9 @@ async function main() {
     const ours = surnames(e.author);
     const theirs = surnames(rec.authors.join(" and "));
     const d = compare(ours, theirs);
-    if (d.missing.length || d.extra.length || d.orderDiffers) {
+    if (!(d.missing.length || d.extra.length || d.orderDiffers))
+      matched.push(e.key);
+    else {
       findings.push({
         key: e.key,
         venue: `${rec.venue} ${rec.year}`.trim(),
@@ -417,12 +424,27 @@ async function main() {
         ...d,
       });
     }
-    // A braced body rather than a concise arrow — see `no-promise-executor-return` (2026-08-28).
-    await new Promise((r) => {
-      setTimeout(r, 900);
-    }); // DBLP asks for gentle clients; 350 ms drew 429s
+    await pause(900); // DBLP asks for gentle clients; 350 ms drew 429s
   }
 
+  return { findings, skipped, unchecked, matched };
+}
+
+function die(msg) {
+  console.error(`bib-authors: ${msg}`);
+  process.exit(2);
+}
+
+async function main() {
+  const args = process.argv.slice(2).filter((a) => a !== "--json");
+  const asJson = process.argv.includes("--json");
+  if (!args[0])
+    die("usage: bib-authors.mjs <paper-dir|file.bib|file.tex> [--json]");
+
+  const { text, file, markdown } = bibTextFrom(args[0]);
+  const parsed = markdown ? parseMarkdownRefs(text) : parseBib(text);
+  const entries = parsed.filter((e) => e.title && e.author);
+  const { findings, skipped, unchecked } = await checkAuthors(parsed);
   if (asJson) {
     console.log(
       JSON.stringify(

package/src/adapters/references/index.ts

@@ -0,0 +1,102 @@
+/**
+ * The online reference checks, as the `CheckReferences` port: `verify-cites` (the cited work
+ * exists, the title matches — Crossref, OpenAlex, Semantic Scholar, arXiv) and `bib-authors` (the
+ * authors are the published version's — DBLP). Both ship in this package's verify-citations skill;
+ * this adapter only runs them and shapes their answers.
+ *
+ * "Not checked" is decided up front, by one request: when Crossref cannot be reached at all, the
+ * checkers would degrade every entry to `unresolvable` / `unchecked`, which reads like a result.
+ * Saying `not-checked` with the reason is the honest record.
+ */
+import type {
+  CheckReferences,
+  EntryVerdict,
+} from "../../ports/check-references.ts";
+import { unreachable } from "./reach.io.ts";
+// @ts-expect-error — a skill script in .mjs, it has no types
+import * as cites from "../../../skills/verify-citations/scripts/verify-cites.mjs";
+// @ts-expect-error — a skill script in .mjs, it has no types
+import * as authors from "../../../skills/verify-citations/scripts/bib-authors.mjs";
+
+interface CiteResult {
+  readonly id: string;
+  readonly verdict: "true" | "false" | "unresolvable";
+  readonly reason?: string;
+}
+interface AuthorFinding {
+  readonly key: string;
+  readonly venue: string;
+  readonly missing: readonly string[];
+  readonly extra: readonly string[];
+  readonly orderDiffers: boolean;
+}
+interface KeyWhy {
+  readonly key: string;
+  readonly why: string;
+}
+
+const describeAuthors = (f: AuthorFinding): string =>
+  [
+    f.missing.length ? `missing ${f.missing.join(", ")}` : "",
+    f.extra.length ? `extra ${f.extra.join(", ")}` : "",
+    f.orderDiffers ? "order differs" : "",
+  ]
+    .filter(Boolean)
+    .join("; ") + ` (DBLP: ${f.venue})`;
+
+interface AuthorBuckets {
+  readonly findings: readonly AuthorFinding[];
+  readonly skipped: readonly KeyWhy[];
+  readonly unchecked: readonly KeyWhy[];
+  readonly matched: readonly string[];
+}
+
+const authorsOf = (key: string, a: AuthorBuckets): EntryVerdict["authors"] =>
+  a.findings.some((f) => f.key === key)
+    ? "mismatch"
+    : a.unchecked.some((u) => u.key === key)
+      ? "unchecked"
+      : a.matched.includes(key)
+        ? "match"
+        : "skipped";
+
+/** One entry's verdict from the two checkers' answers. */
+function entryVerdict(
+  key: string,
+  found: readonly CiteResult[],
+  a: AuthorBuckets,
+): EntryVerdict {
+  const c = found.find((x) => x.id === key);
+  const mismatch = a.findings.find((f) => f.key === key);
+  const why = [
+    c && c.verdict !== "true" ? c.reason : undefined,
+    mismatch ? describeAuthors(mismatch) : undefined,
+    a.unchecked.find((u) => u.key === key)?.why,
+  ]
+    .filter(Boolean)
+    .join("; ");
+  return {
+    key,
+    exists: c?.verdict ?? "unresolvable",
+    authors: authorsOf(key, a),
+    ...(why ? { why } : {}),
+  };
+}
+
+export const onlineReferences: CheckReferences = async (bib) => {
+  const why = await unreachable();
+  if (why !== null) return { kind: "not-checked", why };
+  const cache = {};
+  const found: CiteResult[] = [];
+  for (const c of cites.parseBib(bib) as { id?: string }[])
+    if (c.id) found.push(await cites.verifyCitationLive(c, { cache }));
+  const a = (await authors.checkAuthors(
+    authors.parseBib(bib),
+  )) as AuthorBuckets;
+  const keys = new Set([
+    ...found.map((c) => c.id),
+    ...a.findings.map((f) => f.key),
+  ]);
+  const entries = [...keys].map((key) => entryVerdict(key, found, a));
+  return { kind: "checked", entries };
+};

package/src/adapters/references/reach.io.ts

@@ -0,0 +1,12 @@
+/** Whether the citation services answer at all — the one request that decides "not checked". */
+export async function unreachable(): Promise<string | null> {
+  try {
+    await fetch("https://api.crossref.org/", {
+      method: "HEAD",
+      signal: AbortSignal.timeout(10_000),
+    });
+    return null;
+  } catch (e) {
+    return `the citation services cannot be reached (${(e as Error).message})`;
+  }
+}

package/src/build-engine.ts

@@ -29,7 +29,11 @@ import {
   usableTree,
   type InstallResult,
 } from "./toolchain.ts";
-import { declaredUnion, type TexRequirements } from "./tex-requirements.ts";
+import {
+  declaredUnion,
+  mergeRequirements,
+  type TexRequirements,
+} from "./tex-requirements.ts";
 
 export interface EngineOptions {
   /** What the targeted papers need: the base set plus each paper's venue. */
@@ -81,7 +85,11 @@ function withDefaults(o: EngineOptions): Resolved {
   };
   return {
     ...r,
-    install: o.install ?? (() => ensureTexLive(declaredUnion().tex, r)),
+    // The shipped union AND what the targeted papers need: a project's own preset lives outside
+    // the package, and its packages are only in `r.tex`.
+    install:
+      o.install ??
+      (() => ensureTexLive(mergeRequirements(declaredUnion().tex, r.tex), r)),
   };
 }
 

package/src/build.harness.mjs

@@ -137,6 +137,24 @@ const fakeRead = async (pdf) => {
 const CLEAN_TEX = "\\documentclass{article}\\begin{document}x\\end{document}";
 
 try {
+  // ── inputs: paperlint's own venues directory, no configuration ───────────────────────────────
+  // First: the facts below resolve a paper's venue preset in this same directory, so a wrong one
+  // must be named HERE, not as a missing venue label two checks later.
+  const venues = packageVenuesDir();
+  check(
+    "the venues directory is paperlint's own and holds paper-guards.tex",
+    existsSync(join(venues, "paper-guards.tex")),
+  );
+  check(
+    "🔴 with no TEXINPUTS set, the value ENDS in the separator — otherwise the system tree stops resolving",
+    withTexInputs({}, [venues]).TEXINPUTS === `${venues}${delimiter}`,
+  );
+  check(
+    "an existing TEXINPUTS is kept, after ours",
+    withTexInputs({ TEXINPUTS: `/mine${delimiter}` }, [venues]).TEXINPUTS ===
+      `${venues}${delimiter}/mine${delimiter}`,
+  );
+
   // ── facts: parsed from the paper, not configured ──────────────────────────────────────
   check(
     "documentclass and options come from the parser",
@@ -157,33 +175,20 @@ try {
   );
   const venued = paper("venued", {
     "paper.tex": CLEAN_TEX,
-    "venue.json": JSON.stringify({ venue: "agenticdev", kind: "short" }),
+    "paperlint.json": JSON.stringify({
+      extends: "paperlint:agenticdev",
+      kind: "short",
+    }),
     "build.sh": "exit 0\n",
   });
   const facts = readFacts(venued);
-  check("the venue comes from venue.json", facts.venue === "agenticdev");
+  check("the venue comes from paperlint.json", facts.venue === "agenticdev");
   check(
     "a leftover build.sh is a FACT (reported), not a step",
     JSON.stringify(facts.ignoredScripts) === JSON.stringify(["build.sh"]) &&
       IGNORED_SCRIPTS.includes("repro/build-submission.sh"),
   );
 
-  // ── inputs: paperlint's own venues directory, no configuration ───────────────────────────────
-  const venues = packageVenuesDir();
-  check(
-    "the venues directory is paperlint's own and holds paper-guards.tex",
-    existsSync(join(venues, "paper-guards.tex")),
-  );
-  check(
-    "🔴 with no TEXINPUTS set, the value ENDS in the separator — otherwise the system tree stops resolving",
-    withTexInputs({}, [venues]).TEXINPUTS === `${venues}${delimiter}`,
-  );
-  check(
-    "an existing TEXINPUTS is kept, after ours",
-    withTexInputs({ TEXINPUTS: `/mine${delimiter}` }, [venues]).TEXINPUTS ===
-      `${venues}${delimiter}/mine${delimiter}`,
-  );
-
   // ── the plan ──────────────────────────────────────────────────────────────────────────
   const plan = planFor(facts);
   check(
@@ -268,10 +273,14 @@ try {
   // ── the measure step: facts for the lint rules ────────────────────────────────────────
   const factsFile = join(clean, "_build", "paper.facts.json");
   check(
-    "measure: the plan's last step writes the facts, and says it judges nothing",
-    r.plan.at(-1)?.step === "measure" &&
-      /pdf\.js → _build\/paper\.facts\.json/.test(r.plan.at(-1)?.why ?? "") &&
-      /nothing is judged/.test(r.plan.at(-1)?.why ?? ""),
+    "measure: the plan's measure step writes the facts, and says it judges nothing",
+    r.plan.find((p) => p.step === "measure") !== undefined &&
+      /pdf\.js → _build\/paper\.facts\.json/.test(
+        r.plan.find((p) => p.step === "measure")?.why ?? "",
+      ) &&
+      /nothing is judged/.test(
+        r.plan.find((p) => p.step === "measure")?.why ?? "",
+      ),
   );
   check(
     "🔴 measure: a green build wrote _build/paper.facts.json through the readPdf port, on paper.pdf",

package/src/build.ts

@@ -12,7 +12,7 @@
  *
  * ── THE SHAPE: an ordered list of STEPS, composed, not configured ────────────
  * Each step says whether it applies to THIS paper and why — decided from FACTS parsed out of the
- * paper (its `\documentclass` and options, the venue named in `venue.json`), never from a config
+ * paper (its `\documentclass` and options, the venue named in `paperlint.json`), never from a config
  * flag. `paperlint build` prints that plan before running anything, and `--dry-run` prints only the
  * plan. Adding a step is one entry in `STEPS`.
  *
@@ -45,6 +45,7 @@ import { delimiter, join, relative } from "node:path";
 // eslint-disable-next-line boundaries/dependencies -- legacy layer, moves behind a port in #76
 import { getParser } from "@unified-latex/unified-latex-util-parse";
 import { packageVenuesDir } from "../skills/paper-pipeline/scripts/consumer.mjs";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 import {
   declaredVenue,
   factsPath,
@@ -63,6 +64,8 @@ import { whyNoGeometry } from "./domain/geometry.ts";
 import type { AbsolutePath } from "./domain/paths.ts";
 import type { Files } from "./ports/files.ts";
 import type { MeasureGeometry } from "./ports/measure-geometry.ts";
+import type { CheckReferences } from "./ports/check-references.ts";
+import { recordReferences, REFERENCES_FILE } from "./references.ts";
 import {
   auxBib,
   bibtexExcerpt,
@@ -86,7 +89,7 @@ export const PAPER_MARKERS = [
   "PIPELINE-STATUS.md",
   "paper.tex",
   "paper.md",
-  "venue.json",
+  CONFIG_FILE,
 ];
 
 /** The source paperlint compiles, and the job name every output file carries. */
@@ -114,7 +117,7 @@ export interface PaperFacts {
     readonly name: string;
     readonly options: readonly string[];
   } | null;
-  /** The `venue` field of `venue.json`, or null. */
+  /** The label of the venue preset `paperlint.json` extends, or null. */
   readonly venue: string | null;
   /** Paper-supplied build scripts found on disk — reported as ignored. */
   readonly ignoredScripts: readonly string[];
@@ -134,6 +137,8 @@ export interface BuildContext {
   readonly measure: MeasureGeometry;
   /** Where the facts file is written. */
   readonly files: Files;
+  /** The online reference checks; the CLI wires the real ones, a test passes a function. */
+  readonly checkReferences: CheckReferences;
 }
 
 export type StepOutcome =
@@ -222,7 +227,7 @@ export function readFacts(paperDir: string): PaperFacts {
   return {
     main,
     documentclass: documentclassOf(ast),
-    venue: venue?.venue ?? null,
+    venue: venue?.label ?? null,
     ignoredScripts: IGNORED_SCRIPTS.filter((s) =>
       existsSync(join(paperDir, s)),
     ),
@@ -520,11 +525,36 @@ export const measureStep: BuildStep = {
   },
 };
 
+// ── step: references ────────────────────────────────────────────────────────────────────
+
+/**
+ * Check the bibliography online — the cited work exists and its title matches (verify-cites), its
+ * authors are the published version's (bib-authors) — and record the verdicts in
+ * `_build/references.json` for the offline lint rules (`reference-rules.ts`). OPTIONAL and NEVER
+ * FAILING: without network the PDF is still built, and the record says `not-checked`.
+ */
+export const referencesStep: BuildStep = {
+  name: "references",
+  required: false,
+  applies: (facts) =>
+    facts.main
+      ? {
+          yes: true,
+          why: `online: citations exist, titles and authors match → ${FACTS_DIR}/${REFERENCES_FILE} (never fails the build)`,
+        }
+      : { yes: false, why: "nothing is compiled" },
+  run: async (ctx) => ({
+    ok: true,
+    note: await recordReferences(ctx.files, ctx.paperDir, ctx.checkReferences),
+  }),
+};
+
 /** The build, in order. A new step is one entry here. */
 export const STEPS: readonly BuildStep[] = [
   inputsStep,
   compileStep,
   measureStep,
+  referencesStep,
 ];
 
 // ── the command ─────────────────────────────────────────────────────────────────────────
@@ -573,6 +603,11 @@ export interface BuildOptions {
   measure?: MeasureGeometry;
   /** Where the facts file is written. Default: the disk. */
   files?: Files;
+  /**
+   * The online reference checks. Default: none — the record then says `not-checked`, and lint
+   * warns. The CLI passes the real ones (`adapters/references`).
+   */
+  checkReferences?: CheckReferences;
 }
 
 /**
@@ -593,13 +628,21 @@ function baseDefaults({
   dryRun = false,
   readPdf = pdfjsReader,
   projectRoot = env["CLAUDE_PROJECT_DIR"] || cwd,
-}: BuildOptions): Required<Omit<BuildOptions, "measure" | "files">> {
+}: BuildOptions): Required<
+  Omit<BuildOptions, "measure" | "files" | "checkReferences">
+> {
   return { run, cwd, env, steps, log, dryRun, readPdf, projectRoot };
 }
 
+/** Without a checker the record says so — never a pass. The CLI wires the real one. */
+const notWired: CheckReferences = async () => ({
+  kind: "not-checked",
+  why: "no reference checker was wired into this build",
+});
+
 /** banal as the measurer, wired from the build's environment: the one piece of root work left here (#76). */
 function defaultMeasurer(
-  b: Required<Omit<BuildOptions, "measure" | "files">>,
+  b: Required<Omit<BuildOptions, "measure" | "files" | "checkReferences">>,
 ): MeasureGeometry {
   const dirs = hostDirs({ cwd: b.cwd });
   return banalMeasurer(
@@ -613,7 +656,12 @@ function defaultMeasurer(
 function withDefaults(o: BuildOptions): Required<BuildOptions> {
   const base = baseDefaults(o);
   const measure = o.measure ?? defaultMeasurer(base);
-  return { ...base, measure, files: o.files ?? nodeFiles };
+  return {
+    ...base,
+    measure,
+    files: o.files ?? nodeFiles,
+    checkReferences: o.checkReferences ?? notWired,
+  };
 }
 
 /** Run the applicable steps in order, each on the environment the steps before it left. */
@@ -621,7 +669,15 @@ async function runSteps(
   paperDir: string,
   dir: string,
   plan: PlanLine[],
-  { run, env, steps, readPdf, measure, files }: Required<BuildOptions>,
+  {
+    run,
+    env,
+    steps,
+    readPdf,
+    measure,
+    files,
+    checkReferences,
+  }: Required<BuildOptions>,
 ): Promise<BuildResult> {
   let stepEnv = env;
   const notes: string[] = [];
@@ -634,6 +690,7 @@ async function runSteps(
       readPdf,
       measure,
       files,
+      checkReferences,
     });
     if (!out.ok) {
       // The PDF THIS run wrote and the step then rejected (a partial pass).