paperlint 2.1.0 → 3.0.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.harness.mjs

@@ -273,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

@@ -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 =
@@ -521,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 ─────────────────────────────────────────────────────────────────────────
@@ -574,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;
 }
 
 /**
@@ -594,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(
@@ -614,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. */
@@ -622,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[] = [];
@@ -635,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).