Repository Public Research preview
1/**2 * =============================================================================3 * SP BOUCHER | SOFTWARE & RESEARCH4 * ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING5 * =============================================================================6 *7 * Project : LLM API toolkits8 * File : scholarly/skill/citation-verification/scripts/lib/index.mjs9 * Module : scholarly10 * Repository : https://git.spboucher.ai/llm-api-toolkits11 * Created : 2026-11-1012 * Last Modified : 2026-11-1013 *14 * Author : Simon-Pierre Boucher15 * Position : Professor of Finance16 * Institution : Université du Québec en Outaouais (UQO)17 * Organization : SP Boucher18 * Website : https://spboucher.ai19 * Git : https://git.spboucher.ai20 *21 * Preferred Contact: dev@spboucher.ai22 * Development : dev@spboucher.ai23 * Support : support@spboucher.ai24 * Security/Admin : admin@spboucher.ai25 *26 * Copyright (c) 202627 * Simon-Pierre Boucher28 * All rights reserved where applicable. This file is governed by the29 * applicable project license, copyright notices and relevant law.30 * Existing third-party rights and notices remain unaffected.31 *32 * License : None specified (no license file in this repository)33 *34 * Do not embed credentials, private keys, access tokens,35 * certificates or confidential personal information.36 *37 * =============================================================================38 * END OF SP BOUCHER SOURCE HEADER39 * =============================================================================40 */4142import { readFileSync, realpathSync, statSync } from "node:fs";43import path from "node:path";44import { parseBibtex } from "./bibtex.mjs";45import { STYLES, formatWork } from "./format.mjs";46import { ScholarlyError, USER_AGENT, createHttp, mapLimit } from "./http.mjs";47import { compareWork, judgeCandidate, parseReference } from "./match.mjs";48import { normalizeArxivId, normalizeDoi, parseYear } from "./normalize.mjs";49import { createSources } from "./sources.mjs";5051export { ScholarlyError, STYLES };52export const ENGINE_VERSION = "1.0.0";53const MAX_FILE_BYTES = 5 * 1024 * 1024;54const FILE_EXT = new Set([".bib", ".bibtex", ".txt", ".md"]);55const NOT_FOUND_NOTE = "Absence from Crossref and arXiv is not proof of fabrication: books, theses, reports, working papers and older or regional journals are often missing. Ask the author for the source.";56const invalid = (m) => new ScholarlyError("invalid_input", m);5758/** Recognise a DOI (bare, doi: or URL), an arXiv id, an OpenAlex work id (W…) or "pmid:123". */59export function parseId(id) {60 const s = String(id ?? "").trim();61 if (!s) throw invalid("An identifier is required: a DOI, an arXiv id, an OpenAlex work id (W…) or pmid:<number>.");62 let m;63 if ((m = /^(?:https?:\/\/openalex\.org\/)?(W\d+)$/i.exec(s))) return { kind: "openalex", value: m[1].toUpperCase() };64 if ((m = /^pmid:\s*(\d+)$/i.exec(s))) return { kind: "pmid", value: m[1] };65 const doi = normalizeDoi(s);66 if (doi) { const ax = /^10\.48550\/arxiv\.(.+)$/.exec(doi); return ax ? { kind: "arxiv", value: ax[1].replace(/v\d+$/, ""), doi } : { kind: "doi", value: doi }; }67 const ax = normalizeArxivId(s);68 if (ax) return { kind: "arxiv", value: ax };69 throw invalid(`"${s.slice(0, 80)}" is not a DOI, an arXiv id, an OpenAlex work id or pmid:<number>.`);70}7172/** Compact form of a work for lists. */73export function brief(w, { abstract = false } = {}) {74 if (!w) return null;75 const names = (w.authors ?? []).map((a) => a.name ?? [a.given, a.family].filter(Boolean).join(" ")).filter(Boolean);76 return {77 doi: w.doi ?? null, title: w.title ?? null, authors: names.slice(0, 8), ...(names.length > 8 ? { authors_total: names.length } : {}), year: w.year ?? null, venue: w.venue ?? null,78 ...(w.volume ? { volume: w.volume } : {}), ...(w.issue ? { issue: w.issue } : {}), ...(w.pages ? { pages: w.pages } : {}), type: w.type ?? null,79 ...(w.citation_count != null ? { citation_count: w.citation_count } : {}), is_retracted: !!w.is_retracted, url: w.doi ? `https://doi.org/${w.doi}` : w.url ?? null,80 ...(w.ids?.openalex ? { openalex_id: w.ids.openalex } : {}), ...(w.ids?.arxiv ? { arxiv_id: w.ids.arxiv } : {}), ...(w.relevance != null ? { relevance: w.relevance } : {}),81 ...(abstract && w.abstract ? { abstract: w.abstract.slice(0, 3000) } : {}), source: w.source,82 };83}8485export function createEngine({ env = process.env, fetchImpl, httpOptions = {} } = {}) {86 const timeoutMs = Number(env.SCHOLARLY_TIMEOUT_MS) > 0 ? Number(env.SCHOLARLY_TIMEOUT_MS) : 20000;87 const http = createHttp({ timeoutMs, ...(fetchImpl ? { fetchImpl } : {}), ...httpOptions });88 const src = createSources(http, env);89 const root = path.resolve(env.SCHOLARLY_ROOT || process.cwd());9091 /** Read a bibliography file. Only inside SCHOLARLY_ROOT (symlinks resolved), only text bibliography formats, 5 MB at most. */92 function readInputFile(p) {93 if (typeof p !== "string" || !p.trim()) throw invalid("path is required.");94 const abs = path.resolve(root, p);95 let real, realRoot;96 try { realRoot = realpathSync(root); real = realpathSync(abs); } catch { throw new ScholarlyError("not_found", `No such file: ${p}`); }97 if (real !== realRoot && !real.startsWith(realRoot + path.sep)) throw new ScholarlyError("path_not_allowed", `${p} is outside the allowed directory (${root}). Set SCHOLARLY_ROOT to change it.`);98 if (!FILE_EXT.has(path.extname(real).toLowerCase())) throw new ScholarlyError("path_not_allowed", `Only ${[...FILE_EXT].join(", ")} files can be read.`);99 const st = statSync(real);100 if (!st.isFile()) throw invalid(`${p} is not a file.`);101 if (st.size > MAX_FILE_BYTES) throw invalid(`${p} is larger than 5 MB.`);102 return { text: readFileSync(real, "utf8"), ext: path.extname(real).toLowerCase(), file: path.relative(realRoot, real) };103 }104105 const merge = (base, oa) => ({ ...base, citation_count: oa.citation_count ?? base.citation_count, open_access: oa.open_access ?? base.open_access, is_retracted: base.is_retracted || oa.is_retracted, abstract: base.abstract ?? oa.abstract, ids: { ...oa.ids, ...base.ids, doi: base.doi ?? oa.doi }, sources: [base.source, "openalex"] });106107 async function getWork(id, { enrich = false } = {}) {108 const pid = typeof id === "object" && id?.kind ? id : parseId(id);109 let work, references;110 if (pid.kind === "doi") {111 try { ({ work, references } = await src.crossrefWork(pid.value)); }112 catch (e) { if (e.code !== "not_found") throw e; work = await src.doiCsl(pid.value); if (!work.doi) work.doi = pid.value; }113 } else if (pid.kind === "arxiv") {114 const r = await src.arxiv({ ids: [pid.value] });115 if (!r.works.length) throw new ScholarlyError("not_found", `arXiv has no paper ${pid.value}.`);116 work = r.works[0];117 } else return { ...(await src.openalexWork(pid.kind === "pmid" ? `pmid:${pid.value}` : pid.value)), sources: ["openalex"] };118 if (enrich && work.doi) {119 try { work = merge(work, await src.openalexWork(`doi:${work.doi}`)); }120 catch (e) { work = { ...work, enrichment_error: { code: e.code ?? "error", message: e.message } }; }121 }122 return references ? { ...work, references_deposited: references.length } : work;123 }124125 async function searchWorks({ query, author, title, from_year, to_year, type, limit = 10, offset = 0, sort = "relevance", source = "crossref", include_abstract = false } = {}) {126 if (![query, author, title].some((x) => typeof x === "string" && x.trim())) throw invalid("Give at least one of query, author or title.");127 const n = Math.min(Math.max(1, limit), 50);128 let r;129 if (source === "openalex") {130 const f = [];131 if (from_year || to_year) f.push(`publication_year:${from_year ?? ""}-${to_year ?? ""}`);132 if (type) f.push(`type:${type}`);133 if (title) f.push(`title.search:${String(title).replace(/[,|:]/g, " ")}`);134 if (author) f.push(`raw_author_name.search:${String(author).replace(/[,|:]/g, " ")}`);135 r = await src.openalexList({ search: query || null, filter: f.join(",") || null, sort: sort === "citations" ? "cited_by_count:desc" : sort === "date" ? "publication_date:desc" : null, "per-page": n, page: Math.floor(offset / n) + 1 });136 } else r = await src.crossrefSearch({ bibliographic: query, author, title, from_year, to_year, type, rows: n, offset, sort });137 return { source, total: r.total, returned: r.works.length, works: r.works.map((w) => brief(w, { abstract: include_abstract })) };138 }139140 function retractionInfo(work) {141 const notices = [...(work.updates ?? [])];142 const kind = (t) => (/retract|withdraw|removal/i.test(t) ? "retraction" : /concern/i.test(t) ? "expression_of_concern" : /correct|errat|corrig/i.test(t) ? "correction" : "other");143 const kinds = new Set(notices.map((n) => kind(n.type ?? "")));144 const isNotice = (work.updates_other ?? []).find((u) => /retract|withdraw/i.test(u.type ?? ""));145 return { status: work.is_retracted || kinds.has("retraction") ? "retracted" : kinds.has("expression_of_concern") ? "expression_of_concern" : kinds.has("correction") ? "corrected" : "no_notice", notices, ...(isNotice ? { is_retraction_notice_for: isNotice.doi } : {}) };146 }147148 async function verifyDoi(claim = {}) {149 const doi = normalizeDoi(claim.doi ?? "");150 if (!doi) return { status: "invalid_doi", doi: claim.doi ?? null, doi_resolves: false, notes: ["This string is not a syntactically valid DOI."] };151 let work;152 try { work = await getWork(doi); }153 catch (e) { if (e.code !== "not_found") throw e; return { status: "not_found", doi, doi_resolves: false, notes: ["No registration agency knows this DOI. It is mistyped or invented: do not cite it."] }; }154 const cmp = compareWork(claim, work), ret = retractionInfo(work), notes = [];155 const substantive = ["title", "first_author", "year"].filter((f) => !["not_claimed", "not_in_record"].includes(cmp.fields[f]?.status));156 let status = cmp.verdict === "mismatch" ? "metadata_mismatch" : substantive.includes("title") || substantive.length >= 2 ? "verified" : "doi_resolves_unchecked";157 if (status === "doi_resolves_unchecked") notes.push("The DOI exists, but no title (or author and year) was supplied to compare: existence alone does not verify a citation.");158 if (cmp.mismatches.length) notes.push(`The DOI resolves to a different record than the citation claims (${cmp.mismatches.join(", ")}). Either the DOI or the citation text is wrong.`);159 if (cmp.fields.year?.status === "off_by_one") notes.push("Year differs by one: often online-first versus issue year. Use the registry year unless the style guide says otherwise.");160 if (ret.status === "retracted") { status = "retracted"; notes.push("This work is retracted. Cite it only to discuss the retraction, and say so."); }161 else if (ret.status !== "no_notice") notes.push(`A notice is attached to this work: ${ret.status}.`);162 if (ret.is_retraction_notice_for) notes.push(`This DOI is the retraction notice for ${ret.is_retraction_notice_for}, not the article.`);163 if (work.source === "arxiv" && work.published_doi) notes.push(`This is a preprint; a published version exists: ${work.published_doi}. Prefer it unless you rely on the preprint text.`);164 return { status, doi, doi_resolves: true, verdict: cmp.verdict, mismatches: cmp.mismatches, warnings: cmp.warnings, comparison: cmp.fields, retraction: ret, work: brief(work), notes };165 }166167 async function resolveReference(input = {}) {168 const parsed = input.reference ? parseReference(input.reference) : { raw: null };169 const claim = { ...parsed, ...Object.fromEntries(Object.entries({ title: input.title, authors: input.authors, first_author: input.first_author, year: input.year, venue: input.venue, volume: input.volume, pages: input.pages, doi: input.doi ? normalizeDoi(input.doi) ?? input.doi : undefined, arxiv: input.arxiv ? normalizeArxivId(input.arxiv) : undefined }).filter(([, v]) => v != null && v !== "")) };170 if (!claim.raw && !claim.title && !claim.doi && !claim.arxiv) throw invalid("Give a reference string, a title, a DOI or an arXiv id.");171 const out = { parsed: { title: claim.title ?? null, first_author: claim.first_author ?? (Array.isArray(claim.authors) ? claim.authors[0]?.name ?? claim.authors[0] : null) ?? null, year: claim.year ?? null, doi: claim.doi ?? null, arxiv: claim.arxiv ?? null }, notes: [] };172 if (claim.doi) {173 const v = await verifyDoi(claim);174 if (v.doi_resolves) return { ...out, status: v.status === "verified" || v.status === "doi_resolves_unchecked" ? "found" : v.status, confident: v.status === "verified", via: "doi", match: v.work, verification: v, notes: v.notes };175 out.claimed_doi = { doi: v.doi, status: v.status };176 out.notes.push("The DOI given in the reference does not resolve; searched by title instead.");177 }178 if (claim.arxiv) {179 const r = await src.arxiv({ ids: [claim.arxiv] });180 if (r.works.length) { const w = r.works[0], cmp = compareWork(claim, w); return { ...out, status: cmp.verdict === "mismatch" ? "metadata_mismatch" : "found", confident: cmp.verdict !== "mismatch", via: "arxiv", match: brief(w), mismatches: cmp.mismatches, warnings: cmp.warnings, comparison: cmp.fields, ...(w.published_doi ? { published_doi: w.published_doi } : {}) }; }181 out.notes.push(`arXiv has no paper ${claim.arxiv}; searched by title instead.`);182 }183 const q = claim.raw ?? [claim.first_author ?? (Array.isArray(claim.authors) ? claim.authors.map((a) => a.family ?? a.name ?? a).slice(0, 3).join(" ") : ""), claim.title, claim.year].filter(Boolean).join(" ");184 if (!q.trim() || (!claim.title && !claim.raw)) return { ...out, status: "not_found", confident: false, candidates: [] };185 const rows = Math.min(Math.max(3, input.rows ?? 6), 20);186 const found = await src.crossrefSearch({ bibliographic: q.slice(0, 600), rows });187 let cands = found.works.map((w) => ({ work: w, judge: judgeCandidate(claim, w) }));188 if (!cands.some((c) => c.judge.confident) && claim.title && input.include_arxiv !== false) {189 try {190 const phrase = claim.title.replace(/[^\p{L}\p{N} ]+/gu, " ").replace(/\s+/g, " ").trim();191 const ax = await src.arxiv({ query: `ti:"${phrase}"`, max: 3 });192 cands = cands.concat(ax.works.map((w) => ({ work: w, judge: judgeCandidate(claim, w) })));193 } catch (e) { out.notes.push(`arXiv search skipped: ${e.message}`); }194 }195 const cy = parseYear(claim.year);196 cands.sort((a, b) => (b.judge.confident - a.judge.confident) || (b.judge.score - a.judge.score) || ((cy ? (b.work.year === cy) - (a.work.year === cy) : 0)) || ((b.work.relevance ?? 0) - (a.work.relevance ?? 0)));197 const view = (c) => ({ ...brief(c.work), match: c.judge });198 const sure = cands.filter((c) => c.judge.confident);199 if (sure.length) {200 const best = sure[0], cmp = compareWork(claim, best.work), ret = retractionInfo(best.work);201 if (sure.length > 1) out.notes.push("Several records match (for example a reprint, or a preprint and its published version). Check that the chosen one is the version you read.");202 if (ret.status === "retracted") out.notes.push("This work is retracted.");203 return { ...out, status: "found", confident: true, via: best.work.source, match: view(best), mismatches: cmp.mismatches, warnings: cmp.warnings, comparison: cmp.fields, retraction: ret, alternatives: sure.slice(1, 4).map(view) };204 }205 const close = cands.filter((c) => c.judge.close);206 if (close.length) return { ...out, status: "ambiguous", confident: false, candidates: close.slice(0, 5).map(view), notes: [...out.notes, "No candidate is a confident match. These are similar records, not confirmations: compare them with the source by hand."] };207 return { ...out, status: "not_found", confident: false, candidates: [], closest: cands.slice(0, 3).map(view), notes: [...out.notes, NOT_FOUND_NOTE] };208 }209210 /** One bibliography entry → one status. See references/statuses.md in the skill for the full definitions. */211 async function verifyEntry(entry) {212 const claim = { title: entry.title, authors: entry.authors?.length ? entry.authors : undefined, first_author: entry.first_author, year: entry.year, venue: entry.venue, volume: entry.volume, pages: entry.pages, doi: entry.doi, arxiv: entry.arxiv, raw: entry.raw };213 const base = { key: entry.key ?? null, ...(entry.line ? { line: entry.line } : {}), ...(entry.type ? { entry_type: entry.type } : {}), claimed: { title: entry.title ?? null, first_author: entry.authors?.[0]?.name ?? entry.first_author ?? null, year: entry.year ?? null, doi: entry.doi ?? null, ...(entry.arxiv ? { arxiv: entry.arxiv } : {}), ...(entry.raw ? { reference: entry.raw.slice(0, 300) } : {}) } };214 try {215 if (entry.doi) {216 const v = await verifyDoi(claim);217 if (v.doi_resolves) return { ...base, status: v.status === "doi_resolves_unchecked" ? "unverifiable" : v.status, doi: v.doi, mismatches: v.mismatches, warnings: v.warnings, ...(v.mismatches.length || v.warnings.length ? { comparison: Object.fromEntries(Object.entries(v.comparison).filter(([, f]) => !["match", "not_claimed"].includes(f.status))) } : {}), ...(v.retraction.status !== "no_notice" ? { retraction: v.retraction } : {}), work: v.work, notes: v.notes };218 if (!entry.title && !entry.raw) return { ...base, status: v.status === "invalid_doi" ? "doi_invalid" : "doi_not_found", doi: v.doi, notes: v.notes };219 const r = await resolveReference({ ...claim, doi: undefined, reference: entry.raw });220 return { ...base, status: v.status === "invalid_doi" ? "doi_invalid" : "doi_not_found", doi: v.doi, ...(r.confident ? { suggested_doi: r.match.doi, work: r.match } : {}), notes: [...v.notes, r.confident ? "A record with this title, author and year exists under a different DOI (suggested_doi). Confirm it is the work you mean before replacing." : "No record with this title was found either."] };221 }222 if (!entry.title && !entry.raw && !entry.arxiv) return { ...base, status: "unverifiable", notes: ["The entry has neither a DOI nor a title."] };223 const r = await resolveReference({ ...claim, reference: entry.raw });224 if (r.status === "metadata_mismatch") return { ...base, status: "metadata_mismatch", mismatches: r.mismatches, warnings: r.warnings, comparison: r.comparison, work: r.match, notes: r.notes };225 if (r.confident) {226 const retracted = r.retraction?.status === "retracted" || r.match.is_retracted;227 const status = retracted ? "retracted" : r.mismatches.length ? "metadata_mismatch" : r.via === "arxiv" ? "verified" : "doi_missing_found";228 return { ...base, status, ...(r.match.doi ? { suggested_doi: r.match.doi } : {}), mismatches: r.mismatches, warnings: r.warnings, ...(r.mismatches.length || r.warnings.length ? { comparison: Object.fromEntries(Object.entries(r.comparison).filter(([, f]) => !["match", "not_claimed"].includes(f.status))) } : {}), work: r.match, ...(r.published_doi ? { published_doi: r.published_doi } : {}), ...(r.alternatives?.length ? { alternatives: r.alternatives.map((a) => ({ doi: a.doi, title: a.title, year: a.year, venue: a.venue, type: a.type })) } : {}), notes: r.notes };229 }230 if (r.status === "ambiguous") return { ...base, status: "ambiguous", candidates: r.candidates.map((a) => ({ doi: a.doi, title: a.title, authors: a.authors.slice(0, 3), year: a.year, venue: a.venue, title_similarity: a.match.title_similarity })), notes: r.notes };231 return { ...base, status: "not_found", notes: r.notes };232 } catch (e) {233 return { ...base, status: "error", error: { code: e.code ?? "error", message: String(e.message ?? e).slice(0, 300) }, notes: ["The lookup failed; this says nothing about the reference. Run it again."] };234 }235 }236237 function loadEntries({ bibtex, path: file, references } = {}) {238 const given = [bibtex, file, references].filter((x) => x != null && x !== "" && !(Array.isArray(x) && !x.length)).length;239 if (given !== 1) throw invalid("Give exactly one of: bibtex (text), path (a .bib/.txt/.md file) or references (array).");240 let text = bibtex, ext = ".bib", source = "inline";241 if (file) { const f = readInputFile(file); text = f.text; ext = f.ext; source = f.file; }242 if (references) return { source, parse_errors: [], entries: references.map((r, i) => (typeof r === "string" ? { key: `ref${i + 1}`, raw: r.trim(), ...parseReference(r) } : { key: r.key ?? `ref${i + 1}`, ...r, doi: r.doi ? normalizeDoi(r.doi) ?? r.doi : null, authors: (r.authors ?? []).map((a) => (typeof a === "string" ? { name: a } : a)) })) };243 if (ext === ".bib" || ext === ".bibtex" || /^\s*(%.*\n\s*)*@\w+\s*[{(]/.test(text)) { const p = parseBibtex(text); return { source, parse_errors: p.errors, entries: p.entries.map(({ raw_fields, ...e }) => e) }; }244 const blocks = /\n\s*\n/.test(text.trim()) ? text.split(/\n\s*\n/) : text.split("\n");245 const refs = blocks.map((b) => b.replace(/\s+/g, " ").trim()).filter((b) => b.length >= 20 && !/^#/.test(b));246 return { source, parse_errors: [], entries: refs.map((r, i) => ({ key: `ref${i + 1}`, raw: r, ...parseReference(r) })) };247 }248249 async function verifyBibliography(input = {}) {250 const { entries, parse_errors, source } = loadEntries(input);251 const max = Math.min(Math.max(1, input.max_entries ?? 300), 1000);252 const todo = input.keys?.length ? entries.filter((e) => input.keys.includes(e.key)) : entries;253 const slice = todo.slice(input.offset ?? 0, (input.offset ?? 0) + max);254 const results = await mapLimit(slice, Math.min(Math.max(1, input.concurrency ?? 4), 8), verifyEntry);255 const counts = {};256 for (const r of results) counts[r.status] = (counts[r.status] ?? 0) + 1;257 const byDoi = new Map();258 for (const r of results) { const d = r.suggested_doi ?? r.doi; if (d) byDoi.set(d, [...(byDoi.get(d) ?? []), r.key]); }259 const duplicates = [...byDoi].filter(([, k]) => k.length > 1).map(([doi, keys]) => ({ doi, keys }));260 const attention = results.filter((r) => !["verified", "doi_missing_found"].includes(r.status)).map((r) => r.key);261 return { source, entries_total: entries.length, entries_checked: slice.length, ...(todo.length > slice.length + (input.offset ?? 0) ? { truncated: true, next_offset: (input.offset ?? 0) + slice.length } : {}), summary: counts, needs_attention: attention, duplicates, parse_errors, results: input.only_problems ? results.filter((r) => r.status !== "verified") : results };262 }263264 async function checkRetractions({ dois, use_openalex = true } = {}) {265 if (!Array.isArray(dois) || !dois.length) throw invalid("dois must be a non-empty array.");266 if (dois.length > 200) throw invalid("At most 200 DOIs per call.");267 const results = await mapLimit(dois, 4, async (raw) => {268 const doi = normalizeDoi(String(raw));269 if (!doi) return { doi: String(raw), status: "invalid_doi" };270 try {271 let work, checked = ["crossref"];272 try { work = (await src.crossrefWork(doi)).work; }273 catch (e) { if (e.code !== "not_found") throw e; checked = []; }274 let oa = null, oaError = null;275 if (use_openalex) { try { oa = await src.openalexWork(`doi:${doi}`); checked.push("openalex"); } catch (e) { if (e.code !== "not_found") oaError = e.code ?? "error"; } }276 if (!work && !oa) return { doi, status: checked.length || !oaError ? "not_found" : "error", ...(oaError ? { openalex_error: oaError } : {}) };277 const info = work ? retractionInfo(work) : { status: "no_notice", notices: [] };278 const status = oa?.is_retracted ? "retracted" : info.status;279 return { doi, status, title: (work ?? oa).title, year: (work ?? oa).year, notices: info.notices, ...(info.is_retraction_notice_for ? { is_retraction_notice_for: info.is_retraction_notice_for } : {}), ...(oa ? { openalex_is_retracted: oa.is_retracted } : {}), sources_checked: checked, ...(oaError ? { openalex_error: oaError } : {}) };280 } catch (e) { return { doi, status: "error", error: { code: e.code ?? "error", message: String(e.message).slice(0, 200) } }; }281 });282 const counts = {};283 for (const r of results) counts[r.status] = (counts[r.status] ?? 0) + 1;284 return { checked: results.length, summary: counts, flagged: results.filter((r) => ["retracted", "expression_of_concern"].includes(r.status)).map((r) => r.doi), results, note: "\"no_notice\" means neither registry lists a retraction today. Notices can lag publication by weeks; registries miss some." };285 }286287 async function openalexId(id, select = "id,doi,title,publication_year,cited_by_count") {288 const pid = parseId(id);289 const ref = pid.kind === "openalex" ? pid.value : pid.kind === "pmid" ? `pmid:${pid.value}` : `doi:${pid.kind === "arxiv" ? pid.doi ?? `10.48550/arxiv.${pid.value.toLowerCase()}` : pid.value}`;290 const raw = await src.openalexRaw(ref, select).catch((e) => { if (e.code === "not_found") throw new ScholarlyError("not_found", `OpenAlex does not index ${pid.value}; the citation graph is unavailable for it.`); throw e; });291 return { raw, w: raw.id.split("/").pop() };292 }293 const head = (raw) => ({ openalex_id: raw.id.split("/").pop(), doi: normalizeDoi(raw.doi ?? ""), title: raw.title ?? null, year: raw.publication_year ?? null, ...(raw.cited_by_count != null ? { citation_count: raw.cited_by_count } : {}) });294295 async function getCitations({ id, limit = 25, sort = "citations", from_year, page = 1 } = {}) {296 const { raw, w } = await openalexId(id);297 const n = Math.min(Math.max(1, limit), 100);298 const r = await src.openalexList({ filter: `cites:${w}${from_year ? `,publication_year:>${Number(from_year) - 1}` : ""}`, sort: sort === "date" ? "publication_date:desc" : "cited_by_count:desc", "per-page": n, page });299 return { work: head(raw), total_citing: r.total, returned: r.works.length, page, sorted_by: sort === "date" ? "date" : "citations", citing_works: r.works.map((x) => brief(x)) };300 }301302 async function worksByOpenAlexIds(ids, limit) {303 const want = ids.slice(0, limit), out = [];304 for (let i = 0; i < want.length; i += 50) out.push(...(await src.openalexList({ filter: `openalex:${want.slice(i, i + 50).join("|")}`, "per-page": 50 })).works);305 const order = new Map(want.map((x, i) => [x, i]));306 return out.sort((a, b) => (order.get(a.ids.openalex) ?? 0) - (order.get(b.ids.openalex) ?? 0));307 }308309 async function getReferences({ id, source = "auto", limit = 200 } = {}) {310 const pid = parseId(id), n = Math.min(Math.max(1, limit), 500);311 if (pid.kind === "doi" && source !== "openalex") {312 const { work, references } = await src.crossrefWork(pid.value);313 if (references.length || source === "crossref") return { work: brief(work), source: "crossref", total: references.length, returned: Math.min(n, references.length), with_doi: references.filter((r) => r.doi).length, references: references.slice(0, n), note: references.length ? "As deposited by the publisher: entries without a DOI are unparsed strings and may contain errors." : "The publisher deposited no reference list with Crossref." };314 }315 if (source === "crossref") throw invalid("Crossref reference lists need a Crossref DOI.");316 const { raw } = await openalexId(id, "id,doi,title,publication_year,referenced_works");317 const ids = (raw.referenced_works ?? []).map((u) => u.split("/").pop());318 const works = ids.length ? await worksByOpenAlexIds(ids, n) : [];319 return { work: head(raw), source: "openalex", total: ids.length, returned: works.length, references: works.map((x) => brief(x)), note: "OpenAlex lists only the references it could match to an indexed work; the true list can be longer." };320 }321322 async function relatedWorks({ id, limit = 10 } = {}) {323 const { raw } = await openalexId(id, "id,doi,title,publication_year,related_works");324 const ids = (raw.related_works ?? []).map((u) => u.split("/").pop());325 const works = ids.length ? await worksByOpenAlexIds(ids, Math.min(Math.max(1, limit), 50)) : [];326 return { work: head(raw), returned: works.length, related_works: works.map((x) => brief(x)), note: "Related works are computed by OpenAlex from shared concepts: a discovery aid, not evidence of relevance." };327 }328329 async function authorWorks({ name, orcid, openalex_id, limit = 25, sort = "citations", from_year, to_year } = {}) {330 let filter, author = null, candidates = [];331 if (openalex_id) { if (!/^A\d+$/i.test(openalex_id)) throw invalid("openalex_id must look like A1234567890."); filter = `author.id:${openalex_id.toUpperCase()}`; }332 else if (orcid) { const o = String(orcid).replace(/^https?:\/\/orcid\.org\//, ""); if (!/^\d{4}-\d{4}-\d{4}-\d{3}[\dX]$/.test(o)) throw invalid("orcid must look like 0000-0002-1825-0097."); filter = `author.orcid:${o}`; }333 else if (name && String(name).trim()) {334 candidates = await src.openalexAuthors(String(name).trim(), 5);335 if (!candidates.length) return { status: "author_not_found", author_candidates: [], works: [] };336 author = candidates[0]; filter = `author.id:${author.openalex_id}`;337 } else throw invalid("Give one of name, orcid or openalex_id.");338 if (from_year || to_year) filter += `,publication_year:${from_year ?? ""}-${to_year ?? ""}`;339 const r = await src.openalexList({ filter, sort: sort === "date" ? "publication_date:desc" : "cited_by_count:desc", "per-page": Math.min(Math.max(1, limit), 100) });340 return { status: "ok", ...(author ? { author, ambiguous: candidates.length > 1, author_candidates: candidates, ...(candidates.length > 1 ? { note: "Several authors share this name. The works below belong to the first candidate only: confirm with an ORCID or the openalex_id of the right person. OpenAlex author profiles can also merge or split people." } : {}) } : {}), total: r.total, returned: r.works.length, works: r.works.map((x) => brief(x)) };341 }342343 async function searchArxiv({ query, ids, limit = 10, sort = "relevance", offset = 0 } = {}) {344 const list = (ids ?? []).map((x) => { const n = normalizeArxivId(String(x)); if (!n) throw invalid(`"${x}" is not an arXiv id.`); return n; });345 if (!list.length && !(query && String(query).trim())) throw invalid("Give query or ids.");346 const r = await src.arxiv({ query: query ? String(query).trim() : undefined, ids: list, max: Math.min(Math.max(1, limit), 50), start: offset, sort });347 return { total: r.total, returned: r.works.length, works: r.works.map((w) => ({ ...brief(w, { abstract: true }), date: w.date, updated: w.updated, version: w.version, categories: w.categories, pdf_url: w.open_access.pdf_url, ...(w.published_doi ? { published_doi: w.published_doi } : {}), ...(w.journal_ref ? { journal_ref: w.journal_ref } : {}), ...(w.comment ? { comment: w.comment } : {}) })), note: "arXiv papers are preprints: not peer reviewed unless published_doi or journal_ref says otherwise." };348 }349350 async function getOpenAccess({ id } = {}) {351 const pid = parseId(id);352 if (pid.kind === "arxiv") { const w = await getWork(pid); return { work: brief(w), is_open_access: true, status: "green", best: { url: w.open_access.url, pdf_url: w.open_access.pdf_url, host: "arXiv", version: "submittedVersion" }, locations: [], ...(w.published_doi ? { published_doi: w.published_doi } : {}) }; }353 const { raw } = await openalexId(id, "id,doi,title,publication_year,open_access,best_oa_location,locations");354 const loc = (l) => ({ url: l.landing_page_url ?? null, pdf_url: l.pdf_url ?? null, host: l.source?.display_name ?? null, version: l.version ?? null, license: l.license ?? null });355 const open = (raw.locations ?? []).filter((l) => l.is_oa).map(loc);356 const is = !!raw.open_access?.is_oa;357 return { work: head(raw), is_open_access: is, status: raw.open_access?.oa_status ?? null, best: raw.best_oa_location ? loc(raw.best_oa_location) : null, locations: open, note: is ? "Legal open copies reported by OpenAlex. Check the version: an accepted manuscript can differ from the published text." : "No legal open copy is known. Use the reader's library access, an interlibrary loan, or write to the authors. This tool does not look for unauthorised copies." };358 }359360 async function formatCitation({ id, work, style = "apa", key, styles } = {}) {361 const list = styles?.length ? styles : [style];362 for (const s of list) if (!STYLES.includes(s)) throw invalid(`Unknown style "${s}". Use one of: ${STYLES.join(", ")}.`);363 if (!id && !work) throw invalid("Give id (looked up in the registry) or work (your own metadata).");364 const w = id ? await getWork(id) : { ...work, doi: work.doi ? normalizeDoi(work.doi) : null, authors: (work.authors ?? []).map((a) => (typeof a === "string" ? { name: a } : a)) };365 const citations = Object.fromEntries(list.map((s) => [s, formatWork(w, s, { key })]));366 return { ...(list.length === 1 ? { style: list[0], citation: citations[list[0]] } : { citations }), metadata_source: id ? w.source : "caller", work: brief(w), notes: [id ? "Built from registry metadata as registered: titles are not re-cased, journal names are not abbreviated, italics are not marked." : "Built from metadata you supplied: nothing was verified.", ...(w.is_retracted ? ["This work is retracted."] : [])] };367 }368369 async function bibtexFromDoi({ doi, source = "registry", key } = {}) {370 const d = normalizeDoi(doi ?? "");371 if (!d) throw invalid("A valid DOI is required.");372 if (source === "registry") {373 try { return { doi: d, source: "registry", bibtex: await src.doiBibtex(d), note: "As returned by the DOI registration agency (content negotiation). Check capitalisation and the citation key before use." }; }374 catch (e) { if (e.code === "not_found") throw e; const w = await getWork(d); return { doi: d, source: "generated", bibtex: formatWork(w, "bibtex", { key }), note: `The registry did not return BibTeX (${e.code ?? "error"}); this entry was generated from its metadata.` }; }375 }376 const w = await getWork(d);377 return { doi: d, source: "generated", bibtex: formatWork(w, "bibtex", { key }), ...(w.is_retracted ? { warning: "This work is retracted." } : {}) };378 }379380 function parseBibtexInput({ bibtex, path: file } = {}) {381 if ((bibtex == null) === (file == null)) throw invalid("Give exactly one of bibtex or path.");382 const p = parseBibtex(file ? readInputFile(file).text : bibtex);383 const seen = new Map();384 for (const e of p.entries) seen.set(e.key, (seen.get(e.key) ?? 0) + 1);385 return { entries_total: p.entries.length, with_doi: p.entries.filter((e) => e.doi).length, without_doi: p.entries.filter((e) => !e.doi).map((e) => e.key), duplicate_keys: [...seen].filter(([, n]) => n > 1).map(([k]) => k), parse_errors: p.errors, entries: p.entries.map(({ raw_fields, ...e }) => ({ ...e, authors: e.authors.map((a) => a.name), fields: Object.keys(raw_fields) })) };386 }387388 const status = () => ({389 engine_version: ENGINE_VERSION, user_agent: USER_AGENT, file_root: root,390 config: { mailto_sent: src.config.mailto_set, openalex_api_key_set: src.config.openalex_key_set, timeout_ms: timeoutMs },391 sources: { crossref: "search, DOI metadata, reference lists, retraction and correction notices", openalex: "citing works, related works, author works, open-access locations, retraction flag", arxiv: "preprint search and lookup", "doi.org": "DOIs of every agency (DataCite included), registry BibTeX" },392 http: { requests: http.stats.requests, cache_hits: http.stats.cache_hits, retries: http.stats.retries, by_host: http.stats.by_host, cache_entries: http.cacheSize() },393 openalex_budget: http.stats.openalex_budget ?? "unknown until the first OpenAlex call",394 notes: [src.config.openalex_key_set ? "OpenAlex calls use the operator's API key." : "No OPENALEX_API_KEY: OpenAlex allows a small daily budget shared by everyone on this IP address (about 100 list calls). Tools that use only Crossref, arXiv and doi.org are unaffected.", src.config.mailto_set ? "A contact address set by the operator (SCHOLARLY_MAILTO) is sent to Crossref and OpenAlex." : "No contact address is sent to any service."],395 });396397 return { http, root, readInputFile, loadEntries, getWork, searchWorks, verifyDoi, resolveReference, verifyEntry, verifyBibliography, checkRetractions, getCitations, getReferences, relatedWorks, authorWorks, searchArxiv, getOpenAccess, formatCitation, bibtexFromDoi, parseBibtexInput, status };398}399