Repository Public Research preview
1#!/usr/bin/env node2/**3 * =============================================================================4 * SP BOUCHER | SOFTWARE & RESEARCH5 * ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING6 * =============================================================================7 *8 * Project : LLM API toolkits9 * File : scholarly/skill/citation-verification/scripts/scholarly.mjs10 * Module : scholarly11 * Repository : https://git.spboucher.ai/llm-api-toolkits12 * Created : 2026-11-1013 * Last Modified : 2026-11-1014 *15 * Author : Simon-Pierre Boucher16 * Position : Professor of Finance17 * Institution : Université du Québec en Outaouais (UQO)18 * Organization : SP Boucher19 * Website : https://spboucher.ai20 * Git : https://git.spboucher.ai21 *22 * Preferred Contact: dev@spboucher.ai23 * Development : dev@spboucher.ai24 * Support : support@spboucher.ai25 * Security/Admin : admin@spboucher.ai26 *27 * Copyright (c) 202628 * Simon-Pierre Boucher29 * All rights reserved where applicable. This file is governed by the30 * applicable project license, copyright notices and relevant law.31 * Existing third-party rights and notices remain unaffected.32 *33 * License : None specified (no license file in this repository)34 *35 * Do not embed credentials, private keys, access tokens,36 * certificates or confidential personal information.37 *38 * =============================================================================39 * END OF SP BOUCHER SOURCE HEADER40 * =============================================================================41 */4243/**44 * scholarly.mjs — verify citations and search the scholarly record from the command line.45 * No dependency: Node.js 20+ and the network. Output is JSON on stdout (or Markdown with --format md46 * for verify-bib). Sources: Crossref, OpenAlex, arXiv, doi.org. Nothing identifying is sent unless47 * SCHOLARLY_MAILTO is set.48 */49import { writeFileSync } from "node:fs";50import path from "node:path";51import { STYLES, createEngine } from "./lib/index.mjs";5253const USAGE = `Usage: node scripts/scholarly.mjs <command> [arguments] [options]5455Verify56 verify-doi <doi> [--title T] [--author A]... [--year Y] [--venue V] DOI resolves AND metadata matches57 resolve "<reference>" | --title T [--author A] [--year Y] find the record of a reference without DOI58 verify-bib <file> [--only-problems] [--keys k1,k2] [--max N] [--offset N]59 [--format json|md] [--out FILE] [--strict] audit a .bib file or a text list of references60 retractions <doi>... | --bib <file> [--no-openalex] retractions, concerns, corrections61 parse-bib <file> offline: entries, missing DOIs, duplicates, errors6263Find64 search <query> [--title T] [--author A] [--from Y] [--to Y] [--type T]65 [--sort relevance|citations|date] [--limit N] [--source crossref|openalex] [--abstract]66 get <id> [--enrich] id: DOI, arXiv id, OpenAlex W…, pmid:N67 arxiv <query> | --id <id>... [--limit N] [--sort relevance|date]68 citations <id> [--limit N] [--sort citations|date] [--from Y] works citing it (OpenAlex)69 references <id> [--limit N] [--source auto|crossref|openalex] what it cites70 related <id> [--limit N] related works (OpenAlex)71 author <name> | --orcid O | --id A… [--limit N] [--sort citations|date] [--from Y] [--to Y]72 oa <id> legal open-access copies7374Write75 cite <id> [--style ${STYLES.join("|")}] [--styles a,b] [--key K]76 bibtex <doi> [--generated] [--key K]7778 status configuration and OpenAlex budget (no network)7980Options: --root DIR (directory files may be read from; default: the file's own directory)81Environment: OPENALEX_API_KEY, SCHOLARLY_MAILTO, SCHOLARLY_ROOT, SCHOLARLY_TIMEOUT_MS (all optional)82Exit status: 0 success, 1 error, 2 usage, 3 verify-bib --strict found entries needing attention`;8384const MULTI = new Set(["author", "id"]);85const FLAGS = new Set(["only-problems", "strict", "no-openalex", "enrich", "abstract", "generated", "help"]);86function parseArgs(argv) {87 const pos = [], opt = {};88 for (let i = 0; i < argv.length; i++) {89 const a = argv[i];90 if (a === "--") { pos.push(...argv.slice(i + 1)); break; }91 if (!a.startsWith("--")) { pos.push(a); continue; }92 const eq = a.indexOf("="), k = (eq > 0 ? a.slice(2, eq) : a.slice(2));93 if (FLAGS.has(k)) { opt[k] = true; continue; }94 const v = eq > 0 ? a.slice(eq + 1) : argv[++i];95 if (v === undefined) throw Object.assign(new Error(`--${k} needs a value`), { usage: true });96 if (MULTI.has(k)) (opt[k] ??= []).push(v); else opt[k] = v;97 }98 return { pos, opt };99}100const num = (v, name) => { if (v == null) return undefined; const n = Number(v); if (!Number.isInteger(n)) throw Object.assign(new Error(`--${name} must be an integer`), { usage: true }); return n; };101const need = (v, what) => { if (v == null || v === "") throw Object.assign(new Error(`${what} is required`), { usage: true }); return v; };102103/** Markdown report of a bibliography audit: a summary, then the entries that need a human. */104function bibReport(r) {105 const esc = (s) => String(s ?? "").replace(/\|/g, "\\|").replace(/\s+/g, " ");106 const order = ["doi_not_found", "doi_invalid", "not_found", "retracted", "metadata_mismatch", "ambiguous", "unverifiable", "error", "doi_missing_found", "verified"];107 const lines = [`# Bibliography audit`, "", `Source: ${r.source}. Entries: ${r.entries_total}; checked: ${r.entries_checked}.`, "", "| Status | Entries |", "|---|---|"];108 for (const s of order) if (r.summary[s]) lines.push(`| ${s} | ${r.summary[s]} |`);109 const problems = r.results.filter((x) => !["verified", "doi_missing_found"].includes(x.status)).sort((a, b) => order.indexOf(a.status) - order.indexOf(b.status));110 if (problems.length) {111 lines.push("", "## Needs attention", "", "| Key | Status | Cited as | What the registry says |", "|---|---|---|---|");112 for (const x of problems) {113 const cited = [x.claimed.first_author, x.claimed.year, x.claimed.title ?? x.claimed.reference].filter(Boolean).join(", ");114 let says = x.notes?.[0] ?? "";115 if (x.status === "metadata_mismatch") says = Object.entries(x.comparison ?? {}).filter(([, f]) => ["mismatch", "differs", "off_by_one", "close", "count_differs", "order_differs"].includes(f.status)).map(([k, f]) => `${k}: cited "${f.claimed}", registered "${f.actual}"`).join("; ");116 else if (x.status === "retracted") says = `Retracted${x.retraction?.notices?.find((n) => /retract/i.test(n.type))?.doi ? ` (notice: ${x.retraction.notices.find((n) => /retract/i.test(n.type)).doi})` : ""}`;117 else if (x.status === "ambiguous") says = `Similar records: ${(x.candidates ?? []).slice(0, 3).map((c) => `${c.doi ?? "no DOI"} (${c.year})`).join(", ")}`;118 else if (x.suggested_doi) says = `Same title, author and year registered as ${x.suggested_doi}`;119 else if (x.status === "error") says = `Lookup failed (${x.error?.code}); run again`;120 lines.push(`| ${esc(x.key)} | ${x.status} | ${esc(cited).slice(0, 160)} | ${esc(says).slice(0, 300)} |`);121 }122 }123 const add = r.results.filter((x) => x.status === "doi_missing_found");124 if (add.length) { lines.push("", "## DOI found for entries that had none", "", "| Key | DOI |", "|---|---|"); for (const x of add) lines.push(`| ${esc(x.key)} | ${x.suggested_doi} |`); }125 if (r.duplicates?.length) { lines.push("", "## Same work cited under several keys", ""); for (const d of r.duplicates) lines.push(`- ${d.doi}: ${d.keys.join(", ")}`); }126 if (r.parse_errors?.length) { lines.push("", "## BibTeX syntax errors", ""); for (const e of r.parse_errors) lines.push(`- line ${e.line} (@${e.type}): ${e.message}`); }127 lines.push("", "Statuses are produced by string comparison against Crossref, arXiv and doi.org. \"not_found\" is not proof that a reference is invented; \"verified\" is not a judgement on the work.", "");128 return lines.join("\n");129}130131async function main(argv) {132 const { pos, opt } = parseArgs(argv);133 const cmd = pos.shift();134 if (!cmd || opt.help || cmd === "help") { console.log(USAGE); return 0; }135 const env = { ...process.env };136 const fileArg = (p) => { // Files are confined to one directory: --root, SCHOLARLY_ROOT, or the file's own directory.137 const abs = path.resolve(need(p, "a file"));138 if (opt.root) env.SCHOLARLY_ROOT = path.resolve(opt.root); else if (!env.SCHOLARLY_ROOT) env.SCHOLARLY_ROOT = path.dirname(abs);139 return abs;140 };141 let file = null;142 if (["verify-bib", "parse-bib"].includes(cmd)) file = fileArg(pos[0]);143 if (cmd === "retractions" && opt.bib) file = fileArg(opt.bib);144 const e = createEngine({ env });145 const claim = { title: opt.title, authors: opt.author, year: num(opt.year, "year"), venue: opt.venue, volume: opt.volume, pages: opt.pages };146 let result;147 switch (cmd) {148 case "status": result = e.status(); break;149 case "verify-doi": result = await e.verifyDoi({ doi: need(pos[0], "a DOI"), ...claim }); break;150 case "resolve": result = await e.resolveReference({ reference: pos.join(" ") || undefined, ...claim, doi: opt.doi, arxiv: opt.arxiv }); break;151 case "parse-bib": result = e.parseBibtexInput({ path: file }); break;152 case "verify-bib": {153 result = await e.verifyBibliography({ path: file, only_problems: !!opt["only-problems"], keys: opt.keys ? opt.keys.split(",").map((s) => s.trim()).filter(Boolean) : undefined, max_entries: num(opt.max, "max"), offset: num(opt.offset, "offset"), concurrency: num(opt.concurrency, "concurrency") });154 const text = opt.format === "md" ? bibReport(result) : JSON.stringify(result, null, 2);155 if (opt.out) { writeFileSync(opt.out, text.endsWith("\n") ? text : `${text}\n`, { flag: "wx" }); console.log(JSON.stringify({ written: opt.out, summary: result.summary, needs_attention: result.needs_attention }, null, 2)); }156 else console.log(text);157 return opt.strict && result.needs_attention.length ? 3 : 0;158 }159 case "retractions": {160 const dois = file ? [...new Set(e.parseBibtexInput({ path: file }).entries.map((x) => x.doi).filter(Boolean))] : pos;161 if (!dois.length) throw Object.assign(new Error(file ? "that file has no entry with a DOI" : "give one or more DOIs, or --bib <file>"), { usage: true });162 result = await e.checkRetractions({ dois, use_openalex: !opt["no-openalex"] });163 break;164 }165 case "search": result = await e.searchWorks({ query: pos.join(" ") || undefined, title: opt.title, author: opt.author?.[0], from_year: num(opt.from, "from"), to_year: num(opt.to, "to"), type: opt.type, sort: opt.sort, limit: num(opt.limit, "limit"), offset: num(opt.offset, "offset"), source: opt.source, include_abstract: !!opt.abstract }); break;166 case "get": result = { work: await e.getWork(need(pos[0], "an identifier"), { enrich: !!opt.enrich }) }; break;167 case "arxiv": result = await e.searchArxiv({ query: pos.join(" ") || undefined, ids: opt.id, limit: num(opt.limit, "limit"), sort: opt.sort }); break;168 case "citations": result = await e.getCitations({ id: need(pos[0], "an identifier"), limit: num(opt.limit, "limit"), sort: opt.sort, from_year: num(opt.from, "from") }); break;169 case "references": result = await e.getReferences({ id: need(pos[0], "an identifier"), limit: num(opt.limit, "limit"), source: opt.source }); break;170 case "related": result = await e.relatedWorks({ id: need(pos[0], "an identifier"), limit: num(opt.limit, "limit") }); break;171 case "author": result = await e.authorWorks({ name: pos.join(" ") || undefined, orcid: opt.orcid, openalex_id: opt.id?.[0], limit: num(opt.limit, "limit"), sort: opt.sort, from_year: num(opt.from, "from"), to_year: num(opt.to, "to") }); break;172 case "oa": result = await e.getOpenAccess({ id: need(pos[0], "an identifier") }); break;173 case "cite": result = await e.formatCitation({ id: need(pos[0], "an identifier"), style: opt.style, styles: opt.styles ? opt.styles.split(",").map((s) => s.trim()) : undefined, key: opt.key }); break;174 case "bibtex": result = await e.bibtexFromDoi({ doi: need(pos[0], "a DOI"), source: opt.generated ? "generated" : "registry", key: opt.key }); break;175 default: throw Object.assign(new Error(`unknown command "${cmd}"`), { usage: true });176 }177 console.log(JSON.stringify(result, null, 2));178 return 0;179}180181main(process.argv.slice(2)).then((c) => { process.exitCode = c; }, (err) => {182 if (err.usage) { console.error(`${err.message}\n\n${USAGE}`); process.exitCode = 2; return; }183 console.log(JSON.stringify({ error: { code: err.code ?? "error", message: String(err.message ?? err).slice(0, 600) } }, null, 2));184 process.exitCode = 1;185});186