citegate 0.1.0__tar.gz

citegate-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,94 @@
+# 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/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "citegate"
+version = "0.1.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Yang Song", email = "songyang0714@gmail.com" }]
+keywords = [
+    "bibtex",
+    "citations",
+    "references",
+    "hallucination",
+    "retraction",
+    "crossref",
+    "openalex",
+    "ci",
+    "research-integrity",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Text Processing :: Markup :: LaTeX",
+]
+dependencies = [
+    "requests>=2.28",
+    "bibtexparser>=1.4,<2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/chrisyangsong/citegate"
+Issues = "https://github.com/chrisyangsong/citegate/issues"
+
+[project.scripts]
+citegate = "citegate.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

citegate-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

citegate-0.1.0/src/citegate/__init__.py

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

citegate-0.1.0/src/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())