paperlint 3.1.1 → 3.1.3

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

@@ -6,7 +6,11 @@
  */
 import assert from "node:assert/strict";
 import { afterEach, expect, test, vi } from "vitest";
-import { verifyCitationLive } from "./verify-cites.mjs";
+import {
+  createBreaker,
+  verifyCitationLive,
+  wouldAsk,
+} from "./verify-cites.mjs";
 
 const json = (status, body) =>
   new Response(body === undefined ? null : JSON.stringify(body), { status });
@@ -18,7 +22,7 @@ const text = (status, body) => new Response(body, { status });
  */
 function fakeFetch(routes) {
   const calls = [];
-  vi.stubGlobal("fetch", async (url) => {
+  vi.stubGlobal("fetch", async (url, init) => {
     calls.push(url);
     const hit = Object.keys(routes)
       .filter((p) => url.startsWith(p))
@@ -26,7 +30,7 @@ function fakeFetch(routes) {
     if (hit === undefined) throw new Error(`unrouted request: ${url}`);
     const r = routes[hit];
     if (r instanceof Error) throw r;
-    return r();
+    return r(init?.signal);
   });
   return calls;
 }
@@ -90,8 +94,10 @@ test("records with fields missing: no title, a subtitle, a year only in `publish
   const calls = fakeFetch({
     [CR]: () =>
       json(200, {
+        // No title and a subtitle that is not the claimed title's: no match, so the lookups go on
+        // (a match would end them) and every registry's missing fields are read.
         message: {
-          subtitle: ["All You Need"],
+          subtitle: ["Unrelated Words About Gardening"],
           published: { "date-parts": [[2017]] },
         },
       }),
@@ -130,19 +136,22 @@ test("an arXiv id nobody has: the arXiv API's empty feed and S2's 404", async ()
 });
 
 test("a title only: every registry's search endpoint, hits and all", async () => {
+  // The first three registries' hits carry the title with a year too far off to match, so the
+  // lookups go on (a match would end them) and every search endpoint's answer is read; arXiv's
+  // hit is the one that matches.
   const calls = fakeFetch({
     [`${CR}?`]: () =>
       json(200, {
         message: {
-          items: [{ title: [TITLE], issued: { "date-parts": [[2017]] } }, {}],
+          items: [{ title: [TITLE], issued: { "date-parts": [[1990]] } }, {}],
         },
       }),
     [`${OA}?`]: () =>
       json(200, {
-        results: [{ display_name: TITLE, publication_year: 2017 }, {}],
+        results: [{ display_name: TITLE, publication_year: 1990 }, {}],
       }),
     [`${S2}/search`]: () =>
-      json(200, { data: [{ title: TITLE, year: 2017 }, {}] }),
+      json(200, { data: [{ title: TITLE, year: 1990 }, {}] }),
     [AX]: () => text(200, feed(TITLE, 2017)),
   });
   const result = await verifyCitationLive({
@@ -205,8 +214,9 @@ test("CVEs: found by count, found by list, not found, NVD down, and a malformed
 
 test("a second lookup is served from the cache; failures and a nonexistent DOI are not cached", async () => {
   const cache = {};
+  // No registry confirms the DOI, so every lookup runs: a match would end them (tested below).
   fakeFetch({
-    [CR]: () => json(200, { message: { title: [TITLE] } }),
+    [CR]: () => json(404),
     [OA]: () => json(503),
     [S2]: () => json(404),
     [DOI]: () => json(200, { responseCode: 1 }),
@@ -233,6 +243,330 @@ test("a second lookup is served from the cache; failures and a nonexistent DOI a
   );
 });
 
+// Guards: each resolver's cache key names the identifier that resolver ASKED. arXiv is asked by
+// arXiv id even when the entry has a DOI; keyed by the DOI, a corrected arXiv id kept the old
+// id's answer and was never asked.
+test("a corrected arXiv id is asked again even when the DOI is unchanged", async () => {
+  const cache = {};
+  const routes = {
+    [CR]: () => json(404),
+    [OA]: () => json(404),
+    [S2]: () => json(404),
+    [AX]: () => text(200, "<feed></feed>"),
+    [DOI]: () => json(200, { responseCode: 1 }),
+  };
+  fakeFetch(routes);
+  await verifyCitationLive(
+    { id: "c", doi: "10.1/x", arxiv: "2401.00001", title: TITLE },
+    { cache },
+  );
+  const again = fakeFetch(routes);
+  await verifyCitationLive(
+    { id: "c", doi: "10.1/x", arxiv: "2401.00002", title: TITLE },
+    { cache },
+  );
+  assert.deepEqual(
+    again.filter((u) => u.startsWith(AX)),
+    [`${AX}?id_list=2401.00002&max_results=1`],
+  );
+});
+
+// Guards: an arXiv DOI (10.48550/arXiv.<id>) names an arXiv id, so arXiv is asked by that id.
+// Measured 2026-09-27 on a real bibliography: OpenAlex maps 10.48550/arXiv.2310.06770 (SWE-bench)
+// to an unrelated work; with Crossref and Semantic Scholar refusing and arXiv asked only by title
+// "when there is no DOI", nothing contradicted it and the paper came out `exists: false`.
+test("an arXiv DOI is asked of arXiv by its id, whose match outweighs a registry's wrong record", async () => {
+  const calls = fakeFetch({
+    [CR]: () => json(429),
+    [OA]: () =>
+      json(200, {
+        id: "W1",
+        display_name: "GardenBench",
+        publication_year: 2023,
+      }),
+    [S2]: () => json(429),
+    [AX]: () => text(200, feed(TITLE, 2017)),
+    [DOI]: () => json(200, { responseCode: 1 }),
+  });
+  const v = await verifyCitationLive(
+    { id: "c", doi: "10.48550/arXiv.1706.03762", title: TITLE, year: "2017" },
+    { cache: {} },
+  );
+  assert.deepEqual(
+    {
+      verdict: v.verdict,
+      matched: v.matched_db,
+      arxiv: calls.filter((u) => u.startsWith(AX)),
+    },
+    {
+      verdict: "true",
+      matched: "arxiv",
+      arxiv: [`${AX}?id_list=1706.03762&max_results=1`],
+    },
+  );
+});
+
+// Guards: NVD's "not found" must not be cached. A CVE cited before NVD indexes it would otherwise
+// stay "fabricated" in the committed cache forever; only positive existence is kept, as for doi.org.
+test("an NVD not-found answer is not cached, so a later build asks again", async () => {
+  const cache = {};
+  fakeFetch({ [NVD]: () => json(200, { totalResults: 0 }) });
+  await verifyCitationLive({ id: "c", cve: "CVE-2026-0001" }, { cache });
+  const again = fakeFetch({ [NVD]: () => json(200, { totalResults: 1 }) });
+  await verifyCitationLive({ id: "c", cve: "CVE-2026-0001" }, { cache });
+  assert.deepEqual(
+    { asked: again.length, keys: Object.keys(cache) },
+    { asked: 1, keys: ["nvd:CVE-2026-0001"] },
+  );
+});
+
+// Guards: a title-only cache key must keep punctuation that names a different work. A shared key
+// for `C` and `C++` would answer the second from the first's registry responses, no request made.
+test("title-only keys keep punctuation: a C++ title is not served the C title's cached answers", async () => {
+  const cache = {};
+  const miss = () =>
+    json(200, { message: { items: [] }, results: [], data: [] });
+  fakeFetch({
+    [CR]: miss,
+    [OA]: miss,
+    [S2]: miss,
+    [AX]: () => text(200, "<feed></feed>"),
+  });
+  await verifyCitationLive(
+    { id: "a", title: "Fuzzing C Compilers" },
+    { cache },
+  );
+  const asked = fakeFetch({
+    [CR]: miss,
+    [OA]: miss,
+    [S2]: miss,
+    [AX]: () => text(200, "<feed></feed>"),
+  });
+  await verifyCitationLive(
+    { id: "b", title: "Fuzzing C++ Compilers" },
+    { cache },
+  );
+  expect(asked.length).toBeGreaterThan(0);
+});
+
+// Guards: `paperlint build` skips its reachability probe when no citation `wouldAsk`. If it said
+// "no" for a citation a live run asks about, a "fully cached" paper would go online anyway; if it
+// said "yes" for one a live run answers from the cache, every warm build would probe the network.
+test("wouldAsk: false exactly when a live run over the same cache makes no request", async () => {
+  const cites = [
+    { id: "d", doi: "doi:10.1/X.", title: TITLE },
+    { id: "a", arxiv: "arXiv:1706.03762", title: TITLE },
+    { id: "t", title: TITLE, year: 2017 },
+    { id: "v", cve: "cve-2024-0001" },
+    { id: "g", commit: "github.com/a/b/commit/abc1234" },
+  ];
+  fakeFetch({
+    [CR]: () =>
+      json(200, {
+        message: {
+          title: [TITLE],
+          issued: { "date-parts": [[2017]] },
+          items: [],
+        },
+      }),
+    [OA]: () => json(200, { results: [] }),
+    [S2]: () => json(200, { data: [] }),
+    [AX]: () => text(200, "<feed></feed>"),
+    [DOI]: () => json(200, { responseCode: 1 }),
+    [NVD]: () => json(200, { totalResults: 1 }),
+  });
+  const cache = {};
+  const cold = [];
+  for (const c of cites) cold.push(await wouldAsk(c, cache));
+  for (const c of cites) await verifyCitationLive(c, { cache });
+  const warm = [];
+  for (const c of cites) warm.push(await wouldAsk(c, cache));
+  const again = fakeFetch({});
+  for (const c of cites) await verifyCitationLive(c, { cache });
+  assert.deepEqual(
+    { cold, warm, again },
+    {
+      cold: [true, true, true, true, false],
+      warm: [false, false, false, false, false],
+      again: [],
+    },
+  );
+});
+
+test("🔴 the first match ends the lookups: nothing asked after it could change the verdict", async () => {
+  const calls = fakeFetch({
+    [CR]: () =>
+      json(200, {
+        message: { title: [TITLE], issued: { "date-parts": [[2017]] } },
+      }),
+  });
+  const result = await verifyCitationLive({
+    id: "m",
+    doi: "10.1/x",
+    title: TITLE,
+  });
+  assert.deepEqual(
+    { verdict: result.verdict, matched: result.matched_db, calls },
+    {
+      verdict: "true",
+      matched: "crossref",
+      // Not OpenAlex, not Semantic Scholar, not doi.org: a match wins over anything they say.
+      calls: ["https://api.crossref.org/works/10.1%2Fx"],
+    },
+  );
+});
+
+// ── #120: a service that refuses is asked once per run ─────────────────────────────────
+
+/** Three title-only citations nobody can find; `s2` answers Semantic Scholar's search. */
+async function threeTitles(s2, { concurrent = false } = {}) {
+  const calls = fakeFetch({
+    [CR]: () => json(200, { message: { items: [] } }),
+    [OA]: () => json(200, { results: [] }),
+    [S2]: s2,
+    [AX]: () => text(200, "<feed></feed>"),
+  });
+  const breaker = createBreaker();
+  const cites = ["One", "Two", "Three"].map((t) => ({
+    id: t,
+    title: `${t} Paper`,
+  }));
+  const run = (c) => verifyCitationLive(c, { breaker });
+  const results = concurrent
+    ? await Promise.all(cites.map(run))
+    : await (async () => {
+        const out = [];
+        for (const c of cites) out.push(await run(c));
+        return out;
+      })();
+  const count = (prefix) => calls.filter((u) => u.startsWith(prefix)).length;
+  return {
+    asked: {
+      crossref: count(CR),
+      openalex: count(OA),
+      s2: count(S2),
+      arxiv: count(AX),
+    },
+    refused: results.map((r) => r.refused),
+    verdicts: results.map((r) => r.verdict),
+  };
+}
+
+const REFUSED = (why) => [
+  [`semantic_scholar: ${why}`],
+  [`semantic_scholar: semantic_scholar refused earlier in this run (${why})`],
+  [`semantic_scholar: semantic_scholar refused earlier in this run (${why})`],
+];
+
+test("#120: a 429 on the first request — Semantic Scholar is asked ONCE; the other services go on", async () => {
+  assert.deepEqual(await threeTitles(() => json(429)), {
+    asked: { crossref: 3, openalex: 3, s2: 1, arxiv: 3 },
+    refused: REFUSED("http 429"),
+    verdicts: ["unresolvable", "unresolvable", "unresolvable"],
+  });
+});
+
+test("#120: an HTML page where JSON was asked trips the breaker, and says so", async () => {
+  assert.deepEqual(
+    await threeTitles(() =>
+      text(200, "<!doctype html><title>slow down</title>"),
+    ),
+    {
+      asked: { crossref: 3, openalex: 3, s2: 1, arxiv: 3 },
+      refused: REFUSED("answered HTML, not JSON"),
+      verdicts: ["unresolvable", "unresolvable", "unresolvable"],
+    },
+  );
+});
+
+test("#120: a body that is not JSON and not HTML is a refusal too", async () => {
+  const r = await threeTitles(() => text(200, "rate limited"));
+  assert.deepEqual(r.refused[0], [
+    "semantic_scholar: answered something that is not JSON",
+  ]);
+});
+
+test("#120: a timeout trips the breaker — the 15 s is paid once, not per citation", async () => {
+  vi.useFakeTimers();
+  // Never answers; the request's own timeout aborts it.
+  const pending = threeTitles(
+    (signal) =>
+      new Promise((_, reject) =>
+        signal.addEventListener("abort", () =>
+          reject(Object.assign(new Error("aborted"), { name: "AbortError" })),
+        ),
+      ),
+  );
+  let done = false;
+  void pending.finally(() => (done = true));
+  while (!done) await vi.advanceTimersByTimeAsync(1000);
+  assert.deepEqual(await pending, {
+    asked: { crossref: 3, openalex: 3, s2: 1, arxiv: 3 },
+    refused: REFUSED("timeout"),
+    verdicts: ["unresolvable", "unresolvable", "unresolvable"],
+  });
+});
+
+test("#120: citations in flight at once still ask a refusing service once — the first request goes alone", async () => {
+  assert.deepEqual(
+    (await threeTitles(() => json(429), { concurrent: true })).asked,
+    {
+      crossref: 3,
+      openalex: 3,
+      s2: 1,
+      arxiv: 3,
+    },
+  );
+});
+
+// Guards the stated bound: requests already in flight when a service starts refusing still land
+// (at most as many as run at once), and nothing is asked after the first refusal is recorded.
+test("#120: a service that starts refusing costs at most the requests already in flight", async () => {
+  const breaker = createBreaker();
+  let attempts = 0;
+  let release;
+  const first = new Promise((r) => (release = r));
+  const call = (answer) =>
+    breaker.call("s2", async () => {
+      attempts++;
+      return answer();
+    });
+  const opener = call(() => first);
+  const waiters = Array.from({ length: 5 }, () =>
+    call(async () => ({ ok: false, reason: "http 429" })),
+  );
+  release({ ok: true, value: 1 });
+  await Promise.all([opener, ...waiters]);
+  const after = await call(async () => ({ ok: true, value: 2 }));
+  assert.deepEqual(
+    { attempts, after },
+    {
+      attempts: 6,
+      after: { ok: false, reason: "s2 refused earlier in this run (http 429)" },
+    },
+  );
+});
+
+test("#120: a service that answered keeps being asked; one that refuses later is cut off from then on", async () => {
+  let n = 0;
+  const r = await threeTitles(() =>
+    ++n === 1 ? json(200, { data: [] }) : json(503),
+  );
+  assert.deepEqual(
+    { s2: r.asked.s2, refused: r.refused },
+    {
+      s2: 2,
+      refused: [
+        undefined,
+        ["semantic_scholar: http 503"],
+        [
+          "semantic_scholar: semantic_scholar refused earlier in this run (http 503)",
+        ],
+      ],
+    },
+  );
+});
+
 test("offline: no request at all, the verdict from the citation alone", async () => {
   const calls = fakeFetch({});
   const result = await verifyCitationLive(
@@ -265,23 +599,25 @@ test("a registry that never answers is abandoned after the timeout, as unreachab
 test("a registry that answers 200 with no body, or a record without its title, still classifies", async () => {
   const calls = fakeFetch({
     [CR]: () => json(200, {}),
-    [OA]: () => json(200, { id: "W1", publication_year: 2017 }),
+    [`${OA}/doi:10.1%2Fx`]: () =>
+      json(200, { id: "W1", publication_year: 2017 }),
+    [`${OA}/doi:10.1%2Fy`]: () => json(200, {}),
     [S2]: () => json(200, { title: "", year: 2017 }),
     [DOI]: () => json(200, { responseCode: 1 }),
   });
-  const result = await verifyCitationLive({
-    id: "b",
-    doi: "10.1/x",
-    title: TITLE,
-  });
-  // OpenAlex resolves the DOI to a record with no title: an incomparable title is not a
-  // mismatch, so the DOI stands confirmed.
+  const run = async (doi) => {
+    const r = await verifyCitationLive({ id: doi, doi, title: TITLE });
+    return [r.verdict, r.matched_db];
+  };
+  // A record with no title is incomparable, which is not a mismatch, so the DOI stands confirmed:
+  // x by OpenAlex's untitled record; y, which OpenAlex does not know, by Semantic Scholar's.
   assert.deepEqual(
+    { x: await run("10.1/x"), y: await run("10.1/y"), calls: calls.length },
     {
-      verdict: result.verdict,
-      matched_db: result.matched_db,
-      calls: calls.length,
+      x: ["true", "openalex"],
+      y: ["true", "semantic_scholar"],
+      // x: Crossref, OpenAlex (match, the lookups end). y: Crossref, OpenAlex, Semantic Scholar.
+      calls: 5,
     },
-    { verdict: "true", matched_db: "openalex", calls: 4 },
   );
 });

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

@@ -30,6 +30,7 @@ import {
   normalizeArxiv,
   normalizeIdentifiers,
   normalizeTitle,
+  titleIdentity,
   isValidCveId,
 } from "./verify-cites.mjs";
 
@@ -737,15 +738,30 @@ console.log("\n[S4] .bib parser edge cases:");
 
 // ── Edges of the pure layer: the defensive arms, each with the input that reaches it ──────────
 
-test("levenshtein and normalizeTitle take a missing string as empty", () => {
+// Guards: the arXiv id is read out of an arXiv DOI whenever the entry has no USABLE arXiv id, so
+// a blank `arxiv` field (JSON input) does not keep arXiv from being asked.
+test.each([
+  [{ doi: "10.48550/arXiv.2310.06770" }, "2310.06770"],
+  [{ doi: "10.48550/arXiv.2310.06770", arxiv: " " }, "2310.06770"],
+  [
+    { doi: "10.48550/arXiv.2310.06770", arxiv: "arXiv:2401.00001" },
+    "2401.00001",
+  ],
+  [{ doi: "10.1145/3548606" }, undefined],
+])("normalizeIdentifiers(%o).arxiv is %s", (citation, arxiv) => {
+  assert.equal(normalizeIdentifiers(citation).arxiv || undefined, arxiv);
+});
+
+test("levenshtein, normalizeTitle and titleIdentity take a missing string as empty", () => {
   assert.deepEqual(
     [
       levenshtein(null, "ab"),
       levenshtein("abc", undefined),
       levenshtein("", ""),
       normalizeTitle(undefined),
+      titleIdentity(undefined),
     ],
-    [2, 3, 0, ""],
+    [2, 3, 0, "", ""],
   );
 });
 

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

@@ -0,0 +1,8 @@
+/** The clock, for the lookup cache: the day an answer was fetched, in UTC. */
+export const todayUtc = (): string => new Date().toISOString().slice(0, 10);
+
+/** Wait `ms` — DBLP's pace between requests. */
+export const sleep = (ms: number): Promise<void> =>
+  new Promise((r) => {
+    setTimeout(r, ms);
+  });