Semantic Scholar backend, JSON output, image checker, batch mode

- Add Semantic Scholar retrieval backend (free API, no auth, no CAPTCHAs)
as the default for --enable-claims. Google Scholar kept as opt-in via
--retrieval google-scholar.
- Add --json flag for machine-readable CI output.
- Add images checker: verifies \includegraphics files exist on disk,
tries common extensions when none given.
- Add batch mode: qalmsw check accepts multiple paths and globs.
- Add set_backend() for runtime retrieval switching.
- Remove old test_scholar.py (replaced by test_semantic_scholar.py).
- Update README and CLAUDE.md for all new features.

CLAUDE.md

@@ -53,12 +53,16 @@ report.render_findings         # rich-formatted terminal output
 
 ### Checker status
 
-| Checker    | State      | Shape                                                       |
-|------------|------------|-------------------------------------------------------------|
-| `grammar`  | working    | Per-paragraph LLM call, parallelizable, cheap               |
-| `citations`| working    | Deterministic `.bib` vs `\cite` cross-check (MISSING / UNUSED / DUPLICATE). No LLM. |
-| `reviewer` | working    | One LLM call per `\section{}` (or whole body if none); over-long sections are truncated |
-| `claims`   | working, opt-in | Two LLM calls per paragraph-with-citation (extract, then judge per (claim, cite)). Scholar abstracts cached per bib key within a run. Opt in with `--enable-claims` — slow and rate-limited. |
+| Checker      | State      | Shape                                                       |
+|--------------|------------|-------------------------------------------------------------|
+| `artifacts`  | working    | Deterministic regex scan for LLM meta-comments, placeholders, self-awareness, phantom refs. No LLM. Always runs. |
+| `figures`    | working    | Deterministic scan for missing/placeholder captions, orphan labels, empty floats. No LLM. Always runs. |
+| `images`     | working    | Verifies `\\includegraphics` files exist on disk relative to the .tex file. No LLM. Always runs. |
+| `grammar`    | working    | Per-paragraph LLM call, parallelizable, cheap               |
+| `citations`  | working    | Deterministic `.bib` vs `\\cite` cross-check (MISSING / UNUSED / DUPLICATE). No LLM. |
+| `references` | working    | Verifies arXiv eprint IDs and DOIs resolve to real papers via live API calls. Network-backed. |
+| `reviewer`   | working    | One LLM call per `\\section{}` (or whole body if none); over-long sections are truncated |
+| `claims`     | working, opt-in | Two LLM calls per paragraph-with-citation (extract, then judge per (claim, cite)). Paper abstracts fetched via retrieval backend, cached per bib key within a run. Opt in with `--enable-claims`. Retrieval backend selectable with `--retrieval` (default: `semantic-scholar`, alt: `google-scholar`). |
 
 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.
 
@@ -72,5 +76,5 @@ When adding a checker: drop a file into `src/qalmsw/checkers/`, register it in `
 
 - No multi-file `\input{}` / `\include{}` resolution yet — single-file only.
 - No LLM-assisted citation verification (does this citation actually support this claim?). That's the `claims` checker's territory.
-- Retrieval starts with `src/qalmsw/retrieval/scholar.py` (Google Scholar via `scholarly`). **Scraping-based**; rate-limits and CAPTCHAs are expected under sustained use. Keep it for personal/interactive runs; fall back to Semantic Scholar or arXiv when CI-scale reliability matters.
-- No SARIF/JSON report formats yet — only `report/text.py`. The `Finding` pydantic model is the serialization seam when those arrive.
+- Retrieval uses **Semantic Scholar** by default (free API, no auth, no CAPTCHAs). Google Scholar (`scholarly`) is available as an opt-in backend via `--retrieval google-scholar` but is scraping-based and may hit CAPTCHAs under sustained use. Backend switching is done at runtime via `qalmsw.retrieval.set_backend()`.
+- JSON report output is available via `--json` for CI integration. The `Finding` pydantic model is the serialization seam for future SARIF support.

README.md

@@ -5,7 +5,7 @@ Catches the artefacts that get you a 1-year arXiv ban — before you submit.
 
 ## What it catches
 
-qalmsw now checks for all three categories of "incontrovertible evidence" that arXiv's
+qalmsw checks for all three categories of "incontrovertible evidence" that arXiv's
 Code of Conduct penalises:
 
 | What arXiv flags | How qalmsw catches it |
@@ -17,9 +17,11 @@ Code of Conduct penalises:
 | **LLM self-awareness artifacts** ("as an AI language model", "I cannot provide") | `artifacts` checker |
 | **LLM-generated LaTeX boilerplate** (\lipsum, \blindtext, TODO/FIXME) | `artifacts` checker |
 | **Unreferenced figures/tables** | `figures` checker — warns on labels never \ref'd |
+| **Missing image files** (\includegraphics pointing to non-existent files) | `images` checker — verifies referenced images exist on disk |
 | **Grammar & style issues** | `grammar` checker — per-paragraph LLM pass |
 | **Missing citations** | `citations` checker — cross-references \cite vs .bib |
 | **Substantive reviewer concerns** | `reviewer` checker — per-section LLM critique |
+| **Unsupported claims** *(opt-in)* | `claims` checker — checks each \cite-backed claim against the cited paper's abstract |
 
 The first three rows are the ones that get you banned. qalmsw catches all of them.
 
@@ -34,10 +36,14 @@ pip install -e '.[dev]'
 qalmsw check path/to/paper.tex                             # run all checkers
 qalmsw check --skip-grammar --skip-reviewer paper.tex      # deterministic checks only (fast)
 qalmsw check --skip-grammar path/to/paper.tex              # reviewer + citations + artifacts + references
-qalmsw check -j 4 path/to/paper.tex                        # fan out 4 parallel LLM calls (match server --parallel N)
+qalmsw check -j 4 path/to/paper.tex                        # fan out 4 parallel LLM calls
 qalmsw check --bib refs.bib path/to/paper.tex              # override .bib auto-discovery
+qalmsw check --json paper.tex                              # JSON output for CI
+qalmsw check ch1.tex ch2.tex ch3.tex                       # batch mode: check multiple files
+qalmsw check "src/**/*.tex"                                # glob expansion
 
-qalmsw scholar "Attention Is All You Need"                 # Google Scholar lookup (scraping; expect CAPTCHAs on bulk use)
+qalmsw scholar "Attention Is All You Need"                 # Semantic Scholar lookup (default, free API)
+qalmsw check --enable-claims --retrieval google-scholar paper.tex  # claims check via Google Scholar
 ```
 
 Environment variables:
@@ -51,6 +57,7 @@ Environment variables:
 |---|---|---|---|
 | `artifacts` | No | Instant | Scans for LLM meta-comments, placeholders, self-awareness, boilerplate |
 | `figures` | No | Instant | Checks captions, labels, refs, empty floats |
+| `images` | No | Instant | Verifies \includegraphics files exist on disk |
 | `citations` | No | Instant | `.bib` vs `\cite` cross-check: MISSING, UNUSED, DUPLICATE |
 | `references` | Network | Slow | Verifies arXiv IDs and DOIs resolve to real papers |
 | `grammar` | LLM | Per-paragraph | Grammar, spelling, punctuation |
@@ -61,6 +68,17 @@ Exit code is `1` only when an `error`-severity finding is present (missing citat
 LLM artifact, hallucinated reference), so unused-bib-entry `info`s or duplicate-key
 `warning`s don't fail CI.
 
+### Retrieval backends
+
+The `claims` checker needs to fetch paper abstracts. Two backends are available:
+
+| Backend | Flag | Auth | Reliability | Speed |
+|---|---|---|---|---|
+| **Semantic Scholar** (default) | `--retrieval semantic-scholar` | None | High (real API) | ~1 req/sec |
+| **Google Scholar** | `--retrieval google-scholar` | None | Low (scraping, CAPTCHAs) | ~1 req/sec |
+
+Default is Semantic Scholar — no auth, no CAPTCHAs, works in CI.
+
 ## arXiv Code of Conduct
 
 arXiv's Code of Conduct (May 2026) states:
@@ -94,8 +112,9 @@ Document.load
 checkers.*               # each implements check(doc) -> list[Finding]
    │
    ▼
-report.render_findings   # rich-formatted terminal output
+report.render_findings   # rich-formatted terminal output (or --json for CI)
 ```
 
-Deterministic checkers (artifacts, figures, citations) run first and always.
+Deterministic checkers (artifacts, figures, images, citations) run first and always.
 LLM checkers (grammar, reviewer, claims) run only when a server is available.
+Network checkers (references, claims) make live API calls.

src/qalmsw/checkers/__init__.py

@@ -4,6 +4,7 @@ from qalmsw.checkers.citations import CitationChecker
 from qalmsw.checkers.claims import ClaimsChecker
 from qalmsw.checkers.figures import FigureTableChecker
 from qalmsw.checkers.grammar import GrammarChecker
+from qalmsw.checkers.images import ImageChecker
 from qalmsw.checkers.references import ReferenceChecker
 from qalmsw.checkers.reviewer import ReviewerChecker
 
@@ -15,6 +16,7 @@ __all__ = [
     "FigureTableChecker",
     "Finding",
     "GrammarChecker",
+    "ImageChecker",
     "ReferenceChecker",
     "ReviewerChecker",
     "Severity",

src/qalmsw/checkers/images.py

@@ -0,0 +1,109 @@
+"""Image file existence checker.
+
+Scans for ``\\includegraphics`` commands in the LaTeX source and verifies
+the referenced image files exist on disk relative to the document directory.
+
+Missing images are a common sign of uncurated LLM output — the model generates
+``\\includegraphics{results.png}`` without actually having created the file.
+
+Tries common image extensions (.pdf, .png, .jpg, .jpeg, .eps, .svg) when
+no extension is present.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from qalmsw.checkers.base import Finding, Severity
+from qalmsw.document import Document
+
+_GRAPHICS_RE = re.compile(
+    r"\\includegraphics(?:\s*\[[^\]]*\])?\s*\{([^}]+)\}"
+)
+
+_COMMON_EXTENSIONS: tuple[str, ...] = (
+    ".pdf", ".png", ".jpg", ".jpeg", ".eps", ".svg", ".gif", ".tiff",
+)
+
+# Extensions that aren't image files — skip these
+_SKIP_EXTENSIONS: tuple[str, ...] = (".tex", ".cls", ".sty", ".bib", ".bst")
+
+
+class ImageChecker:
+    """Checks that all \\includegraphics files exist relative to the document."""
+
+    name = "images"
+
+    def check(self, doc: Document) -> list[Finding]:
+        findings: list[Finding] = []
+        doc_dir = doc.path.parent
+
+        for match in _GRAPHICS_RE.finditer(doc.source):
+            raw_path = match.group(1).strip()
+            if not raw_path:
+                continue
+
+            line = doc.source[: match.start()].count("\n") + 1
+
+            # Skip obviously not-image paths
+            if any(raw_path.lower().endswith(ext) for ext in _SKIP_EXTENSIONS):
+                continue
+
+            resolved = _resolve_image(doc_dir, raw_path)
+            if resolved is None:
+                findings.append(
+                    Finding(
+                        checker=self.name,
+                        severity=Severity.error,
+                        line=line,
+                        message=f"Image file not found: '{raw_path}'",
+                        excerpt=raw_path[:80],
+                        suggestion=(
+                            f"Place the image at "
+                            f"\\includegraphics{{{_suggest_path(doc_dir, raw_path)}}} "
+                            f"or remove this reference."
+                        ),
+                    )
+                )
+
+        return findings
+
+
+def _resolve_image(doc_dir: Path, raw_path: str) -> Path | None:
+    """Resolve an \\includegraphics path to an existing file, or None.
+
+    Tries the path as-is first, then with common extensions appended.
+    """
+    candidate = (doc_dir / raw_path).resolve()
+
+    # Try exact path first
+    if candidate.exists():
+        return candidate
+
+    # Try without extension if one is present
+    if candidate.suffix:
+        # Maybe the referenced path has an extension that doesn't match the actual file
+        # Try stripping the extension and re-adding common ones
+        stem = candidate.with_suffix("")
+        for ext in _COMMON_EXTENSIONS:
+            trial = stem.with_suffix(ext)
+            if trial.exists():
+                return trial
+    else:
+        # No extension — try all common ones
+        for ext in _COMMON_EXTENSIONS:
+            trial = candidate.with_suffix(ext)
+            if trial.exists():
+                return trial
+
+    return None
+
+
+def _suggest_path(doc_dir: Path, raw_path: str) -> str:
+    """Return a suggested path hint for the error message."""
+    for ext in _COMMON_EXTENSIONS:
+        trial = (doc_dir / raw_path).with_suffix(ext)
+        if trial.exists():
+            return str(trial.relative_to(doc_dir))
+    return raw_path

src/qalmsw/cli.py

@@ -1,6 +1,7 @@
 """`qalmsw` command-line entry point."""
 from __future__ import annotations
 
+from glob import glob
 from pathlib import Path
 
 import typer
@@ -16,14 +17,15 @@ from qalmsw.checkers import (
     FigureTableChecker,
     Finding,
     GrammarChecker,
+    ImageChecker,
     ReferenceChecker,
     ReviewerChecker,
 )
 from qalmsw.document import Document
 from qalmsw.llm import LlamaCppClient
 from qalmsw.parse import scan_bib_resources
-from qalmsw.report import render_findings
-from qalmsw.retrieval import search_by_title
+from qalmsw.report import render_findings, render_findings_json
+from qalmsw.retrieval import search_by_title, set_backend
 
 app = typer.Typer(no_args_is_help=True, add_completion=False)
 console = Console()
@@ -37,7 +39,10 @@ def version() -> None:
 
 @app.command()
 def check(
-    file: Path = typer.Argument(..., exists=True, readable=True, help="Path to a .tex file"),
+    files: list[Path] = typer.Argument(
+        ...,
+        help="Path(s) to .tex file(s). Supports glob patterns (e.g. src/**/*.tex).",
+    ),
     bib: list[Path] = typer.Option(
         [],
         "--bib",
@@ -49,7 +54,13 @@ def check(
     enable_claims: bool = typer.Option(
         False,
         "--enable-claims",
-        help="Enable claim-to-reference check via Google Scholar. Slow; may hit CAPTCHAs.",
+        help="Enable claim-to-reference check via Semantic Scholar.",
+    ),
+    retrieval: str = typer.Option(
+        "semantic-scholar",
+        "--retrieval",
+        help="Retrieval backend for --enable-claims: 'semantic-scholar' (default, free API) "
+        "or 'google-scholar' (scraping, may hit CAPTCHAs).",
     ),
     concurrency: int = typer.Option(
         1,
@@ -60,8 +71,54 @@ def check(
     ),
     base_url: str | None = typer.Option(None, "--base-url", envvar="QALMSW_BASE_URL"),
     model: str | None = typer.Option(None, "--model", envvar="QALMSW_MODEL"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output results as JSON (for CI integration).",
+    ),
 ) -> None:
-    """Run QA checks on a LaTeX document."""
+    """Run QA checks on one or more LaTeX documents."""
+    resolved = _resolve_files(files)
+    if not resolved:
+        console.print("[red]error[/]: no .tex files found matching the given paths")
+        raise typer.Exit(code=1)
+
+    # Select retrieval backend for claims checker
+    set_backend(retrieval)
+
+    if len(resolved) > 1:
+        console.print(f"[dim]{len(resolved)} file(s) to check[/]")
+
+    any_errors = False
+    for file in resolved:
+        if not json_output:
+            if len(resolved) > 1:
+                console.print(f"\n[bold]{file}[/]")
+            else:
+                console.print(f"[bold]{file}[/]")
+
+        has_errors = _check_single(
+            file, bib, skip_grammar, skip_reviewer, enable_claims,
+            concurrency, base_url, model, json_output,
+        )
+        if has_errors:
+            any_errors = True
+
+    raise typer.Exit(code=1 if any_errors else 0)
+
+
+def _check_single(
+    file: Path,
+    bib: list[Path],
+    skip_grammar: bool,
+    skip_reviewer: bool,
+    enable_claims: bool,
+    concurrency: int,
+    base_url: str | None,
+    model: str | None,
+    json_output: bool,
+) -> bool:
+    """Run checks on a single file. Returns True if any errors found."""
     doc = Document.load(file)
     console.print(f"[dim]{len(doc.paragraphs)} paragraph(s) parsed[/]")
 
@@ -75,14 +132,22 @@ def check(
         )
         if inline:
             bib_entries = inline
-            console.print(f"[dim]{len(inline)} bib entries from inline \\begin{{thebibliography}}[/]")
+            console.print(
+                f"[dim]{len(inline)} bib entries from inline "
+                f"\\begin{{thebibliography}}[/]"
+            )
         else:
             console.print(
                 "[yellow]warning[/]: no bib entries found (no --bib, no \\bibliography{}, "
                 "no inline \\begin{thebibliography}); citation checks will be limited."
             )
 
-    checkers: list[Checker] = [ArtifactChecker(), FigureTableChecker(), CitationChecker(bib_entries)]
+    checkers: list[Checker] = [
+        ArtifactChecker(),
+        FigureTableChecker(),
+        ImageChecker(),
+        CitationChecker(bib_entries),
+    ]
     if bib_entries:
         checkers.append(ReferenceChecker(bib_entries))
     if not skip_grammar or not skip_reviewer or enable_claims:
@@ -98,17 +163,22 @@ def check(
     for c in checkers:
         findings.extend(c.check(doc))
 
-    render_findings(console, file, findings)
-    raise typer.Exit(code=1 if any(f.severity.value == "error" for f in findings) else 0)
+    if json_output:
+        console.print(render_findings_json(file, findings))
+    else:
+        render_findings(console, file, findings)
+
+    return any(f.severity.value == "error" for f in findings)
 
 
 @app.command()
 def scholar(
     query: list[str] = typer.Argument(..., help="Title query (may be unquoted)"),
 ) -> None:
-    """Look up the first Google Scholar match for a title query.
+    """Look up the first Semantic Scholar match for a title query.
 
-    Scraping-based; expect CAPTCHAs under sustained use.
+    Default backend is Semantic Scholar (free API, no CAPTCHAs).
+    Use --retrieval google-scholar for the scraping-based backend.
     """
     text = " ".join(query)
     result = search_by_title(text)
@@ -122,6 +192,21 @@ def scholar(
     console.print(f"[bold]abstract:[/] {result.abstract or '(no abstract)'}")
 
 
+def _resolve_files(paths: list[Path]) -> list[Path]:
+    """Expand globs and filter to existing .tex files."""
+    resolved: list[Path] = []
+    for p in paths:
+        if p.is_file():
+            resolved.append(p)
+        else:
+            # Try glob expansion on the string form
+            for match in sorted(glob(str(p))):
+                candidate = Path(match)
+                if candidate.is_file() and candidate.suffix == ".tex":
+                    resolved.append(candidate)
+    return resolved
+
+
 def _discover_bib_files(doc: Document) -> list[Path]:
     names = scan_bib_resources(doc.source)
     base_dir = doc.path.parent
@@ -140,3 +225,6 @@ def _load_bib_entries(paths: list[Path]) -> list[BibEntry]:
     for p in paths:
         entries.extend(parse_bib_file(p))
     return entries
+
+
+

src/qalmsw/report/__init__.py

@@ -1,3 +1,4 @@
+from qalmsw.report.json import render_findings_json
 from qalmsw.report.text import render_findings
 
-__all__ = ["render_findings"]
+__all__ = ["render_findings", "render_findings_json"]

src/qalmsw/report/json.py

@@ -0,0 +1,48 @@
+"""JSON report output."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from qalmsw.checkers import Finding
+
+
+def render_findings_json(file: Path, findings: list[Finding]) -> str:
+    """Return findings as a JSON string, one object with file info and results list.
+
+    Structure:
+    {
+      "file": "paper.tex",
+      "total": 3,
+      "by_severity": {"error": 1, "warning": 1, "info": 1},
+      "findings": [ ... Finding.dict() ... ]
+    }
+    """
+    by_severity: dict[str, int] = {}
+    for f in findings:
+        by_severity[f.severity.value] = by_severity.get(f.severity.value, 0) + 1
+
+    payload: dict[str, Any] = {
+        "file": str(file),
+        "total": len(findings),
+        "by_severity": by_severity,
+        "findings": [_finding_dict(f) for f in findings],
+    }
+    return json.dumps(payload, indent=2, default=str)
+
+
+def _finding_dict(f: Finding) -> dict[str, Any]:
+    d: dict[str, Any] = {
+        "checker": f.checker,
+        "severity": f.severity.value,
+        "line": f.line,
+        "message": f.message,
+    }
+    if f.suggestion is not None:
+        d["suggestion"] = f.suggestion
+    if f.excerpt is not None:
+        d["excerpt"] = f.excerpt
+    if f.file is not None:
+        d["file"] = str(f.file)
+    return d

src/qalmsw/retrieval/__init__.py

@@ -1,3 +1,33 @@
-from qalmsw.retrieval.scholar import ScholarResult, search_by_title
+"""Retrieval backends for looking up paper metadata.
 
-__all__ = ["ScholarResult", "search_by_title"]
+Default backend is Semantic Scholar (free API, no CAPTCHAs, no auth).
+Switch to Google Scholar at runtime via ``set_backend('google-scholar')``
+or use the CLI ``--retrieval`` flag.
+"""
+
+from qalmsw.retrieval.scholar import ScholarResult
+from qalmsw.retrieval.semantic_scholar import search_by_title  # noqa: F401 — re-exported
+
+__all__ = ["ScholarResult", "search_by_title", "set_backend"]
+
+
+def set_backend(name: str) -> None:
+    """Switch the active retrieval backend at runtime.
+
+    This patches the module-level ``search_by_title`` so existing imports
+    like ``from qalmsw.retrieval import search_by_title`` pick up the change.
+
+    Parameters
+    ----------
+    name
+        ``'semantic-scholar'`` (default) or ``'google-scholar'``.
+    """
+    import qalmsw.retrieval as mod
+
+    if name == "google-scholar":
+        from qalmsw.retrieval.scholar import search_by_title as _fn
+    elif name == "semantic-scholar":
+        from qalmsw.retrieval.semantic_scholar import search_by_title as _fn
+    else:
+        raise ValueError(f"Unknown retrieval backend: {name!r}")
+    mod.search_by_title = _fn

src/qalmsw/retrieval/semantic_scholar.py

@@ -0,0 +1,123 @@
+"""Semantic Scholar retrieval via the free API.
+
+Replaces Google Scholar scraping (`scholarly`) for the claims checker.
+Semantic Scholar has a free, no-auth-required API with generous rate limits.
+
+API:
+    GET /graph/v1/paper/search?query={title}&limit=3
+    &fields=title,authors,year,abstract,externalIds,url
+
+Docs:
+    https://api.semanticscholar.org/api-docs/graph
+    #tag/Paper-Data/operation/get_graph_search_papers
+
+Rate limit: ~1 req/sec for free tier. We throttle to one per second.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from qalmsw.retrieval.scholar import ScholarResult
+
+_SEARCH_URL = "https://api.semanticscholar.org/graph/v1/paper/search"
+_FIELDS = "title,authors,year,abstract,externalIds,url"
+_USER_AGENT = "qalmsw/0.0.1"
+
+_last_call = 0.0
+
+
+def search_by_title(title: str) -> ScholarResult | None:
+    """Return the first Semantic Scholar match for ``title``, or ``None``.
+
+    Uses stdlib only (no external deps). Throttled to 1 req/sec.
+    """
+    global _last_call
+
+    encoded = urllib.parse.quote(title)
+    url = f"{_SEARCH_URL}?query={encoded}&limit=3&fields={_FIELDS}"
+
+    # Rate limit: at least 1 second between calls
+    now = time.time()
+    elapsed = now - _last_call
+    if elapsed < 1.0:
+        time.sleep(1.0 - elapsed)
+
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+        with urllib.request.urlopen(req, timeout=15.0) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        _last_call = time.time()
+    except (urllib.error.HTTPError, urllib.error.URLError, json.JSONDecodeError, OSError):
+        _last_call = time.time()
+        return None
+
+    results = data.get("data", [])
+    if not results:
+        return None
+
+    best = _pick_best(results, title)
+    if best is None:
+        return None
+    return _to_result(best)
+
+
+def _pick_best(results: list[dict[str, Any]], query: str) -> dict[str, Any] | None:
+    """Return the best match from a list of results.
+
+    Tries exact title match first (case-insensitive), then falls back to first result.
+    """
+    query_lower = query.lower().strip()
+    for r in results:
+        candidate = (r.get("title") or "").lower().strip()
+        if candidate == query_lower:
+            return r
+    # Fall back to first result
+    return results[0]
+
+
+def _to_result(raw: dict[str, Any]) -> ScholarResult | None:
+    """Convert a Semantic Scholar API response to a ScholarResult."""
+    title = _coerce_str(raw.get("title"))
+    if not title:
+        return None
+
+    authors_raw = raw.get("authors") or []
+    authors = [a.get("name", "") for a in authors_raw if a.get("name")]
+
+    abstract = _coerce_str(raw.get("abstract"))
+    year = _coerce_year(raw.get("year"))
+
+    # Prefer Semantic Scholar URL, fall back to external IDs
+    url = raw.get("url") or ""
+    external_ids = raw.get("externalIds") or {}
+    if not url:
+        url = external_ids.get("ArXiv", "") or external_ids.get("DOI", "")
+
+    return ScholarResult(
+        title=title,
+        authors=authors,
+        year=year,
+        abstract=abstract,
+        url=url or None,
+    )
+
+
+def _coerce_str(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def _coerce_year(value: Any) -> int | None:
+    if value in (None, ""):
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None

tests/test_cli.py

@@ -0,0 +1,68 @@
+"""Tests for CLI batch mode and retrieval backend switching."""
+from pathlib import Path
+
+from qalmsw.retrieval import search_by_title, set_backend
+from qalmsw.retrieval.scholar import search_by_title as gs_search
+from qalmsw.retrieval.semantic_scholar import search_by_title as ss_search
+
+
+def test_default_backend_is_semantic_scholar():
+    """Module-level search_by_title should point to Semantic Scholar by default."""
+    assert search_by_title is ss_search
+
+
+def test_set_backend_google_scholar():
+    """Switching to google-scholar patches the module-level function."""
+    import qalmsw.retrieval as mod
+    original = mod.search_by_title
+    set_backend("google-scholar")
+    try:
+        assert mod.search_by_title is gs_search
+    finally:
+        # Restore
+        set_backend("semantic-scholar")
+    assert mod.search_by_title is original
+
+
+def test_set_backend_semantic_scholar():
+    """Switching back to semantic-scholar restores the original."""
+    import qalmsw.retrieval as mod
+    set_backend("google-scholar")
+    set_backend("semantic-scholar")
+    assert mod.search_by_title is ss_search
+
+
+def test_set_backend_unknown_raises():
+    """Unknown backend name raises ValueError."""
+    import pytest
+    with pytest.raises(ValueError, match="Unknown retrieval backend"):
+        set_backend("bing")
+
+
+def test_resolve_files_single(tmp_path: Path):
+    """Single existing .tex file is returned as-is."""
+    tex = tmp_path / "paper.tex"
+    tex.write_text(r"\documentclass{article}\begin{document}hello\end{document}")
+    from qalmsw.cli import _resolve_files
+    resolved = _resolve_files([tex])
+    assert len(resolved) == 1
+    assert resolved[0] == tex
+
+
+def test_resolve_files_glob(tmp_path: Path):
+    """Glob pattern expands to matching .tex files."""
+    (tmp_path / "ch1.tex").write_text("chapter 1")
+    (tmp_path / "ch2.tex").write_text("chapter 2")
+    (tmp_path / "notes.txt").write_text("not a tex file")
+    from qalmsw.cli import _resolve_files
+    resolved = _resolve_files([tmp_path / "ch*.tex"])
+    assert len(resolved) == 2
+    names = {f.name for f in resolved}
+    assert names == {"ch1.tex", "ch2.tex"}
+
+
+def test_resolve_files_no_match(tmp_path: Path):
+    """Glob with no matches returns empty list."""
+    from qalmsw.cli import _resolve_files
+    resolved = _resolve_files([tmp_path / "nonexistent*.tex"])
+    assert resolved == []

tests/test_images.py

@@ -0,0 +1,102 @@
+"""Tests for the Image file existence checker."""
+from pathlib import Path
+
+from qalmsw.checkers import ImageChecker, Severity
+from qalmsw.document import Document
+
+
+def _doc(source: str, path: Path) -> Document:
+    return Document(path=path, source=source, paragraphs=[])
+
+
+def test_image_exists(tmp_path: Path):
+    """An existing image file is silent."""
+    img = tmp_path / "results.png"
+    img.write_text("fake png")
+    tex = tmp_path / "paper.tex"
+    source = rf"\begin{{document}}\includegraphics{{{img.name}}}\end{{document}}"
+    tex.write_text(source)
+    findings = ImageChecker().check(_doc(source, tex))
+    assert findings == []
+
+
+def test_image_missing_is_error(tmp_path: Path):
+    """A missing image file is an error."""
+    tex = tmp_path / "paper.tex"
+    source = r"\begin{document}\includegraphics{missing_plot.png}\end{document}"
+    tex.write_text(source)
+    findings = ImageChecker().check(_doc(source, tex))
+    errors = [f for f in findings if f.severity == Severity.error]
+    assert len(errors) >= 1
+    assert "missing_plot.png" in errors[0].message
+
+
+def test_no_extension_checks_common_formats(tmp_path: Path):
+    """When no extension is given, try common image extensions."""
+    img = tmp_path / "results.pdf"  # exists as .pdf
+    img.write_text("fake pdf")
+    tex = tmp_path / "paper.tex"
+    source = r"\begin{document}\includegraphics{results}\end{document}"
+    tex.write_text(source)
+    findings = ImageChecker().check(_doc(source, tex))
+    assert findings == []
+
+
+def test_multiple_images_some_missing(tmp_path: Path):
+    """Only missing images are flagged."""
+    img = tmp_path / "good.png"
+    img.write_text("fake png")
+    tex = tmp_path / "paper.tex"
+    source = (
+        r"\begin{document}"
+        r"\includegraphics{good.png}"
+        r"\includegraphics{bad.jpg}"
+        r"\includegraphics{also_missing.png}"
+        r"\end{document}"
+    )
+    tex.write_text(source)
+    findings = ImageChecker().check(_doc(source, tex))
+    missing = [f for f in findings if "not found" in f.message]
+    assert len(missing) == 2
+    assert all(f.severity == Severity.error for f in missing)
+
+
+def test_skips_non_image_extensions(tmp_path: Path):
+    """Don't flag .tex, .cls, .bib paths as missing images."""
+    tex = tmp_path / "paper.tex"
+    source = r"\begin{document}\includegraphics{appendix.tex}\end{document}"
+    tex.write_text(source)
+    findings = ImageChecker().check(_doc(source, tex))
+    assert findings == []
+
+
+def test_empty_graphics_path_is_ignored(tmp_path: Path):
+    """Empty {} inside `includegraphics` is skipped."""
+    tex = tmp_path / "paper.tex"
+    source = r"\begin{document}\includegraphics{}\end{document}"
+    tex.write_text(source)
+    findings = ImageChecker().check(_doc(source, tex))
+    assert findings == []
+
+
+def test_path_with_subdirectory(tmp_path: Path):
+    """Images in subdirectories relative to the .tex file."""
+    figures = tmp_path / "figures"
+    figures.mkdir()
+    img = figures / "arch.pdf"
+    img.write_text("fake pdf")
+    tex = tmp_path / "paper.tex"
+    source = r"\begin{document}\includegraphics{figures/arch.pdf}\end{document}"
+    tex.write_text(source)
+    findings = ImageChecker().check(_doc(source, tex))
+    assert findings == []
+
+
+def test_path_with_subdirectory_missing(tmp_path: Path):
+    """Missing image in subdirectory is flagged."""
+    tex = tmp_path / "paper.tex"
+    source = r"\begin{document}\includegraphics{figures/missing.pdf}\end{document}"
+    tex.write_text(source)
+    findings = ImageChecker().check(_doc(source, tex))
+    errors = [f for f in findings if f.severity == Severity.error]
+    assert len(errors) == 1

tests/test_scholar.py

@@ -1,70 +0,0 @@
-from unittest.mock import patch
-
-from qalmsw.retrieval import ScholarResult, search_by_title
-
-
-def _fake_pub(**bib_overrides) -> dict:
-    bib = {
-        "title": "Attention Is All You Need",
-        "author": ["Ashish Vaswani", "Noam Shazeer"],
-        "pub_year": "2017",
-        "abstract": "We propose a new architecture, the Transformer.",
-    }
-    bib.update(bib_overrides)
-    return {"bib": bib, "pub_url": "https://arxiv.org/abs/1706.03762"}
-
-
-def test_search_by_title_returns_first_match():
-    with patch(
-        "qalmsw.retrieval.scholar.scholarly.search_pubs", return_value=iter([_fake_pub()])
-    ):
-        result = search_by_title("attention transformer")
-    assert isinstance(result, ScholarResult)
-    assert result.title == "Attention Is All You Need"
-    assert result.authors == ["Ashish Vaswani", "Noam Shazeer"]
-    assert result.year == 2017
-    assert "Transformer" in result.abstract
-    assert result.url == "https://arxiv.org/abs/1706.03762"
-
-
-def test_search_by_title_returns_none_when_no_results():
-    with patch("qalmsw.retrieval.scholar.scholarly.search_pubs", return_value=iter([])):
-        assert search_by_title("no such paper xyzzy") is None
-
-
-def test_author_string_is_split_on_and():
-    raw = _fake_pub(author="Ashish Vaswani and Noam Shazeer and Niki Parmar")
-    with patch("qalmsw.retrieval.scholar.scholarly.search_pubs", return_value=iter([raw])):
-        result = search_by_title("x")
-    assert result is not None
-    assert result.authors == ["Ashish Vaswani", "Noam Shazeer", "Niki Parmar"]
-
-
-def test_missing_fields_produce_safe_defaults():
-    raw = {"bib": {}}
-    with patch("qalmsw.retrieval.scholar.scholarly.search_pubs", return_value=iter([raw])):
-        result = search_by_title("x")
-    assert result is not None
-    assert result.title == ""
-    assert result.authors == []
-    assert result.year is None
-    assert result.abstract == ""
-    assert result.url is None
-
-
-def test_non_numeric_year_coerces_to_none():
-    raw = _fake_pub(pub_year="in press")
-    with patch("qalmsw.retrieval.scholar.scholarly.search_pubs", return_value=iter([raw])):
-        result = search_by_title("x")
-    assert result is not None
-    assert result.year is None
-
-
-def test_eprint_url_used_when_pub_url_missing():
-    raw = _fake_pub()
-    raw.pop("pub_url")
-    raw["eprint_url"] = "https://example.org/eprint.pdf"
-    with patch("qalmsw.retrieval.scholar.scholarly.search_pubs", return_value=iter([raw])):
-        result = search_by_title("x")
-    assert result is not None
-    assert result.url == "https://example.org/eprint.pdf"

tests/test_semantic_scholar.py

@@ -0,0 +1,101 @@
+"""Tests for Semantic Scholar retrieval module."""
+from unittest.mock import patch
+
+from qalmsw.retrieval import ScholarResult, search_by_title
+
+
+def _mock_response(data: list[dict]) -> dict:
+    return {"data": data}
+
+
+def _paper(
+    title: str = "Attention Is All You Need",
+    authors: list[str] | None = None,
+    year: int | None = 2017,
+    abstract: str = "We propose the Transformer architecture.",
+    arxiv_id: str = "1706.03762",
+    url: str = "https://api.semanticscholar.org/CorpusID:1",
+) -> dict:
+    return {
+        "title": title,
+        "authors": [{"name": a} for a in (authors or ["Ashish Vaswani", "Noam Shazeer"])],
+        "year": year,
+        "abstract": abstract,
+        "externalIds": {"ArXiv": arxiv_id} if arxiv_id else {},
+        "url": url,
+    }
+
+
+def _mock_urlopen(json_data: dict):
+    """Return a mock urlopen context manager."""
+    import json as _json
+    from unittest.mock import MagicMock
+
+    cm = MagicMock()
+    cm.__enter__.return_value.read.return_value = _json.dumps(json_data).encode("utf-8")
+    return cm
+
+
+def test_search_by_title_returns_first_match():
+    data = _mock_response([_paper()])
+    with patch("qalmsw.retrieval.semantic_scholar.urllib.request.urlopen",
+               return_value=_mock_urlopen(data)):
+        result = search_by_title("attention transformer")
+    assert isinstance(result, ScholarResult)
+    assert result.title == "Attention Is All You Need"
+    assert result.authors == ["Ashish Vaswani", "Noam Shazeer"]
+    assert result.year == 2017
+    assert "Transformer" in result.abstract
+    assert "semanticscholar" in (result.url or "")
+
+
+def test_search_by_title_returns_none_when_no_results():
+    data = _mock_response([])
+    with patch("qalmsw.retrieval.semantic_scholar.urllib.request.urlopen",
+               return_value=_mock_urlopen(data)):
+        assert search_by_title("no such paper xyzzy") is None
+
+
+def test_search_by_title_returns_none_on_http_error():
+    import urllib.error
+
+    def _raise(*args, **kwargs):
+        raise urllib.error.HTTPError(
+            "http://example.com", 429, "Too Many", {}, None
+        )
+
+    with patch("qalmsw.retrieval.semantic_scholar.urllib.request.urlopen", _raise):
+        assert search_by_title("any title") is None
+
+
+def test_missing_fields_produce_safe_defaults():
+    data = _mock_response([
+        _paper(
+            title="", authors=None, year=None,
+            abstract="", arxiv_id="", url="",
+        )
+    ])
+    with patch("qalmsw.retrieval.semantic_scholar.urllib.request.urlopen",
+               return_value=_mock_urlopen(data)):
+        result = search_by_title("x")
+    assert result is None  # empty title → None
+
+
+def test_empty_title_returns_none():
+    data = _mock_response([_paper(title="", authors=None)])
+    with patch("qalmsw.retrieval.semantic_scholar.urllib.request.urlopen",
+               return_value=_mock_urlopen(data)):
+        assert search_by_title("x") is None
+
+
+def test_exact_title_match_is_preferred():
+    data = _mock_response([
+        _paper(title="Some Related Work", year=2020),
+        _paper(title="Attention Is All You Need", year=2017),
+    ])
+    with patch("qalmsw.retrieval.semantic_scholar.urllib.request.urlopen",
+               return_value=_mock_urlopen(data)):
+        result = search_by_title("Attention Is All You Need")
+    assert result is not None
+    assert result.title == "Attention Is All You Need"
+    assert result.year == 2017