SPB Git

Repository Public Research preview

index.mjs 35.6 KB 399 lines javascript

1/**2 * =============================================================================3 *                  SP BOUCHER | SOFTWARE & RESEARCH4 *             ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING5 * =============================================================================6 *7 * Project          : LLM API toolkits8 * File             : scholarly/mcp/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
Files main
Menu

Theme