docassert 0.1.0__py3-none-any.whl

docassert/report.py

@@ -0,0 +1,83 @@
+"""Render check results as console text, PR-comment markdown, or JUnit XML."""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from xml.dom import minidom
+
+from .models import CheckResult
+
+_TICK = "✓"
+_CROSS = "✗"
+_DASH = "—"
+
+
+def _mark(r: CheckResult) -> str:
+    if r.kind == "semantic" and r.score is None:
+        return "○"  # ○ skipped/unavailable
+    return _TICK if r.passed else _CROSS
+
+
+def console(results_by_doc: dict[str, list[CheckResult]]) -> str:
+    lines: list[str] = []
+    for path, results in results_by_doc.items():
+        lines.append(f"\n{path}")
+        for r in results:
+            tier = "structural" if r.kind == "structural" else "advisory  "
+            gate = "BLOCK" if r.is_blocking_failure else "     "
+            score = f" [{r.score:.2f}]" if r.score is not None else ""
+            lines.append(f"  {_mark(r)} {gate} {tier} {r.check_id}{score}: {r.detail}")
+    return "\n".join(lines)
+
+
+def summary_line(results_by_doc: dict[str, list[CheckResult]]) -> str:
+    blocking = sum(1 for rs in results_by_doc.values() for r in rs if r.is_blocking_failure)
+    docs = len(results_by_doc)
+    if blocking:
+        return f"{_CROSS} {blocking} blocking failure(s) across {docs} document(s) {_DASH} merge blocked."
+    return f"{_TICK} All structural checks passed across {docs} document(s) {_DASH} clear to merge."
+
+
+def markdown(results_by_doc: dict[str, list[CheckResult]],
+             title: str = "docassert audit") -> str:
+    """PR-comment body."""
+    out = [f"## {title}", "", summary_line(results_by_doc), ""]
+    for path, results in results_by_doc.items():
+        out.append(f"### `{path}`")
+        out.append("")
+        out.append("| | Check | Tier | Result |")
+        out.append("|---|---|---|---|")
+        for r in results:
+            tier = "structural (blocking)" if r.kind == "structural" else "AI advisory"
+            score = f" · score {r.score:.2f}" if r.score is not None else ""
+            if r.kind == "semantic" and r.score is None:
+                emoji = "⚪"  # advisory check skipped/unavailable
+            elif r.passed:
+                emoji = "🟢"
+            else:
+                emoji = "🔴"
+            out.append(f"| {emoji} | `{r.check_id}` | {tier} | {r.detail}{score} |")
+        out.append("")
+    out.append("<sub>Structural checks block the merge. AI advisory checks inform "
+               "reviewers but never block. Configure criteria in `criteria/`.</sub>")
+    return "\n".join(out)
+
+
+def junit(results_by_doc: dict[str, list[CheckResult]]) -> str:
+    total = sum(len(rs) for rs in results_by_doc.values())
+    failures = sum(1 for rs in results_by_doc.values()
+                   for r in rs if r.is_blocking_failure)
+    suites = ET.Element("testsuites", tests=str(total), failures=str(failures))
+    for path, results in results_by_doc.items():
+        suite = ET.SubElement(suites, "testsuite", name=path,
+                              tests=str(len(results)),
+                              failures=str(sum(1 for r in results if r.is_blocking_failure)))
+        for r in results:
+            case = ET.SubElement(suite, "testcase",
+                                 classname=f"{path}:{r.kind}", name=r.check_id)
+            if r.is_blocking_failure:
+                ET.SubElement(case, "failure", message=r.detail).text = r.detail
+            elif r.kind == "semantic" and not r.passed:
+                # advisory failures surface as skipped, never as build failures
+                ET.SubElement(case, "skipped", message=r.detail)
+    xml = ET.tostring(suites, encoding="unicode")
+    return minidom.parseString(xml).toprettyxml(indent="  ")

docassert/rtm.py

@@ -0,0 +1,70 @@
+"""Generate a Requirements Traceability Matrix from the item graph.
+
+Derived, never authored: it walks BR → PR → FR/NFR → AC → TC and renders the
+coverage as a table, so gaps are visible at a glance.
+"""
+from __future__ import annotations
+
+import csv
+import io
+
+
+def _cell(ids: set[str]) -> str:
+    return ", ".join(sorted(ids)) if ids else "—"
+
+
+def build_rows(graph, project: str | None = None) -> list[dict]:
+    rows: list[dict] = []
+    brs = graph.by_type.get("BR", [])
+    if project:
+        brs = [b for b in brs if b.project == project]
+    for br in sorted(brs, key=lambda i: i.id):
+        prs = graph.children(br.id, "traces", "PR")
+        fr_ids, ac_ids, tc_ids = set(), set(), set()
+        for pr in prs:
+            for src in graph.children(pr.id, "traces"):
+                if src.type in {"FR", "NFR"}:
+                    fr_ids.add(src.id)
+            for ac in graph.children(pr.id, "verifies", "AC"):
+                ac_ids.add(ac.id)
+                for tc in graph.children(ac.id, "tests", "TC"):
+                    tc_ids.add(tc.id)
+        rows.append({
+            "BR": br.id,
+            "PR": {p.id for p in prs},
+            "FR/NFR": fr_ids,
+            "AC": ac_ids,
+            "TC": tc_ids,
+        })
+    return rows
+
+
+_COLS = ["BR", "PR", "FR/NFR", "AC", "TC"]
+_HEADERS = ["Business Req", "Product Req", "Functional / NFR",
+            "Acceptance Criteria", "Test Cases"]
+
+
+def render_markdown(graph, project: str | None = None) -> str:
+    rows = build_rows(graph, project)
+    title = f"# Requirements Traceability Matrix — {project}" if project else "# Requirements Traceability Matrix"
+    out = [title, ""]
+    out.append("| " + " | ".join(_HEADERS) + " |")
+    out.append("|" + "|".join(["---"] * len(_HEADERS)) + "|")
+    for r in rows:
+        out.append("| " + " | ".join(
+            [r["BR"]] + [_cell(r[c]) for c in _COLS[1:]]) + " |")
+    uncovered = [r["BR"] for r in rows if not r["PR"]]
+    out += ["",
+            f"_{len(rows)} business requirement(s); "
+            f"{len(uncovered)} with no product requirement"
+            + (": " + ", ".join(uncovered) if uncovered else "") + "._"]
+    return "\n".join(out) + "\n"
+
+
+def render_csv(graph, project: str | None = None) -> str:
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    writer.writerow(_HEADERS)
+    for r in build_rows(graph, project):
+        writer.writerow([r["BR"]] + [_cell(r[c]) for c in _COLS[1:]])
+    return buf.getvalue()

docassert/semantic.py

@@ -0,0 +1,124 @@
+"""AI-graded semantic checks. These are ADVISORY — they never block a merge.
+
+Each check asks a model to score one rubric criterion against the document and
+return structured JSON: {score: 0..1, pass: bool, rationale: str}. Results are
+cached by content hash so unchanged documents are not re-billed.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+
+from .models import CheckResult, Document
+
+DEFAULT_MODEL = os.environ.get("DOCUNIT_MODEL", "claude-sonnet-5")
+CACHE_DIR = Path(os.environ.get("DOCUNIT_CACHE", ".docassert-cache"))
+
+_SYSTEM = (
+    "You are a meticulous document auditor. You are given one audit criterion "
+    "and a business document. Judge only that criterion. Respond with a single "
+    "JSON object and nothing else: "
+    '{"score": <number 0..1>, "pass": <true|false>, "rationale": "<one or two '
+    'sentences citing specifics from the document>"}.'
+)
+
+
+def _cache_key(model: str, prompt: str, content: str) -> str:
+    h = hashlib.sha256()
+    h.update(model.encode())
+    h.update(b"\x00")
+    h.update(prompt.encode())
+    h.update(b"\x00")
+    h.update(content.encode())
+    return h.hexdigest()
+
+
+def _cache_get(key: str) -> dict | None:
+    f = CACHE_DIR / f"{key}.json"
+    if f.exists():
+        try:
+            return json.loads(f.read_text())
+        except (OSError, json.JSONDecodeError):
+            return None
+    return None
+
+
+def _cache_put(key: str, value: dict) -> None:
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        (CACHE_DIR / f"{key}.json").write_text(json.dumps(value))
+    except OSError:
+        pass  # caching is best-effort
+
+
+def _grade(prompt: str, content: str, model: str) -> dict:
+    """Call the Anthropic API and return the parsed JSON grade."""
+    import anthropic  # imported lazily so structural-only runs need no dependency
+
+    client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
+    # Note: newer Claude models deprecate the `temperature` parameter, so we do
+    # not set it. Grading is kept consistent by the strict JSON rubric instead.
+    message = client.messages.create(
+        model=model,
+        max_tokens=400,
+        system=_SYSTEM,
+        messages=[{
+            "role": "user",
+            "content": f"AUDIT CRITERION:\n{prompt}\n\nDOCUMENT:\n{content}",
+        }],
+    )
+    text = "".join(block.text for block in message.content
+                   if getattr(block, "type", None) == "text").strip()
+    # tolerate models that wrap JSON in prose or fences
+    start, end = text.find("{"), text.rfind("}")
+    if start == -1 or end == -1:
+        raise ValueError(f"no JSON in model response: {text[:120]!r}")
+    return json.loads(text[start:end + 1])
+
+
+def advisory(check_id: str, prompt: str, content: str,
+             threshold: float = 0.7, model: str = DEFAULT_MODEL) -> CheckResult:
+    """Grade one rubric prompt against `content`. Always advisory (non-blocking).
+
+    Fails safe: if the key is missing or the model errors, returns a skipped/
+    unavailable result rather than raising, so it can never block a merge.
+    """
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        return CheckResult(check_id, True, False,
+                           "skipped — no ANTHROPIC_API_KEY (advisory only)",
+                           kind="semantic", score=None)
+
+    key = _cache_key(model, prompt, content)
+    grade = _cache_get(key)
+    if grade is None:
+        try:
+            grade = _grade(prompt, content, model)
+            _cache_put(key, grade)
+        except Exception as exc:
+            return CheckResult(check_id, True, False,
+                               f"advisory check unavailable: {exc}",
+                               kind="semantic", score=None)
+
+    score = float(grade.get("score", 0.0))
+    passed = bool(grade.get("pass", score >= threshold))
+    rationale = str(grade.get("rationale", "")).strip()
+    return CheckResult(check_id, passed, False,
+                       rationale or f"score {score:.2f} (threshold {threshold:.2f})",
+                       kind="semantic", score=score)
+
+
+def run_semantic(doc: Document, spec: dict, content: str) -> CheckResult:
+    return advisory(
+        spec["id"], spec.get("prompt", "").strip(), content,
+        threshold=float(spec.get("pass_threshold", 0.7)),
+        model=spec.get("model", DEFAULT_MODEL),
+    )
+
+
+def run_alignment(check_id: str, prompt: str, parent_text: str,
+                  child_text: str, threshold: float = 0.7) -> CheckResult:
+    """Advisory: does the child item genuinely fulfil the parent it links to?"""
+    content = f"PARENT:\n{parent_text}\n\nCHILD:\n{child_text}"
+    return advisory(check_id, prompt, content, threshold=threshold)