SPB Git

Repository Public Research preview

scholarly.mjs 12.6 KB 186 lines javascript

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
Files main
Menu

Theme