codegraph-brain 0.6.0__py3-none-any.whl

cgis/guardian/collector.py

@@ -0,0 +1,309 @@
+"""Gathers git diff and project files needed for Guardian review context."""
+
+import subprocess
+from pathlib import Path
+
+import structlog
+
+from cgis.extractors.python_extractor import file_path_to_module_fqn
+from cgis.guardian.chunker import Chunk
+from cgis.query.drift.drift import DriftScorer
+from cgis.query.drift.fingerprint import FingerprintExtractor
+from cgis.query.drift.quotient import build_quotient
+from cgis.query.engine import QueryEngine
+from cgis.query.render.mermaid import MermaidCompiler
+from cgis.storage.sqlite_store import SQLiteStore
+
+log = structlog.getLogger(__name__)
+
+VALID_FEATURES = frozenset({"full_files", "flow", "drift", "chunked"})
+
+_MAX_FILE_LINES = 1200
+_MAX_TOTAL_CHARS = 120_000
+
+
+def parse_features(raw: str) -> frozenset[str]:
+    """Parse a GUARDIAN_FEATURES value ('full_files,flow,drift') into a validated set.
+
+    Raises ValueError on unknown names: a typo silently disabling an ablation
+    arm would corrupt the benchmark comparison.
+    """
+    items = {item.strip() for item in raw.split(",") if item.strip()}
+    unknown = items - VALID_FEATURES
+    if unknown:
+        _msg = f"Unknown GUARDIAN_FEATURES: {sorted(unknown)}; valid: {sorted(VALID_FEATURES)}"
+        raise ValueError(_msg)
+    return frozenset(items)
+
+
+class ContextCollector:
+    """Gathers all necessary context for the review."""
+
+    def __init__(
+        self,
+        project_root: Path,
+        base_branch: str = "main",
+        db_path: Path | None = None,
+        base_ref: str | None = None,
+        source_root: str = "src",
+        features: frozenset[str] = frozenset(),
+        include_graph: bool = True,
+    ) -> None:
+        """Set project root, diff base (branch or explicit ref), and optional graph DB.
+
+        base_ref, when given, is used verbatim (e.g. a SHA for benchmark
+        replays); otherwise the diff base is origin/<base_branch>.
+
+        source_root must match the ingest root used to build the graph DB
+        (CI runs `cgis ingest ./src`): node FQNs are relative to that root,
+        so changed-file paths are stripped of it before lookup.
+
+        features gates the optional context sections (spec §4): "full_files", "flow", "drift".
+
+        include_graph=False drops the impact-graph Mermaid section — a "diff-only"
+        prompt that fits a smaller context window (e.g. a local Ollama model whose
+        window is exceeded once the graph is appended).
+        """
+        self.project_root = project_root
+        self.base_branch = base_branch
+        self.db_path = db_path
+        self.base_ref = base_ref
+        self.source_root = source_root
+        self.features = features
+        self.include_graph = include_graph
+        self.graph_stats: dict[str, int] = {"total": 0, "with_graph": 0, "flow_fallback": 0}
+        self._diff_cache: str | None = None
+
+    def _diff_range(self) -> str:
+        """Return the git range argument for diff commands."""
+        base = self.base_ref or f"origin/{self.base_branch}"
+        return f"{base}...HEAD"
+
+    def get_git_diff(self) -> str:
+        """Returns diff between HEAD and the base branch on origin.
+
+        The diff is cached after the first successful call: within one review
+        run it is needed twice (LLM context and inline-comment line index),
+        and the working tree does not change in between.
+        """
+        if self._diff_cache is not None:
+            return self._diff_cache
+        try:
+            result = subprocess.run(
+                ["git", "diff", self._diff_range()],
+                capture_output=True,
+                text=True,
+                check=True,
+                cwd=self.project_root,
+            )
+        except subprocess.CalledProcessError as e:
+            return f"Error getting git diff: {e.stderr}"
+        else:
+            self._diff_cache = result.stdout
+            return self._diff_cache
+
+    def get_changed_py_files(self) -> list[str]:
+        """Returns relative paths of .py files changed vs the base branch."""
+        try:
+            result = subprocess.run(
+                ["git", "diff", "--name-only", self._diff_range()],
+                capture_output=True,
+                text=True,
+                check=True,
+                cwd=self.project_root,
+            )
+        except subprocess.CalledProcessError:
+            return []
+        return [p for p in result.stdout.splitlines() if p.endswith(".py")]
+
+    def read_file(self, relative_path: str) -> str:
+        """Reads a file from the project root; returns "" when it does not exist.
+
+        An empty string (not an error marker) lets the prompt builder omit the
+        corresponding section entirely — a repo without CONTRIBUTING.md or
+        docs/ontology/ should review cleanly, not get "Error: File ..." injected
+        as if it were the standards/ontology text. `is_file()` (not `exists()`)
+        so a path that resolves to a directory degrades to "" instead of raising
+        IsADirectoryError on read.
+        """
+        file_path = self.project_root / relative_path
+        if not file_path.is_file():
+            return ""
+        return file_path.read_text(encoding="utf-8")
+
+    def collect_full_files(self, files: list[str] | None = None) -> str:
+        """Full HEAD text of given (default: changed) .py files, smallest-first under budgets.
+
+        Per-file cap ~1200 lines and a global ~120K-char budget; omitted files get
+        an explicit note so the model never reads absence-of-file as absence-of-code.
+        In chunked mode the budget applies per chunk (spec §4.2).
+        """
+        changed = files if files is not None else self.get_changed_py_files()
+        sized: list[tuple[int, str, str]] = []
+        omitted: list[str] = []
+        for rel_path in changed:
+            path = self.project_root / rel_path
+            if not path.exists():  # deleted in this PR — nothing to show at HEAD
+                continue
+            text = path.read_text(encoding="utf-8")
+            if len(text.splitlines()) > _MAX_FILE_LINES:
+                omitted.append(f"file omitted: too large ({rel_path})")
+                continue
+            sized.append((len(text), rel_path, text))
+
+        sections: list[str] = []
+        used = 0
+        for size, rel_path, text in sorted(sized):
+            if used + size > _MAX_TOTAL_CHARS:
+                omitted.append(f"file omitted: budget exhausted ({rel_path})")
+                continue
+            used += size
+            sections.append(f"#### `{rel_path}`\n```python\n{text}\n```")
+        return "\n\n".join(sections + omitted)
+
+    def _graph_sections(
+        self, changed_files: list[str], *, flow: bool
+    ) -> tuple[list[str], dict[str, int]]:
+        """Impact-graph Mermaid sections + local stats for the given files.
+
+        Pure with respect to self.graph_stats — callers decide whether to
+        overwrite (global path) or accumulate (per-chunk path).
+        """
+        stats = {"total": 0, "with_graph": 0, "flow_fallback": 0}
+        if self.db_path is None or not self.db_path.exists() or not changed_files:
+            return [], stats
+        stats["total"] = len(changed_files)
+        compiler = MermaidCompiler()
+        sections: list[str] = []
+        with SQLiteStore(str(self.db_path)) as store:
+            engine = QueryEngine(store)
+            for rel_path in changed_files:
+                module_fqn = file_path_to_module_fqn(rel_path, self.source_root)
+                nodes, edges = engine.get_impact_graph(module_fqn, max_depth=2)
+                title = "Impact graph"
+                if not nodes and flow:
+                    # New file: nothing references it yet (#94) — show what it calls.
+                    nodes, edges = engine.get_flow_graph(module_fqn, max_depth=2)
+                    title = "Dependency graph (outbound)"
+                    if nodes:
+                        stats["flow_fallback"] += 1
+                if not nodes:
+                    log.debug("No impact graph for module", fqn=module_fqn)
+                    continue
+                mermaid = compiler.compile(nodes, edges)
+                sections.append(f"#### {title} for `{module_fqn}`:\n```mermaid\n{mermaid}\n```")
+        stats["with_graph"] = len(sections)
+        return sections, stats
+
+    def collect_graph_context(self) -> str:
+        """Query graph.db for impact graphs of changed files; return Mermaid blocks."""
+        if not self.include_graph:
+            return ""  # diff-only prompt (fits a smaller context window)
+        if self.db_path is None or not self.db_path.exists():
+            return ""
+        changed_files = self.get_changed_py_files()
+        if not changed_files:
+            return ""
+        sections, stats = self._graph_sections(changed_files, flow="flow" in self.features)
+        self.graph_stats = stats
+        if stats["total"] > 0 and stats["with_graph"] == 0:
+            log.warning(
+                "No graph context found for any changed file.",
+                changed_files=stats["total"],
+                project_root=str(self.project_root),
+            )
+        return "\n\n".join(sections)
+
+    def collect_drift(self) -> str:
+        """Compact per-domain drift table + quotient k=1 lines (spec §4.3).
+
+        First real consumer of drift v2 outside tests — the soft enforcement
+        channel deferred in #146/#151. Any failure degrades to an empty section.
+        """
+        if self.db_path is None or not self.db_path.exists():
+            return ""
+        patterns = self.project_root / "docs" / "ontology" / "patterns.yaml"
+        if not patterns.exists():
+            return ""
+        try:
+            scorer = DriftScorer(str(patterns))
+            domains = scorer.load_project_domains()
+            quotient_lines: list[str] = []
+            with SQLiteStore(str(self.db_path)) as store:
+                extractor = FingerprintExtractor(store)
+                # default_tolerance=0.50 fallback is deliberate here: collector has no
+                # max_drift to thread, and production domains declare their own tolerance.
+                reports = [scorer.score(extractor.extract(d.fqn_prefix), d) for d in domains]
+                level = scorer.load_project_level()
+                if level:
+                    qnodes, qedges = build_quotient(
+                        store.get_all_nodes(), store.get_all_edges(), domains
+                    )
+                    q_extractor = FingerprintExtractor.from_graph(qnodes, qedges)
+                    quotient_lines = [
+                        f"Quotient k=1 [{b.name}] vs {qr.expected_pattern}: "
+                        f"drift={qr.drift_score:.2f} (observe-only)"
+                        for b in level
+                        # default_tolerance=0.50 fallback is deliberate here (see comment above).
+                        for qr in [scorer.score(q_extractor.extract(b.fqn_prefix), b)]
+                    ]
+        except Exception:
+            log.warning("Drift section skipped.", exc_info=True)
+            return ""
+
+        if not reports and not quotient_lines:  # no domains declared — skip the empty table
+            return ""
+
+        rows = [
+            f"| {r.fqn_prefix} | {r.expected_pattern or '(hygiene)'} "
+            f"| {r.drift_score:.2f} | {r.tolerance:.2f} "
+            f"| {'⚠' if r.drift_score > r.tolerance else ''} |"
+            for r in reports
+        ]
+        table = "| domain | expected | drift | tolerance | over |\n|---|---|---|---|---|\n"
+        return (
+            table + "\n".join(rows) + ("\n" + "\n".join(quotient_lines) if quotient_lines else "")
+        )
+
+    def collect_all(self) -> dict[str, str]:
+        """Collects all relevant files, git diff, and optional graph context."""
+        context: dict[str, str] = {
+            "diff": self.get_git_diff(),
+            "contributing": self.read_file("CONTRIBUTING.md"),
+            "ontology": self.read_file("docs/ontology/core.yaml"),
+        }
+        graph_context = self.collect_graph_context()
+        if graph_context:
+            context["graph_context"] = graph_context
+        if "full_files" in self.features:
+            full_files = self.collect_full_files()
+            if full_files:
+                context["full_files"] = full_files
+        if "drift" in self.features:
+            drift = self.collect_drift()
+            if drift:
+                context["drift"] = drift
+        return context
+
+    def collect_for_chunk(self, chunk: Chunk) -> dict[str, str]:
+        """Per-chunk context: the chunk's diff, full files, and impact graphs (spec §4.2).
+
+        chunked implies per-chunk full_files, graph context, AND the flow
+        fallback — each chunk gets a small, complete world. graph_stats
+        ACCUMULATE across chunks so the footer coverage stays truthful.
+        """
+        py_files = [f for f in chunk.files if f.endswith(".py")]
+        context: dict[str, str] = {
+            "diff": chunk.diff,
+            "contributing": self.read_file("CONTRIBUTING.md"),
+            "ontology": self.read_file("docs/ontology/core.yaml"),
+        }
+        sections, stats = self._graph_sections(py_files, flow=True)
+        for key, value in stats.items():
+            self.graph_stats[key] = self.graph_stats.get(key, 0) + value
+        if sections:
+            context["graph_context"] = "\n\n".join(sections)
+        full_files = self.collect_full_files(py_files)
+        if full_files:
+            context["full_files"] = full_files
+        return context

cgis/guardian/core.py

@@ -0,0 +1,120 @@
+"""Main orchestrator that wires together collector, prompts, and LLM provider."""
+
+import structlog
+from pydantic import ValidationError
+
+from cgis.guardian.collector import ContextCollector
+from cgis.guardian.findings import ReviewResult, extract_json
+from cgis.guardian.prompts import PromptBuilder
+from cgis.guardian.providers.base import BaseProvider
+from cgis.guardian.skeptic import (
+    DEFAULT_SKEPTIC_CONCURRENCY,
+    apply_judgements,
+    judge_all,
+    skeptic_status_for,
+)
+
+log = structlog.getLogger(__name__)
+
+_RETRY_SUFFIX = (
+    "\n\n---\nYour previous response failed validation against the required JSON schema:\n"
+    "{error}\n"
+    "Respond again with ONLY the JSON object — no prose, no markdown fences."
+)
+
+
+def _sanitize_finder_result(result: ReviewResult) -> ReviewResult:
+    """Reset skeptic-owned fields the finder LLM may have hallucinated.
+
+    ReviewResult doubles as the finder's structured-output schema, so the
+    model sees `skeptic_status`, the judged/total counters and per-finding
+    `verdict`/`skeptic_note`/`impact_score`, and sometimes fills them in. A
+    hallucinated `verdict="refuted"` would make visible_findings() silently drop
+    a finder finding; a hallucinated `impact_score` would hide one behind the
+    impact threshold just as silently — only the skeptic pass may set these.
+    """
+    findings = [
+        f.model_copy(update={"verdict": None, "skeptic_note": None, "impact_score": None})
+        for f in result.findings
+    ]
+    return result.model_copy(
+        update={
+            "findings": findings,
+            "skeptic_status": "off",
+            "skeptic_judged": 0,
+            "skeptic_total": 0,
+        }
+    )
+
+
+async def finder_pass(provider: BaseProvider, context: dict[str, str]) -> ReviewResult:
+    """Run the finder (pass 1) with parse-retry semantics.
+
+    Parse policy (spec §2.3): one retry with the validation error appended;
+    on a second failure the raw text becomes the summary with parse_failed=True.
+    Module-level so the chunked orchestrator reuses it per chunk (slice 2).
+    """
+    builder = PromptBuilder()
+    system_prompt = builder.build_system_prompt()
+    user_prompt = builder.build_user_prompt(context)
+    raw = await provider.generate_structured(system_prompt, user_prompt, ReviewResult)
+    try:
+        return _sanitize_finder_result(ReviewResult.model_validate_json(extract_json(raw)))
+    except ValidationError as exc:
+        log.warning(
+            "Structured output failed validation; retrying once.",
+            validation_error=str(exc),
+        )
+        retry_prompt = user_prompt + _RETRY_SUFFIX.format(error=exc)
+        raw = await provider.generate_structured(system_prompt, retry_prompt, ReviewResult)
+        try:
+            return _sanitize_finder_result(ReviewResult.model_validate_json(extract_json(raw)))
+        except ValidationError:
+            log.exception("Structured output failed twice; falling back to raw text.")
+            return ReviewResult(findings=[], summary=raw, parse_failed=True)
+
+
+class GuardianReviewer:
+    """Orchestrates the entire review process."""
+
+    def __init__(
+        self,
+        provider: BaseProvider,
+        context_collector: ContextCollector,
+        skeptic_provider: BaseProvider | None = None,
+        concurrency: int = DEFAULT_SKEPTIC_CONCURRENCY,
+    ) -> None:
+        """Wire up the LLM provider, context collector, and optional skeptic.
+
+        ``concurrency`` bounds the per-finding judgement calls; the default keeps
+        provider rate limits out of reach (#246 §3.4).
+        """
+        self.provider = provider
+        self.context_collector = context_collector
+        self.skeptic_provider = skeptic_provider
+        self.concurrency = concurrency
+
+    async def _finder_pass(self, context: dict[str, str]) -> ReviewResult:
+        """Delegate to the module-level finder_pass (kept for call-site stability)."""
+        return await finder_pass(self.provider, context)
+
+    async def run_review(self) -> ReviewResult:
+        """Run the review; optionally judge each finding with the skeptic pass (#246 §3.4)."""
+        context = self.context_collector.collect_all()
+        result = await self._finder_pass(context)
+        if self.skeptic_provider is None or not result.findings or result.parse_failed:
+            return result
+        judgements = await judge_all(
+            self.skeptic_provider, result.findings, context.get("diff", ""), self.concurrency
+        )
+        judged = sum(1 for j in judgements if j is not None)
+        if judged == 0:
+            log.warning("Every skeptic judgement failed; returning single-pass results.")
+        return result.model_copy(
+            update={
+                "findings": apply_judgements(result.findings, judgements),
+                "skeptic_status": skeptic_status_for(judged, len(judgements)),
+                "skeptic_judged": judged,
+                "skeptic_total": len(judgements),
+            }
+        )

cgis/guardian/diff_index.py

@@ -0,0 +1,151 @@
+"""Pure unified-diff parsers: RIGHT-side line index, and the per-file split.
+
+Two families of `---`/`+++` header patterns live here on purpose, and they are
+NOT interchangeable. The line indexer keys on the new path only and ignores
+git's C-quoting; the per-file splitter is quote-aware and falls back to the old
+path so deletions stay reviewable. Keeping them side by side makes the
+difference visible instead of accidental.
+"""
+
+import re
+
+import structlog
+
+log = structlog.getLogger(__name__)
+
+_DEV_NULL = "/dev/null"  # git's marker for "this side of the diff has no file"
+
+_HUNK_RE = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+_NEW_FILE_RE = re.compile(r"^\+\+\+ (?:b/)?(.+)$")
+
+# Quote-aware variants used by split_diff_by_file. Git C-quotes paths with
+# special characters: `--- "a/x y.py"` — the optional quotes wrap the WHOLE
+# `a/...` token, so they must be stripped around the prefix (PR #157 review).
+_QUOTED_OLD_FILE_RE = re.compile(r'^--- "?(?:a/)?(.+?)"?$')
+_QUOTED_NEW_FILE_RE = re.compile(r'^\+\+\+ "?(?:b/)?(.+?)"?$')
+
+
+def _new_file_path(header: re.Match[str]) -> str | None:
+    """New-side path from a matched `+++` header; None for deletions (/dev/null)."""
+    path = header.group(1)
+    return None if path == _DEV_NULL else path
+
+
+def diff_line_content(diff_text: str) -> dict[str, dict[int, str]]:
+    """Map each changed file (new path) to ``{RIGHT-side line number: line text}``.
+
+    The text is the line content with its leading diff marker (``+``/`` ``)
+    stripped, so it can be matched verbatim against a finding's quote to anchor
+    the comment deterministically (#181). Same right-side accounting as
+    :func:`diff_line_index`: added and context lines carry a number, removed
+    lines don't, and ``+++ /dev/null`` deletions are excluded.
+    """
+    content: dict[str, dict[int, str]] = {}
+    current: str | None = None
+    in_hunk = False
+    new_line = 0
+    for line in diff_text.splitlines():
+        if line.startswith("diff --git"):
+            current = None
+            in_hunk = False
+            continue
+        # Real `+++` headers only appear between hunks (after `diff --git`
+        # resets in_hunk); inside a hunk a `+++ ...` line is added CONTENT
+        # whose text starts with `++` — counting it as a header would both
+        # drop the rest of the file and shift line numbers.
+        if not in_hunk and (header := _NEW_FILE_RE.match(line)):
+            current = _new_file_path(header)
+            continue
+        if (hunk := _HUNK_RE.match(line)) and current is not None:
+            new_line = int(hunk.group(1))
+            in_hunk = True
+            content.setdefault(current, {})
+            continue
+        if not in_hunk or current is None or line.startswith(("-", "\\")):
+            continue  # outside a hunk / removed line / "\ No newline" marker
+        content[current][new_line] = line[1:]  # drop the '+'/' ' marker, keep the text
+        new_line += 1
+    return {path: lines for path, lines in content.items() if lines}
+
+
+def diff_line_index(diff_text: str) -> dict[str, set[int]]:
+    """Map each changed file (new path) to the set of RIGHT-side line numbers.
+
+    GitHub only accepts inline review comments on lines present in the diff;
+    context and added lines count, removed lines do not (spec §6.2). Renames
+    are keyed by the new path so keys match Finding.file. Files deleted in the
+    PR (+++ /dev/null) have no RIGHT side and are excluded. Derived from
+    :func:`diff_line_content` so the two never diverge.
+    """
+    return {path: set(lines) for path, lines in diff_line_content(diff_text).items()}
+
+
+def _block_path(lines: list[str]) -> str | None:
+    """Path for one diff block: the new path, or the old path for deletions.
+
+    Headers are only read before the first `@@` line — past that, a
+    `+++ ...` line is added content (the 5e53dd0 lesson, avoided structurally).
+    """
+    old: str | None = None
+    new: str | None = None
+    for line in lines:
+        if line.startswith("@@"):
+            break
+        if old is None and (m := _QUOTED_OLD_FILE_RE.match(line)):
+            old = None if m.group(1) == _DEV_NULL else m.group(1)
+        elif new is None and (m := _QUOTED_NEW_FILE_RE.match(line)):
+            new = None if m.group(1) == _DEV_NULL else m.group(1)
+    return new or old or _git_header_path(lines[0])
+
+
+def _git_header_path(header: str) -> str | None:
+    """Fallback for blocks without ---/+++ headers (binary, mode-only): b/ side.
+
+    Tries the quoted form first (`diff --git "a/x y.png" "b/x y.png"` — the
+    quote sits before b/, so a bare ` b/` search misses it; gemini review,
+    PR #157), then the plain ` b/` marker.
+    """
+    quoted = ' "b/'
+    idx = header.rfind(quoted)
+    if idx != -1:
+        return header[idx + len(quoted) :].removesuffix('"') or None
+    marker = " b/"
+    idx = header.rfind(marker)
+    if idx == -1:
+        return None
+    return header[idx + len(marker) :] or None
+
+
+def split_diff_by_file(diff_text: str) -> dict[str, str]:
+    """Split a unified diff into per-file blocks keyed by repo-relative path.
+
+    Key = new path; deletions (`+++ /dev/null`) fall back to the old path so
+    deleted files stay reviewable (unlike diff_line_index, which drops them — no
+    RIGHT side to anchor an inline comment on). Splitting on a column-zero
+    `diff --git` is safe: inside a hunk every content line carries a
+    `+`/`-`/space prefix, so a bare header can only be a real one.
+    """
+    blocks: dict[str, str] = {}
+    current: list[str] = []
+
+    def _flush() -> None:
+        if not current:
+            return
+        path = _block_path(current)
+        if path is None:
+            log.warning("Diff block without parsable path skipped.", head=current[0])
+        else:
+            block = "\n".join(current) + "\n"
+            if path in blocks:
+                log.warning("Duplicate diff block for path; merging.", path=path)
+                blocks[path] += block
+            else:
+                blocks[path] = block
+        current.clear()
+
+    for line in diff_text.splitlines():
+        if line.startswith("diff --git"):
+            _flush()
+        current.append(line)
+    _flush()
+    return blocks

cgis/guardian/findings.py

@@ -0,0 +1,70 @@
+"""Structured findings contract for the Guardian reviewer (spec §2.1)."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+Severity = Literal["critical", "major", "minor"]
+Category = Literal["logic", "contract", "tests", "types", "ontology"]
+Verdict = Literal["confirmed", "refuted", "uncertain"]
+
+
+class Finding(BaseModel, frozen=True):
+    """One reviewed defect, anchored to a file (and optionally a line)."""
+
+    file: str
+    # ge (not gt): gemini's response Schema rejects exclusiveMinimum
+    line: int | None = Field(default=None, ge=1)
+    severity: Severity
+    category: Category
+    title: str
+    evidence: str
+    problem: str
+    fix: str
+    confidence: int = Field(ge=0, le=100)
+    # Verbatim single source line the finding sits on, used to derive the inline
+    # anchor deterministically instead of trusting the model's ``line`` (#181).
+    anchor: str | None = None
+    verdict: Verdict | None = None
+    skeptic_note: str | None = None
+    # 0-10 importance from the skeptic (#246 spec §3.1). None = not judged.
+    # Orthogonal to `verdict`: a finding can be true (confirmed) and worthless
+    # (score 1), which one enum value cannot express.
+    impact_score: int | None = Field(default=None, ge=0, le=10)
+
+
+class ReviewResult(BaseModel, frozen=True):
+    """The full review: findings (empty = LGTM) plus a checked-aspects summary."""
+
+    findings: list[Finding]
+    summary: str
+    parse_failed: bool = False
+    # "off" = skeptic not configured; "ok" = every finding judged; "partial" =
+    # some judgement calls failed (see skeptic_judged/skeptic_total); "failed" =
+    # no finding was judged, single-pass results returned (spec §5.5 / #246
+    # §3.4 — never silent).
+    skeptic_status: Literal["off", "ok", "partial", "failed"] = "off"
+    skeptic_judged: int = 0
+    skeptic_total: int = 0
+
+
+def extract_json(text: str) -> str:
+    """Return the JSON payload from an LLM response, stripping markdown fences.
+
+    The closing fence is matched as a real newline followed by ``` — raw
+    newlines cannot occur inside JSON strings, so embedded backticks in
+    field values are safe. Text after the closing fence is discarded.
+    """
+    stripped = text.strip()
+    if not stripped.startswith("```"):
+        return stripped
+    newline = stripped.find("\n")
+    if newline == -1:
+        return ""
+    body = stripped[newline + 1 :]
+    closing = body.find("\n```")
+    if closing != -1:
+        return body[:closing].strip()
+    # No newline before the closing fence (e.g. `{...}```` on one line):
+    # valid JSON never ends with backticks, so stripping the suffix is safe.
+    return body.strip().removesuffix("```").strip()