paperlint 8.0.0 → 9.0.1

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

@@ -43,122 +43,60 @@
  * Usage:  node bib-authors.mjs <paper-dir-or-.bib-or-.tex> [--json]
  * Exit:   0 = no author-set/order differences   1 = differences found   2 = usage/IO error
  */
-import { readFileSync, existsSync, readdirSync } from "node:fs";
-import { join, extname } from "node:path";
+import { resolve } from "node:path";
+import { latexReader } from "#src/adapters/latex/index";
+import { nodeFiles } from "#src/adapters/node/index";
+import { sourcesCodec } from "#src/adapters/sources-record/index";
+import { absolutePath } from "#src/domain/paths";
+import { bibReader } from "#src/adapters/bibtex/index";
+import { bibliographyAt, bibliographyUnreadWhy } from "#src/paper-sources";
 import { isMain } from "../../paper-pipeline/scripts/consumer.mjs";
 
 const DBLP = "https://dblp.org/search/publ/api";
 
-/* ---------- input: a .bib, a .tex with filecontents, or a paper dir ---------- */
+/* ---------- input: the bibliography TeX reads, or a .bib named ---------- */
 
-function bibTextFrom(target) {
-  let file = target;
-  if (!existsSync(file)) die(`no such path: ${file}`);
-  if (!extname(file)) {
-    const names = readdirSync(file);
-    // 🔴 THE CANONICAL NAME FIRST, then the only candidate, and never "whichever
-    // turns up first" (review #189). It used to be `names.find(f => f.endsWith(".tex"))`,
-    // that is, the first in directory order. Measured: one of the papers in the corpus
-    // has FIVE drafts lying around (paper-CONSTRUCTIVE-…, paper-FOLDED-…, paper-SAFE-…),
-    // while PIPELINE-STATUS.md names `paper.tex` as the submitted source. The author
-    // check went off into a stale draft and printed a verdict about the WRONG
-    // bibliography — a gate that checks the wrong file is worse than a missing one,
-    // because it says "checked".
-    const pick = (ext) => {
-      const canon = names.find((f) => f === `paper${ext}`);
-      if (canon) return canon;
-      const all = names.filter((f) => f.endsWith(ext)).sort();
-      if (all.length === 1) return all[0];
-      if (all.length > 1) {
-        // We do not fail: a new check here would set up one more surface, and its
-        // home is decided by the ladder in the `CLAUDE.md` next to the papers, not by
-        // this script (the `frozen-checks` ratchet is what guards that). It is enough
-        // to SAY it out loud and to choose DETERMINISTICALLY — the header below prints
-        // which file was checked anyway, so the reader sees the choice.
-        console.error(
-          `⚠️ ${file} holds several ${ext} files and no canonical paper${ext}: ` +
-            `${all.join(", ")} — took ${all[0]}. If that is the wrong one, name the file explicitly.`,
-        );
-        return all[0];
-      }
-      return undefined;
-    };
-    const found = pick(".bib") || pick(".tex");
-    if (!found) die(`no .bib or .tex in ${file}`);
-    file = join(file, found);
-  }
-  const text = readFileSync(file, "utf-8");
-  if (file.endsWith(".bib")) return { text, file };
-  // Only a .bib and a .tex are read: any other file would fall through to the refs.bib beside it,
-  // and the report would name a file nobody asked about.
-  if (!file.endsWith(".tex"))
-    die(`${file} is not a .bib or a .tex — give the paper's .bib or paper.tex`);
-  // A .tex may carry the bibliography inline via filecontents — that is how our papers do it.
-  const m = text.match(
-    /\\begin\{filecontents\*?\}(?:\[[^\]]*\])?\{[^}]*\.bib\}\r?\n([\s\S]*?)\\end\{filecontents\*?\}/,
-  );
-  if (m) return { text: m[1], file };
-  const sibling = join(file, "..", "refs.bib");
-  if (existsSync(sibling))
-    return { text: readFileSync(sibling, "utf-8"), file: sibling };
-  die(
-    `no bibliography found in ${file} (no filecontents block, no refs.bib beside it)`,
-  );
-}
+const DEPS = {
+  files: nodeFiles,
+  codec: sourcesCodec,
+  latex: latexReader,
+  bib: bibReader,
+};
 
-/* ---------- a deliberately small bib reader ----------
- * 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. */
-export function parseBib(text) {
-  const out = [];
-  const re = /@(\w+)\s*\{\s*([^,\s]+)\s*,/g;
-  let m;
-  while ((m = re.exec(text))) {
-    const [, type, key] = m;
-    let i = re.lastIndex,
-      depth = 1;
-    while (i < text.length && depth > 0) {
-      if (text[i] === "{") depth++;
-      else if (text[i] === "}") depth--;
-      i++;
-    }
-    const body = text.slice(re.lastIndex, i - 1);
-    out.push({ type: type.toLowerCase(), key, ...fields(body) });
-  }
-  return out;
+/**
+ * The texts to read: a `.bib` as named; for a paper directory or a `.tex`, the databases the last
+ * build's bibtex opened (`_build/sources.json`) — `bibliographyAt` (src/paper-sources.ts) answers, and
+ * refuses in its words, "run `npx paperlint build` first" among them.
+ */
+function bibliographyFrom(target) {
+  const r = bibliographyAt(absolutePath(resolve(target)), DEPS);
+  if (!r.ok) die(bibliographyUnreadWhy(r.error));
+  const { texts } = r.value;
+  return { files: [...new Set(texts.map((x) => x.path))], texts };
 }
 
-function fields(body) {
-  const get = (name) => {
-    const r = new RegExp(`(?:^|[,\\s])${name}\\s*=\\s*`, "i");
-    const at = body.search(r);
-    if (at === -1) return "";
-    let i = body.indexOf("=", at) + 1;
-    while (/\s/.test(body[i])) i++;
-    if (body[i] === "{") {
-      let depth = 1,
-        j = i + 1;
-      while (j < body.length && depth > 0) {
-        if (body[j] === "{") depth++;
-        else if (body[j] === "}") depth--;
-        j++;
-      }
-      return body.slice(i + 1, j - 1);
-    }
-    if (body[i] === '"') {
-      const j = body.indexOf('"', i + 1);
-      return body.slice(i + 1, j);
-    }
-    const j = body.indexOf(",", i);
-    return body.slice(i, j === -1 ? undefined : j);
-  };
-  return {
-    author: get("author"),
-    title: get("title"),
-    booktitle: get("booktitle"),
-    journal: get("journal"),
-  };
+/* ---------- entries: as the bibtex reader read them ---------- */
+
+/** A name of a name list as BibTeX writes it, family part first: `von Last, First`, or the literal. */
+const writtenName = (n) =>
+  n.name ??
+  [[n.prefix, n.lastName].filter(Boolean).join(" "), n.firstName]
+    .filter(Boolean)
+    .join(", ");
+
+/**
+ * The entries this check reads, from the bibtex reader's (src/ports/bib-reader.ts): type, key, the
+ * author list written out (`and others` kept), title, booktitle and journal; "" for a field it lacks.
+ */
+export function authorEntries(entries) {
+  return entries.map((e) => ({
+    type: e.type,
+    key: e.key,
+    author: (e.names.author ?? []).map(writtenName).join(" and "),
+    title: e.fields.title ?? "",
+    booktitle: e.fields.booktitle ?? "",
+    journal: e.fields.journal ?? "",
+  }));
 }
 
 /* ---------- normalisation: surnames only, in order ---------- */
@@ -353,14 +291,22 @@ async function main() {
   if (!args[0])
     die("usage: bib-authors.mjs <paper-dir|file.bib|file.tex> [--json]");
 
-  const { text, file } = bibTextFrom(args[0]);
-  const parsed = parseBib(text);
+  const { files, texts } = bibliographyFrom(args[0]);
+  const file = files.join(", ");
+  const parsed = texts.flatMap((t) => authorEntries(t.entries));
   const entries = parsed.filter((e) => e.title && e.author);
   const { findings, skipped, unchecked } = await checkAuthors(parsed);
   if (asJson) {
     console.log(
       JSON.stringify(
-        { file, entries: entries.length, findings, skipped, unchecked },
+        {
+          file: files[0],
+          files,
+          entries: entries.length,
+          findings,
+          skipped,
+          unchecked,
+        },
         null,
         2,
       ),

package/skills/verify-citations/scripts/verify-cites.cli.test.ts

@@ -10,6 +10,8 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { test } from "vitest";
 import { z } from "zod";
+import { absolutePath } from "#src/domain/paths";
+import { bibliographyUnreadWhy } from "#src/paper-sources";
 import {
   runNode,
   useTempDir,
@@ -92,6 +94,20 @@ test("an input that cannot be read: exit 2, named", () => {
   );
 });
 
+test("a .bib that is not there: exit 2, in bibliographyAt's words", () => {
+  // The path → bibliography vocabulary is tested once, beside bibliographyAt (src/paper-sources.ts).
+  const gone = join(root, "gone.bib");
+  const r = offline([gone]);
+  assert.deepEqual(
+    { status: r.status, stdout: r.stdout, stderr: r.stderr },
+    {
+      status: 2,
+      stdout: "",
+      stderr: `error: could not read input — ${bibliographyUnreadWhy({ kind: "missing", path: absolutePath(gone) })}\n`,
+    },
+  );
+});
+
 test("offline over a JSON list: a citation with no id is unresolvable by name, a short SHA is flagged", () => {
   const r = parsed(offline([join(root, "cites.json")]));
   assert.deepEqual(

package/skills/verify-citations/scripts/verify-cites.d.mts

@@ -5,14 +5,30 @@
 // Only what `src/` imports is declared. The `.mjs` is not typechecked, so a declaration nobody
 // compiles against would drift without anyone noticing.
 
-/** One entry as `parseBib` returns it: the BibTeX key as `id`, plus the fields it recognised. */
+/** One citation as `citationsOf` returns it: the BibTeX key as `id`, plus the fields it recognised. */
 export interface Citation {
   readonly id: string;
   readonly [field: string]: unknown;
 }
 
-/** Every entry of a BibTeX text, `@comment`/`@string`/`@preamble` skipped. */
-export declare function parseBib(text: string): Citation[];
+/** A name of a name list, in its parts (`BibName`). */
+export interface ReadName {
+  readonly lastName?: string;
+  readonly firstName?: string;
+  readonly prefix?: string;
+  readonly suffix?: string;
+  readonly name?: string;
+}
+
+/** An entry as the bibtex reader reads it (`BibEntry`, src/domain/paper-sources.ts), as far as citations use it. */
+export interface ReadEntry {
+  readonly key: string;
+  readonly fields: Readonly<Record<string, string>>;
+  readonly names: Readonly<Record<string, readonly ReadName[]>>;
+}
+
+/** The citations of a bibliography's entries, as the bibtex reader read them. */
+export declare function citationsOf(entries: readonly ReadEntry[]): Citation[];
 
 /** The title reduced to what identifies it: case, braces and punctuation removed. */
 export declare function titleIdentity(title: string): string;

package/skills/verify-citations/scripts/verify-cites.mjs

@@ -47,7 +47,13 @@
 
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, extname } from "node:path";
+import { dirname, join, extname, resolve } from "node:path";
+import { bibReader } from "#src/adapters/bibtex/index";
+import { latexReader } from "#src/adapters/latex/index";
+import { nodeFiles } from "#src/adapters/node/index";
+import { sourcesCodec } from "#src/adapters/sources-record/index";
+import { absolutePath } from "#src/domain/paths";
+import { bibliographyAt, bibliographyUnreadWhy } from "#src/paper-sources";
 import { createHash } from "node:crypto";
 import {
   consumerContactEmail,
@@ -588,116 +594,32 @@ export function reduceVerdict(citation, evidence, commitFlags = []) {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// .bib PARSER — small, best-effort. Extracts @article/@inproceedings/... entries
-// and (loosely) \bibitem blocks. Not a full BibTeX grammar; enough to seed cites.
+// CITATIONS — from the entries the bibtex reader read (src/ports/bib-reader.ts).
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** A name of a name list, written out: `First von Last, Jr.`, or the literal it was. */
+const writtenName = (n) =>
+  n.name ??
+  [n.firstName, n.prefix, n.lastName, n.suffix].filter(Boolean).join(" ");
+
 /**
- * field(body, name) — extract a BibTeX field value from an entry body.
- *  (a) anchors `name` so `title` does NOT also match `booktitle` (S4a);
- *  (b) reads BRACE-delimited values with balanced-brace scanning, so a protected
- *      acronym `{Evaluating {LLM}-based ...}` is captured whole, not truncated at
- *      the inner `}` (S4b);
- *  also handles "quoted" and bare (numeric) values.
+ * The citations of a bibliography's entries, as the bibtex reader read them: the key as `id`, and
+ * the doi, title, year, authors and arXiv eprint each entry has.
  */
-function bibField(body, name) {
-  const re = new RegExp(`(?<![a-zA-Z])${name}\\s*=\\s*`, "i");
-  const fm = re.exec(body);
-  if (!fm) return undefined;
-  let i = fm.index + fm[0].length;
-  const ch = body[i];
-  if (ch === "{") {
-    let depth = 0;
-    let j = i;
-    for (; j < body.length; j++) {
-      if (body[j] === "{") depth++;
-      else if (body[j] === "}") {
-        depth--;
-        if (depth === 0) break;
-      }
-    }
-    return body
-      .slice(i + 1, j)
-      .replace(/\s+/g, " ")
-      .trim();
-  }
-  if (ch === '"') {
-    let j = i + 1;
-    while (j < body.length && body[j] !== '"') j++;
-    return body
-      .slice(i + 1, j)
-      .replace(/\s+/g, " ")
-      .trim();
-  }
-  // bare value (e.g. year = 2017,) — up to the next comma / newline / close brace
-  let j = i;
-  while (j < body.length && !/[,\n}]/.test(body[j])) j++;
-  const v = body.slice(i, j).replace(/\s+/g, " ").trim();
-  return v || undefined;
-}
-
-export function parseBib(text) {
-  const cites = [];
-  // @type{key,  — then read the entry body with BALANCED-BRACE scanning so that
-  // one-line entries and indented / same-line closing braces (`\n  }` or `...}`)
-  // are captured, not dropped by a `\n}`-at-column-0 requirement (S4c).
-  const headRe = /@(\w+)\s*\{\s*([^,\s}]+)\s*,/g;
-  let m;
-  while ((m = headRe.exec(text)) !== null) {
-    const type = m[1].toLowerCase();
-    if (type === "comment" || type === "string" || type === "preamble")
-      continue;
-    const key = m[2].trim();
-    // Balanced scan from just after the key's comma to the entry's closing brace.
-    let depth = 1; // the entry's opening `{` was already consumed by headRe
-    let j = headRe.lastIndex;
-    for (; j < text.length && depth > 0; j++) {
-      if (text[j] === "{") depth++;
-      else if (text[j] === "}") depth--;
-    }
-    const body = text.slice(headRe.lastIndex, j - 1);
-    headRe.lastIndex = j; // resume scanning AFTER this entry
-
-    const c = { id: key };
-    const doi = bibField(body, "doi");
-    const title = bibField(body, "title");
-    const year = bibField(body, "year");
-    const author = bibField(body, "author");
-    const eprint = bibField(body, "eprint");
-    const archive =
-      bibField(body, "archiveprefix") || bibField(body, "eprinttype");
-    if (doi) c.doi = normalizeDoi(doi);
-    if (title) c.title = title.replace(/[{}]/g, "");
-    if (year) c.year = year;
-    if (author) c.authors = author;
-    if (eprint && (!archive || /arxiv/i.test(archive)))
-      c.arxiv = normalizeArxiv(eprint);
-    cites.push(c);
-  }
-  if (cites.length > 0) return cites;
-
-  // Fallback: \bibitem — grab arXiv ids / DOIs out of each block, best-effort.
-  const itemRe =
-    /\\bibitem(?:\[[^\]]*\])?\{([^}]+)\}([\s\S]*?)(?=\\bibitem|\\end\{thebibliography\}|$)/g;
-  while ((m = itemRe.exec(text)) !== null) {
-    const key = m[1].trim();
-    const block = m[2];
-    const c = { id: key };
-    const doiM = block.match(/10\.\d{4,9}\/[-._;()/:A-Z0-9]+/i);
-    const arxivM = block.match(/arXiv:\s*(\d{4}\.\d{4,5})/i);
-    const yearM = block.match(/\b(19|20)\d{2}\b/);
-    if (doiM) c.doi = normalizeDoi(doiM[0]);
-    if (arxivM) c.arxiv = normalizeArxiv(arxivM[1]);
-    if (yearM) c.year = yearM[0];
-    // crude title: longest quoted or {\em ...} run
-    const titleM =
-      block.match(/``([^']{6,}?)''/) ||
-      block.match(/\\emph\{([^}]{6,}?)\}/) ||
-      block.match(/\{\\em\s+([^}]{6,}?)\}/);
-    if (titleM) c.title = titleM[1].replace(/\s+/g, " ").trim();
-    cites.push(c);
-  }
-  return cites;
+export function citationsOf(entries) {
+  return entries.map((e) => {
+    const f = e.fields;
+    const c = { id: e.key };
+    if (f.doi) c.doi = normalizeDoi(f.doi);
+    if (f.title) c.title = f.title.replace(/\s+/g, " ").trim();
+    if (f.year) c.year = f.year;
+    const authors = (e.names.author ?? []).map(writtenName).join(" and ");
+    if (authors) c.authors = authors;
+    const archive = f.archiveprefix || f.eprinttype;
+    if (f.eprint && (!archive || /arxiv/i.test(archive)))
+      c.arxiv = normalizeArxiv(f.eprint);
+    return c;
+  });
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1212,11 +1134,23 @@ export async function verifyCitationLive(
 // CLI
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** What `bibliographyAt` needs to read a `.bib` (src/paper-sources.ts, the one answer for a path). */
+const DEPS = {
+  files: nodeFiles,
+  codec: sourcesCodec,
+  latex: latexReader,
+  bib: bibReader,
+};
+
 function loadInput(argv) {
   const path = argv.find((a) => !a.startsWith("-"));
+  if (path && extname(path).toLowerCase() === ".bib") {
+    const r = bibliographyAt(absolutePath(resolve(path)), DEPS);
+    if (!r.ok) throw new Error(bibliographyUnreadWhy(r.error));
+    return citationsOf(r.value.texts.flatMap((t) => t.entries));
+  }
   const raw =
     path && path !== "-" ? readFileSync(path, "utf8") : readFileSync(0, "utf8"); // stdin
-  if (path && extname(path).toLowerCase() === ".bib") return parseBib(raw);
   const parsed = JSON.parse(raw);
   return Array.isArray(parsed) ? parsed : [parsed];
 }

package/skills/verify-citations/scripts/verify-cites.test.mjs

@@ -24,7 +24,7 @@ import {
   checkNvd,
   checkCommit,
   reduceVerdict,
-  parseBib,
+  citationsOf,
   parseArxivFeed,
   normalizeDoi,
   normalizeArxiv,
@@ -33,6 +33,12 @@ import {
   titleIdentity,
   isValidCveId,
 } from "./verify-cites.mjs";
+import { bibReader } from "#src/adapters/bibtex/index";
+import { absolutePath } from "#src/domain/paths";
+
+/** The citations of a BibTeX text, read by the one bibtex reader. */
+const citationsIn = (bib) =>
+  citationsOf(bibReader.readFile(absolutePath("/p/refs.bib"), bib).entries);
 
 /** One vitest case per check, named by it. */
 function ok(cond, name) {
@@ -377,7 +383,7 @@ console.log("\n(extra) .bib parser best-effort extraction:");
   eprint={1512.03385}
 }
 `;
-  const cites = parseBib(bib);
+  const cites = citationsIn(bib);
   eq(cites.length, 2, "parsed 2 entries");
   eq(cites[0].doi, "10.5555/3295222.3295349", "entry 1 doi");
   eq(cites[1].arxiv, "1512.03385", "entry 2 arxiv eprint");
@@ -724,7 +730,7 @@ console.log("\n[S4] .bib parser edge cases:");
   title = {The Real Paper Title},
   year = {2021}
 }`;
-  const a = parseBib(bibA)[0];
+  const a = citationsIn(bibA)[0];
   eq(a.title, "The Real Paper Title", "title anchored — not booktitle");
 
   // (b) brace-protected acronym must not truncate at the inner brace.
@@ -733,14 +739,14 @@ console.log("\n[S4] .bib parser edge cases:");
   year = {2026}
 }`;
   eq(
-    parseBib(bibB)[0].title,
+    citationsIn(bibB)[0].title,
     "Evaluating LLM-based Systems for Code Review",
     "brace-protected acronym kept whole",
   );
 
   // (c1) one-line entry (no \n} at column 0).
   const bibC1 = `@article{k3, title = {A One Line Entry}, year = {2020}, doi = {10.1/abc}}`;
-  const c1 = parseBib(bibC1)[0];
+  const c1 = citationsIn(bibC1)[0];
   eq(c1.title, "A One Line Entry", "one-line entry title parsed");
   eq(c1.doi, "10.1/abc", "one-line entry doi parsed");
 
@@ -750,14 +756,14 @@ console.log("\n[S4] .bib parser edge cases:");
     year = {2019}
   }`;
   eq(
-    parseBib(bibC2)[0].title,
+    citationsIn(bibC2)[0].title,
     "Indented Closing Brace",
     "indented-closing-brace entry parsed",
   );
 
   // all four parse together, in sequence (balanced-brace scan resumes correctly).
   eq(
-    parseBib(bibA + "\n" + bibB + "\n" + bibC1 + "\n" + bibC2).length,
+    citationsIn(bibA + "\n" + bibB + "\n" + bibC1 + "\n" + bibC2).length,
     4,
     "all 4 entries parsed in sequence",
   );
@@ -796,15 +802,6 @@ console.log("\n[S4] .bib parser edge cases:");
   });
   eq(n.doi, "10.1/y", "normalizeIdentifiers cleans doi");
   eq(n.arxiv, "1234.5678", "normalizeIdentifiers cleans arxiv");
-  // the exact live-reproduced break: a \bibitem DOI with a swallowed sentence period.
-  const bib = `\\begin{thebibliography}{9}
-\\bibitem{ccs23} A. Author. Title. In Proc. CCS. doi:10.1145/3576915.3623218. 2023.
-\\end{thebibliography}`;
-  eq(
-    parseBib(bib)[0].doi,
-    "10.1145/3576915.3623218",
-    "bibitem DOI trailing period not swallowed",
-  );
 }
 
 // ── Edges of the pure layer: the defensive arms, each with the input that reaches it ──────────
@@ -916,32 +913,22 @@ test("reduceVerdict: an arXiv id missed only by a non-authoritative source is un
   });
 });
 
-test("parseBib: @comment/@string/@preamble are skipped, a bare value is read, an empty one is absent", () => {
+test("citationsOf: @comment/@string/@preamble are no citations; a quoted and a bare value are read; authors written out", () => {
   const bib = [
     "@comment{c, not an entry}",
-    "@string{s, x = {y}}",
-    '@article{k1, title = "Quoted Title", year = 2017, eprint = {1706.03762}, archiveprefix = {arXiv}}',
-    "@misc{k2, title = {T}, year = ,}",
-  ].join("\n");
-  assert.deepEqual(parseBib(bib), [
-    { id: "k1", title: "Quoted Title", year: "2017", arxiv: "1706.03762" },
-    { id: "k2", title: "T" },
-  ]);
-});
-
-test("parseBib's \\bibitem fallback reads an arXiv id and an \\emph title", () => {
-  const text = [
-    "\\begin{thebibliography}{9}",
-    "\\bibitem{a} A. Author. \\emph{A Long Enough Title}. arXiv:1706.03762, 2017.",
-    "\\end{thebibliography}",
+    "@string{s = {y}}",
+    '@article{k1, title = "Quoted Title", year = 2017, eprint = {1706.03762}, archiveprefix = {arXiv}, author = {Vaswani, Ashish and von Neumann, John}}',
+    "@misc{k2, title = {T}, eprint = {x}, archiveprefix = {HAL}}",
   ].join("\n");
-  assert.deepEqual(parseBib(text), [
+  assert.deepEqual(citationsIn(bib), [
     {
-      id: "a",
-      arxiv: "1706.03762",
+      id: "k1",
+      title: "Quoted Title",
       year: "2017",
-      title: "A Long Enough Title",
+      authors: "Ashish Vaswani and John von Neumann",
+      arxiv: "1706.03762",
     },
+    { id: "k2", title: "T" },
   ]);
 });
 

package/src/CLAUDE.md

@@ -1,9 +1,15 @@
-# CLAUDE.md — `src/`
+<!-- vigiles:sha256:f51051aae2ef09f8 compiled from src/CLAUDE.md.spec.ts -->
+
+# CLAUDE.md
+
+## `src/`
 
 The package's TypeScript: the CLI, the build, the toolchain installer, and the measuring that feeds
 the facts file. Loaded when working under `src/`; the repository-wide rules are in the root
 `CLAUDE.md`.
 
+## The two layer axes
+
 **`src/` is hexagonal on two axes, and the linter enforces both** (`eslint.config.mjs`; fixtures in
 `test/fixtures/layers/`, run by `test/eslint-layers.test.ts`; issue #76).
 
@@ -49,3 +55,19 @@ against `process.cwd()`, so lint started from any other directory classifies not
 `checkAllOrigins: true`: without it no `module:` policy is evaluated, so axis B and the library bans
 report nothing — dropping it turns the fixtures `src/domain/reads-disk.ts` and
 `src/adapters/one/disk.ts` clean (measured).
+
+## Readers and commands
+
+`@retorquere/bibtex-parser` is the one `.bib` reader, behind `src/ports/bib-reader.ts`.
+Rejected on 2026-09-27, so not proposed again: a separate `paperlint refs` command; the slowness it
+would have moved was a cache thrown away after every build (`docs/references.md`).
+
+## Rules
+
+### Layers
+
+**Enforced by:** `eslint/boundaries/dependencies`
+
+### Effect Globals
+
+**Enforced by:** `eslint/no-restricted-globals`