overkill 0.6.1__tar.gz → 0.7.0__tar.gz

{overkill-0.6.1 → overkill-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overkill
-Version: 0.6.1
+Version: 0.7.0
 Summary: AI-powered code review loop — automates Codex/Gemini review + Claude fix cycles
 Project-URL: Repository, https://github.com/modocai/mr-overkill
 Project-URL: Issues, https://github.com/modocai/mr-overkill/issues

{overkill-0.6.1 → overkill-0.7.0}/prompts/active/claude-review.prompt.md

@@ -62,7 +62,7 @@ We only want findings where you are confident the issue is real. **If you are no
 
 ## Output Format
 
-Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON.
+Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON. Begin your response with the `{` character — no prose, no commentary, no preamble.
 
 {
   "findings": [

{overkill-0.6.1 → overkill-0.7.0}/prompts/active/codex-review.prompt.md

@@ -53,7 +53,7 @@ Output all findings that the original author would fix if they knew about them.
 
 ## Output Format
 
-Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON.
+Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON. Begin your response with the `{` character — no prose, no commentary, no preamble.
 
 {
   "findings": [

{overkill-0.6.1 → overkill-0.7.0}/prompts/active/gemini-review.prompt.md

@@ -62,7 +62,7 @@ We only want findings where you are confident the issue is real. **If you are no
 
 ## Output Format
 
-Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON.
+Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON. Begin your response with the `{` character — no prose, no commentary, no preamble.
 
 {
   "findings": [

{overkill-0.6.1 → overkill-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "overkill"
-version = "0.6.1"
+version = "0.7.0"
 description = "AI-powered code review loop — automates Codex/Gemini review + Claude fix cycles"
 readme = "README.md"
 license = { text = "MIT" }

{overkill-0.6.1 → overkill-0.7.0}/src/mr_overkill/agents.py

@@ -13,6 +13,7 @@ import logging
 import string
 import subprocess
 from abc import ABC, abstractmethod
+from importlib.resources import as_file, files
 from pathlib import Path
 
 from mr_overkill.budget.claude import claude_budget_sufficient
@@ -45,6 +46,41 @@ def _format_reviewer_context(raw: str) -> str:
     return f"## Author Context\n\n{raw}"
 
 
+# ── Review schema (single source of truth for structured output) ─────
+
+
+def _review_schema_text() -> str:
+    """Read the bundled review JSON Schema as a string."""
+    return files("mr_overkill.data").joinpath("review.schema.json").read_text(
+        encoding="utf-8"
+    )
+
+
+def _unwrap_claude_structured_output(output_path: Path) -> None:
+    """Replace Claude's ``--output-format json`` wrapper with its inner schema object.
+
+    Claude CLI emits ``{"type":"result", ..., "structured_output": {...}, ...}``
+    when both ``--output-format json`` and ``--json-schema`` are set. The
+    schema-conforming object lives under ``structured_output``. Downstream
+    consumers expect the file to contain that object directly. If the file does
+    not match the wrapper shape (older Claude versions, error responses), it is
+    left untouched so the parser's fallback tiers can still try.
+    """
+    try:
+        raw = output_path.read_text(encoding="utf-8")
+    except OSError:
+        return
+    try:
+        wrapper = json.loads(raw)
+    except json.JSONDecodeError:
+        return
+    if not isinstance(wrapper, dict):
+        return
+    inner = wrapper.get("structured_output")
+    if isinstance(inner, dict):
+        output_path.write_text(json.dumps(inner), encoding="utf-8")
+
+
 # ── Budget / retry helpers (moved from review_loop.py) ───────────────
 
 
@@ -183,16 +219,20 @@ class CodexReviewAgent(ReviewAgent):
             )
 
         stderr_path = output_path.with_suffix(".stderr")
-        return retry_codex_cmd(
-            stderr_path,
-            "Codex review",
-            [
-                "codex", "exec", "--sandbox", "read-only",
-                "-o", str(output_path), prompt_text,
-            ],
-            max_wait=config.retry_max_wait,
-            initial_wait=config.retry_initial_wait,
-        )
+        with as_file(
+            files("mr_overkill.data").joinpath("review.schema.json")
+        ) as schema_path:
+            return retry_codex_cmd(
+                stderr_path,
+                "Codex review",
+                [
+                    "codex", "exec", "--sandbox", "read-only",
+                    "--output-schema", str(schema_path),
+                    "-o", str(output_path), prompt_text,
+                ],
+                max_wait=config.retry_max_wait,
+                initial_wait=config.retry_initial_wait,
+            )
 
 
 class CodexRefactorReviewAgent(ReviewAgent):
@@ -284,15 +324,20 @@ class ClaudeReviewAgent(ReviewAgent):
                 f"Claude budget timeout (iteration {iteration})."
             )
 
-        return self._retry_fn(
+        ok = self._retry_fn(
             output_path,
             "Claude review",
             [
                 "claude", "-p", "-",
                 "--allowedTools", "Bash,Read,Glob,Grep",
+                "--output-format", "json",
+                "--json-schema", _review_schema_text(),
             ],
             stdin=prompt_text,
         )
+        if ok:
+            _unwrap_claude_structured_output(output_path)
+        return ok
 
 
 class ClaudeRefactorReviewAgent(ReviewAgent):

overkill-0.7.0/src/mr_overkill/data/review.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewResult",
+  "type": "object",
+  "required": [
+    "findings",
+    "overall_correctness",
+    "overall_explanation",
+    "overall_confidence_score"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["title", "body", "confidence_score", "priority", "code_location"],
+        "additionalProperties": false,
+        "properties": {
+          "title": {
+            "type": "string",
+            "maxLength": 80,
+            "description": "P-tag + imperative description (max 80 chars)"
+          },
+          "body": {
+            "type": "string",
+            "description": "Markdown explanation; cite files/lines/functions"
+          },
+          "confidence_score": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "priority": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 3
+          },
+          "code_location": {
+            "type": "object",
+            "required": ["file_path", "line_range"],
+            "additionalProperties": false,
+            "properties": {
+              "file_path": {
+                "type": "string",
+                "description": "Repo-relative file path"
+              },
+              "line_range": {
+                "type": "object",
+                "required": ["start", "end"],
+                "additionalProperties": false,
+                "properties": {
+                  "start": {"type": "integer", "minimum": 0},
+                  "end": {"type": "integer", "minimum": 0}
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "overall_correctness": {
+      "type": "string",
+      "enum": ["patch is correct", "patch is incorrect"]
+    },
+    "overall_explanation": {
+      "type": "string",
+      "description": "1-3 sentence justification"
+    },
+    "overall_confidence_score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    }
+  }
+}

{overkill-0.6.1 → overkill-0.7.0}/src/mr_overkill/json_extract.py

@@ -1,7 +1,7 @@
 """JSON extraction utilities ported from common.sh and self-review.sh.
 
 Provides a 3-tier extraction pipeline (direct parse -> fenced code block ->
-regex fallback) that mirrors _extract_json_from_file in the shell codebase,
+balanced-brace scan) that mirrors _extract_json_from_file in the shell codebase,
 plus helpers for path normalisation and refactoring-plan injection.
 """
 
@@ -24,7 +24,9 @@ def extract_json_from_file(path: Path) -> dict[str, Any] | None:
     Tier 2: Look for a fenced code block (`` ```json ... ``` ``) and parse its
     content.
 
-    Tier 3: Use a greedy regex to extract the outermost ``{ ... }`` and parse.
+    Tier 3: Scan every ``{`` position with ``json.JSONDecoder().raw_decode()``
+    and return the largest valid dict found. Robust to prose with embedded
+    braces (e.g. preambles that mention schemas).
 
     Returns
     -------
@@ -53,8 +55,8 @@ def extract_json_from_file(path: Path) -> dict[str, Any] | None:
     if result is not None:
         return result
 
-    # ── Tier 3: regex fallback ────────────────────────────────────────
-    return _try_regex_fallback(content)
+    # ── Tier 3: balanced-brace scan ───────────────────────────────────
+    return _try_balanced_scan(content)
 
 
 def parse_review_json(
@@ -188,18 +190,28 @@ def _try_fenced_block(content: str) -> dict[str, Any] | None:
     return None
 
 
-_BRACE_RE = re.compile(r"\{.*\}", re.DOTALL)
+def _try_balanced_scan(content: str) -> dict[str, Any] | None:
+    """Tier 3: try ``raw_decode`` from each ``{`` position, keep the largest dict.
 
-
-def _try_regex_fallback(content: str) -> dict[str, Any] | None:
-    """Tier 3: greedy regex for the outermost ``{ ... }``."""
-    match = _BRACE_RE.search(content)
-    if match is None:
-        return None
-    try:
-        obj = json.loads(match.group(0))
-        if isinstance(obj, dict):
-            return obj
-    except json.JSONDecodeError:
-        pass
-    return None
+    Greedy regex (``\\{.*\\}``) breaks when prose preceding the JSON contains
+    its own ``{`` — the match starts at the prose brace and consumes the rest
+    of the file as one invalid string. ``raw_decode`` walks the JSON grammar
+    and stops at the matching brace, so each candidate is parsed correctly.
+    """
+    decoder = json.JSONDecoder()
+    best: dict[str, Any] | None = None
+    best_len = 0
+    idx = 0
+    while True:
+        idx = content.find("{", idx)
+        if idx < 0:
+            break
+        try:
+            obj, end = decoder.raw_decode(content, idx)
+        except json.JSONDecodeError:
+            idx += 1
+            continue
+        if isinstance(obj, dict) and (end - idx) > best_len:
+            best, best_len = obj, end - idx
+        idx = end if end > idx else idx + 1
+    return best

{overkill-0.6.1 → overkill-0.7.0}/src/mr_overkill/retry.py

@@ -26,9 +26,13 @@ BUDGET_POLL_MAX = 1200
 
 
 def extract_result_from_stream(stream_path: Path) -> str:
-    """Extract final result text from a Claude stream-json event log.
+    """Extract final result from a Claude stream-json event log.
 
-    Returns empty string if the file is empty or no result event found.
+    When the ``result`` event includes a ``structured_output`` object
+    (set by ``--json-schema``), the JSON-encoded structured object is
+    returned so downstream parsers receive schema-conforming JSON.
+    Otherwise the plain ``result`` text is returned. Returns empty
+    string if the file is empty or no result event is found.
     """
     if not stream_path.is_file() or stream_path.stat().st_size == 0:
         return ""
@@ -39,10 +43,13 @@ def extract_result_from_stream(stream_path: Path) -> str:
             continue
         try:
             data = json.loads(line)
-            if data.get("result"):
-                last_result = data["result"]
-        except (json.JSONDecodeError, KeyError):
+        except json.JSONDecodeError:
             continue
+        structured = data.get("structured_output")
+        if isinstance(structured, dict):
+            last_result = json.dumps(structured)
+        elif data.get("result"):
+            last_result = data["result"]
     return last_result
 
 

{overkill-0.6.1 → overkill-0.7.0}/tests/test_agents.py

@@ -60,6 +60,12 @@ class TestCodexReviewAgent:
         assert "feat/test" in prompt_text
         assert "develop" in prompt_text
 
+        # Structured output: schema flag must point at the bundled review schema.
+        assert "--output-schema" in cmd_args
+        schema_path = cmd_args[cmd_args.index("--output-schema") + 1]
+        assert Path(schema_path).name == "review.schema.json"
+        assert Path(schema_path).is_file()
+
     def test_fails_on_missing_prompt(
         self,
         tmp_path: Path,
@@ -143,6 +149,68 @@ class TestClaudeReviewAgent:
         assert "feat/test" in call_kw["stdin"]
         assert "develop" in call_kw["stdin"]
 
+        # Structured output: --output-format json + --json-schema with the
+        # bundled review schema text inlined into argv.
+        cmd_args = mock_retry.call_args[0][2]
+        assert "--output-format" in cmd_args
+        assert cmd_args[cmd_args.index("--output-format") + 1] == "json"
+        assert "--json-schema" in cmd_args
+        schema_text = cmd_args[cmd_args.index("--json-schema") + 1]
+        schema = json.loads(schema_text)
+        assert schema["title"] == "ReviewResult"
+        assert "findings" in schema["properties"]
+
+    def test_unwraps_claude_structured_output(
+        self,
+        tmp_path: Path,
+        make_loop_config: Callable[..., LoopConfig],
+    ) -> None:
+        """Wrapper produced by ``--output-format json`` is unwrapped on disk.
+
+        Regression for the Claude CLI emitting
+        ``{"type":"result", ..., "structured_output": {<review>}}`` — the
+        downstream parser expects the review object, not the wrapper.
+        """
+        review = {
+            "findings": [],
+            "overall_correctness": "patch is correct",
+            "overall_confidence_score": 0.9,
+        }
+        wrapper = {
+            "type": "result",
+            "subtype": "success",
+            "is_error": False,
+            "result": "Done.",
+            "structured_output": review,
+        }
+
+        prompts = tmp_path / "prompts"
+        prompts.mkdir(exist_ok=True)
+        (prompts / "claude-review.prompt.md").write_text("prompt body")
+        config = make_loop_config(prompts_dir=prompts)
+
+        output = tmp_path / "review.json"
+
+        def fake_retry(
+            out_path: Path,
+            _label: str,
+            _argv: list[str],
+            **_kw: object,
+        ) -> bool:
+            out_path.write_text(json.dumps(wrapper))
+            return True
+
+        with (
+            patch("mr_overkill.agents._make_budget_fn") as mb,
+            patch("mr_overkill.agents._make_retry_fn") as mr,
+        ):
+            mb.return_value = MagicMock(return_value=True)
+            mr.return_value = fake_retry
+            agent = ClaudeReviewAgent(config)
+            assert agent(output, 1) is True
+
+        assert json.loads(output.read_text()) == review
+
     def test_fails_on_missing_prompt(
         self,
         tmp_path: Path,

{overkill-0.6.1 → overkill-0.7.0}/tests/test_json_extract.py

@@ -57,14 +57,56 @@ class TestExtractJsonFromFile:
         p.write_text(content)
         assert extract_json_from_file(p) == data
 
-    def test_regex_fallback(self, tmp_path: Path) -> None:
-        """Tier 3: JSON embedded in free text is extracted via regex."""
+    def test_balanced_scan_fallback(self, tmp_path: Path) -> None:
+        """Tier 3: JSON embedded in free text is extracted by the balanced scan."""
         data = {"found": True}
         content = "Random preamble text\n" + json.dumps(data) + "\nmore text\n"
         p = tmp_path / "mixed.txt"
         p.write_text(content)
         assert extract_json_from_file(p) == data
 
+    def test_balanced_scan_with_prose_braces(self, tmp_path: Path) -> None:
+        """Tier 3: prose containing ``{`` does not derail extraction.
+
+        Regression for parse_error encountered when a Claude reviewer prefixed
+        its JSON with prose that mentioned schema fields like ``{user_id}``.
+        """
+        review = {
+            "findings": [],
+            "overall_correctness": "patch is correct",
+            "overall_confidence_score": 0.88,
+        }
+        content = (
+            "Based on my analysis of the iteration 2 review of this diff, "
+            "I've examined:\n"
+            "- The schema additions like {user_id} and {created_at}\n"
+            "- The JSON shape `{findings: [], overall_correctness: ...}`\n"
+            "- IAM permissions for s3 access\n"
+            "\n"
+            "Here is the review:\n"
+            f"{json.dumps(review, indent=2)}\n"
+        )
+        p = tmp_path / "prose.json"
+        p.write_text(content)
+        assert extract_json_from_file(p) == review
+
+    def test_balanced_scan_picks_largest_dict(self, tmp_path: Path) -> None:
+        """Tier 3: when several ``{...}`` candidates parse, prefer the largest."""
+        small = {"k": 1}
+        big = {
+            "findings": [],
+            "overall_correctness": "patch is correct",
+            "overall_confidence_score": 0.9,
+        }
+        content = (
+            f"first candidate: {json.dumps(small)}\n"
+            "more prose\n"
+            f"actual review: {json.dumps(big)}\n"
+        )
+        p = tmp_path / "multi.txt"
+        p.write_text(content)
+        assert extract_json_from_file(p) == big
+
     def test_empty_file_returns_none(self, tmp_path: Path) -> None:
         """Empty (or whitespace-only) file returns None."""
         p = tmp_path / "empty.json"

{overkill-0.6.1 → overkill-0.7.0}/tests/test_retry.py

@@ -46,6 +46,17 @@ class TestExtractResultFromStream:
         f.write_text(f"not json with result\n{ok_line}")
         assert extract_result_from_stream(f) == "ok"
 
+    def test_prefers_structured_output(self, tmp_path: Path) -> None:
+        f = tmp_path / "stream.jsonl"
+        structured = {"findings": [], "overall_correctness": "patch is correct"}
+        line = json.dumps({
+            "type": "result",
+            "result": "plain text summary",
+            "structured_output": structured,
+        })
+        f.write_text(line)
+        assert json.loads(extract_result_from_stream(f)) == structured
+
 
 class TestWaitForBudget:
     def test_budget_ok_immediately(self) -> None:

{overkill-0.6.1 → overkill-0.7.0}/uv.lock

@@ -247,7 +247,7 @@ wheels = [
 
 [[package]]
 name = "overkill"
-version = "0.6.1"
+version = "0.7.0"
 source = { editable = "." }
 
 [package.dev-dependencies]