citegate 0.1.0__py3-none-any.whl

citegate/__init__.py

@@ -0,0 +1,3 @@
+"""citegate: citation integrity as a CI gate."""
+
+__version__ = "0.1.0"

citegate/cli.py

@@ -0,0 +1,144 @@
+"""citegate command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import os
+import sys
+from pathlib import Path
+from typing import List
+
+from . import __version__
+from .core import (
+    Entry,
+    Result,
+    ResultCache,
+    Verdict,
+    entry_cache_key,
+    parse_bib_file,
+    result_from_dict,
+    verify_entry,
+)
+from .report import github_annotations, github_step_summary, print_console, write_json
+from .sources import make_clients
+
+FAIL_CHOICES = {
+    "not-found": Verdict.NOT_FOUND,
+    "retracted": Verdict.RETRACTED,
+    "mismatch": Verdict.MISMATCH,
+    "error": Verdict.ERROR,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="citegate",
+        description=(
+            "Verify BibTeX references against Crossref and OpenAlex: catch fabricated "
+            "citations, metadata errors, and retracted papers — and fail CI when they appear."
+        ),
+    )
+    parser.add_argument("files", nargs="+", help=".bib files or globs to check")
+    parser.add_argument(
+        "--fail-on",
+        default="not-found,retracted",
+        help="comma-separated verdicts that fail the run "
+        "(choices: not-found, retracted, mismatch, error; default: not-found,retracted)",
+    )
+    parser.add_argument(
+        "--mailto",
+        default=os.environ.get("CITEGATE_MAILTO", ""),
+        help="contact email sent to the APIs (enables the Crossref polite pool); "
+        "also read from CITEGATE_MAILTO",
+    )
+    parser.add_argument("--json", metavar="PATH", help="write a JSON report to PATH ('-' for stdout)")
+    parser.add_argument(
+        "--cache",
+        metavar="PATH",
+        nargs="?",
+        const=".citegate-cache.json",
+        help="cache results in a JSON file so repeated runs skip unchanged entries "
+        "(default path: .citegate-cache.json)",
+    )
+    parser.add_argument("--quiet", action="store_true", help="only print entries with problems")
+    parser.add_argument("--version", action="version", version=f"citegate {__version__}")
+    return parser
+
+
+def collect_files(patterns: List[str]) -> List[Path]:
+    paths: List[Path] = []
+    for pattern in patterns:
+        matches = sorted(glob.glob(pattern, recursive=True))
+        if matches:
+            paths.extend(Path(m) for m in matches)
+        elif Path(pattern).exists():
+            paths.append(Path(pattern))
+        else:
+            print(f"citegate: no files match '{pattern}'", file=sys.stderr)
+    seen = set()
+    unique = []
+    for p in paths:
+        if p not in seen:
+            seen.add(p)
+            unique.append(p)
+    return unique
+
+
+def main(argv: List[str] = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    failing = set()
+    for name in args.fail_on.split(","):
+        name = name.strip().lower()
+        if not name:
+            continue
+        if name not in FAIL_CHOICES:
+            print(f"citegate: unknown --fail-on value '{name}'", file=sys.stderr)
+            return 2
+        failing.add(FAIL_CHOICES[name])
+
+    files = collect_files(args.files)
+    if not files:
+        print("citegate: no .bib files to check", file=sys.stderr)
+        return 2
+
+    entries: List[Entry] = []
+    for path in files:
+        try:
+            entries.extend(parse_bib_file(path))
+        except Exception as exc:  # bibtexparser raises plain Exceptions on bad input
+            print(f"citegate: could not parse {path}: {exc}", file=sys.stderr)
+            return 2
+
+    cache = ResultCache(Path(args.cache)) if args.cache else None
+    crossref, openalex = make_clients(mailto=args.mailto or None)
+
+    results: List[Result] = []
+    for entry in entries:
+        cached = cache.get(entry_cache_key(entry)) if cache else None
+        if cached is not None:
+            result = result_from_dict(cached)
+            result.file = entry.file
+        else:
+            result = verify_entry(entry, crossref, openalex)
+            if cache and result.verdict is not Verdict.ERROR:
+                cache.put(entry_cache_key(entry), result)
+        results.append(result)
+
+    if cache:
+        cache.save()
+
+    print_console(results, quiet=args.quiet)
+    github_annotations(results, failing)
+    github_step_summary(results)
+    if args.json:
+        write_json(results, args.json)
+
+    if any(r.verdict in failing for r in results):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

citegate/core.py

@@ -0,0 +1,388 @@
+"""Entry parsing, matching logic, and verdicts."""
+
+from __future__ import annotations
+
+import enum
+import hashlib
+import json
+import re
+import time
+import unicodedata
+from dataclasses import dataclass, field, asdict
+from difflib import SequenceMatcher
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import bibtexparser
+from bibtexparser.bparser import BibTexParser
+
+from .sources import (
+    CONCERN_UPDATE_TYPES,
+    RETRACTION_UPDATE_TYPES,
+    CandidateRecord,
+    Crossref,
+    OpenAlex,
+    SourceError,
+)
+
+# Entry types that generally cannot be verified against scholarly indexes
+# unless they carry a DOI (websites, standards, lecture notes, ...).
+UNVERIFIABLE_TYPES = {
+    "misc",
+    "online",
+    "electronic",
+    "www",
+    "manual",
+    "unpublished",
+    "software",
+    "dataset",
+    "standard",
+    "techreport",
+    "patent",
+}
+
+STRONG_MATCH = 0.93
+WEAK_MATCH = 0.75
+DOI_TITLE_MATCH = 0.80
+
+
+class Verdict(str, enum.Enum):
+    VERIFIED = "verified"
+    RETRACTED = "retracted"
+    NOT_FOUND = "not-found"
+    MISMATCH = "mismatch"
+    UNVERIFIABLE = "unverifiable"
+    ERROR = "error"
+
+
+@dataclass
+class Entry:
+    key: str
+    entry_type: str
+    title: str = ""
+    authors: List[str] = field(default_factory=list)
+    year: Optional[int] = None
+    doi: Optional[str] = None
+    venue: str = ""
+    file: str = ""
+
+
+@dataclass
+class Result:
+    key: str
+    file: str
+    verdict: Verdict
+    problems: List[str] = field(default_factory=list)
+    similarity: Optional[float] = None
+    matched_doi: Optional[str] = None
+    matched_title: Optional[str] = None
+    source: Optional[str] = None
+    suggestion: Optional[str] = None
+
+    def to_dict(self) -> Dict:
+        d = asdict(self)
+        d["verdict"] = self.verdict.value
+        return d
+
+
+_LATEX_CMD = re.compile(r"\\[a-zA-Z]+\s*")
+_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+
+
+def normalize(text: str) -> str:
+    """Normalize a title for comparison: strip LaTeX markup, accents, case, punctuation."""
+    text = re.sub(r"\\['\"^`~=.]", "", text)  # accent commands: \'e -> e
+    text = _LATEX_CMD.sub(" ", text)  # commands before brace stripping, so \emph{X} keeps X
+    text = text.replace("{", "").replace("}", "").replace("~", " ")
+    text = unicodedata.normalize("NFKD", text)
+    text = "".join(c for c in text if not unicodedata.combining(c))
+    return _NON_ALNUM.sub(" ", text.lower()).strip()
+
+
+def title_similarity(a: str, b: str) -> float:
+    na, nb = normalize(a), normalize(b)
+    if not na or not nb:
+        return 0.0
+    # A record title that merely extends the entry title (or vice versa, e.g.
+    # missing subtitle) should still count as a near-match.
+    if na == nb or na.startswith(nb) or nb.startswith(na):
+        return 1.0
+    return SequenceMatcher(None, na, nb).ratio()
+
+
+def parse_families(author_field: str) -> List[str]:
+    """Extract family names from a BibTeX author field."""
+    families = []
+    for person in re.split(r"\s+and\s+", author_field):
+        person = person.strip().strip("{}")
+        if not person or person.lower() == "others":
+            continue
+        if "," in person:
+            families.append(person.split(",")[0].strip().strip("{}"))
+        else:
+            families.append(person.split()[-1].strip("{}"))
+    return [f for f in families if f]
+
+
+def clean_doi(raw: str) -> Optional[str]:
+    doi = raw.strip().strip("{}").strip()
+    doi = re.sub(r"^(https?://)?(dx\.)?doi\.org/", "", doi, flags=re.I)
+    doi = doi.strip()
+    return doi.lower() or None
+
+
+def parse_bib_file(path: Path) -> List[Entry]:
+    parser = BibTexParser(common_strings=True)
+    parser.ignore_nonstandard_types = False
+    with open(path, encoding="utf-8") as fh:
+        db = bibtexparser.load(fh, parser=parser)
+    entries = []
+    for raw in db.entries:
+        year = None
+        raw_year = (raw.get("year") or "").strip("{} ")
+        match = re.search(r"\d{4}", raw_year)
+        if match:
+            year = int(match.group())
+        entries.append(
+            Entry(
+                key=raw.get("ID", "?"),
+                entry_type=(raw.get("ENTRYTYPE") or "misc").lower(),
+                title=(raw.get("title") or "").strip(),
+                authors=parse_families(raw.get("author", "")),
+                year=year,
+                doi=clean_doi(raw.get("doi", "")),
+                venue=(raw.get("journal") or raw.get("booktitle") or "").strip(),
+                file=str(path),
+            )
+        )
+    return entries
+
+
+def _author_overlap(entry: Entry, record: CandidateRecord) -> bool:
+    if not entry.authors or not record.families:
+        return True  # nothing to compare; do not penalize
+    entry_set = {normalize(f) for f in entry.authors}
+    record_set = {normalize(f) for f in record.families}
+    return bool(entry_set & record_set)
+
+
+def _year_close(entry: Entry, record: CandidateRecord, slack: int = 1) -> bool:
+    if entry.year is None or record.year is None:
+        return True
+    return abs(entry.year - record.year) <= slack
+
+
+def _check_retraction(doi: str, crossref: Crossref, openalex: OpenAlex) -> tuple:
+    """Return (is_retracted, notes) for a DOI, consulting both sources."""
+    notes: List[str] = []
+    retracted = False
+    try:
+        oa = openalex.get_by_doi(doi)
+        if oa is not None and oa.is_retracted:
+            retracted = True
+            notes.append("OpenAlex marks this work as retracted")
+    except SourceError:
+        notes.append("OpenAlex unreachable for retraction check")
+    try:
+        updates = crossref.retraction_updates(doi)
+    except SourceError:
+        updates = []
+        notes.append("Crossref unreachable for retraction check")
+    hits = [u for u in updates if u in RETRACTION_UPDATE_TYPES]
+    if hits:
+        retracted = True
+        notes.append(f"Crossref/Retraction Watch records: {', '.join(sorted(set(hits)))}")
+    concerns = [u for u in updates if u in CONCERN_UPDATE_TYPES]
+    if concerns and not retracted:
+        notes.append("an expression of concern has been issued for this work")
+    return retracted, notes
+
+
+def verify_entry(entry: Entry, crossref: Crossref, openalex: OpenAlex) -> Result:
+    result = Result(key=entry.key, file=entry.file, verdict=Verdict.UNVERIFIABLE)
+
+    if not entry.doi and not entry.title:
+        result.problems.append("entry has neither a title nor a DOI")
+        return result
+    if not entry.doi and entry.entry_type in UNVERIFIABLE_TYPES:
+        result.problems.append(
+            f"@{entry.entry_type} entries without a DOI are not checked against scholarly indexes"
+        )
+        return result
+
+    try:
+        if entry.doi:
+            return _verify_by_doi(entry, result, crossref, openalex)
+        return _verify_by_search(entry, result, crossref, openalex)
+    except SourceError as exc:
+        result.verdict = Verdict.ERROR
+        result.problems.append(str(exc))
+        return result
+
+
+def _verify_by_doi(entry: Entry, result: Result, crossref: Crossref, openalex: OpenAlex) -> Result:
+    record = crossref.get_by_doi(entry.doi)
+    if record is None:
+        try:
+            record = openalex.get_by_doi(entry.doi)
+        except SourceError:
+            record = None
+    if record is None:
+        result.verdict = Verdict.NOT_FOUND
+        result.problems.append(f"DOI {entry.doi} resolves in neither Crossref nor OpenAlex")
+        return result
+
+    result.matched_doi = record.doi or entry.doi
+    result.matched_title = record.title
+    result.source = record.source
+    sim = title_similarity(entry.title, record.title) if entry.title and record.title else None
+    result.similarity = sim
+
+    problems = []
+    if sim is not None and sim < DOI_TITLE_MATCH:
+        problems.append(
+            f'title does not match the DOI record (similarity {sim:.2f}): index has "{record.title}"'
+        )
+    if not _year_close(entry, record):
+        problems.append(f"year mismatch: entry says {entry.year}, index says {record.year}")
+    if not _author_overlap(entry, record):
+        problems.append(
+            "no author overlap with the DOI record "
+            f"(index authors: {', '.join(record.families[:4]) or 'unknown'})"
+        )
+
+    retracted, notes = _check_retraction(result.matched_doi, crossref, openalex)
+    result.problems.extend(notes)
+    if retracted:
+        result.verdict = Verdict.RETRACTED
+        result.problems[:0] = problems
+        return result
+
+    if problems:
+        result.verdict = Verdict.MISMATCH
+        result.problems[:0] = problems
+    else:
+        result.verdict = Verdict.VERIFIED
+    return result
+
+
+def _verify_by_search(entry: Entry, result: Result, crossref: Crossref, openalex: OpenAlex) -> Result:
+    query = entry.title
+    author = entry.authors[0] if entry.authors else None
+    candidates: List[CandidateRecord] = []
+    try:
+        candidates.extend(crossref.search(query, author=author))
+    except SourceError:
+        result.problems.append("Crossref search unavailable; relying on OpenAlex only")
+    try:
+        candidates.extend(openalex.search(query))
+    except SourceError:
+        result.problems.append("OpenAlex search unavailable; relying on Crossref only")
+    if not candidates and result.problems:
+        result.verdict = Verdict.ERROR
+        return result
+
+    best: Optional[CandidateRecord] = None
+    best_sim = 0.0
+    for cand in candidates:
+        sim = title_similarity(entry.title, cand.title)
+        if sim > best_sim:
+            best, best_sim = cand, sim
+
+    result.similarity = round(best_sim, 3)
+    if best is not None:
+        result.matched_doi = best.doi
+        result.matched_title = best.title
+        result.source = best.source
+
+    if best is None or best_sim < WEAK_MATCH:
+        result.verdict = Verdict.NOT_FOUND
+        result.problems.append(
+            "no record with a similar title in Crossref or OpenAlex — possibly a fabricated reference"
+        )
+        if best is not None and best.title:
+            result.problems.append(f'closest match (similarity {best_sim:.2f}): "{best.title}"')
+        return result
+
+    problems = []
+    if best_sim < STRONG_MATCH:
+        problems.append(
+            f'best match is only similarity {best_sim:.2f}: "{best.title}" — check the title'
+        )
+    if not _year_close(entry, best):
+        problems.append(f"year mismatch: entry says {entry.year}, index says {best.year}")
+    if not _author_overlap(entry, best):
+        problems.append(
+            f"no author overlap with the matched record ({', '.join(best.families[:4]) or 'unknown'})"
+        )
+
+    if best.doi:
+        retracted, notes = _check_retraction(best.doi, crossref, openalex)
+        result.problems.extend(notes)
+        if retracted:
+            result.verdict = Verdict.RETRACTED
+            result.problems[:0] = problems
+            return result
+
+    if problems:
+        result.verdict = Verdict.MISMATCH
+        result.problems[:0] = problems
+    else:
+        result.verdict = Verdict.VERIFIED
+        if best.doi and not entry.doi:
+            result.suggestion = f"add doi = {{{best.doi}}}"
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Cache
+
+
+def entry_cache_key(entry: Entry) -> str:
+    payload = json.dumps(
+        [entry.doi or "", normalize(entry.title), entry.year or 0, sorted(entry.authors)],
+        ensure_ascii=False,
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+class ResultCache:
+    """A small JSON file cache so repeated CI runs skip unchanged entries."""
+
+    def __init__(self, path: Path, ttl_days: float = 14.0):
+        self.path = path
+        self.ttl = ttl_days * 86400
+        self.data: Dict[str, Dict] = {}
+        if path.exists():
+            try:
+                self.data = json.loads(path.read_text(encoding="utf-8"))
+            except (ValueError, OSError):
+                self.data = {}
+
+    def get(self, key: str) -> Optional[Dict]:
+        item = self.data.get(key)
+        if not item:
+            return None
+        if time.time() - item.get("ts", 0) > self.ttl:
+            return None
+        return item.get("result")
+
+    def put(self, key: str, result: Result) -> None:
+        self.data[key] = {"ts": time.time(), "result": result.to_dict()}
+
+    def save(self) -> None:
+        self.path.write_text(json.dumps(self.data, indent=1), encoding="utf-8")
+
+
+def result_from_dict(d: Dict) -> Result:
+    return Result(
+        key=d["key"],
+        file=d.get("file", ""),
+        verdict=Verdict(d["verdict"]),
+        problems=list(d.get("problems", [])),
+        similarity=d.get("similarity"),
+        matched_doi=d.get("matched_doi"),
+        matched_title=d.get("matched_title"),
+        source=d.get("source"),
+        suggestion=d.get("suggestion"),
+    )

citegate/report.py

@@ -0,0 +1,117 @@
+"""Console, JSON, and GitHub Actions reporting."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections import Counter
+from typing import Dict, List
+
+from . import __version__
+from .core import Result, Verdict
+
+_COLORS = {
+    Verdict.VERIFIED: "\033[32m",     # green
+    Verdict.RETRACTED: "\033[31m",    # red
+    Verdict.NOT_FOUND: "\033[31m",    # red
+    Verdict.MISMATCH: "\033[33m",     # yellow
+    Verdict.UNVERIFIABLE: "\033[90m", # gray
+    Verdict.ERROR: "\033[35m",        # magenta
+}
+_RESET = "\033[0m"
+
+_LABELS = {
+    Verdict.VERIFIED: "OK        ",
+    Verdict.RETRACTED: "RETRACTED ",
+    Verdict.NOT_FOUND: "NOT FOUND ",
+    Verdict.MISMATCH: "MISMATCH  ",
+    Verdict.UNVERIFIABLE: "SKIPPED   ",
+    Verdict.ERROR: "ERROR     ",
+}
+
+
+def _use_color() -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        return True
+    return sys.stdout.isatty()
+
+
+def print_console(results: List[Result], quiet: bool = False) -> None:
+    color = _use_color()
+    for res in results:
+        if quiet and res.verdict in (Verdict.VERIFIED, Verdict.UNVERIFIABLE):
+            continue
+        label = _LABELS[res.verdict]
+        if color:
+            label = f"{_COLORS[res.verdict]}{label}{_RESET}"
+        line = f"  {label} {res.key}"
+        if res.similarity is not None and res.verdict is not Verdict.VERIFIED:
+            line += f"  (best title similarity {res.similarity:.2f})"
+        print(line)
+        for problem in res.problems:
+            print(f"             - {problem}")
+        if res.suggestion:
+            print(f"             > suggestion: {res.suggestion}")
+
+    counts = Counter(r.verdict for r in results)
+    total = len(results)
+    summary = ", ".join(
+        f"{counts[v]} {v.value}" for v in Verdict if counts.get(v)
+    )
+    print(f"\ncitegate: checked {total} entries — {summary or 'nothing to check'}")
+
+
+def github_annotations(results: List[Result], failing: set) -> None:
+    """Emit GitHub Actions workflow annotations for problem entries."""
+    if os.environ.get("GITHUB_ACTIONS") != "true":
+        return
+    for res in results:
+        if res.verdict in (Verdict.VERIFIED, Verdict.UNVERIFIABLE):
+            continue
+        level = "error" if res.verdict in failing else "warning"
+        detail = "; ".join(res.problems) or res.verdict.value
+        print(f"::{level} file={res.file},title=citegate {res.verdict.value}: {res.key}::{detail}")
+
+
+def github_step_summary(results: List[Result]) -> None:
+    path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if not path:
+        return
+    counts = Counter(r.verdict for r in results)
+    lines = [
+        "## citegate reference check",
+        "",
+        f"Checked **{len(results)}** entries: "
+        + ", ".join(f"{counts[v]} {v.value}" for v in Verdict if counts.get(v)),
+        "",
+    ]
+    problems = [r for r in results if r.verdict not in (Verdict.VERIFIED, Verdict.UNVERIFIABLE)]
+    if problems:
+        lines += ["| entry | verdict | detail |", "|---|---|---|"]
+        for res in problems:
+            detail = "; ".join(res.problems).replace("|", "\\|")
+            lines.append(f"| `{res.key}` | {res.verdict.value} | {detail} |")
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write("\n".join(lines) + "\n")
+
+
+def to_json(results: List[Result]) -> Dict:
+    counts = Counter(r.verdict for r in results)
+    return {
+        "tool": "citegate",
+        "version": __version__,
+        "summary": {v.value: counts.get(v, 0) for v in Verdict},
+        "results": [r.to_dict() for r in results],
+    }
+
+
+def write_json(results: List[Result], path: str) -> None:
+    payload = json.dumps(to_json(results), indent=2, ensure_ascii=False)
+    if path == "-":
+        print(payload)
+    else:
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(payload)

citegate/sources.py

@@ -0,0 +1,190 @@
+"""HTTP clients for the Crossref and OpenAlex APIs.
+
+Both clients identify themselves with a descriptive User-Agent (including the
+user's mailto address when provided, which places Crossref requests in the
+polite pool), retry transient failures with backoff, and pause briefly between
+requests so that CI runs stay well within published rate limits.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+import requests
+
+from . import __version__
+
+CROSSREF_API = "https://api.crossref.org"
+OPENALEX_API = "https://api.openalex.org"
+
+# Crossref update-types that mean the cited work is no longer standing.
+RETRACTION_UPDATE_TYPES = {
+    "retraction",
+    "retraction_note",
+    "partial_retraction",
+    "withdrawal",
+    "removal",
+}
+CONCERN_UPDATE_TYPES = {"expression_of_concern"}
+
+
+class SourceError(Exception):
+    """A source API could not be reached after retries."""
+
+
+@dataclass
+class CandidateRecord:
+    """A bibliographic record from either source, normalized for comparison."""
+
+    title: str
+    year: Optional[int]
+    families: List[str]
+    doi: Optional[str]
+    source: str
+    is_retracted: bool = False
+    notes: List[str] = field(default_factory=list)
+
+
+class _Http:
+    def __init__(self, mailto: Optional[str] = None, timeout: float = 20.0, pause: float = 0.1):
+        self.session = requests.Session()
+        ua = f"citegate/{__version__} (https://github.com/chrisyangsong/citegate"
+        if mailto:
+            ua += f"; mailto:{mailto}"
+        ua += ")"
+        self.session.headers["User-Agent"] = ua
+        self.mailto = mailto
+        self.timeout = timeout
+        self.pause = pause
+
+    def get_json(self, url: str, params: Optional[Dict[str, Any]] = None) -> Optional[Dict[str, Any]]:
+        """GET a JSON document. Returns None on 404; raises SourceError when unreachable."""
+        last_error: Optional[Exception] = None
+        for attempt in range(3):
+            if attempt:
+                time.sleep(1.5 * attempt)
+            try:
+                resp = self.session.get(url, params=params, timeout=self.timeout)
+            except requests.RequestException as exc:
+                last_error = exc
+                continue
+            if resp.status_code == 404:
+                return None
+            if resp.status_code in (429, 500, 502, 503, 504):
+                last_error = RuntimeError(f"HTTP {resp.status_code} from {url}")
+                continue
+            resp.raise_for_status()
+            time.sleep(self.pause)
+            try:
+                return resp.json()
+            except ValueError as exc:
+                last_error = exc
+                continue
+        raise SourceError(f"could not reach {url}: {last_error}")
+
+
+def _crossref_year(message: Dict[str, Any]) -> Optional[int]:
+    for key in ("issued", "published-print", "published-online", "created"):
+        parts = (message.get(key) or {}).get("date-parts") or []
+        if parts and parts[0] and parts[0][0]:
+            return int(parts[0][0])
+    return None
+
+
+def _crossref_record(message: Dict[str, Any]) -> CandidateRecord:
+    titles = message.get("title") or []
+    families = [a.get("family", "") for a in message.get("author", []) if a.get("family")]
+    return CandidateRecord(
+        title=titles[0] if titles else "",
+        year=_crossref_year(message),
+        families=families,
+        doi=(message.get("DOI") or "").lower() or None,
+        source="crossref",
+    )
+
+
+def _openalex_record(work: Dict[str, Any]) -> CandidateRecord:
+    families = []
+    for authorship in work.get("authorships", []):
+        name = (authorship.get("author") or {}).get("display_name") or ""
+        if name:
+            families.append(name.split()[-1])
+    doi = work.get("doi") or ""
+    doi = doi.replace("https://doi.org/", "").lower() or None
+    return CandidateRecord(
+        title=work.get("display_name") or "",
+        year=work.get("publication_year"),
+        families=families,
+        doi=doi,
+        source="openalex",
+        is_retracted=bool(work.get("is_retracted")),
+    )
+
+
+class Crossref:
+    def __init__(self, http: _Http):
+        self.http = http
+
+    def get_by_doi(self, doi: str) -> Optional[CandidateRecord]:
+        data = self.http.get_json(f"{CROSSREF_API}/works/{quote(doi, safe='')}")
+        if data is None:
+            return None
+        return _crossref_record(data["message"])
+
+    def search(self, query: str, author: Optional[str] = None, rows: int = 5) -> List[CandidateRecord]:
+        params: Dict[str, Any] = {"query.bibliographic": query, "rows": rows}
+        if author:
+            params["query.author"] = author
+        if self.http.mailto:
+            params["mailto"] = self.http.mailto
+        data = self.http.get_json(f"{CROSSREF_API}/works", params=params)
+        items = ((data or {}).get("message") or {}).get("items") or []
+        return [_crossref_record(m) for m in items]
+
+    def retraction_updates(self, doi: str) -> List[str]:
+        """Return update-types of any Crossref works that update (retract/withdraw) this DOI.
+
+        Crossref hosts the Retraction Watch database, so this catches formally
+        indexed retractions even when the publisher's own record is silent.
+        """
+        params = {"filter": f"updates:{doi}", "rows": 10}
+        data = self.http.get_json(f"{CROSSREF_API}/works", params=params)
+        items = ((data or {}).get("message") or {}).get("items") or []
+        update_types: List[str] = []
+        for item in items:
+            for upd in item.get("update-to", []):
+                if (upd.get("DOI") or "").lower() == doi.lower() and upd.get("type"):
+                    update_types.append(upd["type"])
+        return update_types
+
+
+class OpenAlex:
+    def __init__(self, http: _Http):
+        self.http = http
+
+    def _params(self, extra: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        params = dict(extra or {})
+        if self.http.mailto:
+            params["mailto"] = self.http.mailto
+        return params
+
+    def get_by_doi(self, doi: str) -> Optional[CandidateRecord]:
+        url = f"{OPENALEX_API}/works/https://doi.org/{quote(doi, safe='')}"
+        data = self.http.get_json(url, params=self._params())
+        if data is None:
+            return None
+        return _openalex_record(data)
+
+    def search(self, query: str, per_page: int = 5) -> List[CandidateRecord]:
+        data = self.http.get_json(
+            f"{OPENALEX_API}/works", params=self._params({"search": query, "per-page": per_page})
+        )
+        return [_openalex_record(w) for w in (data or {}).get("results", [])]
+
+
+def make_clients(mailto: Optional[str] = None) -> tuple:
+    http = _Http(mailto=mailto)
+    return Crossref(http), OpenAlex(http)

citegate-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: citegate
+Version: 0.1.0
+Summary: Citation integrity as a CI gate: verify BibTeX references against Crossref and OpenAlex, catch fabricated citations, and get alerted when a paper you cite is retracted.
+Author-email: Yang Song <songyang0714@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/chrisyangsong/citegate
+Project-URL: Issues, https://github.com/chrisyangsong/citegate/issues
+Keywords: bibtex,citations,references,hallucination,retraction,crossref,openalex,ci,research-integrity
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: bibtexparser<2,>=1.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# citegate
+
+**Citation integrity as a CI gate.** citegate verifies every entry in your BibTeX files against [Crossref](https://www.crossref.org/) and [OpenAlex](https://openalex.org/), then fails your build when a reference is fabricated, wrong, or retracted.
+
+LLM writing assistants fabricate plausible-looking references, and even careful humans cite papers that later get retracted. Existing checkers are interactive tools you have to remember to run. citegate is the piece that belongs in your repository instead: a GitHub Action, a pre-commit hook, and a weekly monitor that opens an issue the day a paper you cite is retracted.
+
+```
+  OK         he2016deep
+  NOT FOUND  fabricated2023  (best title similarity 0.42)
+             - no record with a similar title in Crossref or OpenAlex — possibly a fabricated reference
+  RETRACTED  wakefield1998retracted
+             - OpenAlex marks this work as retracted
+             - Crossref/Retraction Watch records: retraction
+
+citegate: checked 3 entries — 1 verified, 1 retracted, 1 not-found
+```
+
+## What it checks
+
+| Verdict | Meaning |
+|---|---|
+| `verified` | The entry matches a real indexed work (title, year, authors agree). |
+| `not-found` | No similar record exists in Crossref or OpenAlex. Likely fabricated. |
+| `retracted` | The cited work is retracted or withdrawn, per OpenAlex and the [Retraction Watch data in Crossref](https://www.crossref.org/blog/news-crossref-and-retraction-watch/). |
+| `mismatch` | A real work exists, but the year, title, or authors in your entry disagree with the index. |
+| `unverifiable` | Websites, standards, and other entries without a DOI that scholarly indexes do not cover. Never fails the build. |
+| `error` | A source API was unreachable. |
+
+Entries with a DOI are resolved directly and their metadata compared field by field. Entries without a DOI are matched by fuzzy bibliographic search across both indexes; strong matches also get a `suggestion` with the DOI you should add.
+
+## Quick start
+
+```bash
+pip install citegate            # or: pipx install citegate
+citegate paper/references.bib --mailto you@example.edu
+```
+
+`--mailto` is optional but recommended: it identifies you to the APIs and places you in Crossref's polite pool. The exit code is non-zero when any `not-found` or `retracted` entry appears (configurable with `--fail-on not-found,retracted,mismatch`), so the same command works locally and in CI. Add `--json report.json` for machine-readable output and `--cache` to skip unchanged entries on repeated runs.
+
+## GitHub Action
+
+```yaml
+name: References
+on: [push, pull_request]
+jobs:
+  citegate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: chrisyangsong/citegate@main
+        with:
+          files: '**/*.bib'
+          mailto: 'you@example.edu'
+```
+
+Failures show up as inline annotations and a job-summary table listing exactly which entries are suspect and why.
+
+## Retraction monitoring
+
+A bibliography that verified cleanly last month can go bad without you touching it: about [one in 500 published papers is eventually retracted](https://www.crossref.org/blog/news-crossref-and-retraction-watch/), and citing one in a submission is an avoidable reviewer complaint. Copy [`examples/retraction-monitor.yml`](examples/retraction-monitor.yml) into `.github/workflows/` and citegate re-verifies your references every Monday, opening an issue in your repository when a cited paper is retracted or stops resolving.
+
+## pre-commit hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/chrisyangsong/citegate
+    rev: v0.1.0
+    hooks:
+      - id: citegate
+```
+
+## Relation to other tools
+
+Several good interactive checkers exist, including [refchecker](https://github.com/markrussinovich/refchecker) and [hallucinator](https://github.com/gianlucasb/hallucinator) for auditing a finished paper or PDF, and browser tools like [BibTeX Verifier](https://merfanian.github.io/Bibtex-Verifier/). citegate covers the other half of the problem: it lives in the repository with your `.bib` files, runs automatically on every push, and keeps watching after you stop looking. If you want a one-off deep audit of a PDF, use those tools; if you want your references checked continuously, use citegate.
+
+## Design notes
+
+- Sources: Crossref (REST API, polite pool) and OpenAlex. Retraction status is the union of OpenAlex's `is_retracted` flag and Crossref update records, which include the Retraction Watch database.
+- Matching is deliberately conservative: `@misc` and other non-indexed entry types without DOIs are skipped rather than flagged, and a one-year slack is allowed on years (print vs online dates). False alarms are the fastest way to get a checker removed from CI.
+- No LLMs are involved in verification; every verdict is traceable to an index record.
+
+## Roadmap
+
+- Parallel lookups for large bibliographies
+- DOCX/PDF reference-list extraction (currently BibTeX only)
+- arXiv and DBLP as additional sources
+- An `--only retractions` fast mode for high-frequency monitoring
+
+Issues and pull requests are welcome.
+
+## License
+
+MIT © 2026 Yang Song. Not affiliated with Crossref, OpenAlex, or Retraction Watch; please respect their API terms.

citegate-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+citegate/__init__.py,sha256=vlVuVdZDm3PXVCAVJ7kaxTeD4Wk0em0bq4pzXMXzjkE,72
+citegate/cli.py,sha256=VFxagJSzumQTaIbuyXgOp89P6JcXlRizX-DmLzJxTEg,4448
+citegate/core.py,sha256=r0oiK_opL6YQj4li-ivpe8Bq5EkYClPMxcXzu6_0e6s,12771
+citegate/report.py,sha256=jYfepSZQ8UqxryuVEIZw2b--OJvdZG4SLoQO9zndBqw,3906
+citegate/sources.py,sha256=gluMtnLWmUrTul2DLYYKSYRJE2xMAHW17r6Mk-BCSBk,6824
+citegate-0.1.0.dist-info/licenses/LICENSE,sha256=5Ji97VnY5J8_o4TIdOM0sod_Gh-9sosgPL2tmwu2cjk,1066
+citegate-0.1.0.dist-info/METADATA,sha256=-Suvjx1cfErx0-9jbzVtDzZ3cmIj8WciWbNwRRo2Sbw,6324
+citegate-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+citegate-0.1.0.dist-info/entry_points.txt,sha256=JELUCBOjyhVMv_GZR3zNnBUUsCKL5nyy7F_PL895xtI,47
+citegate-0.1.0.dist-info/top_level.txt,sha256=hHv1xl_lM1LYkeC9nxuwhExGFS_PnscOwbg6zutv2pU,9
+citegate-0.1.0.dist-info/RECORD,,

citegate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

citegate-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+citegate = citegate.cli:main

citegate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yang Song
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

citegate-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+citegate