codereview-loop 0.13.0__py3-none-any.whl

codereview/intake.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""codereview intake — issue report in, solution plan out.
+
+The front half of the workflow. Everything else in codereview
+starts from a code change that already exists; intake starts from
+the problem. An issue report (Markdown) plus optional context
+files goes to one or more solver models, and each returns a
+solution plan in the shape a builder can execute: what to check
+first, ranked hypotheses — each with the test that settles it — a
+concrete fix plan, prevention, risks and rollback, and closure
+criteria a verifier can run.
+
+The primary solver (the first configured seat that answers)
+becomes solution.md; every other solver's plan is kept alongside
+as an alternate for the builder to compare. Intake never writes
+code and never gates anything: the builder reads the plan,
+implements it, and the review loop gates the resulting change
+exactly as before.
+
+Report and context are secret-redacted before they leave the
+machine and size-capped; every truncation is recorded in the
+manifest (intake.json) and disclosed inside the prompt itself, so
+a solver never mistakes a cut-off file for a complete one.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+
+from .core import VERSION, redact_secrets
+
+MAX_REPORT_CHARS = 60000
+MAX_CONTEXT_FILE_CHARS = 40000
+MAX_TOTAL_CONTEXT_CHARS = 120000
+MAX_SOLVER_WORKERS = 8
+DEFAULT_SOLVER_TIMEOUT = 300
+
+_INSTRUCTIONS = """You are the solver in a software-maintenance workflow. A coding agent (the builder) will execute your plan on the real system, and an independent multi-model review will gate the resulting change. Your plan is the only guidance the builder gets, so it must be executable as written.
+
+Write the solution plan in Markdown with exactly these sections:
+
+# Solution — <short title naming the problem>
+
+## Diagnosis — what to check first, in order
+## Hypotheses — ranked most likely first; for each: the evidence for it, and the concrete test or observation that would prove or disprove it
+## Fix plan — numbered steps the builder can execute in order; name files, functions, and commands when the material supports it
+## Prevention — the guard, alarm, or test that keeps this from recurring silently
+## Risks and rollback
+## Closure criteria — a checklist a verifier can run to confirm the issue is actually closed
+
+Rules:
+- Ground every claim in the issue report and context below. Label inferences as inferences; if you are guessing, say so.
+- Do not invent file names, function names, line numbers, or log lines that are not in the material. Where the material is silent, make the missing check a diagnosis step instead of assuming its result.
+- Prefer the smallest fix that addresses the root cause. Where two hypotheses imply different fixes, order the plan so the builder tests before committing to one.
+- If the report shows this issue was already "fixed" before and recurred, treat the recurrence itself as the primary defect: the plan must explain why the earlier fix failed or was incomplete, not just repeat it."""
+
+
+def _cap(text, limit):
+    """(sent_text, truncated) — cut with a disclosed marker."""
+    if len(text) <= limit:
+        return text, False
+    return text[:limit] + "\n\n[truncated by codereview intake: " \
+        f"{len(text) - limit} chars omitted]", True
+
+
+def build_solver_prompt(report, contexts=(), repo_tree=""):
+    """Assemble the solver prompt from already-redacted material.
+
+    Two cap layers, by design: _prepare caps the report and each
+    context file individually (and records it in the manifest);
+    this builder additionally enforces the total context budget
+    across files, disclosing any further cut in the prompt.
+
+    contexts: [(label, text)] — texts are per-file capped here; the
+    running total is capped as well and later files disclose it."""
+    parts = [_INSTRUCTIONS, "", "## Issue report", "", report]
+    if repo_tree:
+        parts += ["", "## Repository layout", "", repo_tree]
+    total = 0
+    for label, text in contexts:
+        sent, truncated = _cap(text, MAX_CONTEXT_FILE_CHARS)
+        if total + len(sent) > MAX_TOTAL_CONTEXT_CHARS:
+            sent, truncated = _cap(
+                text, max(0, MAX_TOTAL_CONTEXT_CHARS - total))
+        total += len(sent)
+        parts += ["", f"## Context: {label}", "", sent]
+        if truncated:
+            parts.append(f"[note: context {label} was truncated "
+                         "to fit the prompt budget]")
+    return "\n".join(parts)
+
+
+def _prepare(report, contexts, repo_tree=""):
+    """Redact + cap the raw inputs; return (prompt, meta)."""
+    clean_report, rep_trunc = _cap(redact_secrets(report),
+                                   MAX_REPORT_CHARS)
+    clean_contexts = []
+    ctx_meta = []
+    for label, text in contexts:
+        clean = redact_secrets(text)
+        sent, truncated = _cap(clean, MAX_CONTEXT_FILE_CHARS)
+        clean_contexts.append((label, sent))
+        ctx_meta.append({"label": label, "chars": len(text),
+                         "sent_chars": len(sent),
+                         "truncated": truncated})
+    prompt = build_solver_prompt(clean_report, clean_contexts,
+                                 repo_tree=repo_tree)
+    meta = {
+        "report": {"chars": len(report), "sent_chars": len(clean_report),
+                   "truncated": rep_trunc,
+                   "sha256": hashlib.sha256(
+                       report.encode("utf-8")).hexdigest()},
+        "contexts": ctx_meta,
+        "prompt_chars": len(prompt),
+    }
+    return prompt, meta
+
+
+def run_intake(report, solvers, contexts=(), repo_tree="",
+               timeout=DEFAULT_SOLVER_TIMEOUT):
+    """Run every solver over the report in parallel.
+
+    solvers: {seat name: callable(prompt) -> markdown text}; dict
+    order is the configuration order and decides the primary.
+    A solver that has not answered within `timeout` seconds is
+    recorded as failed ("timed out") instead of blocking the run:
+    the provider HTTP layer already times out at 240s, and this
+    deadline is the outer guard for callables that ignore theirs.
+    Returns the intake result dict (see write_intake)."""
+    prompt, meta = _prepare(report, contexts, repo_tree=repo_tree)
+
+    def call(name, fn):
+        started = time.monotonic()
+        try:
+            text = fn(prompt)
+            return {"name": name, "ok": True,
+                    "seconds": round(time.monotonic() - started, 1),
+                    "chars": len(text or ""), "text": text or "",
+                    "error": ""}
+        except Exception as exc:  # noqa: BLE001 - solver failure is data
+            return {"name": name, "ok": False,
+                    "seconds": round(time.monotonic() - started, 1),
+                    "chars": 0, "text": "",
+                    "error": str(exc)[:300]}
+
+    solutions = []
+    if solvers:
+        workers = max(1, min(len(solvers), MAX_SOLVER_WORKERS))
+        pool = ThreadPoolExecutor(max_workers=workers)
+        try:
+            futures = {name: pool.submit(call, name, fn)
+                       for name, fn in solvers.items()}
+            deadline = time.monotonic() + timeout
+            by_name = {}
+            for name, fut in futures.items():
+                try:
+                    by_name[name] = fut.result(
+                        timeout=max(0.0, deadline - time.monotonic()))
+                except TimeoutError:
+                    by_name[name] = {
+                        "name": name, "ok": False, "seconds": timeout,
+                        "chars": 0, "text": "",
+                        "error": f"timed out after {timeout}s"}
+            solutions = [by_name[name] for name in solvers]
+        finally:
+            # Never block the run on a hung solver thread; a stray
+            # thread may outlive the call but holds no shared state.
+            pool.shutdown(wait=False, cancel_futures=True)
+    primary = next((s["name"] for s in solutions if s["ok"]), None)
+    return {"tool": "codereview", "version": VERSION, "kind": "intake",
+            "created": datetime.now(timezone.utc).isoformat(),
+            "ok": primary is not None, "primary": primary,
+            "solutions": solutions, **meta}
+
+
+def write_intake(result, out_dir, report_name=""):
+    """Write solution.md (primary), alternates, and intake.json.
+
+    Returns (solution_path or None, manifest_path)."""
+    os.makedirs(out_dir, exist_ok=True)
+    manifest = {k: v for k, v in result.items() if k != "solutions"}
+    manifest["report"] = {**result["report"], "name": report_name}
+    manifest["solvers"] = [
+        {k: s[k] for k in ("name", "ok", "seconds", "chars", "error")}
+        for s in result["solutions"]]
+    solution_path = None
+    for s in result["solutions"]:
+        if not s["ok"]:
+            continue
+        header = (f"<!-- codereview intake {result['version']} · "
+                  f"solver: {s['name']} · report: {report_name} · "
+                  f"{result['created']} -->\n\n")
+        if s["name"] == result["primary"]:
+            solution_path = os.path.join(out_dir, "solution.md")
+            path = solution_path
+        else:
+            path = os.path.join(out_dir, f"solution-{s['name']}.md")
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(header + s["text"].strip() + "\n")
+    manifest_path = os.path.join(out_dir, "intake.json")
+    with open(manifest_path, "w", encoding="utf-8") as fh:
+        json.dump(manifest, fh, ensure_ascii=False, indent=1)
+    return solution_path, manifest_path

codereview/mcp_tools.py

@@ -0,0 +1,455 @@
+"""MCP tool layer (Epic L2): the gate, served to other agents.
+
+`codereview mcp serve` speaks the Model Context Protocol over
+stdio (transport: codereview.mcp_transport) and exposes two
+tools:
+
+- `run_gate` — a diff (patch text, or a git range in a repo)
+  plus an optional policy path → the gate's verdict and the
+  run record's path;
+- `get_verdict` — a stored record (file or directory) → the
+  verdict summary and findings.
+
+Serving only, by design: the server is a new front door onto
+the EXISTING gate, not a new gate. A run goes through the
+CLI's own `main()` with the arguments translated, so a verdict
+served here is the CLI's verdict on the same change — same
+panel resolution, same saved-setup and environment discipline,
+same record on disk. The review path itself consumes no MCP
+tools and reviewers stay read-only and tool-less (Epic F2
+unchanged).
+
+The server holds no credentials of its own: seats come only
+from the user's saved setup (or $CODEREVIEW_PROVIDERS), exactly
+as for the CLI. With no setup, run_gate answers with the CLI's
+own not-set-up message — there is no built-in panel to fall
+back to, here or anywhere.
+
+Fail-closed: a malformed tool call (wrong types, unknown
+arguments, patch+range together) is refused with an error
+result before anything runs; a refused or failed run is an
+`isError` tool result carrying the reason, never an exception
+escaping into the transport loop.
+"""
+
+import contextlib
+import io
+import json
+import os
+import re
+import tempfile
+
+from . import __version__, hardening
+from .mcp_transport import (INVALID_PARAMS, METHOD_NOT_FOUND,
+                            JsonRpcError, StdioServer)
+
+# Protocol versions this subset implements, newest first. The
+# handshake echoes the client's version when it is one of
+# these and answers with the newest otherwise (the MCP
+# negotiation rule).
+PROTOCOL_VERSIONS = ("2025-03-26", "2024-11-05")
+
+SERVER_INFO = {"name": "codereview", "version": __version__}
+
+TOOL_DEFS = [
+    {
+        "name": "run_gate",
+        "description": (
+            "Run the CodeReview gate on a change and return "
+            "the verdict plus the run record's path. Give "
+            "either `patch` (unified diff text) or `range` "
+            "(a git range such as HEAD~1..HEAD, evaluated in "
+            "`repo`); with neither, the repo's working-tree "
+            "change is reviewed, as with the CLI. Seats come "
+            "from the operator's saved CodeReview setup — "
+            "with no setup the call fails with the setup "
+            "instructions, exactly like the CLI."),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "repo": {
+                    "type": "string",
+                    "description": "repository path (default: "
+                                   "the server's working "
+                                   "directory)",
+                },
+                "range": {
+                    "type": "string",
+                    "description": "git diff range, e.g. "
+                                   "main...HEAD",
+                },
+                "patch": {
+                    "type": "string",
+                    "description": "unified diff text (mutually "
+                                   "exclusive with range)",
+                },
+                "policy": {
+                    "type": "string",
+                    "description": "project policy file (TOML); "
+                                   "default: .codereview.toml "
+                                   "at the repo root, when "
+                                   "present",
+                },
+                "trust_repo_policy": {
+                    "type": "boolean",
+                    "description": "honour a policy discovered "
+                                   "in the reviewed repository "
+                                   "in full, including its hooks "
+                                   "and gate-weakening keys; "
+                                   "without it a discovered "
+                                   "policy keeps only its "
+                                   "strengthening keys (P3-01 "
+                                   "trust restriction) and the "
+                                   "dropped keys are returned as "
+                                   "policy_ignored_keys",
+                },
+                "out": {
+                    "type": "string",
+                    "description": "output directory for the "
+                                   "run record (default: "
+                                   "<repo>/codereview-out)",
+                },
+                "context": {
+                    "type": "string",
+                    "description": "builder's change "
+                                   "description, shown to the "
+                                   "reviewers",
+                },
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "get_verdict",
+        "description": (
+            "Read a stored CodeReview run record and return "
+            "its verdict summary and findings. `record` is a "
+            "record JSON file or the directory holding it "
+            "(the newest timestamped record in the directory "
+            "wins, as with the CLI's record arguments)."),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "record": {
+                    "type": "string",
+                    "description": "record JSON file or "
+                                   "record directory",
+                },
+                "repo": {
+                    "type": "string",
+                    "description": "repository the record "
+                                   "belongs to (default: the "
+                                   "server's working "
+                                   "directory)",
+                },
+            },
+            "required": ["record"],
+            "additionalProperties": False,
+        },
+    },
+]
+
+
+class ToolError(Exception):
+    """A tool-level refusal or failure: returned to the client
+    as an isError tool result, never raised into the
+    transport."""
+
+
+_FINDING_FIELDS = ("id", "severity", "category", "file", "line",
+                   "title", "recommendation", "confidence")
+
+
+def _finding_summary(finding):
+    return {key: finding.get(key) for key in _FINDING_FIELDS}
+
+
+def _verdict_payload(record, record_path):
+    """The verdict shape both tools answer with: the gate,
+    its reasons, the findings (summarised — the full record
+    stays on disk at record_path), and severity counts.
+
+    Policy visibility (P3-01 follow-ups): the payload also
+    carries the record's policy origin, its self-modification
+    flag, and — since the trust restriction landed — the keys
+    dropped from a repo-discovered policy. The CLI's stderr
+    warning is captured and discarded on a successful
+    run_gate, so without these fields an MCP client could not
+    tell that the verdict was produced under a policy
+    discovered in the reviewed repo, which of its keys were
+    ignored, or that the change touched the policy file
+    itself. The keys are always present (null / [] when the
+    run had no policy section) so clients can rely on the
+    shape."""
+    findings = [_finding_summary(f)
+                for f in record.get("findings") or []]
+    by_severity = {}
+    for finding in findings:
+        sev = finding["severity"] or "unknown"
+        by_severity[sev] = by_severity.get(sev, 0) + 1
+    policy = record.get("policy") or {}
+    return {
+        "gate": record.get("gate"),
+        "gate_reasons": record.get("gate_reasons") or [],
+        "mode": record.get("mode"),
+        "degraded": bool(record.get("degraded")),
+        "policy_origin": policy.get("origin"),
+        "policy_ignored_keys": policy.get("ignored_keys") or [],
+        "policy_self_modification":
+            record.get("policy_self_modification") or [],
+        "record_path": record_path,
+        "findings": findings,
+        "counts": {
+            "total": len(findings),
+            "blocking": by_severity.get("blocker", 0)
+                        + by_severity.get("major", 0),
+            "by_severity": by_severity,
+        },
+    }
+
+
+class GateTools:
+    """The two gate tools. The *_override seams are the CLI's
+    own (tests and internal runners inject stub seats through
+    them); a production server is constructed with none, so
+    seats resolve from the saved setup / environment exactly
+    as a CLI run's do."""
+
+    def __init__(self, providers_override=None,
+                 seat_meta_override=None, fallbacks_override=None):
+        self._providers_override = providers_override
+        self._seat_meta_override = seat_meta_override
+        self._fallbacks_override = fallbacks_override
+
+    # -- argument discipline -------------------------------------
+
+    @staticmethod
+    def _checked_args(tool, arguments):
+        if arguments is None:
+            arguments = {}
+        if not isinstance(arguments, dict):
+            raise ToolError(
+                f"{tool}: arguments must be an object")
+        schema = next(t["inputSchema"] for t in TOOL_DEFS
+                      if t["name"] == tool)
+        allowed = schema["properties"]
+        for key, value in arguments.items():
+            if key not in allowed:
+                raise ToolError(
+                    f"{tool}: unknown argument {key!r} "
+                    f"(allowed: {', '.join(sorted(allowed))})")
+            if allowed[key].get("type") == "boolean":
+                if not isinstance(value, bool):
+                    raise ToolError(
+                        f"{tool}: argument {key!r} must be "
+                        f"a boolean")
+            elif not isinstance(value, str):
+                raise ToolError(
+                    f"{tool}: argument {key!r} must be a string")
+        for key in schema.get("required", []):
+            if key not in arguments:
+                raise ToolError(
+                    f"{tool}: missing required argument {key!r}")
+        return arguments
+
+    # -- run_gate --------------------------------------------------
+
+    def run_gate(self, arguments):
+        from . import cli, userconfig
+        args = self._checked_args("run_gate", arguments)
+        if args.get("patch") and args.get("range"):
+            raise ToolError(
+                "run_gate: give either patch or range, not both")
+        # P3-09: same repo validation as the CLI — an
+        # explicitly given repo must be an existing directory;
+        # "" must not silently become the server's CWD and a
+        # nonexistent path must not silently skip the project
+        # context in patch mode.
+        if "repo" in args and (not args["repo"]
+                               or not os.path.isdir(args["repo"])):
+            raise ToolError(
+                f"run_gate: repo {args['repo']!r} is not an "
+                f"existing directory")
+        repo = args.get("repo") or "."
+        out = args.get("out") or os.path.join(
+            repo, "codereview-out")
+        argv = ["--repo", repo, "--out", out]
+        if args.get("range"):
+            argv += ["--range", args["range"]]
+        if args.get("policy"):
+            argv += ["--policy", args["policy"]]
+        if args.get("trust_repo_policy"):
+            argv += ["--trust-repo-policy"]
+        if args.get("context"):
+            argv += ["--context", args["context"]]
+        patch_file = None
+        if args.get("patch") is not None:
+            fd, patch_file = tempfile.mkstemp(
+                prefix="codereview-mcp-", suffix=".patch")
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(args["patch"])
+            argv += ["--patch", patch_file]
+        stdout, stderr = io.StringIO(), io.StringIO()
+        try:
+            with contextlib.redirect_stdout(stdout), \
+                    contextlib.redirect_stderr(stderr):
+                rc = cli.main(
+                    argv,
+                    providers_override=self._providers_override,
+                    seat_meta_override=self._seat_meta_override,
+                    fallbacks_override=self._fallbacks_override)
+        except SystemExit as exc:
+            raise ToolError(
+                "run_gate: the gate refused the request "
+                f"(exit {exc.code}): "
+                f"{_tail(stderr.getvalue())}") from exc
+        except Exception as exc:  # noqa: BLE001 — fail closed
+            raise ToolError(
+                f"run_gate: the gate run failed: {exc}") from exc
+        finally:
+            if patch_file is not None:
+                try:
+                    os.unlink(patch_file)
+                except OSError:
+                    pass
+        out_text, err_text = stdout.getvalue(), stderr.getvalue()
+        jpath = _printed_path(out_text, "data")
+        if jpath is None:
+            if userconfig.NOT_SET_UP.splitlines()[0] in err_text:
+                raise ToolError(err_text.strip())
+            raise ToolError(
+                f"run_gate: the gate run produced no record "
+                f"(exit {rc}): {_tail(err_text) or _tail(out_text)}")
+        try:
+            with open(jpath, encoding="utf-8") as fh:
+                record = json.load(fh)
+        except Exception as exc:  # noqa: BLE001
+            raise ToolError(
+                f"run_gate: could not read the record the run "
+                f"wrote ({jpath}): {exc}") from exc
+        payload = _verdict_payload(record, jpath)
+        payload["report_path"] = _printed_path(out_text, "report")
+        payload["exit_code"] = rc
+        return payload
+
+    # -- get_verdict ------------------------------------------------
+
+    def get_verdict(self, arguments):
+        from . import cli
+        args = self._checked_args("get_verdict", arguments)
+        try:
+            record, _record_dir, jpath = cli._load_record_arg(
+                args["record"], args.get("repo") or ".")
+        except Exception as exc:  # noqa: BLE001
+            raise ToolError(
+                f"get_verdict: could not read the record: "
+                f"{exc}") from exc
+        return _verdict_payload(record, jpath)
+
+
+def _printed_path(text, label):
+    """The CLI prints '  report: <path>' / '  data:   <path>'
+    lines at the end of a run; pull one back out."""
+    matches = re.findall(rf"^  {label}:\s+(\S.*)$", text,
+                         flags=re.MULTILINE)
+    return matches[-1].strip() if matches else None
+
+
+def _tail(text, limit=800):
+    text = (text or "").strip()
+    return text[-limit:] if len(text) > limit else text
+
+
+# -- protocol handling --------------------------------------------
+
+
+def _call_result(payload):
+    return {
+        "content": [{
+            "type": "text",
+            "text": json.dumps(payload, ensure_ascii=False,
+                               indent=2),
+        }],
+        "structuredContent": payload,
+        "isError": False,
+    }
+
+
+def _error_result(message):
+    return {
+        "content": [{"type": "text", "text": message}],
+        "isError": True,
+    }
+
+
+def make_dispatch(tools):
+    """Build the transport dispatch callable for a GateTools
+    instance: MCP method handling (initialize / ping /
+    tools/list / tools/call) on top of the wire layer."""
+
+    def dispatch(method, params, notification):
+        if notification:
+            # notifications/initialized, notifications/
+            # cancelled, anything else: notifications are
+            # fire-and-forget and never answered.
+            return None
+        if method == "initialize":
+            params = params if isinstance(params, dict) else {}
+            requested = params.get("protocolVersion")
+            version = requested if requested in PROTOCOL_VERSIONS \
+                else PROTOCOL_VERSIONS[0]
+            return {
+                "protocolVersion": version,
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": dict(SERVER_INFO),
+                "instructions": (
+                    "CodeReview gate. run_gate runs the "
+                    "multi-model review gate on a diff and "
+                    "returns the verdict + record path; "
+                    "get_verdict reads a stored run record."),
+            }
+        if method == "ping":
+            return {}
+        if method == "tools/list":
+            return {"tools": TOOL_DEFS}
+        if method == "tools/call":
+            if not isinstance(params, dict) \
+                    or not isinstance(params.get("name"), str):
+                raise JsonRpcError(
+                    INVALID_PARAMS,
+                    "tools/call needs a params object with a "
+                    "tool name")
+            name = params["name"]
+            handler = {"run_gate": tools.run_gate,
+                       "get_verdict": tools.get_verdict}.get(name)
+            if handler is None:
+                raise JsonRpcError(
+                    INVALID_PARAMS, f"unknown tool: {name}")
+            try:
+                payload = handler(params.get("arguments"))
+            except ToolError as exc:
+                return _error_result(str(exc))
+            return _call_result(payload)
+        raise JsonRpcError(
+            METHOD_NOT_FOUND, f"method not found: {method}")
+
+    return dispatch
+
+
+def serve_stdio(tools=None, stdin=None, stdout=None, log=None,
+                max_frame_bytes=None):
+    """Assemble the server (transport + tools) and serve until
+    EOF. Returns the StdioServer so callers (and tests) can
+    inspect its error ledger."""
+    # P3-04: the server process holds the operator's
+    # environment (provider keys) and spawns gate runs; make
+    # it non-dumpable before serving.
+    hardening.make_non_dumpable()
+    tools = tools if tools is not None else GateTools()
+    kwargs = {}
+    if max_frame_bytes is not None:
+        kwargs["max_frame_bytes"] = max_frame_bytes
+    server = StdioServer(make_dispatch(tools), stdin=stdin,
+                         stdout=stdout, log=log, **kwargs)
+    server.serve_forever()
+    return server