Citation Management skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Citation Management"
  short_description: "One clean .bib, zero broken citations"
  default_prompt: "$citation-management Clean up refs.bib: merge duplicates and fix the entries missing fields"

#!/usr/bin/env python3
"""Lint a BibTeX/biblatex file and cross-check it against the manuscript.

Errors (exit 1): duplicate keys, missing required fields, keys cited in the
manuscript but absent from the .bib.
Warnings: same DOI or same title under two keys, DOI stored as a URL, malformed
DOI, odd years, entries never cited.

Usage:
  python3 bibtex_check.py refs.bib
  python3 bibtex_check.py refs.bib --cited paper.tex chapter2.tex notes.md
"""
import argparse
import re
import sys
from pathlib import Path

REQUIRED = {
    "article": [("author",), ("title",), ("journal", "journaltitle"), ("year", "date")],
    "inproceedings": [("author",), ("title",), ("booktitle",), ("year", "date")],
    "incollection": [("author",), ("title",), ("booktitle",), ("year", "date")],
    "book": [("author", "editor"), ("title",), ("publisher",), ("year", "date")],
    "phdthesis": [("author",), ("title",), ("school", "institution"), ("year", "date")],
    "mastersthesis": [("author",), ("title",), ("school", "institution"), ("year", "date")],
    "techreport": [("author",), ("title",), ("institution",), ("year", "date")],
    "online": [("title",), ("url",)],
    "misc": [("title",)],
}
SKIP = {"comment", "string", "preamble"}
DOI_RE = re.compile(r"^10\.\d{4,9}/\S+$")
CITE_TEX = re.compile(r"\\[a-zA-Z]*cite[a-zA-Z]*\*?(?:\[[^\]]*\]){0,2}\{([^}]*)\}")
CITE_MD = re.compile(r"(?<![\w.])@([A-Za-z0-9_][\w:.#$%&+?<>~/-]*[A-Za-z0-9_])")


def read_value(text: str, i: int):
    """Return (value, next_index) for a field value starting at text[i]."""
    if text[i] == "{":
        depth, j = 0, i
        while j < len(text):
            if text[j] == "{":
                depth += 1
            elif text[j] == "}":
                depth -= 1
                if depth == 0:
                    return text[i + 1:j], j + 1
            j += 1
        raise ValueError("unbalanced braces")
    if text[i] == '"':
        j = i + 1
        while j < len(text) and not (text[j] == '"' and text[j - 1] != "\\"):
            j += 1
        return text[i + 1:j], j + 1
    m = re.match(r"[^,}\s]+", text[i:])
    return (m.group(0) if m else ""), i + (m.end() if m else 0)


def parse(text: str):
    entries = []
    for m in re.finditer(r"@(\w+)\s*\{", text):
        etype = m.group(1).lower()
        if etype in SKIP:
            continue
        line = text.count("\n", 0, m.start()) + 1
        i = m.end()
        km = re.match(r"\s*([^,\s]+)\s*,", text[i:])
        if not km:
            entries.append({"type": etype, "key": None, "fields": {}, "line": line})
            continue
        key, i = km.group(1), i + km.end()
        fields = {}
        while True:
            fm = re.match(r"\s*([A-Za-z][\w-]*)\s*=\s*", text[i:])
            if not fm:
                break
            name, i = fm.group(1).lower(), i + fm.end()
            parts = []
            while True:  # handle "a" # {b} concatenation
                value, i = read_value(text, i)
                parts.append(value)
                cm = re.match(r"\s*#\s*", text[i:])
                if not cm:
                    break
                i += cm.end()
            fields[name] = " ".join(p.strip() for p in parts)
            cm = re.match(r"\s*,", text[i:])
            if not cm:
                break
            i += cm.end()
        entries.append({"type": etype, "key": key, "fields": fields, "line": line})
    return entries


def norm_title(t: str) -> str:
    return re.sub(r"[^a-z0-9]", "", re.sub(r"[{}\\]", "", t.lower()))


def cited_keys(paths):
    keys = set()
    for p in paths:
        text = Path(p).read_text(encoding="utf-8", errors="replace")
        for group in CITE_TEX.findall(text):
            keys.update(k.strip() for k in group.split(",") if k.strip())
        if p.endswith((".md", ".qmd", ".rmd", ".Rmd")):
            keys.update(CITE_MD.findall(text))
    return keys


def main() -> None:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("bib")
    ap.add_argument("--cited", nargs="*", default=[], help="manuscript files (.tex, .md, .qmd) to cross-check")
    args = ap.parse_args()

    entries = parse(Path(args.bib).read_text(encoding="utf-8", errors="replace"))
    errors, warns = [], []
    seen_key, seen_doi, seen_title = {}, {}, {}
    for e in entries:
        where = f"line {e['line']}"
        if not e["key"]:
            errors.append(f"{where}: entry without a citation key")
            continue
        k, f = e["key"], e["fields"]
        if k in seen_key:
            errors.append(f"{where}: duplicate key '{k}' (first at line {seen_key[k]})")
        seen_key.setdefault(k, e["line"])
        for alts in REQUIRED.get(e["type"], []):
            if not any(f.get(a) for a in alts):
                errors.append(f"{where}: @{e['type']}{{{k}}} missing {' or '.join(alts)}")
        doi = f.get("doi", "").strip()
        if doi:
            if re.match(r"https?://", doi):
                warns.append(f"{where}: '{k}' doi stored as URL; keep the bare 10.xxxx/... form")
                doi = re.sub(r"^https?://(dx\.)?doi\.org/", "", doi)
            if not DOI_RE.match(doi):
                warns.append(f"{where}: '{k}' doi '{doi}' does not look like a DOI")
            d = doi.lower()
            if d in seen_doi and seen_doi[d] != k:
                warns.append(f"{where}: '{k}' has the same DOI as '{seen_doi[d]}'")
            seen_doi.setdefault(d, k)
        title = norm_title(f.get("title", ""))
        if title:
            if title in seen_title and seen_title[title] != k:
                warns.append(f"{where}: '{k}' has the same title as '{seen_title[title]}' (preprint and published copy?)")
            seen_title.setdefault(title, k)
        year = f.get("year", "")
        if year and not re.fullmatch(r"\d{4}", year.strip()):
            warns.append(f"{where}: '{k}' year '{year}' is not a 4-digit year")

    if args.cited:
        cited = cited_keys(args.cited)
        for k in sorted(cited - set(seen_key)):
            errors.append(f"cited but not in {args.bib}: '{k}'")
        for k in sorted(set(seen_key) - cited):
            warns.append(f"never cited: '{k}'")

    for w in warns:
        print(f"warn: {w}")
    for x in errors:
        print(f"error: {x}")
    print(f"\n{len(entries)} entries, {len(errors)} error(s), {len(warns)} warning(s)")
    sys.exit(1 if errors else 0)


if __name__ == "__main__":
    main()