papercheck 0.3.0__py3-none-any.whl

papercheck/__init__.py

@@ -0,0 +1,3 @@
+"""papercheck — a reproducible audit harness for mathematical LaTeX papers."""
+
+__version__ = "0.3.0"

papercheck/cli/__init__.py

@@ -0,0 +1 @@
+"""Typer command-line interface for papercheck."""

papercheck/cli/main.py

@@ -0,0 +1,324 @@
+"""papercheck command-line interface.
+
+Defines the Typer ``app`` and command stubs. Command bodies are filled in later
+phases; for now they echo a placeholder so ``papercheck --help`` lists them all.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from papercheck.core import paths, texscan
+
+app = typer.Typer(help="papercheck — audit harness for mathematical LaTeX papers")
+
+
+@app.command()
+def init(
+    paper_root: str = typer.Argument(..., help="Path to the paper's source root."),
+) -> None:
+    """Initialize a paper's audit workspace."""
+    import datetime
+
+    from papercheck.mcp_server import handlers
+
+    run_id = datetime.datetime.now().strftime("%Y-%m-%dT%H-%M-%SZ")
+    state = handlers.init_audit(paper_root, run_id=run_id)
+    typer.echo(f"Initialized audit at {paths.audit_dir(Path(paper_root))}")
+    typer.echo(f"  run_id: {state['run_id']}")
+    typer.echo(f"  stage:  {state['stage']}")
+    raise typer.Exit(0)
+
+
+@app.command()
+def scan(
+    paper_root: str = typer.Argument(..., help="Path to the paper's source root."),
+    json_out: bool = typer.Option(
+        False, "--json", help="Print the full structure JSON instead of a summary."
+    ),
+) -> None:
+    """Scan a paper's LaTeX sources into a structured representation."""
+    root = Path(paper_root)
+    result = texscan.scan(root)
+
+    if json_out:
+        typer.echo(json.dumps(result, indent=2))
+        raise typer.Exit(0)
+
+    typer.echo(f"Scanned {root}")
+    typer.echo(f"  tex files:             {len(result['files']['tex'])}")
+    typer.echo(f"  theorem envs:          {len(result['theorem_envs'])}")
+    typer.echo(f"  duplicate labels:      {len(result['duplicate_labels'])}")
+    typer.echo(f"  unresolved refs:       {len(result['unresolved_refs'])}")
+    typer.echo(f"  unresolved citations:  {len(result['unresolved_citations'])}")
+    typer.echo(f"  draft markers:         {len(result['draft_markers'])}")
+    typer.echo(f"structure.json -> {paths.structure_file(root)}")
+    raise typer.Exit(0)
+
+
+@app.command()
+def segments(
+    paper_root: str = typer.Argument(..., help="Path to the paper's source root."),
+) -> None:
+    """Propose audit segments for a paper."""
+    from papercheck.core import segments as segments_mod
+
+    root = Path(paper_root)
+    struct_path = paths.structure_file(root)
+    if struct_path.exists():
+        structure = json.loads(struct_path.read_text(encoding="utf-8"))
+    else:
+        structure = texscan.scan(root)
+
+    records = segments_mod.write_segments(root, structure)
+
+    budget_counts: dict[str, int] = {}
+    for rec in records:
+        budget_counts[rec["budget"]] = budget_counts.get(rec["budget"], 0) + 1
+    summary = ", ".join(
+        f"{level}={budget_counts.get(level, 0)}" for level in ("HIGH", "MEDIUM", "LOW")
+    )
+    typer.echo(f"Proposed {len(records)} segment(s): {summary}")
+    typer.echo(f"segments.json -> {paths.segments_file(root)}")
+    raise typer.Exit(0)
+
+
+@app.command()
+def gate(
+    paper_root: str = typer.Argument(..., help="Path to the paper's source root."),
+    mechanical_only: bool = typer.Option(
+        False, "--mechanical-only", help="Run only the mechanical gate signals."
+    ),
+) -> None:
+    """Run the final gate checks for a paper."""
+    from papercheck.core.gate import run_gate
+
+    root = Path(paper_root)
+    result = run_gate(root, mechanical_only=mechanical_only)
+
+    typer.echo("")
+    typer.echo(f"==== {result['verdict']} ====")
+    blockers = result.get("blockers", [])
+    if blockers:
+        typer.echo("Blockers:")
+        for b in blockers:
+            typer.echo(f"  - {b}")
+    else:
+        typer.echo("No blockers.")
+
+    ready = result["verdict"] in {"READY", "READY AFTER MECHANICAL FIXES"}
+    raise typer.Exit(0 if ready else 1)
+
+
+@app.command()
+def render(
+    paper_root: str = typer.Argument(..., help="Path to the paper's source root."),
+) -> None:
+    """Render audit reports for a paper."""
+    from papercheck.core.render import render_all
+
+    root = Path(paper_root)
+    render_all(root)
+
+    out_dir = paths.audit_dir(root)
+    candidates = [
+        "03_segment_map.md",
+        "07_issue_ledger.proposed.md",
+        "08_issue_ledger.adjudicated.md",
+        "10_final_acceptance_gate.md",
+        "manual_check_queue.md",
+    ]
+    written = [name for name in candidates if (out_dir / name).exists()]
+    if written:
+        typer.echo("Wrote:")
+        for name in written:
+            typer.echo(f"  - {out_dir / name}")
+    else:
+        typer.echo("No reports written (no source artifacts found).")
+    raise typer.Exit(0)
+
+
+@app.command("verify-quote")
+def verify_quote(
+    file: Path = typer.Argument(..., help="Path to the source file to search."),
+    quote: str = typer.Argument(..., help="The exact quote to look for."),
+    line_start: int | None = typer.Option(None, "--line-start", help="1-based start line."),
+    line_end: int | None = typer.Option(None, "--line-end", help="1-based end line."),
+    slack: int = typer.Option(0, "--slack", help="Lines of slack around the window."),
+) -> None:
+    """Verify that a quote appears in a paper's source."""
+    from papercheck.core.verify import verify_quote as _verify_quote
+
+    found = _verify_quote(file, quote, line_start, line_end, slack)
+    typer.echo("QUOTE FOUND" if found else "QUOTE NOT FOUND")
+    raise typer.Exit(code=0 if found else 1)
+
+
+@app.command()
+def prompts(
+    action: str = typer.Argument("list", help="Either 'list' or 'show'."),
+    name: str | None = typer.Argument(None, help="Prompt name (for 'show')."),
+) -> None:
+    """Show the audit prompt pack ('list' names, or 'show <name>')."""
+    from papercheck.mcp_server import handlers
+
+    if action == "list":
+        typer.echo(handlers.list_prompts())
+        raise typer.Exit(0)
+    if action == "show":
+        if not name:
+            typer.echo("prompts show requires a NAME argument")
+            raise typer.Exit(2)
+        try:
+            typer.echo(handlers.get_prompt(name))
+        except KeyError:
+            typer.echo(f"No such prompt: {name}")
+            raise typer.Exit(1) from None
+        raise typer.Exit(0)
+    typer.echo(f"Unknown action {action!r}; expected 'list' or 'show'")
+    raise typer.Exit(2)
+
+
+@app.command()
+def report(
+    paper_root: str = typer.Argument(..., help="Path to the paper's source root."),
+) -> None:
+    """Render a self-contained HTML audit report from the Paper_Audit artifacts."""
+    from papercheck.core.html_report import render_html
+
+    out = render_html(Path(paper_root))
+    typer.echo(f"HTML report -> {out}")
+    raise typer.Exit(0)
+
+
+@app.command()
+def compare(
+    old_root: str = typer.Argument(..., help="Path to the OLD version's source root."),
+    new_root: str = typer.Argument(..., help="Path to the NEW version's source root."),
+) -> None:
+    """Compare two versions of a paper and write a structural diff report."""
+    from papercheck.core.compare import write_compare_report
+
+    out = write_compare_report(Path(old_root), Path(new_root))
+    typer.echo(f"Version comparison -> {out}")
+    raise typer.Exit(0)
+
+
+@app.command()
+def profile(
+    action: str = typer.Argument("list", help="Either 'list' or 'show'."),
+    name: str | None = typer.Argument(None, help="Profile name (for 'show')."),
+) -> None:
+    """List advisory audit profiles, or show one profile's recommended steps."""
+    from papercheck.core import profiles as profiles_mod
+
+    if action == "list":
+        for pname in profiles_mod.list_profiles():
+            prof = profiles_mod.get_profile(pname)
+            typer.echo(f"{pname}: {prof.get('description', '')}")
+        raise typer.Exit(0)
+    if action == "show":
+        if not name:
+            typer.echo("profile show requires a NAME argument")
+            raise typer.Exit(2)
+        try:
+            prof = profiles_mod.get_profile(name)
+        except KeyError:
+            typer.echo(f"No such profile: {name}")
+            raise typer.Exit(1) from None
+        typer.echo(f"{name}: {prof.get('description', '')}")
+        typer.echo(f"  mechanical_only: {prof.get('mechanical_only')}")
+        typer.echo("  steps:")
+        for step in prof.get("steps", []):
+            typer.echo(f"    - {step}")
+        raise typer.Exit(0)
+    typer.echo(f"Unknown action {action!r}; expected 'list' or 'show'")
+    raise typer.Exit(2)
+
+
+@app.command()
+def packs(
+    action: str = typer.Argument("list", help="One of 'list', 'show', 'scaffold', 'create'."),
+    name: str | None = typer.Argument(None, help="Pack name (for 'show')."),
+    paper_root: str | None = typer.Option(
+        None, "--paper-root", help="Paper root, for paper-local scaffold/create/generated packs."
+    ),
+) -> None:
+    """Manage domain packs: list/show shipped packs, or scaffold/create one from a paper."""
+    from papercheck.core import domainpack
+
+    root = Path(paper_root) if paper_root else None
+
+    if action == "list":
+        for pname in domainpack.list_packs(root):
+            typer.echo(pname)
+        raise typer.Exit(0)
+    if action == "show":
+        if not name:
+            typer.echo("packs show requires a NAME argument")
+            raise typer.Exit(2)
+        try:
+            typer.echo(json.dumps(domainpack.load_pack(name, root), indent=2))
+        except KeyError:
+            typer.echo(f"No such domain pack: {name}")
+            raise typer.Exit(1) from None
+        raise typer.Exit(0)
+    if action == "scaffold":
+        if root is None:
+            typer.echo("packs scaffold requires --paper-root")
+            raise typer.Exit(2)
+        struct_path = paths.structure_file(root)
+        if struct_path.exists():
+            structure = json.loads(struct_path.read_text(encoding="utf-8"))
+        else:
+            structure = texscan.scan(root)
+        typer.echo(json.dumps(domainpack.scaffold_pack(structure), indent=2))
+        typer.echo("")
+        typer.echo(
+            "# Draft only. Refine the fields, save to a JSON file, "
+            "then: papercheck packs create --paper-root <root> <file.json>"
+        )
+        raise typer.Exit(0)
+    if action == "create":
+        if root is None:
+            typer.echo("packs create requires --paper-root")
+            raise typer.Exit(2)
+        if not name:
+            typer.echo("packs create requires a PATH to a pack JSON file as NAME argument")
+            raise typer.Exit(2)
+        pack = json.loads(Path(name).read_text(encoding="utf-8"))
+        out = domainpack.create_pack(root, pack)
+        typer.echo(f"Domain pack -> {out}")
+        raise typer.Exit(0)
+    typer.echo(f"Unknown action {action!r}; expected list/show/scaffold/create")
+    raise typer.Exit(2)
+
+
+@app.command()
+def serve(
+    paper_root: str = typer.Argument(..., help="Path to the paper's source root."),
+    host: str = typer.Option("127.0.0.1", "--host", help="Host to bind (localhost)."),
+    port: int = typer.Option(8765, "--port", help="Port to bind."),
+    open_browser: bool = typer.Option(
+        False, "--open", help="Open the UI in a web browser after starting."
+    ),
+) -> None:
+    """Serve an interactive local web UI for a paper's audit state (blocking)."""
+    from papercheck.core.webserve import serve as _serve
+
+    _serve(Path(paper_root), host=host, port=port, open_browser=open_browser)
+
+
+@app.command()
+def mcp() -> None:
+    """Run the papercheck MCP server (blocking stdio transport)."""
+    from papercheck.mcp_server.server import main as _server_main
+
+    _server_main()
+
+
+if __name__ == "__main__":
+    app()

papercheck/core/__init__.py

@@ -0,0 +1 @@
+"""Deterministic core of the papercheck audit harness."""

papercheck/core/_resources.py

@@ -0,0 +1,38 @@
+"""Locate bundled data directories in both installed and source layouts.
+
+The four data directories (``schemas``, ``prompts``, ``templates``,
+``domain_packs``) live at the repo root during development but are copied
+*inside* the package (via hatchling ``force-include``) when a wheel is built.
+This module resolves either layout so runtime code works identically whether
+``papercheck`` is an editable checkout or an installed wheel.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resource_dir(name: str) -> Path:
+    """Return the directory for a bundled data resource.
+
+    Tries, in order:
+
+    (a) package-relative — ``site-packages/papercheck/<name>`` in an installed
+        wheel (``.parent.parent`` of this file is ``papercheck/``);
+    (b) repo-root fallback — ``<repo>/<name>`` in an editable/source layout
+        (``parents[3]`` of this file is the repo root).
+
+    Raises :class:`FileNotFoundError` if neither exists.
+    """
+    packaged = Path(__file__).resolve().parent.parent / name
+    if packaged.is_dir():
+        return packaged
+    repo_root = Path(__file__).resolve().parents[3] / name
+    if repo_root.is_dir():
+        return repo_root
+    raise FileNotFoundError(name)
+
+
+def resource_file(name: str, filename: str) -> Path:
+    """Return the path to ``filename`` inside the named resource directory."""
+    return resource_dir(name) / filename

papercheck/core/adjudicate.py

@@ -0,0 +1,228 @@
+"""Adjudication, patch planning, and regression helpers.
+
+These functions operate on the file-based ledgers to move issues through their
+post-audit lifecycle: an adjudicator accepts/rejects/defers each proposed
+issue, accepted issues are folded into planned then applied patches, and
+regression results are recorded. Manual checks are created and resolved here
+too.
+
+All functions are pure with respect to wall-clock time (no timestamps are
+generated) so they remain deterministic and testable.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from papercheck.core import ledger, schemas
+from papercheck.core.paths import audit_dir, manual_checks_dir
+
+# Decisions accepted by :func:`adjudicate_issue` and the status each maps to.
+_DECISION_TO_STATUS: dict[str, str] = {
+    "ACCEPT": "ACCEPTED",
+    "REJECT": "REJECTED",
+    "NEEDS_MANUAL_CHECK": "NEEDS_MANUAL_CHECK",
+}
+
+# Issue statuses that count as belonging to the "accepted family": an issue in
+# any of these has passed adjudication and is eligible for patch planning.
+_ACCEPTED_FAMILY: frozenset[str] = frozenset(
+    {"ACCEPTED", "PATCH_PLANNED", "PATCHED", "REGRESSION_PASSED", "CLOSED"}
+)
+
+# Regression outcomes accepted by :func:`record_regression_result`.
+_REGRESSION_RESULTS: frozenset[str] = frozenset(
+    {"FIXED", "PARTIALLY_FIXED", "NOT_FIXED", "NEW_PROBLEM"}
+)
+
+
+def _regression_file(paper_root: Path) -> Path:
+    return audit_dir(Path(paper_root)) / "regression.json"
+
+
+def adjudicate_issue(
+    paper_root: Path,
+    issue_id: str,
+    decision: str,
+    rationale: str,
+    adjudicator: str,
+    severity_final: str | None = None,
+) -> dict:
+    """Record an adjudication decision on an issue and re-route its file.
+
+    ``decision`` must be one of ACCEPT / REJECT / NEEDS_MANUAL_CHECK. The issue
+    is loaded from whichever status folder holds it, annotated with the
+    decision, optionally given a final severity, and re-saved into the folder
+    implied by its new status.
+
+    Raises :class:`KeyError` when the issue is absent and :class:`ValueError`
+    for an unknown decision.
+    """
+    paper_root = Path(paper_root)
+
+    if decision not in _DECISION_TO_STATUS:
+        raise ValueError(
+            f"Unknown decision {decision!r}; expected one of "
+            f"{sorted(_DECISION_TO_STATUS)}"
+        )
+
+    # KeyError propagates when the issue does not exist.
+    issue = ledger.load_issue(paper_root, issue_id)
+
+    issue["adjudication"] = {
+        "decision": decision,
+        "rationale": rationale,
+        "adjudicator": adjudicator,
+    }
+    if severity_final is not None:
+        issue["severity_final"] = severity_final
+    issue["status"] = _DECISION_TO_STATUS[decision]
+
+    # Remove the old file (it may live in a different folder than the new
+    # status routes to) before saving the mutated issue.
+    old_path = ledger._find_issue_path(paper_root, issue_id)
+    if old_path is not None:
+        old_path.unlink()
+    ledger.save_issue(paper_root, issue)
+    return issue
+
+
+def plan_patch(paper_root: Path, patch: dict) -> dict:
+    """Validate and record a *planned* patch over accepted issues.
+
+    Refuses (raises :class:`ValueError`) unless every id in
+    ``patch["accepted_issue_ids"]`` refers to an issue currently in an
+    accepted-family status. On success the patch is saved and each referenced
+    issue is bumped to ``PATCH_PLANNED``.
+    """
+    paper_root = Path(paper_root)
+    schemas.validate(patch, "patch")
+
+    for issue_id in patch["accepted_issue_ids"]:
+        try:
+            issue = ledger.load_issue(paper_root, issue_id)
+        except KeyError as exc:
+            raise ValueError(
+                f"Patch references unknown issue {issue_id!r}"
+            ) from exc
+        if issue.get("status") not in _ACCEPTED_FAMILY:
+            raise ValueError(
+                f"Patch references issue {issue_id!r} with non-accepted status "
+                f"{issue.get('status')!r}"
+            )
+
+    ledger.save_patch(paper_root, patch)
+    for issue_id in patch["accepted_issue_ids"]:
+        ledger.move_issue(paper_root, issue_id, "PATCH_PLANNED")
+    return patch
+
+
+def record_patch(paper_root: Path, patch: dict) -> dict:
+    """Validate and record an *applied* patch, moving issues to ``PATCHED``.
+
+    Like :func:`plan_patch` but represents a patch that has actually been
+    applied; referenced issues are moved to ``PATCHED``.
+    """
+    paper_root = Path(paper_root)
+    schemas.validate(patch, "patch")
+
+    for issue_id in patch["accepted_issue_ids"]:
+        try:
+            issue = ledger.load_issue(paper_root, issue_id)
+        except KeyError as exc:
+            raise ValueError(
+                f"Patch references unknown issue {issue_id!r}"
+            ) from exc
+        if issue.get("status") not in _ACCEPTED_FAMILY:
+            raise ValueError(
+                f"Patch references issue {issue_id!r} with non-accepted status "
+                f"{issue.get('status')!r}"
+            )
+
+    ledger.save_patch(paper_root, patch)
+    for issue_id in patch["accepted_issue_ids"]:
+        ledger.move_issue(paper_root, issue_id, "PATCHED")
+    return patch
+
+
+def record_regression_result(paper_root: Path, issue_id: str, result: str) -> dict:
+    """Append a regression outcome for an issue; promote it if ``FIXED``.
+
+    Results are appended to ``Paper_Audit/regression.json`` (a JSON list). A
+    ``FIXED`` result also moves the issue to ``REGRESSION_PASSED``.
+
+    Raises :class:`ValueError` for an unknown result.
+    """
+    paper_root = Path(paper_root)
+    if result not in _REGRESSION_RESULTS:
+        raise ValueError(
+            f"Unknown regression result {result!r}; expected one of "
+            f"{sorted(_REGRESSION_RESULTS)}"
+        )
+
+    path = _regression_file(paper_root)
+    if path.exists():
+        records = json.loads(path.read_text(encoding="utf-8"))
+    else:
+        records = []
+    entry = {"issue_id": issue_id, "result": result}
+    records.append(entry)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(records, indent=2) + "\n", encoding="utf-8")
+
+    if result == "FIXED":
+        ledger.move_issue(paper_root, issue_id, "REGRESSION_PASSED")
+
+    return dict(entry)
+
+
+def next_check_id(paper_root: Path) -> str:
+    """Return the next unused manual-check id (e.g. ``MANUAL-3``)."""
+    max_n = 0
+    for check in ledger.list_manual_checks(Path(paper_root)):
+        check_id = check.get("check_id", "")
+        prefix, sep, suffix = check_id.rpartition("-")
+        if sep and prefix == "MANUAL" and suffix.isdigit():
+            max_n = max(max_n, int(suffix))
+    return f"MANUAL-{max_n + 1}"
+
+
+def add_manual_check(
+    paper_root: Path,
+    question: str,
+    needed_source: str | None = None,
+    blocking: bool = True,
+    owner: str = "human",
+) -> dict:
+    """Create, validate, and persist a new manual check. Return it."""
+    paper_root = Path(paper_root)
+    check = {
+        "check_id": next_check_id(paper_root),
+        "question": question,
+        "needed_source": needed_source,
+        "blocking": blocking,
+        "owner": owner,
+        "resolution": None,
+        "resolved": False,
+    }
+    schemas.validate(check, "manual_check")
+    ledger.save_manual_check(paper_root, check)
+    return check
+
+
+def resolve_manual_check(paper_root: Path, check_id: str, resolution: str) -> dict:
+    """Mark a manual check resolved with the given resolution text. Return it.
+
+    Raises :class:`KeyError` if the check does not exist.
+    """
+    paper_root = Path(paper_root)
+    path = manual_checks_dir(paper_root) / f"{check_id}.json"
+    if not path.is_file():
+        raise KeyError(f"Manual check {check_id!r} not found")
+    check = json.loads(path.read_text(encoding="utf-8"))
+    check["resolved"] = True
+    check["resolution"] = resolution
+    schemas.validate(check, "manual_check")
+    ledger.save_manual_check(paper_root, check)
+    return check