paperlint 3.0.0 → 3.1.1

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

@@ -278,7 +278,8 @@ export function surnames(authorField) {
     .filter((s) => s && s !== "others");
 }
 
-const truncated = (authorField) => /\band\s+others\b/i.test(authorField || "");
+// Only called for an entry that has an author (checkAuthors filters on it first).
+const truncated = (authorField) => /\band\s+others\b/i.test(authorField);
 
 /** Is the entry claiming a PUBLISHED venue (as opposed to a preprint)? */
 export function claimsPublished(e) {

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

@@ -0,0 +1,160 @@
+/**
+ * verify-cites.mjs as a process — the way the verify-citations skill runs it, which is THROUGH A
+ * SYMLINK (`.claude/skills/verify-citations -> …/skills/verify-citations`, made by `paperlint
+ * init`). Only `--offline` runs here: the online resolvers are driven in-process with a fake
+ * `fetch` (verify-cites.net.test.mjs), because a test must not depend on four live APIs.
+ */
+import assert from "node:assert/strict";
+import { readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "vitest";
+import { runNode, useTempDir, writeTree } from "../../../test/support.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const root = useTempDir("verify-cites-cli-");
+// The skill's own address for the script: a link to the skill directory, as `paperlint init` makes.
+symlinkSync(join(HERE, ".."), join(root, "verify-citations"));
+const LINKED = join(root, "verify-citations", "scripts", "verify-cites.mjs");
+
+test("run through the skill's symlink, the CLI runs at all (--help prints the usage)", () => {
+  assert.deepEqual(runNode(LINKED, ["--help"]), {
+    status: 0,
+    stdout: "",
+    stderr: "usage: verify-cites.mjs <cites.json | refs.bib | -> [--offline]\n",
+  });
+});
+
+const SCRIPT = join(HERE, "verify-cites.mjs");
+const CACHE = join(root, "cache.json");
+const env = { VERIFY_CITES_CACHE: CACHE };
+writeTree(root, {
+  "cites.json": JSON.stringify([
+    { id: "a", doi: "10.1/x", title: "A Title Of Some Length" },
+    { title: "no id at all" },
+    { id: "h", title: "Hygiene", commit: "abc123" },
+  ]),
+  "one.json": JSON.stringify({ id: "solo", title: "Just One Citation" }),
+  "refs.bib": "@article{k, title={A Bib Title}, doi={10.2/y}, year={2020}}\n",
+  "bad.json": "{ not json",
+  // Loaded with --import before the script: every registry answers 404, so a DOI the authority
+  // does not know is FALSE — the one verdict that fails the run.
+  "fetch-404.mjs":
+    "globalThis.fetch = async () => new Response(null, { status: 404 });\n",
+  // Prints the User-Agent of every request, then answers 404.
+  "fetch-ua.mjs":
+    "globalThis.fetch = async (url, init) => {\n" +
+    "  process.stderr.write(`UA ${init.headers['User-Agent']}\\n`);\n" +
+    "  return new Response(null, { status: 404 });\n};\n",
+  "consumer/paperlint.json": JSON.stringify({ contactEmail: "me@example.org" }),
+});
+const offline = (args, opts = {}) =>
+  runNode(SCRIPT, [...args, "--offline"], { env, ...opts });
+const parsed = (r) => ({ ...r, stdout: JSON.parse(r.stdout) });
+const SUMMARY_PASS = (n, t, u, flagged) =>
+  `\nverify-cites: ${n} citation(s) — ${t} true, 0 false (fabrication), ${u} unresolvable` +
+  (flagged ? `, ${flagged} with hygiene flag(s)` : "") +
+  "\nPASS — no fabrication (unresolvable is advisory)\n";
+
+test("-h is --help", () => {
+  assert.equal(
+    runNode(SCRIPT, ["-h"]).stderr,
+    runNode(SCRIPT, ["--help"]).stderr,
+  );
+});
+
+test("an input that cannot be read: exit 2, named", () => {
+  const r = offline([join(root, "bad.json")]);
+  assert.deepEqual(
+    { status: r.status, stdout: r.stdout, stderr: r.stderr.split(" — ")[0] },
+    { status: 2, stdout: "", stderr: "error: could not read input" },
+  );
+});
+
+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(
+    {
+      status: r.status,
+      ids: r.stdout.map((x) => [x.id, x.verdict, x.flags?.length ?? 0]),
+      stderr: r.stderr,
+    },
+    {
+      status: 0,
+      ids: [
+        ["a", "unresolvable", 0],
+        [null, "unresolvable", 0],
+        ["h", "unresolvable", 1],
+      ],
+      stderr: SUMMARY_PASS(3, 0, 3, 1),
+    },
+  );
+});
+
+test("one JSON object on stdin, with `-` and with no path at all", () => {
+  const input = readFileSync(join(root, "one.json"), "utf8");
+  const dash = parsed(offline(["-"], { input }));
+  const bare = parsed(offline([], { input }));
+  assert.deepEqual(
+    [dash.stdout.map((x) => x.id), bare.stdout.map((x) => x.id), dash.status],
+    [["solo"], ["solo"], 0],
+  );
+});
+
+test("a .bib file is parsed into citations", () => {
+  const r = parsed(offline([join(root, "refs.bib")]));
+  assert.deepEqual(
+    r.stdout.map((x) => x.id),
+    ["k"],
+  );
+});
+
+test("online, a DOI the authority does not know is FALSE: FAIL, exit 1, and the cache is written", () => {
+  rmSync(CACHE, { force: true });
+  const r = runNode(SCRIPT, [join(root, "refs.bib")], {
+    env,
+    nodeArgs: ["--import", join(root, "fetch-404.mjs")],
+  });
+  assert.deepEqual(
+    {
+      status: r.status,
+      verdicts: JSON.parse(r.stdout).map((x) => x.verdict),
+      tail: r.stderr.trim().split("\n").pop(),
+      cached: Object.keys(JSON.parse(readFileSync(CACHE, "utf8"))).sort(),
+    },
+    {
+      status: 1,
+      verdicts: ["false"],
+      tail: "FAIL — fabrication(s) found (exit 1)",
+      // 404s are successful transports, so they are cached; the authority's 100 is not.
+      cached: [
+        "crossref:doi:10.2/y",
+        "openalex:doi:10.2/y",
+        "semantic_scholar:doi:10.2/y",
+      ],
+    },
+  );
+});
+
+test("a corrupt cache is ignored, and a cache that cannot be written does not fail the run", () => {
+  writeFileSync(CACHE, "{ corrupt");
+  const corrupt = offline([join(root, "one.json")]);
+  const unwritable = runNode(SCRIPT, [join(root, "one.json"), "--offline"], {
+    env: { VERIFY_CITES_CACHE: root }, // a directory: reading and writing both fail
+  });
+  assert.deepEqual([corrupt.status, unwritable.status], [0, 0]);
+});
+
+test("the consumer's declared contact reaches every request's User-Agent (Crossref's polite pool)", () => {
+  const r = runNode(SCRIPT, [join(root, "refs.bib")], {
+    env: { ...env, CLAUDE_PROJECT_DIR: join(root, "consumer") },
+    nodeArgs: ["--import", join(root, "fetch-ua.mjs")],
+  });
+  const agents = new Set(
+    r.stderr.split("\n").filter((l) => l.startsWith("UA ")),
+  );
+  assert.deepEqual(
+    [...agents],
+    ["UA verify-cites/1.0 (citation gate; mailto:me@example.org)"],
+  );
+});

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

@@ -49,10 +49,16 @@ import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, extname } from "node:path";
 import { createHash } from "node:crypto";
-import { consumerContactEmail } from "../../paper-pipeline/scripts/consumer.mjs";
+import {
+  consumerContactEmail,
+  isMain,
+} from "../../paper-pipeline/scripts/consumer.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const CACHE_PATH = join(__dirname, ".cite-cache.json");
+// Beside this script by default (the skill says so, and `.gitignore` covers it). VERIFY_CITES_CACHE
+// points it elsewhere — how a test keeps the run from writing into the package it is testing.
+const CACHE_PATH =
+  process.env.VERIFY_CITES_CACHE || join(__dirname, ".cite-cache.json");
 // 🔴 THE ADDRESS IS THE CONSUMER'S, NOT OURS. Crossref's "polite pool" keys off this `mailto:`:
 // it decides who gets the faster tier and, more to the point, WHOM THEY WARN before blocking.
 // Hard-coded, it pointed at one person for every user of this package — so the warnings would
@@ -122,11 +128,6 @@ export function titleSimilarity(a, b) {
   return 1 - levenshtein(na, nb) / maxLen;
 }
 
-/** Two titles "match" iff normalized similarity ≥ threshold (default 0.70). */
-export function titlesMatch(a, b, threshold = TITLE_THRESHOLD) {
-  return titleSimilarity(a, b) >= threshold;
-}
-
 /** Normalize a DOI: strip a `doi:` / resolver-URL prefix and any TRAILING sentence
  *  punctuation a .bib or prose extractor swallowed. A trailing `.` makes doi.org
  *  return responseCode 100, so an unnormalized real DOI reads as fabrication (the
@@ -201,7 +202,7 @@ function isAcronymOf(base, words) {
   for (let i = 0; i < words.length; i++) {
     let acr = "";
     for (let j = i; j < words.length && acr.length < base.length; j++) {
-      acr += words[j][0] || "";
+      acr += words[j].charAt(0); // "" for an empty token, like the first letter of nothing
     }
     if (acr === base) return true;
   }
@@ -251,8 +252,7 @@ export function titleRelation(a, b) {
   const sb = scriptsOf(nb);
   if (sa.size && sb.size && ![...sa].some((x) => sb.has(x)))
     return "incomparable";
-  const sim = 1 - levenshtein(na, nb) / Math.max(na.length, nb.length);
-  if (sim >= TITLE_THRESHOLD) return "match";
+  if (titleSimilarity(a, b) >= TITLE_THRESHOLD) return "match";
   const A = contentTokens(na);
   const B = contentTokens(nb);
   if (A.length && B.length) {
@@ -702,32 +702,33 @@ function cacheKey(kind, val) {
   return `${kind}:${val}`;
 }
 
+/** One request, classified: rate-limit/outage and other failures → `ok:false`, 404 → `notFound`. */
+async function request(url, json, signal) {
+  const res = await fetch(url, {
+    headers: {
+      "User-Agent": USER_AGENT,
+      Accept: json ? "application/json" : "*/*",
+    },
+    signal,
+  });
+  if (res.status === 429 || res.status >= 500) {
+    return { ok: false, reason: `http ${res.status}` }; // rate-limit / outage
+  }
+  if (res.status === 404) return { ok: true, notFound: true };
+  if (!res.ok) return { ok: false, reason: `http ${res.status}` };
+  const data = json ? await res.json() : await res.text();
+  return { ok: true, data };
+}
+
 async function httpGet(url, { json = true } = {}) {
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
-  try {
-    const res = await fetch(url, {
-      headers: {
-        "User-Agent": USER_AGENT,
-        Accept: json ? "application/json" : "*/*",
-      },
-      signal: ctrl.signal,
-    });
-    if (res.status === 429 || res.status >= 500) {
-      return { ok: false, reason: `http ${res.status}` }; // rate-limit / outage
-    }
-    if (res.status === 404) return { ok: true, notFound: true };
-    if (!res.ok) return { ok: false, reason: `http ${res.status}` };
-    const data = json ? await res.json() : await res.text();
-    return { ok: true, data };
-  } catch (e) {
-    return {
-      ok: false,
-      reason: e.name === "AbortError" ? "timeout" : String(e),
-    };
-  } finally {
-    clearTimeout(timer);
-  }
+  const result = await request(url, json, ctrl.signal).catch((e) => ({
+    ok: false,
+    reason: e.name === "AbortError" ? "timeout" : String(e),
+  }));
+  clearTimeout(timer);
+  return result;
 }
 
 // Each *Resolver returns a normalized response (the shape classifyResolver eats).
@@ -821,44 +822,44 @@ async function openalexResolve(citation) {
   return null;
 }
 
-async function semanticScholarResolve(citation) {
+const S2 = "https://api.semanticscholar.org/graph/v1/paper";
+
+// By its id when the citation has one, else by the title — the resolvers run only for a citation
+// with at least one of the three, so the title search is given a title.
+const semanticScholarResolve = (citation) =>
+  citation.doi || citation.arxiv
+    ? semanticScholarById(citation)
+    : semanticScholarByTitle(citation.title);
+
+async function semanticScholarById(citation) {
   const db = "semantic_scholar";
-  const base = "https://api.semanticscholar.org/graph/v1/paper";
-  if (citation.doi || citation.arxiv) {
-    const id = citation.doi ? `DOI:${citation.doi}` : `arXiv:${citation.arxiv}`;
-    const r = await httpGet(
-      `${base}/${encodeURIComponent(id)}?fields=title,year`,
-    );
-    if (!r.ok) return { db, transport: "error" };
-    if (r.notFound)
-      return {
-        db,
-        transport: "ok",
-        query: citation.doi ? "doi" : "arxiv",
-        record: null,
-      };
-    const w = r.data;
-    return {
-      db,
-      transport: "ok",
-      query: citation.doi ? "doi" : "arxiv",
-      record: w?.title != null ? { title: w.title || "", year: w.year } : null,
-    };
-  }
-  if (citation.title) {
-    const r = await httpGet(
-      `${base}/search?query=${encodeURIComponent(citation.title)}&fields=title,year&limit=5`,
-    );
-    if (!r.ok) return { db, transport: "error" };
-    const items = r.data?.data || [];
-    return {
-      db,
-      transport: "ok",
-      query: "title",
-      records: items.map((w) => ({ title: w.title || "", year: w.year })),
-    };
-  }
-  return null;
+  const query = citation.doi ? "doi" : "arxiv";
+  const id = citation.doi ? `DOI:${citation.doi}` : `arXiv:${citation.arxiv}`;
+  const r = await httpGet(`${S2}/${encodeURIComponent(id)}?fields=title,year`);
+  if (!r.ok) return { db, transport: "error" };
+  if (r.notFound) return { db, transport: "ok", query, record: null };
+  const w = r.data;
+  return {
+    db,
+    transport: "ok",
+    query,
+    record: w?.title != null ? { title: w.title || "", year: w.year } : null,
+  };
+}
+
+async function semanticScholarByTitle(title) {
+  const db = "semantic_scholar";
+  const r = await httpGet(
+    `${S2}/search?query=${encodeURIComponent(title)}&fields=title,year&limit=5`,
+  );
+  if (!r.ok) return { db, transport: "error" };
+  const items = r.data?.data || [];
+  return {
+    db,
+    transport: "ok",
+    query: "title",
+    records: items.map((w) => ({ title: w.title || "", year: w.year })),
+  };
 }
 
 async function arxivResolve(citation) {
@@ -917,10 +918,9 @@ export function parseArxivFeed(xml) {
  * means "no metadata here"; doi.org responseCode 100 means "this DOI does not
  * exist". Returns { transport, responseCode } for classifyDoiAuthority.
  */
-async function doiAuthorityCheck(citation) {
-  if (!citation.doi) return null;
+async function doiAuthorityCheck(doi) {
   // Keep the DOI's own slashes as path separators; encode the rest.
-  const path = encodeURIComponent(citation.doi.trim()).replace(/%2F/gi, "/");
+  const path = encodeURIComponent(doi.trim()).replace(/%2F/gi, "/");
   const r = await httpGet(`https://doi.org/api/handles/${path}`);
   if (r.notFound) return { transport: "ok", responseCode: 100 }; // 404 = not found
   if (!r.ok) return { transport: "error" };
@@ -931,15 +931,14 @@ async function doiAuthorityCheck(citation) {
   };
 }
 
-async function nvdCheck(citation) {
-  if (!citation.cve) return null;
-  if (!isValidCveId(citation.cve)) {
+async function nvdCheck(cve) {
+  if (!isValidCveId(cve)) {
     // Malformed CVE id — treat as a provided-id-that-cannot-resolve (fabrication).
     return { transport: "ok", found: false };
   }
   const r = await httpGet(
     `https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=${encodeURIComponent(
-      citation.cve.toUpperCase(),
+      cve.toUpperCase(),
     )}`,
   );
   if (!r.ok) return { transport: "error" };
@@ -951,21 +950,18 @@ async function nvdCheck(citation) {
 /**
  * Verify ONE citation live (with caching). Returns the reduceVerdict result.
  *
- * 🔴 CONTRACT: CALL SEQUENTIALLY. The shared `cache` is read BEFORE the `await` and written AFTER
- * it (three places below), so two concurrent calls sharing the same `cache` will both miss the
- * write and both fall through to the network. This doesn't corrupt the data — the resolvers are
- * deterministic, and the second call writes an equivalent value — but it's extra requests to
- * CrossRef / OpenAlex / Semantic Scholar / arXiv / NVD, i.e. a direct route to a 429, which is
- * exactly why the neighboring `bib-authors.mjs` has 900ms pauses.
+ * ⚠️ CONCURRENT CALLS SHARING ONE `cache` MAY ASK TWICE. The cache is read BEFORE the `await` and
+ * written AFTER it (three places below), so two concurrent calls for the SAME identifier both miss
+ * and both go to the network. The data does not suffer — the resolvers are deterministic and the
+ * second write is equivalent — the cost is an extra request per duplicate identifier.
  *
- * Today the contract IS HONORED: the only caller is `main()` in this same file (a sequential
- * `for … of` with `await`), so the interleaving `require-atomic-updates` warns about does not
- * exist. The rule is deliberately left at `warn` for that reason: it judges the SHAPE, not the
- * fact of it. But the function IS EXPORTED and takes a shared cache — exactly what gets
- * parallelized via `Promise.all` — so the warning is left visible rather than suppressed. The real
- * fix would be caching UNRESOLVED promises in the cache (in-flight deduplication) rather than
- * values; that's incompatible with the current JSON-based `saveCache()` and so hasn't been done
- * (measured 2026-08-28).
+ * Callers: `main()` here calls it one citation at a time; `paperlint build`'s references step
+ * (`src/adapters/references/index.ts`) calls it six at a time (#107 — serially, 27 references took
+ * 217 s). Six is the bound on requests in flight to any one service, since a citation's own
+ * requests go to the four resolvers one after another. `require-atomic-updates` stays at `warn`
+ * because the interleaving it describes now exists, and is accepted for the reason above. In-flight
+ * deduplication (caching the promise, not the value) would remove the duplicate request; it does
+ * not fit `saveCache()`'s JSON file and has not been done.
  */
 export async function verifyCitationLive(
   citation,
@@ -1015,13 +1011,13 @@ export async function verifyCitationLive(
       const ck = cacheKey("doi_authority", citation.doi);
       let auth = cache[ck];
       if (!auth) {
-        auth = await doiAuthorityCheck(citation);
+        auth = await doiAuthorityCheck(citation.doi);
         // Cache only POSITIVE existence; never cache authority-absent (100), so a
         // freshly-minted DOI checked pre-propagation isn't pinned to `false` on re-run.
         if (auth && auth.transport === "ok" && auth.responseCode !== 100)
           cache[ck] = auth;
       }
-      if (auth) evidence.push(classifyDoiAuthority(auth));
+      evidence.push(classifyDoiAuthority(auth));
     }
   }
 
@@ -1030,8 +1026,8 @@ export async function verifyCitationLive(
     const ck = cacheKey("nvd", citation.cve.toUpperCase());
     let nvd = cache[ck];
     if (!nvd) {
-      nvd = await nvdCheck(citation);
-      if (nvd && nvd.transport === "ok") cache[ck] = nvd;
+      nvd = await nvdCheck(citation.cve);
+      if (nvd.transport === "ok") cache[ck] = nvd;
     }
     const e = checkNvd(citation, nvd);
     if (e) evidence.push(e);
@@ -1103,6 +1099,10 @@ async function main() {
 }
 
 // Run as CLI only when invoked directly (not when imported by the test).
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+// 🔴 `isMain`, not `fileURLToPath(import.meta.url) === process.argv[1]`. The skill runs this file
+// through `.claude/skills/verify-citations`, a symlink; Node reports `import.meta.url` as the
+// realpath and `argv[1]` as the link, so the old comparison was false and the CLI exited 0 having
+// done nothing — a silent PASS for any bibliography. (consumer.mjs `isMain` documents the class.)
+if (isMain(import.meta.url)) {
   main();
 }