refaudit 0.1.0__py3-none-any.whl

refaudit/__init__.py

@@ -0,0 +1,39 @@
+"""refaudit -- verify bibliography entries against external indexes.
+
+Built for the case where a venue runs an automated check for hallucinated or
+malformed references and a false entry costs you a desk reject.
+
+    from refaudit import Checker, parse_file, default_resolvers
+
+    entries = parse_file("refs.bib")
+    checker = Checker(default_resolvers("you@example.org"))
+    for result in checker.check_all(entries):
+        print(result.key, result.verdict.value)
+"""
+
+from .bibtex import cited_keys, find_tex, parse_file, parse_string
+from .cache import Cache
+from .checker import Checker, Thresholds
+from .models import CheckResult, Entry, Found, NotFound, Record, Unavailable, Verdict
+from .resolvers import default_resolvers
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Cache",
+    "CheckResult",
+    "Checker",
+    "Entry",
+    "Found",
+    "NotFound",
+    "Record",
+    "Thresholds",
+    "Unavailable",
+    "Verdict",
+    "__version__",
+    "cited_keys",
+    "default_resolvers",
+    "find_tex",
+    "parse_file",
+    "parse_string",
+]

refaudit/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

refaudit/bibtex.py

@@ -0,0 +1,133 @@
+"""A small BibTeX reader.
+
+Only what a checker needs: entry type, cite key, and fields as raw strings. It
+does not expand ``@string`` macros or resolve crossrefs, because a checker that
+silently mis-parses is worse than one that reports what it saw.
+
+Brace matching is done by walking the source rather than with a regular
+expression, since BibTeX values nest braces freely (``title = {The {LLM} Era}``)
+and a regex will either stop early or run away.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .models import Entry
+
+_ENTRY_START = re.compile(r"@(?P<type>\w+)\s*[{(]\s*(?P<key>[^,\s{}]+)\s*,", re.MULTILINE)
+_FIELD = re.compile(r"(\w+)\s*=\s*", re.MULTILINE)
+
+# Entry types that are not published records and have no external index.
+NON_ARCHIVAL_TYPES = frozenset({"misc", "online", "manual", "unpublished", "software"})
+
+
+def _match_brace(src: str, open_idx: int) -> int:
+    """Index of the brace closing the one at ``open_idx``; ``len(src)`` if unbalanced."""
+    depth = 0
+    i = open_idx
+    n = len(src)
+    while i < n:
+        c = src[i]
+        if c == "\\":          # skip escaped char
+            i += 2
+            continue
+        if c == "{":
+            depth += 1
+        elif c == "}":
+            depth -= 1
+            if depth == 0:
+                return i
+        i += 1
+    return n
+
+
+def _read_value(src: str, i: int) -> tuple[str, int]:
+    """Read a field value starting at ``i``; returns (value, index after it)."""
+    n = len(src)
+    while i < n and src[i].isspace():
+        i += 1
+    if i >= n:
+        return "", i
+    if src[i] == "{":
+        end = _match_brace(src, i)
+        return src[i + 1:end], min(end + 1, n)
+    if src[i] == '"':
+        j = i + 1
+        while j < n:
+            if src[j] == "\\":
+                j += 2
+                continue
+            if src[j] == '"':
+                break
+            j += 1
+        return src[i + 1:j], min(j + 1, n)
+    # bare value (number, macro name) up to the next comma or closing brace
+    j = i
+    while j < n and src[j] not in ",}\n":
+        j += 1
+    return src[i:j].strip(), j
+
+
+def _clean(value: str) -> str:
+    return re.sub(r"\s+", " ", value).strip()
+
+
+def parse_string(src: str) -> list[Entry]:
+    entries: list[Entry] = []
+    for m in _ENTRY_START.finditer(src):
+        etype = m.group("type").lower()
+        if etype in {"comment", "preamble", "string"}:
+            continue
+        body_start = src.index("{", m.start()) if "{" in src[m.start():m.end()] else m.end()
+        body_end = _match_brace(src, body_start)
+        body = src[m.end():body_end]
+
+        fields: dict[str, str] = {}
+        i = 0
+        while True:
+            fm = _FIELD.search(body, i)
+            if not fm:
+                break
+            value, i = _read_value(body, fm.end())
+            fields[fm.group(1).lower()] = _clean(value)
+        entries.append(Entry(key=m.group("key").strip(), entry_type=etype, fields=fields))
+    return entries
+
+
+def parse_file(path: str | Path) -> list[Entry]:
+    return parse_string(Path(path).read_text(encoding="utf-8", errors="replace"))
+
+
+_CITE = re.compile(r"\\[a-zA-Z]*cite[a-zA-Z]*\*?\s*(?:\[[^\]]*\]\s*)*\{([^}]*)\}")
+
+
+def cited_keys(tex_paths: list[Path]) -> set[str]:
+    """Cite keys appearing in live (non-commented) LaTeX.
+
+    Uncited entries never reach the reference list, so checking them is optional
+    work; separating them also keeps the report focused on what a reviewer sees.
+    """
+    keys: set[str] = set()
+    for path in tex_paths:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for line in text.splitlines():
+            stripped = line.lstrip()
+            if stripped.startswith("%"):
+                continue
+            # drop trailing comments, honouring \%
+            line = re.sub(r"(?<!\\)%.*$", "", line)
+            for m in _CITE.finditer(line):
+                keys.update(k.strip() for k in m.group(1).split(",") if k.strip())
+    return keys
+
+
+def find_tex(root: str | Path) -> list[Path]:
+    root = Path(root)
+    if root.is_file():
+        return [root]
+    return sorted(p for p in root.rglob("*.tex") if p.is_file())

refaudit/cache.py

@@ -0,0 +1,86 @@
+"""Versioned, on-disk cache of resolver results.
+
+A run over a few hundred references takes minutes because it is deliberately
+slow, so it must be resumable. Three properties matter:
+
+* **Versioned.** The cache key includes a schema version; changing how records
+  are interpreted invalidates old entries instead of silently mixing them.
+* **Only successes are cached.** A failure usually means a service was busy, and
+  caching that would bake a transient outage into every later run.
+* **Written atomically.** A run interrupted mid-write must not leave a truncated
+  JSON file that breaks the next run.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION = 2
+
+
+class Cache:
+    def __init__(self, path: str | Path, ttl_days: float = 90.0) -> None:
+        self.path = Path(path)
+        self.ttl = ttl_days * 86400.0
+        self._data: dict[str, dict[str, Any]] = {}
+        self._dirty = False
+        self._load()
+
+    def _load(self) -> None:
+        if not self.path.exists():
+            return
+        try:
+            blob = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return  # corrupt or unreadable: start clean rather than crash
+        if blob.get("schema") != SCHEMA_VERSION:
+            return
+        self._data = blob.get("entries", {})
+
+    def get(self, key: str) -> dict[str, Any] | None:
+        item = self._data.get(key)
+        if not item:
+            return None
+        if self.ttl and time.time() - item.get("stored_at", 0) > self.ttl:
+            self._data.pop(key, None)
+            self._dirty = True
+            return None
+        return item.get("value")
+
+    def put(self, key: str, value: dict[str, Any]) -> None:
+        self._data[key] = {"stored_at": time.time(), "value": value}
+        self._dirty = True
+
+    def flush(self) -> None:
+        if not self._dirty:
+            return
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(
+            {"schema": SCHEMA_VERSION, "entries": self._data}, ensure_ascii=False
+        )
+        fd, tmp = tempfile.mkstemp(dir=str(self.path.parent), suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(payload)
+                fh.flush()
+                os.fsync(fh.fileno())
+            os.replace(tmp, self.path)      # atomic on POSIX and Windows
+            self._dirty = False
+        finally:
+            if os.path.exists(tmp):
+                try:
+                    os.unlink(tmp)
+                except OSError:
+                    pass
+
+    # PYI034 prefers Self, which is 3.11+; this package supports 3.10.
+    def __enter__(self) -> Cache:  # noqa: PYI034
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.flush()

refaudit/checker.py

@@ -0,0 +1,205 @@
+"""Orchestration: try resolvers in order, then judge the match.
+
+Two rules govern the whole design.
+
+**A resolver that could not be reached produces no verdict.** If every resolver
+that applies to an entry came back ``Unavailable``, the result is ``UNVERIFIED``
+and the report says so separately from real findings. This is what stops the
+tool crying wolf when a service is rate-limiting the network.
+
+**Identifier evidence outranks title evidence.** A DOI that Crossref says does
+not exist is a finding. A title search that returns something different is only
+a finding if we had no identifier to go on -- otherwise it is just a weak search
+result, and treating it as a mismatch would flag every arXiv-only workshop paper
+that Crossref happens not to index.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+
+from .bibtex import NON_ARCHIVAL_TYPES
+from .cache import Cache
+from .models import (
+    CheckResult,
+    Entry,
+    Found,
+    NotFound,
+    Record,
+    Unavailable,
+    Verdict,
+)
+from .normalize import clean_arxiv_id, clean_doi, first_surname, similarity, surnames_match
+from .resolvers.base import Resolver
+
+
+@dataclass(frozen=True)
+class Thresholds:
+    title_match: float = 0.75      # at or above this, the titles are the same work
+    title_suspect: float = 0.45    # below this, a resolved record is clearly a different paper
+    year_slack: int = 1            # preprint/publication years legitimately differ by one
+
+
+DEFAULT_THRESHOLDS = Thresholds()
+
+
+class Checker:
+    def __init__(
+        self,
+        resolvers: Sequence[Resolver],
+        *,
+        cache: Cache | None = None,
+        thresholds: Thresholds = DEFAULT_THRESHOLDS,
+    ) -> None:
+        if not resolvers:
+            raise ValueError("at least one resolver is required")
+        self.resolvers = list(resolvers)
+        self.cache = cache
+        self.thresholds = thresholds
+
+    # -- public ------------------------------------------------------------
+
+    def check(self, entry: Entry, *, cited: bool | None = None) -> CheckResult:
+        cached = self.cache.get(self._cache_key(entry)) if self.cache else None
+        if cached:
+            return CheckResult(
+                key=entry.key,
+                verdict=Verdict(cached["verdict"]),
+                entry_title=entry.title,
+                found_title=cached.get("found_title", ""),
+                source=cached.get("source", ""),
+                similarity=cached.get("similarity"),
+                note=cached.get("note", ""),
+                cited=cited,
+            )
+
+        result = self._check_uncached(entry, cited)
+
+        # Only cache outcomes that reflect the entry, not our connectivity.
+        if self.cache and result.verdict is not Verdict.UNVERIFIED:
+            self.cache.put(
+                self._cache_key(entry),
+                {
+                    "verdict": result.verdict.value,
+                    "found_title": result.found_title,
+                    "source": result.source,
+                    "similarity": result.similarity,
+                    "note": result.note,
+                },
+            )
+        return result
+
+    def check_all(self, entries: Iterable[Entry], cited: set[str] | None = None):
+        for entry in entries:
+            yield self.check(entry, cited=(entry.key in cited) if cited is not None else None)
+
+    # -- internals ---------------------------------------------------------
+
+    @staticmethod
+    def _cache_key(entry: Entry) -> str:
+        # Include the fields we compare, so editing an entry re-checks it.
+        return "|".join([
+            entry.key,
+            clean_doi(entry.doi),
+            clean_arxiv_id(entry.arxiv_id),
+            entry.title.strip().lower()[:200],
+            str(entry.year or ""),
+        ])
+
+    def _check_uncached(self, entry: Entry, cited: bool | None) -> CheckResult:
+        applicable = [r for r in self.resolvers if r.can_handle(entry)]
+
+        has_identifier = bool(clean_doi(entry.doi) or clean_arxiv_id(entry.arxiv_id))
+        if not applicable:
+            if entry.entry_type in NON_ARCHIVAL_TYPES and not has_identifier:
+                return CheckResult(entry.key, Verdict.SKIPPED, entry.title,
+                                   note=f"@{entry.entry_type} with no identifier", cited=cited)
+            return CheckResult(entry.key, Verdict.NOT_FOUND, entry.title,
+                               note="no resolver could handle this entry", cited=cited)
+
+        any_unavailable: list[str] = []
+        authoritative_absence: list[str] = []
+
+        for resolver in applicable:
+            outcome = resolver.resolve(entry)
+
+            if isinstance(outcome, Unavailable):
+                any_unavailable.append(f"{outcome.source}: {outcome.reason[:60]}")
+                continue
+
+            if isinstance(outcome, NotFound):
+                # A DOI the registrar does not know is a real problem. A failed
+                # title search is not, on its own.
+                if resolver.name.endswith(":doi") and clean_doi(entry.doi):
+                    return CheckResult(entry.key, Verdict.DEAD_DOI, entry.title,
+                                       source=resolver.name,
+                                       note=f"DOI {clean_doi(entry.doi)} not registered",
+                                       cited=cited)
+                authoritative_absence.append(f"{outcome.source}: {outcome.detail[:50]}")
+                continue
+
+            if isinstance(outcome, Found):
+                return self._judge(entry, outcome.record, resolver, has_identifier, cited)
+
+        if any_unavailable and not authoritative_absence:
+            return CheckResult(entry.key, Verdict.UNVERIFIED, entry.title,
+                               note="; ".join(any_unavailable)[:160], cited=cited)
+        if entry.entry_type in NON_ARCHIVAL_TYPES and not has_identifier:
+            return CheckResult(entry.key, Verdict.SKIPPED, entry.title,
+                               note=f"@{entry.entry_type} not indexed", cited=cited)
+        note = "; ".join(authoritative_absence + any_unavailable)[:160]
+        return CheckResult(entry.key, Verdict.NOT_FOUND, entry.title, note=note, cited=cited)
+
+    def _judge(
+        self,
+        entry: Entry,
+        record: Record,
+        resolver: Resolver,
+        has_identifier: bool,
+        cited: bool | None,
+    ) -> CheckResult:
+        score = similarity(entry.title, record.title)
+
+        def result(verdict: Verdict, note: str = "") -> CheckResult:
+            # Built explicitly rather than by unpacking a dict: the shared
+            # fields are identical for every branch, but keyword unpacking
+            # erases their types and hides genuine mistakes from the checker.
+            return CheckResult(
+                key=entry.key,
+                verdict=verdict,
+                entry_title=entry.title,
+                found_title=record.title,
+                source=resolver.name,
+                similarity=score,
+                note=note,
+                cited=cited,
+            )
+
+        if score < self.thresholds.title_match:
+            resolved_by_identifier = resolver.name.endswith(":doi") or "arxiv" in resolver.name
+            if resolved_by_identifier:
+                # The identifier points at a different paper. This is the
+                # signature of a fabricated or mis-copied citation.
+                return result(Verdict.TITLE_MISMATCH,
+                              "identifier resolves to a different title")
+            if score < self.thresholds.title_suspect:
+                # A dataset or web resource with no identifier was never going
+                # to be in a citation index; a stray title hit is not a finding.
+                if entry.entry_type in NON_ARCHIVAL_TYPES and not has_identifier:
+                    return result(Verdict.SKIPPED,
+                                  f"@{entry.entry_type} with no identifier; not indexed")
+                return result(Verdict.NOT_FOUND, "no close title match found")
+            return result(Verdict.UNVERIFIED,
+                          "only a weak title match; no identifier to confirm")
+
+        want = first_surname(entry.get("author"))
+        if (want and record.first_author_surname
+                and not surnames_match(want, first_surname(record.first_author_surname))):
+            return result(Verdict.AUTHOR_MISMATCH,
+                          f"bib={want} vs {record.first_author_surname.lower()}")
+
+        if entry.year and record.year and abs(entry.year - record.year) > self.thresholds.year_slack:
+            return result(Verdict.YEAR_MISMATCH, f"bib={entry.year} vs {record.year}")
+
+        return result(Verdict.OK)

refaudit/cli.py

@@ -0,0 +1,167 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .bibtex import cited_keys, find_tex, parse_file
+from .cache import Cache
+from .checker import Checker, Thresholds
+from .models import Verdict
+from .resolvers import AVAILABLE, default_resolvers
+
+EPILOG = """\
+examples:
+  refaudit refs.bib --email you@uni.edu
+  refaudit refs.bib --email you@uni.edu --tex paper/sections --only-cited
+  refaudit refs.bib --email you@uni.edu --resolvers crossref:doi,openalex
+
+exit status:
+  0  no findings
+  1  at least one entry needs a human look
+  2  usage or input error
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="refaudit",
+        description="Verify .bib entries against Crossref, arXiv and OpenAlex.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("bib", type=Path, help="path to the .bib file")
+    p.add_argument("--email", default=os.environ.get("REFAUDIT_EMAIL", ""),
+                   help="contact address sent to the APIs (or set REFAUDIT_EMAIL). "
+                        "Crossref and OpenAlex give identified callers a better pool.")
+    p.add_argument("--tex", type=Path,
+                   help="directory or file of LaTeX sources, to determine which keys are cited")
+    p.add_argument("--only-cited", action="store_true",
+                   help="check only keys cited in --tex (uncited entries never reach the PDF)")
+    p.add_argument("--resolvers", default="",
+                   help=f"comma-separated subset of: {', '.join(AVAILABLE)}")
+    p.add_argument("--out", type=Path, default=Path("refaudit-out"),
+                   help="output directory (default: refaudit-out)")
+    p.add_argument("--cache", type=Path, help="cache file (default: <out>/cache.json)")
+    p.add_argument("--no-cache", action="store_true", help="ignore and do not write the cache")
+    p.add_argument("--ttl-days", type=float, default=90.0, help="cache lifetime (default: 90)")
+    p.add_argument("--timeout", type=float, default=20.0, help="per-request timeout seconds")
+    p.add_argument("--title-match", type=float, default=Thresholds.title_match,
+                   help="similarity at or above which two titles are the same work")
+    p.add_argument("--quiet", action="store_true", help="only print the summary")
+    p.add_argument("--version", action="version", version=f"refaudit {__version__}")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if not args.bib.is_file():
+        print(f"error: no such file: {args.bib}", file=sys.stderr)
+        return 2
+    if not args.email:
+        print("error: --email is required (or set REFAUDIT_EMAIL).\n"
+              "       Crossref and OpenAlex ask callers to identify themselves, and\n"
+              "       doing so puts you in a more reliable request pool.", file=sys.stderr)
+        return 2
+    if args.only_cited and not args.tex:
+        print("error: --only-cited requires --tex", file=sys.stderr)
+        return 2
+
+    entries = parse_file(args.bib)
+    if not entries:
+        print(f"error: no entries parsed from {args.bib}", file=sys.stderr)
+        return 2
+
+    cited: set[str] | None = None
+    if args.tex:
+        cited = cited_keys(find_tex(args.tex))
+        if args.only_cited:
+            entries = [e for e in entries if e.key in cited]
+            if not entries:
+                print("error: no cited entries found; is --tex pointing at the right place?",
+                      file=sys.stderr)
+                return 2
+
+    only = [r.strip() for r in args.resolvers.split(",") if r.strip()] or None
+    try:
+        resolvers = default_resolvers(args.email, only=only, timeout=args.timeout)
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    args.out.mkdir(parents=True, exist_ok=True)
+    cache = None if args.no_cache else Cache(args.cache or (args.out / "cache.json"),
+                                             ttl_days=args.ttl_days)
+    checker = Checker(resolvers, cache=cache,
+                      thresholds=Thresholds(title_match=args.title_match))
+
+    results = []
+    try:
+        for i, result in enumerate(checker.check_all(entries, cited=cited), 1):
+            results.append(result)
+            if not args.quiet:
+                print(f"[{i}/{len(entries)}] {result.verdict.value:<15} {result.key}", flush=True)
+            if cache and i % 10 == 0:
+                cache.flush()
+    except KeyboardInterrupt:
+        print("\ninterrupted; partial results kept", file=sys.stderr)
+    finally:
+        if cache:
+            cache.flush()
+
+    return _report(results, args.out, bool(args.only_cited))
+
+
+def _report(results, out: Path, only_cited: bool) -> int:
+    order = list(Verdict)
+    results.sort(key=lambda r: (order.index(r.verdict), r.key.lower()))
+
+    csv_path = out / "reference_check.csv"
+    with csv_path.open("w", newline="", encoding="utf-8") as fh:
+        rows = [r.as_row() for r in results]
+        writer = csv.DictWriter(fh, fieldnames=list(rows[0].keys()))
+        writer.writeheader()
+        writer.writerows(rows)
+
+    counts: dict[str, int] = {}
+    for r in results:
+        counts[r.verdict.value] = counts.get(r.verdict.value, 0) + 1
+
+    findings = [r for r in results if r.verdict.is_finding]
+    unverified = [r for r in results if r.verdict is Verdict.UNVERIFIED]
+
+    lines = ["refaudit", "=" * 72,
+             f"entries checked : {len(results)}" + ("  (cited only)" if only_cited else ""),
+             "counts          : " + ", ".join(f"{k}={v}" for k, v in sorted(counts.items())), ""]
+
+    if unverified:
+        lines += [f"{len(unverified)} entries could not be checked (a source was unreachable).",
+                  "These are not findings. Re-run later or from another network.", ""]
+
+    if findings:
+        lines.append(f"--- {len(findings)} entries need a human look, worst first")
+        for r in findings:
+            lines.append(f"  {r.verdict.value:<15} {r.key}")
+            lines.append(f"      bib   : {r.entry_title[:110]}")
+            if r.found_title:
+                lines.append(f"      found : {r.found_title[:110]}  [{r.source}]")
+            if r.note:
+                lines.append(f"      why   : {r.note}")
+    else:
+        lines.append("No findings.")
+
+    text = "\n".join(lines)
+    (out / "reference_check.txt").write_text(text + "\n", encoding="utf-8")
+    print("\n" + text)
+    print(f"\nwritten to {out}/")
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())