paperlint 2.1.0 → 3.1.0

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

@@ -13,6 +13,7 @@ import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import {
   resolveEngine,
+  missingDependencies,
   probeTree,
   supportedPlatform,
   whichOnPath,
@@ -103,7 +104,11 @@ export function gatherFacts(o: Resolved): EngineFacts {
     (tree): TreeProbe => ({
       label: `TeX Live ${tree.year} — paperlint cache (${tree.dir})`,
       bin: tree.bin,
-      missing: probeTree(tree.bin, o.tex.packages, o.run),
+      // Only a cache tree is asked for its dependencies: its tlmgr writes where we own.
+      missing: [
+        ...probeTree(tree.bin, o.tex.packages, o.run),
+        ...missingDependencies(tree.bin, o.run),
+      ],
     }),
   );
   const cache = usableTree(probes, (p) => p.missing.length === 0);

package/src/build.harness.mjs

@@ -74,6 +74,10 @@ function fakeTex({
   log = "",
   missing = false,
   noPdf = false,
+  // `noLog`: pdflatex that dies before it opens paper.log (a format it cannot load); what it
+  // printed is `stdout`.
+  noLog = false,
+  stdout = "",
 } = {}) {
   const calls = [];
   const run = (bin, args, opts) => {
@@ -85,11 +89,11 @@ function fakeTex({
       };
     if (bin === "pdflatex") {
       writeFileSync(join(opts.cwd, "paper.aux"), aux);
-      writeFileSync(join(opts.cwd, "paper.log"), log);
+      if (!noLog) writeFileSync(join(opts.cwd, "paper.log"), log);
       // `noPdf`: what real pdflatex does on a document with no pages — "No pages of output.", exit 0.
       if (exitCode === 0 && !noPdf)
         writeFileSync(join(opts.cwd, "paper.pdf"), "%PDF-fake");
-      return { status: exitCode, stdout: "", stderr: "" };
+      return { status: exitCode, stdout, stderr: "" };
     }
     if (bin === "bibtex") {
       writeFileSync(join(opts.cwd, "paper.bbl"), "\\begin{thebibliography}{1}");
@@ -273,10 +277,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",
@@ -391,6 +399,46 @@ try {
   check("…and says the PDF was removed", /paper\.pdf removed/.test(shown));
   check("a failed pass is not retried", ftex.calls.length === 1);
 
+  // ── pdflatex dies before writing a log ────────────────────────────────────────────────
+  // Seen 2026-09-26: a TeX Live whose pdflatex format was never built. pdflatex exits 1 having
+  // printed the reason, and paper.log is either absent or left over from an earlier build.
+  const nolog = paper("nolog", {
+    "paper.tex": CLEAN_TEX,
+    "paper.log": "./paper.tex:9: OLD ERROR FROM YESTERDAY\nl.9 \\old\n",
+  });
+  const dieTex = fakeTex({
+    exitCode: 1,
+    noLog: true,
+    stdout:
+      "This is pdfTeX, Version 3.141592653-2.6-1.40.28 (TeX Live 2026) (INITEX)\n" +
+      "I can't find the format file `pdflatex.fmt'!\n",
+  });
+  const rn = await buildPaper(nolog, {
+    cwd: root,
+    readPdf: fakeRead,
+    run: dieTex.run,
+    env: ENV,
+    log: quiet,
+  });
+  const shownN = formatResult(rn);
+  // Guards: the reason pdflatex printed reaches the human when there is no log to quote.
+  check(
+    "🔴 no log: the failure shows what pdflatex printed",
+    rn.status === "failed" && shownN.includes("I can't find the format file"),
+    shownN,
+  );
+  // Guards: a log from an earlier build is never quoted as this build's error.
+  check(
+    "🔴 no log: a stale paper.log from an earlier build is not quoted",
+    !shownN.includes("OLD ERROR FROM YESTERDAY"),
+    shownN,
+  );
+  check(
+    "no log: it does not point at a log file that this run did not write",
+    !shownN.includes("full log:") && shownN.includes("wrote no paper.log"),
+    shownN,
+  );
+
   // ── pdflatex not installed ────────────────────────────────────────────────────────────
   const rm = await buildPaper(clean, {
     cwd: root,

package/src/build.ts

@@ -45,7 +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 { PAPER_SETTINGS_FILE } from "../lib/paper-config.mjs";
+import { CONFIG_FILE } from "../lib/paper-config.mjs";
 import {
   declaredVenue,
   factsPath,
@@ -64,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,
@@ -87,7 +89,7 @@ export const PAPER_MARKERS = [
   "PIPELINE-STATUS.md",
   "paper.tex",
   "paper.md",
-  PAPER_SETTINGS_FILE,
+  CONFIG_FILE,
 ];
 
 /** The source paperlint compiles, and the job name every output file carries. */
@@ -135,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 =
@@ -350,9 +354,8 @@ function latexPass(
   const r = ctx.run("pdflatex", pdflatexArgs(final), opts);
   if (r.error) return null;
   const exitCode = r.status ?? 1;
-  const log = unwrapLog(
-    readOr(join(ctx.paperDir, `${JOB}.log`), "latin1") ?? "",
-  );
+  const written = readOr(join(ctx.paperDir, `${JOB}.log`), "latin1");
+  const log = unwrapLog(written ?? "");
   return {
     step: "latex",
     final,
@@ -361,10 +364,30 @@ function latexPass(
     after: hashes(ctx.paperDir),
     markers: logMarkers(log),
     bib: bibInput(ctx.paperDir),
-    errorLines: exitCode === 0 ? [] : errorExcerpt(log).map(fromLatin1),
+    errorLines:
+      exitCode === 0
+        ? []
+        : written === null
+          ? printed(r)
+          : errorExcerpt(log).map(fromLatin1),
   };
 }
 
+/**
+ * The last lines pdflatex printed, for the run that wrote no log — it died before opening one (a
+ * format it cannot load, a missing TeX Live file). Marked by NO_LOG, which the report keys on.
+ */
+function printed(r: { stdout?: unknown; stderr?: unknown }): string[] {
+  const lines = fromLatin1(
+    `${String(r.stdout ?? "")}\n${String(r.stderr ?? "")}`,
+  )
+    .split("\n")
+    .filter((l) => l.trim());
+  return [NO_LOG, ...lines.slice(-8).map((l) => `  ${l}`)];
+}
+
+const NO_LOG = `pdflatex wrote no ${JOB}.log — the last lines it printed:`;
+
 /** One bibtex run, on the input the `.aux` names BEFORE it runs, or null when it could not start. */
 function bibtexPass(ctx: BuildContext, opts: SpawnOptions): Observation | null {
   const before = hashes(ctx.paperDir);
@@ -391,6 +414,9 @@ export function compile(ctx: BuildContext): {
 } {
   const history: Observation[] = [];
   const opts = spawnOptions(ctx);
+  // Every log this loop reads is one its own pdflatex wrote. A pdflatex that dies before opening
+  // paper.log would otherwise have an earlier build's error quoted as this one's.
+  rmSync(join(ctx.paperDir, `${JOB}.log`), { force: true });
   const runs = { latex: 0, bibtex: 0 };
   for (;;) {
     const step = nextStep(summarize(history));
@@ -446,7 +472,7 @@ export const compileStep: BuildStep = {
           ...(end.lines.length
             ? end.lines
             : ["(no error line found in the log)"]),
-          `full log: ${log}`,
+          ...(end.lines[0] === NO_LOG ? [] : [`full log: ${log}`]),
         ],
       };
     }
@@ -521,11 +547,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 ─────────────────────────────────────────────────────────────────────────
@@ -574,6 +625,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;
 }
 
 /**
@@ -594,13 +650,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(
@@ -614,7 +678,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. */
@@ -622,7 +691,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[] = [];
@@ -635,6 +712,7 @@ async function runSteps(
       readPdf,
       measure,
       files,
+      checkReferences,
     });
     if (!out.ok) {
       // The PDF THIS run wrote and the step then rejected (a partial pass).