machinechecked 0.1.0__py3-none-any.whl

prooflens/promote.py

@@ -0,0 +1,204 @@
+"""Promotion of review reports: from a reviewer's report to the project's review markers.
+
+A report (exported from the review queue) records what a reviewer read, compared and decided.
+Promotion is the maintainer's step. It refuses a report that does not apply to the project as
+it now is, or that the acceptance rules cannot count as an independent review:
+
+* the evidence must be current (the Lean inputs unchanged since the last build);
+* the unit's fingerprints (and the 32-digit legacy hash the markers record) and the manuscript
+  revisions must be those the report was made at;
+* the verdict must be faithful, faithful with representation choices (listed), or broader (with
+  the instantiation that gives the printed claim);
+* the reading must have been locked before the verdict, and the verdict recorded before the
+  author's review was shown;
+* the reviewer must not be an author of the statements, and a model of the same family as the
+  author (or of unknown family) is refused unless the maintainer accepts it explicitly.
+
+For each report it accepts, it archives the report (JSON and the protocol's text block) and
+writes `<!-- spec-review: NAME HASH by=REVIEWER -->` (or `def-review`) after the declaration's
+last marker, in the exact form the acceptance checker reads, then assesses the stored evidence
+again. A promoted marker records the reviewer the report names; who they are is as the report
+states it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from . import evidence as ev
+from .config import Config
+from .reviews import history, load_reviews, review_files
+from .util import read_json
+
+ACCEPTABLE = {"faithful", "faithful with representation choices", "broader"}
+NEEDS_DETAIL = {"faithful with representation choices", "broader"}
+HEX32 = re.compile(r"^[0-9a-f]{32}$")
+
+
+class PromoteError(RuntimeError):
+    pass
+
+
+def latest_record(cfg: Config) -> dict:
+    rels = sorted((cfg.out_dir / "releases").glob("*.json"), key=lambda p: p.stat().st_mtime)
+    if not rels:
+        raise PromoteError("no release: run `prooflens build` first")
+    return ev.load(cfg.out_dir, read_json(rels[-1])["evidence"])
+
+
+def load_reports(paths: list[Path]) -> list[dict]:
+    out = []
+    for p in paths:
+        d = json.loads(Path(p).read_text(encoding="utf-8"))
+        out += d["reports"] if "reports" in d else [d]
+    return out
+
+
+def check_report(r: dict, body: dict, cfg: Config, accept_same_family: bool) -> list[str]:
+    """Why `r` cannot be promoted against the evidence `body` (empty if it can)."""
+    why = []
+    if r.get("schema") != "prooflens/review-report@1":
+        return [f"not a review report (schema {r.get('schema')!r})"]
+    u, pins, rev = r["unit"], r["pins"], r["reviewer"]
+    lean = body.get("lean") or {}
+    if u["kind"] == "spec":
+        cur = lean.get("specs", {}).get(u["name"])
+    elif u["kind"] == "def":
+        cur = lean.get("decls", {}).get(u["name"])
+    else:
+        return [f"a {u['kind']} unit has no review marker in this project"]
+    if cur is None:
+        return [f"{u['name']} is not in the current evidence"]
+    if pins.get("fingerprint") != cur.get("fingerprint"):
+        why.append("the declaration changed since the review (fingerprint differs)")
+    if pins.get("legacy_hash") != cur.get("legacy_hash") or not HEX32.match(
+            cur.get("legacy_hash") or ""):
+        why.append("the legacy hash differs from the current one")
+    papers = body["provenance"]["papers"]
+    for pid, revn in (pins.get("manuscripts") or {}).items():
+        if pid in papers and papers[pid].get("revision") != revn:
+            why.append(f"paper {pid} is at another revision than the one reviewed")
+    v = r["verdict"]["value"]
+    if v not in ACCEPTABLE:
+        why.append(f"verdict {v!r} is not one that is recorded as a review")
+    elif v in NEEDS_DETAIL and not r["verdict"].get("detail", "").strip():
+        why.append(f"verdict {v!r} needs its detail (representation choices or instantiation)")
+    if not r["reading"].get("text", "").strip():
+        why.append("the report has no reading of the paper")
+    t = [r["reading"].get("locked_at"), r["comparison"].get("decided_at"),
+         r["author_review"].get("shown_at"), r.get("submitted_at")]
+    if None in t or t != sorted(t):
+        why.append("the steps are not recorded in order (reading, verdict, author's review)")
+    rid = rev.get("id", "")
+    if not rid or rid in cfg.statement_authors or rev.get("name") in cfg.statement_authors:
+        why.append(f"reviewer {rid!r} is an author of the statements, or unnamed")
+    if rev.get("kind") == "model" and rev.get("same_family_as_author") != "no" \
+            and not accept_same_family:
+        why.append("a model reviewer of the same family as the author, or of unknown family "
+                   "(pass --accept-same-family to accept it)")
+    if not re.fullmatch(r"\S+", rid):
+        why.append(f"reviewer id {rid!r} has spaces")
+    return why
+
+
+def marker(r: dict, cur: dict) -> str:
+    return (f"<!-- {r['unit']['kind']}-review: {r['unit']['name']} {cur['legacy_hash']} "
+            f"by={r['reviewer']['id']} -->")
+
+
+def report_text(r: dict, cur: dict) -> str:
+    """The report as the protocol's text block."""
+    u, p, rv = r["unit"], r["pins"], r["reviewer"]
+    ms = "; ".join(f"{k} {v}" for k, v in (p.get("manuscripts") or {}).items()) or "—"
+    return "\n".join([
+        f"### {', '.join(u['claims']) or u['id']}: {u['name']}",
+        f"Pins: manuscript {ms}; project {p.get('project_commit')}; "
+        f"hash {cur['legacy_hash']} ({p.get('fingerprint')})",
+        f"Reviewer: {rv['id']} ({rv['kind']}{', ' + rv['model'] if rv.get('model') else ''}, "
+        f"self-declared); {r['submitted_at']}; same model family as the author: "
+        f"{rv.get('same_family_as_author')}",
+        f"Phase 1 specification (locked {r['reading']['locked_at']}):", r["reading"]["text"],
+        f"Comparison (verdict recorded {r['comparison']['decided_at']}):",
+        r["comparison"]["text"],
+        f"Witness: {r['comparison'].get('witness') or '—'}",
+        f"Verdict: {r['verdict']['value']}"
+        + (f" — {r['verdict']['detail']}" if r['verdict'].get('detail') else ""),
+        f"Disagreements with the author's review (shown {r['author_review']['shown_at']}): "
+        f"{r['author_review'].get('disagreements') or 'none'}", ""])
+
+
+def target_file(cfg: Config, r: dict, reviews) -> tuple[Path, int | None]:
+    """Where the marker goes: after the declaration's last marker, else at the end of the
+    paper's review file (specs) or of the definitions' review file."""
+    u = r["unit"]
+    hist = history(reviews, u["kind"], u["name"])
+    if hist:
+        return (cfg.root / hist[-1].file).resolve(), hist[-1].line
+    files = review_files(cfg.reviews)
+    if not files:
+        raise PromoteError("the configuration names no review file")
+    want = "definitions.md" if u["kind"] == "def" else f"{(u.get('papers') or ['?'])[0]}.md"
+    return next((f for f in files if f.name == want), files[-1]), None
+
+
+def insert_after(path: Path, line: int | None, lines: list[str]):
+    txt = path.read_text(encoding="utf-8").split("\n")
+    if line is None:
+        while txt and not txt[-1].strip():
+            txt.pop()
+        txt += [""] + lines + [""]
+    else:
+        indent = re.match(r"\s*", txt[line - 1]).group(0)
+        txt[line:line] = [indent + l for l in lines]
+    path.write_text("\n".join(txt), encoding="utf-8")
+
+
+def reports_dir(cfg: Config) -> Path:
+    first = next((p for p in cfg.reviews if p.is_dir()), cfg.reviews[0].parent if cfg.reviews
+                 else cfg.root)
+    return first / "reports"
+
+
+def plan(cfg: Config, reports: list[dict], accept_same_family: bool = False):
+    """For each report: (report, current record, reasons it is refused)."""
+    body = latest_record(cfg)["body"]
+    from .pipeline import lean_inputs_digest
+    if body["provenance"].get("lean_inputs_sha256") != lean_inputs_digest(cfg):
+        raise PromoteError("the Lean project changed since the last build: run `prooflens build` "
+                           "first, so the reports are checked against the current declarations")
+    lean = body.get("lean") or {}
+    out = []
+    for r in reports:
+        u = r.get("unit", {})
+        cur = (lean.get("specs" if u.get("kind") == "spec" else "decls", {}) or {}).get(
+            u.get("name"))
+        out.append((r, cur, check_report(r, body, cfg, accept_same_family)))
+    return out
+
+
+def apply(cfg: Config, accepted: list[tuple[dict, dict]]) -> list[dict]:
+    """Archive each report and write its marker."""
+    reviews, _ = load_reviews(cfg.reviews, cfg.ai_reviewers, cfg.root)
+    rdir = reports_dir(cfg)
+    rdir.mkdir(parents=True, exist_ok=True)
+    done = []
+    for r, cur in accepted:
+        stem = re.sub(r"[^\w.-]+", "_", f"{r['unit']['name']}--{r['reviewer']['id']}--"
+                      f"{r['submitted_at']}")
+        (rdir / f"{stem}.json").write_text(json.dumps(r, indent=1, ensure_ascii=False) + "\n",
+                                           encoding="utf-8")
+        (rdir / f"{stem}.md").write_text(report_text(r, cur), encoding="utf-8")
+        path, line = target_file(cfg, r, reviews)
+        rel = Path(rdir / f"{stem}.md").resolve()
+        try:
+            rel = rel.relative_to(path.parent.resolve())
+        except ValueError:
+            pass
+        mk = marker(r, cur)
+        insert_after(path, line, [f"Review by {r['reviewer']['id']}: {r['verdict']['value']} "
+                                  f"(report `{rel.as_posix()}`).", mk])
+        reviews, _ = load_reviews(cfg.reviews, cfg.ai_reviewers, cfg.root)
+        done.append({"name": r["unit"]["name"], "file": str(path), "marker": mk})
+    return done

prooflens/review_queue.py

@@ -0,0 +1,138 @@
+"""The review queue: what a reviewer can review, in a suggested order.
+
+A unit of review is a locked proposition (`spec`), a definition its meaning depends on (`def`), or,
+in the zero-configuration view, a confirmed link between a claim and a declaration (`link`). Each
+unit carries the fingerprints it would be reviewed at, its current review state, the author's
+review (shown to the reviewer only after their own verdict) and why it sits where it does in the
+order. A unit is reviewed once per fingerprint, however many claims depend on it.
+
+The order is a suggestion: less effort first, with a preference for units that many claims depend
+on. Reviewing a definition settles that definition only; no claim is approved by it.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+
+SCHEMA = "prooflens/review-queue@1"
+
+
+def section_of(number: str, location: str | None = None) -> str:
+    """The section a claim sits in, from its printed number: `Theorem 3.1`, `(4.2)`, `§8.1.3` and
+    `App A.3` give `3`, `4`, `8` and `A`."""
+    m = re.search(r"(?:App(?:endix)?\.?\s*|§\s*|\(|\b)([A-Z]|\d+)(?=[.\d)])", number or "")
+    if m:
+        return m.group(1)
+    m = re.search(r"\b([A-Z]|\d+)\b", number or "")
+    return m.group(1) if m else "—"
+
+
+def _text(seg) -> str:
+    return (seg or {}).get("text", "") if isinstance(seg, dict) else str(seg or "")
+
+
+def _effort_spec(st: dict, unreviewed: int) -> float:
+    binders = len(st.get("binders") or [])
+    size = len(_text(st.get("conclusion"))) + sum(len(_text(b.get("type")))
+                                                 for b in st.get("binders") or [])
+    return binders + size / 200 + unreviewed / 4
+
+
+def _effort_def(rec: dict) -> float:
+    return 1 + len(_text(rec.get("signature"))) / 150 + (2 if rec.get("value") else 0)
+
+
+def _size(effort: float) -> str:
+    return "Short" if effort < 4 else "Medium" if effort < 10 else "Long"
+
+
+def _author_text(review: dict | None) -> list[dict]:
+    return [{"by": r.get("by"), "text": r.get("text", ""), "file": r.get("file"),
+             "line": r.get("line")} for r in (review or {}).get("current", [])]
+
+
+def assurance_queue(index: dict, chunks: dict, store: dict, authors: list[str]) -> dict:
+    """The queue of a full assessment: every locked proposition with a statement, and every
+    definition in their closures."""
+    paper_of = {c["id"]: c["paper"] for c in index["claims"]}
+    by_name = {r["name"]: r for r in store.values()}
+    keys = {r["name"]: k for k, r in store.items()}
+    used_by: dict[str, set] = {}
+    specs: dict[str, dict] = {}
+    unspecified = []
+    for c in index["claims"]:
+        ch = chunks[c["file"]]
+        if c["class"] == "unspecified":
+            unspecified.append({"id": c["id"], "paper": c["paper"], "number": c["number"]})
+        for n in ch.get("decls", {}):
+            used_by.setdefault(n, set()).add(c["id"])
+        for cl in ch.get("clauses", []):
+            st = cl.get("statement")
+            if not cl.get("spec") or not st:
+                continue
+            u = specs.setdefault(cl["spec"], {
+                "id": "spec:" + cl["spec"], "kind": "spec", "name": cl["spec"],
+                "paper": c["paper"], "papers": [c["paper"]],
+                "section": section_of(c["number"]), "claims": [], "clauses": [],
+                "legacy_hash": st.get("legacy_hash"), "fingerprint": st.get("fingerprint"),
+                "state": (cl.get("spec_review") or {}).get("state", "pending"),
+                "author_review": _author_text(cl.get("spec_review")),
+                "witness": cl.get("witness"), "refute": cl.get("refute"),
+                "unreviewed": sum(1 for r in (cl.get("def_reviews") or {}).values()
+                                  if r["state"] != "reviewed"),
+                "effort": 0.0})
+            u["claims"].append({"id": c["id"], "number": c["number"], "title": c["title"],
+                                "file": c["file"], "status": c["status"]})
+            u["clauses"].append(cl["name"])
+            u["effort"] = round(_effort_spec(st, u["unreviewed"]), 2)
+    units = list(specs.values())
+    for u in units:
+        u["reason"] = (f"{_size(u['effort'])} statement"
+                       + (f"; its meaning uses {u['unreviewed']} definition(s) not yet "
+                          "independently reviewed" if u["unreviewed"] else ""))
+    for name, rec in sorted(by_name.items()):
+        if rec.get("review") is None:
+            continue
+        users = sorted(used_by.get(name, ()))
+        effort = round(_effort_def(rec), 2)
+        units.append({
+            "id": "def:" + name, "kind": "def", "name": name, "key": keys.get(name),
+            "paper": None, "papers": sorted({paper_of[i] for i in users}),
+            "section": rec.get("module", "").rsplit(".", 1)[0] or "—",
+            "claims": [{"id": i} for i in users], "legacy_hash": rec.get("legacy_hash"),
+            "fingerprint": rec.get("fingerprint"), "state": rec["review"]["state"],
+            "author_review": _author_text(rec["review"]), "effort": effort,
+            "reason": f"{_size(effort)} definition; used by {len(users)} claim(s)"})
+    for u in units:
+        u["order"] = round(u["effort"] - math.log2(1 + len(u["claims"])), 3)
+    units.sort(key=lambda u: (u["state"] == "reviewed", u["order"], u["id"]))
+    return {"schema": SCHEMA, "release": index["release"], "mode": "assurance",
+            "authors": sorted(authors), "units": units, "needs_statement": unspecified}
+
+
+def simple_queue(index: dict, chunks: dict) -> dict:
+    """The queue of the zero-configuration view: every claim with links, reviewed as one unit
+    (do these declarations say what the claim says?)."""
+    units = []
+    for c in index["claims"]:
+        ch = chunks[c["file"]]
+        links = ch.get("links") or []
+        if not links:
+            continue
+        size = sum(len(_text((l.get("statement") or {}).get("conclusion"))) +
+                   sum(len(_text(b.get("type"))) for b in (l.get("statement") or {})
+                       .get("binders", [])) for l in links)
+        effort = round(1 + size / 200, 2)
+        units.append({
+            "id": "link:" + ch["key"], "kind": "link", "key": ch["key"],
+            "name": ", ".join(l["name"] for l in links), "lean": [l["name"] for l in links],
+            "fingerprints": {l["name"]: l.get("fingerprint") for l in links},
+            "paper": c["paper"], "papers": [c["paper"]], "section": section_of(c["number"]),
+            "claims": [{"id": c["id"], "number": c["number"], "title": c["title"],
+                        "file": c["file"], "status": c["status"]}],
+            "state": ch.get("review_state") or "pending", "author_review": [],
+            "effort": effort, "order": effort, "reason": f"{_size(effort)} statement"})
+    units.sort(key=lambda u: (u["state"] == "reviewed", u["order"], u["id"]))
+    return {"schema": SCHEMA, "release": index["release"], "mode": "simple", "authors": [],
+            "units": units, "needs_statement": []}

prooflens/reviews.py

@@ -0,0 +1,105 @@
+"""Review records: markers in Markdown files, and dismissals of advisory findings.
+
+A marker `<!-- spec-review: <name> <hash> by=<reviewer> [kind=human|ai] -->` records a review of
+the proposition `<name>` at `<hash>`; `def-review` does the same for a definition. The hash is
+either the legacy 128-bit structural hash or a `pl-fp-v1:` fingerprint. The last marker of a
+declaration (files in order, then position) is its record; it counts only while its hash is
+current. The text of the review is the section
+the marker closes.
+
+A marker is a self-declared record: nothing in the file authenticates who wrote it.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .util import sha256_file
+
+MARKER = re.compile(r"<!--\s*(spec|def)-review:\s*(\S+)\s+(\S+)((?:\s+[\w-]+=\S+)*)\s*-->")
+HEADING = re.compile(r"^#{1,6} ", re.M)
+
+
+@dataclass
+class Review:
+    target: str            # "spec" | "def"
+    name: str
+    hash: str
+    by: str
+    kind: str              # "human" | "ai" | "unknown"
+    provenance: str        # "self-declared"
+    file: str
+    line: int
+    text: str
+
+    def to_json(self) -> dict:
+        return dict(self.__dict__)
+
+
+def reviewer_kind(by: str, explicit: str | None, ai_patterns: list[str]) -> str:
+    if explicit in ("human", "ai"):
+        return explicit
+    if any(fnmatch.fnmatch(by, p) for p in ai_patterns):
+        return "ai"
+    return "unknown"
+
+
+def parse_file(path: Path, ai_patterns: list[str], rel_to: Path) -> list[Review]:
+    txt = path.read_text(encoding="utf-8")
+    out, prev = [], 0
+    for m in MARKER.finditer(txt):
+        attrs = dict(a.split("=", 1) for a in m.group(4).split())
+        start = prev
+        heads = [h.start() for h in HEADING.finditer(txt, prev, m.start())]
+        if heads:
+            start = heads[-1]
+        body = MARKER.sub("", txt[start:m.start()]).strip()
+        body = re.sub(r"\A#{1,6} [^\n]*\n", "", body).strip()
+        by = attrs.get("by", "unknown")
+        out.append(Review(
+            target=m.group(1), name=m.group(2), hash=m.group(3), by=by,
+            kind=reviewer_kind(by, attrs.get("kind"), ai_patterns), provenance="self-declared",
+            file=os.path.relpath(path, rel_to),
+            line=txt.count("\n", 0, m.start()) + 1, text=body))
+        prev = m.end()
+    return out
+
+
+def review_files(entries: list[Path]) -> list[Path]:
+    """The review files named by the configuration: a file, or every `.md` file of a directory
+    in name order."""
+    out = []
+    for e in entries:
+        if e.is_dir():
+            out += sorted(p for p in e.iterdir() if p.suffix == ".md")
+        elif e.exists():
+            out.append(e)
+    return out
+
+
+def load_reviews(entries: list[Path], ai_patterns: list[str],
+                 root: Path) -> tuple[list[Review], dict]:
+    """Every marker, in file order and then position."""
+    reviews, hashes = [], {}
+    for f in review_files(entries):
+        reviews += parse_file(f, ai_patterns, root)
+        hashes[os.path.relpath(f, root)] = sha256_file(f)
+    return reviews, hashes
+
+
+def history(reviews: list[Review], target: str, name: str) -> list[Review]:
+    """The markers of a declaration; the last one is its current record."""
+    return [r for r in reviews if r.target == target and r.name == name]
+
+
+def load_dismissals(path: Path | None) -> list[dict]:
+    """Dismissals of advisory findings: `[{code, subject, fingerprint, rationale, by}]`. A
+    dismissal holds only while `fingerprint` is the subject's current fingerprint."""
+    if path is None or not path.exists():
+        return []
+    return json.loads(path.read_text(encoding="utf-8"))

prooflens/schemas.py

@@ -0,0 +1,19 @@
+"""JSON Schemas of the inventory, the evidence record and the presentation manifest."""
+
+from __future__ import annotations
+
+import json
+from functools import cache
+from importlib import resources
+
+import jsonschema
+
+
+@cache
+def schema(name: str) -> dict:
+    return json.loads(resources.files("prooflens").joinpath(f"data/schema/{name}.schema.json")
+                      .read_text())
+
+
+def validate(obj, name: str) -> None:
+    jsonschema.validate(obj, schema(name))

prooflens/server.py

@@ -0,0 +1,63 @@
+"""The local server of `prooflens view`: the site, and saving links into the repository.
+
+It listens on 127.0.0.1 only. `GET /api/status` tells the reader it may edit; `POST /api/link`
+with `{"key", "lean": [names] | null, "reject": [names]}` records a link (or removes it, or
+rejects suggestions) in `prooflens.links.json` and rebuilds the view.
+"""
+
+from __future__ import annotations
+
+import functools
+import http.server
+import json
+import threading
+from pathlib import Path
+
+
+def serve(site: Path, port: int, on_link=None, open_browser: bool = True):
+    lock = threading.Lock()
+
+    class Handler(http.server.SimpleHTTPRequestHandler):
+        def log_message(self, *a):
+            pass
+
+        def _json(self, code: int, obj):
+            b = json.dumps(obj).encode()
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(b)))
+            self.end_headers()
+            self.wfile.write(b)
+
+        def do_GET(self):
+            if self.path == "/api/status":
+                return self._json(200, {"editable": on_link is not None})
+            return super().do_GET()
+
+        def do_POST(self):
+            if self.path != "/api/link" or on_link is None:
+                return self._json(404, {"error": "not found"})
+            try:
+                n = int(self.headers.get("Content-Length", "0"))
+                req = json.loads(self.rfile.read(n) or b"{}")
+                with lock:
+                    on_link(req)
+                return self._json(200, {"ok": True})
+            except Exception as e:  # the reader shows the message
+                return self._json(400, {"error": str(e)})
+
+    handler = functools.partial(Handler, directory=str(site))
+    httpd = http.server.ThreadingHTTPServer(("127.0.0.1", port), handler)
+    url = f"http://127.0.0.1:{httpd.server_address[1]}/"
+    print(f"ProofLens: {url}  (Ctrl-C to stop)")
+    if open_browser:
+        try:
+            import webbrowser
+            webbrowser.open(url)
+        except Exception:
+            pass
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    return url