paperlint 3.1.0 → 3.1.2

package/skills/paper-pipeline/scripts/consumer.harness.mjs

@@ -298,9 +298,9 @@ assert.equal(
 
   // 🔴 RELATIVE, AND `/`-SEPARATED, ASSERTED BEFORE THE EQUALITIES BELOW — and the order is a
   // finding, not a preference. `assert` aborts at the first failure, so with this line placed
-  // after them a resolver that returned an absolute path died on "must be returned as written":
-  // the mutation run reported RED-but-a-DIFFERENT-case, i.e. this assertion was never reached and
-  // nothing showed it can fail. The narrow property goes first; the equalities then cover the rest.
+  // after them a resolver that returned an absolute path died on "must be returned as written" —
+  // a RED result, but for a different case than this one, i.e. this assertion was never reached
+  // and nothing showed it can fail. The narrow property goes first; the equalities then cover the rest.
   // The value is compared against text a human typed inside a SKILL.md, so an absolute path makes
   // every `startsWith` false — not an error, an empty loop body.
   assert.equal(

package/skills/paper-pipeline/scripts/consumer.mjs

@@ -192,27 +192,32 @@ export function consumerSkillsDir(opts) {
  * in the port and the TypeScript writer imports it, as `src/cli.ts` already does for `isMain`.
  *
  * @param dir  the directory to list. A missing directory throws `ENOENT` from `readdirSync`.
+ * @param fs   the four calls it makes; a test passes a fake to stage what a real disk only does
+ *             in a race (an entry gone between the listing and the stat).
  * @returns the skill names, sorted.
  */
-export function installedSkills(dir) {
+export function installedSkills(
+  dir,
+  fs = { readdirSync, statSync, existsSync, readlinkSync },
+) {
   const names = [];
   const dangling = [];
-  for (const name of readdirSync(dir)) {
+  for (const name of fs.readdirSync(dir)) {
     const entry = join(dir, name);
     let st;
     try {
-      st = statSync(entry); // FOLLOWS the link — the question is where the entry LEADS
+      st = fs.statSync(entry); // FOLLOWS the link — the question is where the entry LEADS
     } catch (e) {
       // The entry was listed a moment ago, so a failed stat is a link that leads nowhere
       // (ENOENT) or in a circle (ELOOP) — not an absence.
       dangling.push({
         name,
-        target: readlinkOr(entry),
+        target: readlinkOr(entry, fs.readlinkSync),
         cause: e.code ?? "error",
       });
       continue;
     }
-    if (st.isDirectory() && existsSync(join(entry, "SKILL.md")))
+    if (st.isDirectory() && fs.existsSync(join(entry, "SKILL.md")))
       names.push(name);
   }
   if (dangling.length) {
@@ -233,11 +238,11 @@ export function installedSkills(dir) {
 }
 
 /** Where a link points, for the message — or a placeholder when it is not a link at all. */
-function readlinkOr(entry) {
+function readlinkOr(entry, readlink) {
   try {
-    return readlinkSync(entry);
+    return readlink(entry);
   } catch {
-    return "(not a link)";
+    return "(not a link)"; // a plain entry gone between the listing and the stat
   }
 }
 
@@ -295,23 +300,6 @@ export function ledgerPath(
   return join(hereDir, "runs.jsonl");
 }
 
-/**
- * `ledgerPath()` plus the assurance that the directory holding it exists.
- *
- * Split out rather than folded in, because the two failures are different: an undeclared ledger
- * is a setup mistake the message above can fix, while a declared-but-missing directory may be
- * the very thing the caller is about to create.
- */
-export function ledgerPathExisting(hereDir, opts) {
-  const p = ledgerPath(hereDir, opts);
-  if (!existsSync(p))
-    throw new Error(
-      `${CONFIG_KEY}: the ledger "${p}" does not exist. Create it (an empty file is a valid ` +
-        `empty ledger) or fix the "ledger" declaration in ${CONFIG_FILE}.`,
-    );
-  return p;
-}
-
 // ═════════════════════════════════════════════════════════════════════════════════════════════
 // THE FOURTH CARRIER — WHERE A SKILL'S PROSE NAMES THESE SCRIPTS
 //

package/skills/paper-pipeline/scripts/consumer.test.mjs

@@ -0,0 +1,113 @@
+/**
+ * consumer.mjs carriers the harness does not reach: isMain without a real entry point, a dangling
+ * skill link, the ledger that must exist, the declared time zone, and the contact address.
+ */
+import assert from "node:assert/strict";
+import { mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, test } from "vitest";
+import { useTempDir, writeTree } from "../../../test/support.mjs";
+import {
+  consumerContactEmail,
+  consumerTimezone,
+  installedSkills,
+  isMain,
+} from "./consumer.mjs";
+
+const root = useTempDir("consumer-");
+const argv1 = process.argv[1];
+afterEach(() => {
+  process.argv[1] = argv1;
+});
+/** A consumer root whose paperlint.json holds `settings`. */
+const consumer = (name, settings) =>
+  writeTree(join(root, name), {
+    "paperlint.json": JSON.stringify(settings),
+  });
+const at = (dir) => ({ env: {}, cwd: dir });
+
+test("isMain: no entry point is never main; an entry that is not on disk is compared as written", () => {
+  process.argv[1] = undefined;
+  assert.equal(isMain("file:///x.mjs"), false);
+  process.argv[1] = "/no/such/entry.mjs";
+  assert.equal(isMain("file:///no/such/entry.mjs"), true);
+  assert.equal(isMain("file:///other.mjs"), false);
+});
+
+test("installedSkills: a link that leads nowhere is refused by name, with the errno", () => {
+  const dir = join(root, "skills");
+  mkdirSync(join(dir, "ok"), { recursive: true });
+  writeFileSync(join(dir, "ok", "SKILL.md"), "# ok\n");
+  symlinkSync(join(root, "gone"), join(dir, "dead"));
+  assert.throws(() => installedSkills(dir), {
+    code: "DANGLING_SKILL_LINK",
+    dangling: [{ name: "dead", target: join(root, "gone"), cause: "ENOENT" }],
+  });
+});
+
+test("installedSkills: an entry gone between the listing and the stat is refused as '(not a link)'; an error without a code says 'error'", () => {
+  const fake = (statError) => ({
+    readdirSync: () => ["gone"],
+    statSync: () => {
+      throw statError;
+    },
+    existsSync: () => false,
+    readlinkSync: () => {
+      throw Object.assign(new Error("EINVAL"), { code: "EINVAL" });
+    },
+  });
+  assert.throws(
+    () =>
+      installedSkills(
+        "/s",
+        fake(Object.assign(new Error("ENOENT"), { code: "ENOENT" })),
+      ),
+    { dangling: [{ name: "gone", target: "(not a link)", cause: "ENOENT" }] },
+  );
+  assert.throws(() => installedSkills("/s", fake(new Error("odd"))), {
+    dangling: [{ name: "gone", target: "(not a link)", cause: "error" }],
+  });
+});
+
+test("consumerTimezone: UTC by default, the declared zone, and loud refusals of null and a typo", () => {
+  assert.equal(consumerTimezone(at(join(root, "nothing-declared"))), "UTC");
+  assert.equal(
+    consumerTimezone(at(consumer("tz", { timezone: "Europe/Berlin" }))),
+    "Europe/Berlin",
+  );
+  assert.throws(
+    () => consumerTimezone(at(consumer("tz-null", { timezone: null }))),
+    new TypeError(
+      'paperlint: "timezone" must be a non-empty IANA zone string, got null',
+    ),
+  );
+  assert.throws(
+    () =>
+      consumerTimezone(at(consumer("tz-typo", { timezone: "Europe/Berlinn" }))),
+    {
+      name: "RangeError",
+      message:
+        /^paperlint: "timezone" is "Europe\/Berlinn", which is not an IANA time zone/,
+    },
+  );
+});
+
+test("consumerContactEmail: absent or null is the public pool; a non-address is refused", () => {
+  assert.equal(
+    consumerContactEmail(at(consumer("mail-null", { contactEmail: null }))),
+    null,
+  );
+  assert.equal(
+    consumerContactEmail(
+      at(consumer("mail", { contactEmail: "me@example.org" })),
+    ),
+    "me@example.org",
+  );
+  assert.throws(
+    () =>
+      consumerContactEmail(at(consumer("mail-bad", { contactEmail: "me" }))),
+    new TypeError(
+      'paperlint: "contactEmail" must be an email address, got "me". Remove the key entirely to use the public pool.',
+    ),
+  );
+});

package/skills/paper-pipeline/scripts/extract-ref-facts.mjs

@@ -212,7 +212,7 @@ function dropEtAl(authors) {
   return { authors: out.filter(Boolean), truncated: true };
 }
 
-const yearIn = (s) => (/\b(19|20)\d{2}\b/.exec(s ?? "") ?? [null])[0];
+const yearIn = (s) => (/\b(19|20)\d{2}\b/.exec(s) ?? [null])[0];
 
 // ── parsing: .bib WITH A REAL PARSER ─────────────────────────────────────────
 
@@ -254,10 +254,13 @@ const joinName = (a) =>
  * the same, and "the bibliography was not checked" reads as "the bibliography is fine". That is why
  * the message names the command, not the fact.
  */
-export async function parseBib(text) {
+export async function parseBib(
+  text,
+  { load = () => import("@retorquere/bibtex-parser") } = {},
+) {
   let parse;
   try {
-    ({ parse } = await import("@retorquere/bibtex-parser"));
+    ({ parse } = await load());
   } catch (e) {
     if (e?.code !== "ERR_MODULE_NOT_FOUND") throw e;
     throw new Error(
@@ -289,6 +292,9 @@ export async function parseBib(text) {
       .filter((a) => !isOthers(a))
       .map(joinName)
       .filter(Boolean);
+    // A field is a string in today's parser output (list fields such as `keywords` are arrays,
+    // and none of those is read); an array or a number from another parser version is joined or
+    // printed rather than dropped.
     const str = (v) =>
       Array.isArray(v)
         ? v.join(" ")
@@ -477,7 +483,6 @@ export function loadCache(path) {
 }
 
 function saveCache(path, cache) {
-  if (!path) return;
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(cache, null, 1)}\n`);
 }

package/skills/paper-pipeline/scripts/extract-ref-facts.test.mjs

@@ -0,0 +1,380 @@
+/**
+ * extract-ref-facts.mjs beyond its harness: the edges of each reader (markdown list, .bib, CrossRef,
+ * arXiv, cache) and the command itself — sources, flags, the network loop (with `fetch` stubbed in
+ * the child process), and the refusals.
+ */
+import assert from "node:assert/strict";
+import { readFileSync, 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";
+import {
+  buildFacts,
+  extractIds,
+  loadCache,
+  loadEntries,
+  parseBib,
+  parseMarkdownRefs,
+  primaryOf,
+  readArxiv,
+  readCrossref,
+  recordFrom,
+  resolveSource,
+} from "./extract-ref-facts.mjs";
+
+const SCRIPT = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "extract-ref-facts.mjs",
+);
+const root = useTempDir("extract-ref-facts-");
+
+test("markdown: the list ends at the file's end or a second References heading; lines continue an entry", () => {
+  assert.deepEqual(parseMarkdownRefs("# P\n\n## References"), []);
+  const refs = parseMarkdownRefs(
+    [
+      "## References",
+      "",
+      "1. A. Author, B. Author. *A Title.* Venue,",
+      "   continued 2021.",
+      "2. *Untitled Authors.* 2019 note",
+      "3. C. Writer 2018. *Late Year.* Venue",
+      "4. No title here at all",
+      "",
+      "## References",
+      "5. Never read. *X.* 2000",
+    ].join("\n"),
+  );
+  assert.deepEqual(
+    refs.map(({ n, line, authors, title, year, venue_text }) => ({
+      n,
+      line,
+      authors,
+      title,
+      year,
+      venue_text,
+    })),
+    [
+      {
+        n: 1,
+        line: 3,
+        authors: ["A. Author", "B. Author"],
+        title: "A Title",
+        year: "2021",
+        venue_text: "Venue, continued 2021.",
+      },
+      {
+        n: 2,
+        line: 5,
+        authors: [],
+        title: "Untitled Authors",
+        year: "2019",
+        venue_text: "2019 note",
+      },
+      {
+        n: 3,
+        line: 6,
+        authors: ["C. Writer 2018"],
+        title: "Late Year",
+        year: "2018",
+        venue_text: "Venue",
+      },
+      {
+        n: 4,
+        line: 7,
+        authors: [],
+        title: null,
+        year: null,
+        venue_text: "No title here at all",
+      },
+    ],
+  );
+});
+
+test(".bib: a key the text spells with spaces has no line; a missing title or year is null, not empty", async () => {
+  const [entry] = await parseBib(
+    "@misc{ spaced ,\n  note={see arXiv:2101.00001}\n}\n",
+  );
+  assert.deepEqual(
+    {
+      line: entry.line,
+      title: entry.title,
+      year: entry.year,
+      authors: entry.authors,
+      raw: entry.raw,
+    },
+    {
+      line: 0,
+      title: null,
+      year: null,
+      authors: [],
+      raw: "see arXiv:2101.00001",
+    },
+  );
+});
+
+test(".bib from a parser that returns no fields, or list and number fields: joined and printed, not dropped", async () => {
+  const load = async () => ({
+    parse: () => ({
+      entries: [
+        { key: "bare" },
+        {
+          key: "odd",
+          fields: {
+            title: ["Split", "Title"],
+            year: 2021,
+            note: null,
+            author: [{ firstName: "Ada", lastName: "Lovelace" }],
+          },
+        },
+      ],
+    }),
+  });
+  const [bare, odd] = await parseBib("@misc{bare,}\n@misc{odd,}\n", { load });
+  assert.deepEqual(
+    [
+      bare,
+      { title: odd.title, year: odd.year, authors: odd.authors, raw: odd.raw },
+    ],
+    [
+      {
+        n: 1,
+        line: 1,
+        key: "bare",
+        raw: "",
+        authors: [],
+        truncated: false,
+        title: null,
+        year: null,
+        venue_text: "",
+        doi_field: null,
+      },
+      {
+        title: "Split Title",
+        year: "2021",
+        authors: ["Ada Lovelace"],
+        raw: "Ada Lovelace Split Title 2021",
+      },
+    ],
+  );
+});
+
+test("identifiers: a declared DOI field comes first; an entry without text fields has none", () => {
+  const ids = extractIds({
+    doi_field: "10.1111/field",
+    raw: "doi:10.2222/text.",
+  });
+  assert.deepEqual(ids, { arxiv: [], doi: ["10.1111/field", "10.2222/text"] });
+  assert.equal(primaryOf(ids), "doi:10.1111/field");
+  const none = extractIds({});
+  assert.deepEqual(none, { arxiv: [], doi: [] });
+  assert.equal(primaryOf(none), null);
+});
+
+test("CrossRef: every fallback — no message, the date sources, scalar title/subtitle/venue, nameless authors", () => {
+  assert.equal(readCrossref("{}"), null);
+  const rec = (message) => readCrossref(JSON.stringify({ message }));
+  assert.deepEqual(
+    rec({
+      title: "Scalar",
+      subtitle: "Sub",
+      author: [{ family: "F" }, { name: "Org" }, {}],
+      "container-title": "Journal",
+      "published-print": { "date-parts": [[2019]] },
+    }),
+    {
+      title: "Scalar: Sub",
+      authors: ["F", "Org", ""],
+      year: "2019",
+      venue: "Journal",
+      journalRef: null,
+      doi: null,
+      error: false,
+    },
+  );
+  assert.equal(
+    rec({ title: ["T"], "published-online": { "date-parts": [[2018]] } }).year,
+    "2018",
+  );
+  assert.deepEqual(rec({ title: ["T"] }), {
+    title: "T",
+    authors: [],
+    year: null,
+    venue: undefined,
+    journalRef: null,
+    doi: null,
+    error: false,
+  });
+});
+
+test("arXiv: an entry with no published date and no title", () => {
+  assert.deepEqual(readArxiv("<feed><entry><id>x</id></entry></feed>"), {
+    title: null,
+    authors: [],
+    year: null,
+    venue: null,
+    journalRef: null,
+    doi: null,
+    error: false,
+  });
+});
+
+test("a record: a hand-written cache entry with no status, an undated response, and a 200 naming no work", () => {
+  assert.deepEqual(recordFrom("arxiv:2101.00001", {}), {
+    cached: true,
+    registry: "arxiv",
+    httpStatus: null,
+    fetched: null,
+  });
+  assert.deepEqual(
+    recordFrom("doi:10.1234/x", { httpStatus: 200, body: "{}" }),
+    {
+      cached: true,
+      registry: "crossref",
+      httpStatus: 200,
+      fetched: null,
+      found: false,
+    },
+  );
+});
+
+test("cache: no path and a corrupt file both read as empty", () => {
+  const corrupt = join(root, "corrupt.json");
+  writeFileSync(corrupt, "{ nope");
+  assert.deepEqual([loadCache(undefined), loadCache(corrupt)], [{}, {}]);
+});
+
+test("sources: a file names itself; a .bib is read as BibTeX; facts without a cache say so", async () => {
+  const bib = join(root, "one.bib");
+  writeFileSync(bib, "@misc{k, title={T}, year={2020}}\n");
+  assert.equal(resolveSource(bib), bib);
+  const entries = await loadEntries(bib);
+  const facts = buildFacts({
+    source: bib,
+    text: "",
+    entries,
+    cache: {},
+    cachePath: null,
+  });
+  assert.deepEqual([facts.source_kind, facts.cache], ["bibtex", null]);
+});
+
+// ── the command ─────────────────────────────────────────────────────────────
+
+const CROSSREF_OK = JSON.stringify({
+  message: {
+    title: ["Found"],
+    author: [{ family: "A" }],
+    issued: { "date-parts": [[2020]] },
+  },
+});
+writeTree(root, {
+  "paper/paper.md":
+    "## References\n\n1. A. A. *Found.* doi:10.1234/ok\n2. B. B. *Lost.* doi:10.1234/down\n",
+  "empty/paper.md": "# Nothing cited\n",
+  // `fetch` in the child: 10.1234/down fails at the transport, anything else is a CrossRef hit.
+  "fetch.mjs":
+    `globalThis.fetch = async (url) => {\n` +
+    `  if (url.includes("down")) throw new Error("network down");\n` +
+    `  return { status: 200, text: async () => ${JSON.stringify(CROSSREF_OK)} };\n` +
+    `};\n`,
+  // The optional .bib parser, uninstalled — and broken in some other way.
+  "no-parser.mjs":
+    "import { register } from 'node:module';\n" +
+    "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === '@retorquere/bibtex-parser') throw Object.assign(new Error('gone'), { code: 'ERR_MODULE_NOT_FOUND' }); return next(s, c); }\"));\n",
+  "bad-parser.mjs":
+    "import { register } from 'node:module';\n" +
+    "register('data:text/javascript,' + encodeURIComponent(\"export async function resolve(s, c, next) { if (s === '@retorquere/bibtex-parser') throw Object.assign(new Error('broken install'), { code: 'EACCES' }); return next(s, c); }\"));\n",
+  "bib/refs.bib": "@misc{k, title={T}, note={doi:10.1234/ok}}\n",
+});
+const cli = (args, { cwd = root, nodeArgs = [] } = {}) =>
+  runNode(SCRIPT, args, {
+    cwd,
+    nodeArgs,
+    env: { CLAUDE_PROJECT_DIR: root },
+  });
+const FETCH = ["--import", join(root, "fetch.mjs")];
+
+test("online: hits are fetched and cached, a transport failure is named and stays missing", () => {
+  const r = cli(["paper"], { nodeArgs: FETCH });
+  assert.deepEqual(
+    {
+      status: r.status,
+      stdout: r.stdout,
+      stderr: r.stderr,
+      cached: Object.keys(
+        JSON.parse(readFileSync(join(root, "paper/repro/refs-cache.json"))),
+      ),
+    },
+    {
+      status: 0,
+      stdout:
+        "📚 paper.md → paper/_build/refs.facts.json (2 entries, 2 identifiers, 1 resolved, +1 fetched)\n",
+      stderr: "   … doi:10.1234/down: network down\n",
+      cached: ["doi:10.1234/ok"],
+    },
+  );
+});
+
+test("online again: cached keys are not refetched; --quiet hides the failure; --refresh refetches", () => {
+  const again = cli(["paper", "--quiet"], { nodeArgs: FETCH });
+  assert.deepEqual(again, {
+    status: 0,
+    stdout:
+      "📚 paper.md → paper/_build/refs.facts.json (2 entries, 2 identifiers, 1 resolved, all from cache)\n",
+    stderr: "",
+  });
+  const refresh = cli(["paper", "--refresh", "--quiet"], { nodeArgs: FETCH });
+  assert.match(refresh.stdout, /1 resolved, \+1 fetched\)\n$/);
+});
+
+test("the paper file itself as the target, with --cache, --out and --offline", () => {
+  const r = cli([
+    join(root, "paper/paper.md"),
+    "--offline",
+    `--cache=${join(root, "paper/repro/refs-cache.json")}`,
+    `--out=${join(root, "out/facts.json")}`,
+  ]);
+  assert.deepEqual(r, {
+    status: 0,
+    stdout:
+      "📚 paper.md → out/facts.json (2 entries, 2 identifiers, 1 resolved, offline)\n",
+    stderr: "",
+  });
+});
+
+test("no target: the current directory", () => {
+  const r = cli(["--offline"], { cwd: join(root, "paper") });
+  assert.equal(r.status, 0, r.stderr);
+});
+
+test("refusals: nowhere to read from, and zero entries (not written as a clean bibliography)", () => {
+  assert.deepEqual(cli([join(root, "nope"), "--offline"]), {
+    status: 1,
+    stdout: "",
+    stderr: `🛑 no paper.md, draft.md, refs.bib, build/custom.bib under ${join(root, "nope")} — nowhere to take a bibliography from.\n`,
+  });
+  assert.deepEqual(cli(["empty", "--offline"]), {
+    status: 1,
+    stdout: "",
+    stderr:
+      "🛑 parsed 0 entries out of empty/paper.md. Silence here would look like a clean bibliography.\n",
+  });
+});
+
+test(".bib without its optional parser: the error names the install; any other failure is not masked", () => {
+  const missing = cli(["bib", "--offline"], {
+    nodeArgs: ["--import", join(root, "no-parser.mjs")],
+  });
+  assert.equal(missing.status, 1);
+  assert.match(
+    missing.stderr,
+    /parsing \.bib requires @retorquere\/bibtex-parser[\s\S]*Install: {2}npm i -D @retorquere\/bibtex-parser/,
+  );
+  const broken = cli(["bib", "--offline"], {
+    nodeArgs: ["--import", join(root, "bad-parser.mjs")],
+  });
+  assert.equal(broken.status, 1);
+  assert.match(broken.stderr, /broken install/);
+  assert.doesNotMatch(broken.stderr, /npm i -D/);
+});