Add deterministic citation checker

New checker cross-references .cite keys against parsed .bib entries:
- MISSING: cited key not in any .bib file (error)
- UNUSED: bib entry never cited (info)
- DUPLICATE: same key defined by multiple entries (warning)

Architectural changes to support it:
- Checker protocol now takes a Document (path + source + paragraphs)
instead of just paragraphs, so citation-style checkers can scan the
raw source and .bib discovery can use the document's directory.
- Finding gains an optional file field so bib-level findings can point
at a .bib entry rather than the .tex.
- Prose filtering moved from the CLI into GrammarChecker; citation
scanning needs headings too.
- CLI exit code is 1 only for error-severity findings, so unused-bib
info/warning noise in drafts doesn't fail CI.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -22,17 +22,17 @@ The `qalmsw check` command reads `QALMSW_BASE_URL` (default `http://localhost:80
 
 ## Architecture
 
-The pipeline is **parse → checkers → report**, and every checker produces a uniform `Finding` so the report/CI layer never branches on checker type.
+The pipeline is **load → checkers → report**, and every checker produces a uniform `Finding` so the report/CI layer never branches on checker type.
 
 ```
-.tex file
+.tex file (+ .bib)
    │
    ▼
-parse.parse_paragraphs         # blank-line-split, comments stripped,
-   │  list[Paragraph]           # source line numbers preserved
+Document.load                  # path + source + parse_paragraphs()
+   │  Document                 #
    ▼
 checkers.*                     # each implements the Checker protocol:
-   │  list[Finding]            #     check(paragraphs) -> list[Finding]
+   │  list[Finding]            #     check(doc: Document) -> list[Finding]
    ▼
 report.render_findings         # rich-formatted terminal output
 ```
@@ -41,24 +41,35 @@ report.render_findings         # rich-formatted terminal output
 
 - **`Paragraph.start_line` / `end_line` are 1-indexed against the original source file** (not the stripped body). Findings point at these so editors can jump to the right line. Do not change this without updating every checker that constructs Findings.
 - **Comment stripping preserves newlines** so line numbers stay stable after `%`-stripping. `parse.tex._COMMENT_RE` uses a negative look-behind to skip escaped `\%`.
+- **Checkers receive a `Document`**, not just paragraphs. Citation-style checkers need the raw source (cites can appear outside prose paragraphs) and the path (to resolve `.bib` files). The `Checker` protocol is `check(doc: Document) -> list[Finding]`.
+- **Non-prose paragraphs are filtered by the consumer**, not at load time. `GrammarChecker` calls `has_prose()` per paragraph so citation-scanning checkers still see headings. Don't pre-filter in the CLI.
+- **CLI exit code is `1` only when an `error`-severity finding exists.** `info` (unused bib entry) and `warning` (duplicate bib key) findings are non-fatal by design — drafts routinely have them.
 - **`LLMClient` is a `typing.Protocol`**, not an ABC. Tests pass a `FakeLLM` that only implements `complete_json`. Don't tighten the interface into a base class; the Protocol is intentional so any object with the right shape works.
 - **Checkers never ask the LLM for line numbers.** Small local models count lines unreliably. Instead they ask for an `excerpt` string and we locate it in the paragraph text (`grammar._locate_line`). New checkers should follow this pattern.
 - **Structured output uses `response_format={"type": "json_object"}`** — supported by llama.cpp server. The system prompt must also spell out the JSON shape, because small models otherwise drift.
+- **`LLMClient` has `max_retries=0`.** A slow local model that times out once rarely succeeds silently; failing fast surfaces the real state instead of a 30-minute silent retry loop.
+- **`.bib` parsing is regex-based**, not a full BibTeX parser. We extract `@type{key,` headers + line numbers because that's all MISSING / UNUSED / DUPLICATE needs. If we ever need field values, swap in `bibtexparser`; don't grow the regex.
 
 ### Checker status
 
 | Checker    | State      | Shape                                                       |
 |------------|------------|-------------------------------------------------------------|
 | `grammar`  | working    | Per-paragraph LLM call, parallelizable, cheap               |
-| `citations`| **planned**| Mostly deterministic `.bib` vs `\cite` cross-check, LLM only to verify a cited work actually supports the claim |
+| `citations`| working    | Deterministic `.bib` vs `\cite` cross-check (MISSING / UNUSED / DUPLICATE). No LLM. |
 | `claims`   | **planned**| Needs retrieval (arXiv / local PDF cache / S2) + LLM judge — most expensive |
 | `reviewer` | **planned**| Whole-document pass, must chunk to fit local-model context  |
 
 When adding a checker: drop a file into `src/qalmsw/checkers/`, register it in `checkers/__init__.py`, wire it into `cli.py`'s `checkers` list, and add tests with a `FakeLLM` — don't hit the real server from tests.
 
+### Citations module layout
+
+- `src/qalmsw/bib/parser.py` — regex extractor over `@type{key,` headers + source lines.
+- `src/qalmsw/parse/citations.py` — scanners for `\cite*` keys and `\bibliography{}` / `\addbibresource{}` paths.
+- `src/qalmsw/checkers/citations.py` — the `CitationChecker`; receives parsed `BibEntry`s via its constructor so the CLI owns `.bib` discovery and resolution.
+
 ### What's intentionally *not* here
 
 - No multi-file `\input{}` / `\include{}` resolution yet — single-file only.
-- No `.bib` parser yet — will live in `src/qalmsw/bib/` when the citation checker lands.
+- No LLM-assisted citation verification (does this citation actually support this claim?). That's the `claims` checker's territory.
 - No retrieval layer yet — will live in `src/qalmsw/retrieval/` when the claims checker lands.
 - No SARIF/JSON report formats yet — only `report/text.py`. The `Finding` pydantic model is the serialization seam when those arrive.

README.md

@@ -4,7 +4,7 @@ Automated QA for scientific LaTeX writing, powered by a local LLM (llama.cpp ser
 
 ## Status
 
-Early scaffold. Grammar checker works end-to-end; citation, claim-to-reference, and reviewer-style checkers are planned.
+Grammar and citation checkers work end-to-end. Claim-to-reference and reviewer-style checkers are planned.
 
 ## Quick start
 
@@ -14,7 +14,9 @@ pip install -e '.[dev]'
 # Start llama.cpp server separately, e.g.
 #   ./llama-server -m model.gguf -c 8192 --port 8080
 
-qalmsw check path/to/paper.tex
+qalmsw check path/to/paper.tex                     # run all checkers
+qalmsw check --skip-grammar path/to/paper.tex      # deterministic citation checks only
+qalmsw check --bib refs.bib path/to/paper.tex      # override .bib auto-discovery
 ```
 
 Environment variables:
@@ -24,7 +26,9 @@ Environment variables:
 
 ## Checkers
 
-- `grammar` — per-paragraph grammar/style pass
-- `citations` *(planned)* — `.bib` cross-check for missing/unused keys
+- `grammar` — per-paragraph grammar/style pass (LLM-backed)
+- `citations` — `.bib` vs `\cite` cross-check: MISSING keys, UNUSED entries, DUPLICATE keys
 - `claims` *(planned)* — claim-to-reference consistency via retrieval
 - `reviewer` *(planned)* — whole-document reviewer-style critique
+
+Exit code is `1` only when an `error`-severity finding is present (missing citation, grammar error), so drafts with unused-bib-entry `info`s or duplicate-key `warning`s don't fail CI.

examples/refs.bib

@@ -0,0 +1,25 @@
+@inproceedings{vaswani2017,
+  title={Attention is All You Need},
+  author={Vaswani, Ashish and others},
+  booktitle={NeurIPS},
+  year={2017},
+}
+
+@article{orphan2019,
+  title={A paper nobody cites},
+  author={Ghost, A.},
+  journal={Journal of Nothing},
+  year={2019},
+}
+
+@article{duplicate_key,
+  title={First definition},
+  author={First, A.},
+  year={2020},
+}
+
+@article{duplicate_key,
+  title={Second definition of the same key},
+  author={Second, B.},
+  year={2021},
+}

examples/sample.tex

@@ -9,10 +9,14 @@
 \section{Introduction}
 This paper investigate the role of attention mechanisms in transformer
 architectures. Recent work~\cite{vaswani2017} have shown that self-attention
-outperform recurrence on many task.
+outperform recurrence on many task. See also~\cite{nonexistent2024} for
+context.
 
 We propose an novel method, which we call FastAttn, that reduce the quadratic
 cost of attention to $O(n \log n)$. Their approach are evaluated on three
 benchmarks and shows consistent improvment over the baselines.
 
+\bibliographystyle{plain}
+\bibliography{refs}
+
 \end{document}

src/qalmsw/bib/__init__.py

@@ -0,0 +1,3 @@
+from qalmsw.bib.parser import BibEntry, parse_bib_file, parse_bib_text
+
+__all__ = ["BibEntry", "parse_bib_file", "parse_bib_text"]

src/qalmsw/bib/parser.py

@@ -0,0 +1,50 @@
+"""Minimal BibTeX entry extractor.
+
+Pulls out ``@type{key,`` headers and their source line. We deliberately don't parse
+fields — nested braces in values make full BibTeX parsing a rabbit hole, and the
+citation checker only needs keys + line numbers to produce MISSING / UNUSED /
+DUPLICATE findings. Entries declared inside comment blocks are excluded by pre-stripping
+BibTeX ``@comment{...}`` blocks and ``%``-line comments.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+_ENTRY_START_RE = re.compile(
+    r"^[ \t]*@(\w+)\s*\{\s*([^,\s}]+)\s*,",
+    re.MULTILINE,
+)
+_LINE_COMMENT_RE = re.compile(r"(?<!\\)%[^\n]*")
+
+_SKIPPABLE_TYPES = frozenset({"string", "preamble", "comment"})
+
+
+@dataclass(frozen=True)
+class BibEntry:
+    key: str
+    entry_type: str
+    file: Path
+    line: int
+
+
+def _strip_line_comments_preserve_lines(text: str) -> str:
+    return _LINE_COMMENT_RE.sub("", text)
+
+
+def parse_bib_text(text: str, source: Path) -> list[BibEntry]:
+    cleaned = _strip_line_comments_preserve_lines(text)
+    entries: list[BibEntry] = []
+    for match in _ENTRY_START_RE.finditer(cleaned):
+        entry_type = match.group(1).lower()
+        if entry_type in _SKIPPABLE_TYPES:
+            continue
+        key = match.group(2).strip()
+        line = cleaned.count("\n", 0, match.start()) + 1
+        entries.append(BibEntry(key=key, entry_type=entry_type, file=source, line=line))
+    return entries
+
+
+def parse_bib_file(path: Path) -> list[BibEntry]:
+    return parse_bib_text(path.read_text(encoding="utf-8"), source=path)

src/qalmsw/checkers/__init__.py

@@ -1,4 +1,5 @@
 from qalmsw.checkers.base import Checker, Finding, Severity
+from qalmsw.checkers.citations import CitationChecker
 from qalmsw.checkers.grammar import GrammarChecker
 
-__all__ = ["Checker", "Finding", "GrammarChecker", "Severity"]
+__all__ = ["Checker", "CitationChecker", "Finding", "GrammarChecker", "Severity"]

src/qalmsw/checkers/base.py

@@ -10,7 +10,7 @@ from typing import Protocol
 
 from pydantic import BaseModel, Field
 
-from qalmsw.parse import Paragraph
+from qalmsw.document import Document
 
 
 class Severity(str, Enum):
@@ -26,9 +26,13 @@ class Finding(BaseModel):
     message: str
     suggestion: str | None = None
     excerpt: str | None = Field(default=None, description="Short source snippet this refers to")
+    file: str | None = Field(
+        default=None,
+        description="Source file if different from the document being checked (e.g. a .bib)",
+    )
 
 
 class Checker(Protocol):
     name: str
 
-    def check(self, paragraphs: list[Paragraph]) -> list[Finding]: ...
+    def check(self, doc: Document) -> list[Finding]: ...

src/qalmsw/checkers/citations.py

@@ -0,0 +1,81 @@
+"""Citation consistency checker.
+
+Cross-references the ``\\cite{}`` keys found in the document against the parsed
+``.bib`` entries and emits three kinds of findings:
+
+* **MISSING** — a cited key has no matching bib entry. Error; blocks a clean build.
+* **UNUSED** — a bib entry that no ``\\cite`` references. Info; drafts routinely carry
+  these and the user can choose to prune.
+* **DUPLICATE** — the same key is defined by multiple bib entries. Warning; BibTeX will
+  silently use one and drop the rest.
+
+Bib entries are passed in at construction time because discovering and parsing ``.bib``
+files is the CLI's responsibility (it knows the document's directory and can resolve
+relative paths correctly).
+"""
+from __future__ import annotations
+
+from qalmsw.bib import BibEntry
+from qalmsw.checkers.base import Finding, Severity
+from qalmsw.document import Document
+from qalmsw.parse import scan_citations
+
+
+class CitationChecker:
+    name = "citations"
+
+    def __init__(self, bib_entries: list[BibEntry]) -> None:
+        self._bib_entries = bib_entries
+
+    def check(self, doc: Document) -> list[Finding]:
+        citations = scan_citations(doc.source)
+        cited_keys = {c.key for c in citations}
+
+        entries_by_key: dict[str, list[BibEntry]] = {}
+        for entry in self._bib_entries:
+            entries_by_key.setdefault(entry.key, []).append(entry)
+        known_keys = set(entries_by_key)
+
+        findings: list[Finding] = []
+
+        for cite in citations:
+            if cite.key not in known_keys:
+                findings.append(
+                    Finding(
+                        checker=self.name,
+                        severity=Severity.error,
+                        line=cite.line,
+                        message=f"Cited key '{cite.key}' not found in bibliography.",
+                        excerpt=f"\\cite{{{cite.key}}}",
+                    )
+                )
+
+        for key, entries in entries_by_key.items():
+            if key not in cited_keys:
+                first = entries[0]
+                findings.append(
+                    Finding(
+                        checker=self.name,
+                        severity=Severity.info,
+                        file=str(first.file),
+                        line=first.line,
+                        message=f"Unused bibliography entry '{key}'.",
+                    )
+                )
+            if len(entries) > 1:
+                primary = entries[0]
+                for dup in entries[1:]:
+                    findings.append(
+                        Finding(
+                            checker=self.name,
+                            severity=Severity.warning,
+                            file=str(dup.file),
+                            line=dup.line,
+                            message=(
+                                f"Duplicate bibliography key '{key}' "
+                                f"(first defined at {primary.file}:{primary.line})."
+                            ),
+                        )
+                    )
+
+        return findings

src/qalmsw/checkers/grammar.py

@@ -7,8 +7,9 @@ LLM to count lines itself is unreliable for small local models, so we don't.
 from __future__ import annotations
 
 from qalmsw.checkers.base import Finding, Severity
+from qalmsw.document import Document
 from qalmsw.llm import LLMClient
-from qalmsw.parse import Paragraph
+from qalmsw.parse import Paragraph, has_prose
 
 _SYSTEM_PROMPT = """You are a grammar and style checker for scientific LaTeX writing.
 
@@ -39,9 +40,11 @@ class GrammarChecker:
     def __init__(self, llm: LLMClient) -> None:
         self._llm = llm
 
-    def check(self, paragraphs: list[Paragraph]) -> list[Finding]:
+    def check(self, doc: Document) -> list[Finding]:
         findings: list[Finding] = []
-        for para in paragraphs:
+        for para in doc.paragraphs:
+            if not has_prose(para.text):
+                continue
             result = self._llm.complete_json(_SYSTEM_PROMPT, para.text)
             for raw in result.get("issues", []):
                 findings.append(_to_finding(raw, para, self.name))

src/qalmsw/cli.py

@@ -7,9 +7,11 @@ import typer
 from rich.console import Console
 
 from qalmsw import __version__
-from qalmsw.checkers import Finding, GrammarChecker
+from qalmsw.bib import BibEntry, parse_bib_file
+from qalmsw.checkers import Checker, CitationChecker, Finding, GrammarChecker
+from qalmsw.document import Document
 from qalmsw.llm import LlamaCppClient
-from qalmsw.parse import has_prose, parse_paragraphs
+from qalmsw.parse import scan_bib_resources
 from qalmsw.report import render_findings
 
 app = typer.Typer(no_args_is_help=True, add_completion=False)
@@ -25,20 +27,52 @@ def version() -> None:
 @app.command()
 def check(
     file: Path = typer.Argument(..., exists=True, readable=True, help="Path to a .tex file"),
+    bib: list[Path] = typer.Option(
+        [],
+        "--bib",
+        help="Explicit .bib file(s). If omitted, .bib files are auto-discovered from "
+        "\\bibliography{} / \\addbibresource{} declarations.",
+    ),
+    skip_grammar: bool = typer.Option(False, "--skip-grammar", help="Skip LLM grammar checker"),
     base_url: str | None = typer.Option(None, "--base-url", envvar="QALMSW_BASE_URL"),
     model: str | None = typer.Option(None, "--model", envvar="QALMSW_MODEL"),
 ) -> None:
     """Run QA checks on a LaTeX document."""
-    source = file.read_text(encoding="utf-8")
-    paragraphs = [p for p in parse_paragraphs(source) if has_prose(p.text)]
-    console.print(f"[dim]{len(paragraphs)} prose paragraph(s) to check[/]")
+    doc = Document.load(file)
+    console.print(f"[dim]{len(doc.paragraphs)} paragraph(s) parsed[/]")
 
-    llm = LlamaCppClient(base_url=base_url, model=model)
-    checkers = [GrammarChecker(llm)]
+    bib_paths = list(bib) if bib else _discover_bib_files(doc)
+    bib_entries = _load_bib_entries(bib_paths)
+    if bib_paths:
+        console.print(f"[dim]{len(bib_entries)} bib entries from {len(bib_paths)} file(s)[/]")
+
+    checkers: list[Checker] = [CitationChecker(bib_entries)]
+    if not skip_grammar:
+        checkers.append(GrammarChecker(LlamaCppClient(base_url=base_url, model=model)))
 
     findings: list[Finding] = []
     for c in checkers:
-        findings.extend(c.check(paragraphs))
+        findings.extend(c.check(doc))
 
     render_findings(console, file, findings)
-    raise typer.Exit(code=1 if findings else 0)
+    raise typer.Exit(code=1 if any(f.severity.value == "error" for f in findings) else 0)
+
+
+def _discover_bib_files(doc: Document) -> list[Path]:
+    names = scan_bib_resources(doc.source)
+    base_dir = doc.path.parent
+    resolved: list[Path] = []
+    for name in names:
+        candidate = base_dir / (name if name.endswith(".bib") else f"{name}.bib")
+        if candidate.exists():
+            resolved.append(candidate)
+        else:
+            console.print(f"[yellow]warning[/]: referenced bib file not found: {candidate}")
+    return resolved
+
+
+def _load_bib_entries(paths: list[Path]) -> list[BibEntry]:
+    entries: list[BibEntry] = []
+    for p in paths:
+        entries.extend(parse_bib_file(p))
+    return entries

src/qalmsw/document.py

@@ -0,0 +1,24 @@
+"""The unit of input every checker operates on.
+
+`Document` bundles the .tex path, full source, and parsed paragraphs so individual
+checkers don't each re-parse the file and can choose which level of detail to consume
+(raw source for citation scanning, paragraphs for grammar, etc.).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from qalmsw.parse import Paragraph, parse_paragraphs
+
+
+@dataclass(frozen=True)
+class Document:
+    path: Path
+    source: str
+    paragraphs: list[Paragraph]
+
+    @classmethod
+    def load(cls, path: Path) -> Document:
+        source = path.read_text(encoding="utf-8")
+        return cls(path=path, source=source, paragraphs=parse_paragraphs(source))

src/qalmsw/parse/__init__.py

@@ -1,3 +1,12 @@
+from qalmsw.parse.citations import CitationRef, scan_bib_resources, scan_citations
 from qalmsw.parse.tex import Paragraph, extract_body, has_prose, parse_paragraphs
 
-__all__ = ["Paragraph", "extract_body", "has_prose", "parse_paragraphs"]
+__all__ = [
+    "CitationRef",
+    "Paragraph",
+    "extract_body",
+    "has_prose",
+    "parse_paragraphs",
+    "scan_bib_resources",
+    "scan_citations",
+]

src/qalmsw/parse/citations.py

@@ -0,0 +1,61 @@
+"""Scan a .tex source for citation keys and bibliography resource declarations.
+
+Works directly on the raw source (after comment stripping) because citations can appear
+anywhere — not only inside prose paragraphs — and we need file-accurate line numbers.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from qalmsw.parse.tex import _COMMENT_RE
+
+# Matches natbib + biblatex cite commands: \cite, \citep, \citet, \citeauthor,
+# \citeyear, \nocite, \parencite, \textcite, \autocite, \footcite (+ star variants,
+# optional pre/post-note brackets).
+_CITE_RE = re.compile(
+    r"\\(?:no|paren|text|auto|foot)?cite[a-zA-Z]*\*?"
+    r"(?:\[[^\]]*\])*"
+    r"\{([^}]+)\}"
+)
+
+# \bibliography{a,b}  (bibtex)   and   \addbibresource{a.bib}  (biblatex)
+_BIBLIOGRAPHY_RE = re.compile(r"\\bibliography\{([^}]+)\}")
+_ADDBIBRESOURCE_RE = re.compile(r"\\addbibresource\{([^}]+)\}")
+
+
+@dataclass(frozen=True)
+class CitationRef:
+    key: str
+    line: int
+
+
+def scan_citations(source: str) -> list[CitationRef]:
+    """Return every cited key with its 1-indexed source line."""
+    text = _COMMENT_RE.sub("", source)
+    refs: list[CitationRef] = []
+    for match in _CITE_RE.finditer(text):
+        line = text.count("\n", 0, match.start()) + 1
+        for raw_key in match.group(1).split(","):
+            key = raw_key.strip()
+            if key:
+                refs.append(CitationRef(key=key, line=line))
+    return refs
+
+
+def scan_bib_resources(source: str) -> list[str]:
+    """Return the list of .bib resource names declared in the source.
+
+    Names from ``\\bibliography{}`` are returned without extension (BibTeX convention);
+    names from ``\\addbibresource{}`` are returned verbatim (biblatex always includes
+    the extension). Callers resolve these against the document's directory.
+    """
+    text = _COMMENT_RE.sub("", source)
+    names: list[str] = []
+    for match in _BIBLIOGRAPHY_RE.finditer(text):
+        names.extend(n.strip() for n in match.group(1).split(",") if n.strip())
+    for match in _ADDBIBRESOURCE_RE.finditer(text):
+        n = match.group(1).strip()
+        if n:
+            names.append(n)
+    return names

src/qalmsw/report/text.py

@@ -19,10 +19,11 @@ def render_findings(console: Console, file: Path, findings: list[Finding]) -> No
         console.print(f"[green]{file}[/]: no issues found")
         return
 
-    for f in sorted(findings, key=lambda f: (f.line, f.checker)):
+    for f in sorted(findings, key=lambda f: (f.file or "", f.line, f.checker)):
         style = _SEVERITY_STYLE[f.severity]
+        loc = f"{f.file or file}:{f.line}"
         console.print(
-            f"[{style}]{f.severity.value}[/] [dim]{file}:{f.line}[/] "
+            f"[{style}]{f.severity.value}[/] [dim]{loc}[/] "
             f"[cyan]{f.checker}[/] {f.message}"
         )
         if f.excerpt:

tests/test_bib_parser.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+from qalmsw.bib import parse_bib_text
+
+
+def _parse(text: str):
+    return parse_bib_text(text, source=Path("test.bib"))
+
+
+def test_simple_entry():
+    entries = _parse("@article{smith2020, title={Hello}, author={Smith}}\n")
+    assert len(entries) == 1
+    assert entries[0].key == "smith2020"
+    assert entries[0].entry_type == "article"
+    assert entries[0].line == 1
+
+
+def test_multiple_entries_track_lines():
+    text = (
+        "@book{a2000, title={A}}\n"
+        "\n"
+        "@inproceedings{b2001,\n"
+        "  title={B},\n"
+        "}\n"
+    )
+    entries = _parse(text)
+    assert [(e.key, e.line) for e in entries] == [("a2000", 1), ("b2001", 3)]
+
+
+def test_string_preamble_and_comment_entries_are_ignored():
+    text = (
+        "@string{me = \"John Doe\"}\n"
+        "@preamble{\"hi\"}\n"
+        "@comment{ignored}\n"
+        "@article{real2020, title={X}}\n"
+    )
+    entries = _parse(text)
+    assert [e.key for e in entries] == ["real2020"]
+
+
+def test_line_comment_entries_are_stripped():
+    text = "% @article{hidden, title={x}}\n@article{visible, title={y}}\n"
+    entries = _parse(text)
+    assert [e.key for e in entries] == ["visible"]
+
+
+def test_entry_type_is_lowercased():
+    entries = _parse("@ARTICLE{k, title={T}}\n")
+    assert entries[0].entry_type == "article"

tests/test_citation_scan.py

@@ -0,0 +1,37 @@
+from qalmsw.parse import scan_bib_resources, scan_citations
+
+
+def test_single_cite():
+    refs = scan_citations("See \\cite{smith2020} for details.\n")
+    assert [(r.key, r.line) for r in refs] == [("smith2020", 1)]
+
+
+def test_multiple_keys_in_one_cite():
+    refs = scan_citations("\\cite{a,b, c}\n")
+    assert [r.key for r in refs] == ["a", "b", "c"]
+
+
+def test_citep_with_pre_and_post_notes():
+    refs = scan_citations("\\citep[see][p.~42]{jones1999}\n")
+    assert [(r.key, r.line) for r in refs] == [("jones1999", 1)]
+
+
+def test_line_tracking_across_multiple():
+    source = "first line\n\\cite{a}\n\n\\citet{b}\n"
+    refs = scan_citations(source)
+    assert [(r.key, r.line) for r in refs] == [("a", 2), ("b", 4)]
+
+
+def test_cite_in_comment_is_ignored():
+    refs = scan_citations("real text %\\cite{hidden}\n\\cite{visible}\n")
+    assert [r.key for r in refs] == ["visible"]
+
+
+def test_bibliography_directive():
+    names = scan_bib_resources("\\bibliography{refs,extra}\n")
+    assert names == ["refs", "extra"]
+
+
+def test_addbibresource_directive():
+    names = scan_bib_resources("\\addbibresource{bibliography.bib}\n")
+    assert names == ["bibliography.bib"]

tests/test_citations_checker.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+
+from qalmsw.bib import BibEntry
+from qalmsw.checkers import CitationChecker, Severity
+from qalmsw.document import Document
+
+
+def _doc(source: str) -> Document:
+    return Document(path=Path("paper.tex"), source=source, paragraphs=[])
+
+
+def _entry(key: str, line: int = 1, file: str = "refs.bib") -> BibEntry:
+    return BibEntry(key=key, entry_type="article", file=Path(file), line=line)
+
+
+def test_missing_cite_key_is_error():
+    doc = _doc("Hello \\cite{ghost} world\n")
+    findings = CitationChecker([]).check(doc)
+    missing = [f for f in findings if "not found" in f.message]
+    assert len(missing) == 1
+    assert missing[0].severity == Severity.error
+    assert missing[0].line == 1
+
+
+def test_cited_key_present_in_bib_is_silent():
+    doc = _doc("Hello \\cite{smith2020} world\n")
+    findings = CitationChecker([_entry("smith2020")]).check(doc)
+    assert [f for f in findings if "not found" in f.message] == []
+
+
+def test_unused_entry_is_info():
+    doc = _doc("Hello world\n")
+    findings = CitationChecker([_entry("orphan")]).check(doc)
+    assert len(findings) == 1
+    assert findings[0].severity == Severity.info
+    assert "Unused" in findings[0].message
+    assert findings[0].file == "refs.bib"
+
+
+def test_duplicate_entries_produce_warnings_for_each_after_first():
+    doc = _doc("\\cite{k}\n")
+    entries = [_entry("k", line=10), _entry("k", line=20), _entry("k", line=30)]
+    findings = CitationChecker(entries).check(doc)
+    dups = [f for f in findings if "Duplicate" in f.message]
+    assert [(f.line, f.severity) for f in dups] == [
+        (20, Severity.warning),
+        (30, Severity.warning),
+    ]

tests/test_grammar.py

@@ -1,7 +1,14 @@
+from pathlib import Path
+
 from qalmsw.checkers import GrammarChecker, Severity
+from qalmsw.document import Document
 from qalmsw.parse import Paragraph
 
 
+def _doc(paragraphs: list[Paragraph]) -> Document:
+    return Document(path=Path("test.tex"), source="", paragraphs=paragraphs)
+
+
 class FakeLLM:
     def __init__(self, response: dict) -> None:
         self.response = response
@@ -30,7 +37,7 @@ def test_finding_shape_and_line_mapping():
             ]
         }
     )
-    findings = GrammarChecker(llm).check([para])
+    findings = GrammarChecker(llm).check(_doc([para]))
     assert len(findings) == 1
     f = findings[0]
     assert f.checker == "grammar"
@@ -47,24 +54,43 @@ def test_excerpt_on_later_line_maps_correctly():
         end_line=6,
     )
     llm = FakeLLM({"issues": [{"excerpt": "issue here", "message": "x", "severity": "info"}]})
-    findings = GrammarChecker(llm).check([para])
+    findings = GrammarChecker(llm).check(_doc([para]))
     assert findings[0].line == 6
 
 
 def test_empty_response_yields_no_findings():
-    para = Paragraph(text="Clean.", start_line=1, end_line=1)
-    assert GrammarChecker(FakeLLM({"issues": []})).check([para]) == []
+    para = Paragraph(
+        text="The text here reads reasonably well and needs no changes.",
+        start_line=1,
+        end_line=1,
+    )
+    assert GrammarChecker(FakeLLM({"issues": []})).check(_doc([para])) == []
 
 
 def test_unknown_severity_defaults_to_warning():
-    para = Paragraph(text="x", start_line=1, end_line=1)
-    llm = FakeLLM({"issues": [{"excerpt": "x", "message": "m", "severity": "BOGUS"}]})
-    findings = GrammarChecker(llm).check([para])
+    para = Paragraph(
+        text="The first line contains some reasonably long prose content.",
+        start_line=1,
+        end_line=1,
+    )
+    llm = FakeLLM({"issues": [{"excerpt": "prose", "message": "m", "severity": "BOGUS"}]})
+    findings = GrammarChecker(llm).check(_doc([para]))
     assert findings[0].severity == Severity.warning
 
 
 def test_missing_excerpt_falls_back_to_paragraph_start():
-    para = Paragraph(text="content", start_line=7, end_line=7)
+    para = Paragraph(
+        text="This paragraph contains enough words to qualify as prose.",
+        start_line=7,
+        end_line=7,
+    )
     llm = FakeLLM({"issues": [{"message": "vague", "severity": "info"}]})
-    findings = GrammarChecker(llm).check([para])
+    findings = GrammarChecker(llm).check(_doc([para]))
     assert findings[0].line == 7
+
+
+def test_prose_less_paragraphs_skip_llm_call():
+    para = Paragraph(text="\\maketitle", start_line=3, end_line=3)
+    llm = FakeLLM({"issues": [{"excerpt": "x", "message": "m"}]})
+    assert GrammarChecker(llm).check(_doc([para])) == []
+    assert llm.calls == []