code-mower 0.5.0b5__py3-none-any.whl

code_mower/calibration/identity.py

@@ -0,0 +1,27 @@
+"""Stable identifiers for calibration artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any
+
+
+SAFE_SLUG_RE = re.compile(r"[^A-Za-z0-9_.-]+")
+
+
+def safe_slug(value: Any, fallback: str = "item") -> str:
+    text = SAFE_SLUG_RE.sub("-", str(value or "").strip()).strip("._-")
+    while ".." in text:
+        text = text.replace("..", ".")
+    text = text.strip("._-")
+    return text or fallback
+
+
+def head_slug(value: Any) -> str:
+    head = str(value or "").strip()
+    if not head:
+        return ""
+    safe_head = safe_slug(head, "")
+    digest = hashlib.sha256(head.encode("utf-8")).hexdigest()[:12]
+    return f"{safe_head[:12] or digest}-{digest}"

code_mower/calibration/metrics.py

@@ -0,0 +1,18 @@
+"""Calibration metric normalization helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def float_or_zero(value: Any) -> float:
+    if isinstance(value, bool):
+        return 0.0
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except ValueError:
+            return 0.0
+    return 0.0

code_mower/calibration/overlap.py

@@ -0,0 +1,103 @@
+"""Calibration finding-overlap reports."""
+
+from __future__ import annotations
+
+import hashlib
+from itertools import combinations
+from typing import Any, Iterable, Mapping
+
+
+def finding_key(finding: Mapping[str, Any]) -> str:
+    raw = "\n".join(
+        [
+            str(finding.get("repo") or ""),
+            str(finding.get("pr_number") or ""),
+            str(finding.get("head_sha") or ""),
+            str(finding.get("severity") or ""),
+            str(finding.get("path") or ""),
+            " ".join(str(finding.get("text") or "").lower().split()),
+        ]
+    )
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]
+
+
+def build_overlap_report(reports: Iterable[Mapping[str, Any]]) -> dict[str, Any]:
+    profile_findings: dict[str, set[str]] = {}
+    profile_sources: dict[str, set[str]] = {}
+    report_count = 0
+
+    for report in reports:
+        report_count += 1
+        if report.get("mode") != "local-llm-calibration":
+            raise ValueError("overlap reports currently expect local-llm-calibration inputs")
+        source = ",".join(str(item) for item in report.get("sources", []) or [])
+        profiles = report.get("profiles")
+        if isinstance(profiles, Mapping):
+            for profile_id in profiles:
+                profile_id = str(profile_id)
+                if not profile_id:
+                    continue
+                profile_findings.setdefault(profile_id, set())
+                if source:
+                    profile_sources.setdefault(profile_id, set()).add(source)
+        for finding in report.get("findings", []) or []:
+            if not isinstance(finding, Mapping):
+                continue
+            profile_id = str(finding.get("profile_id") or "")
+            if not profile_id:
+                continue
+            profile_findings.setdefault(profile_id, set()).add(finding_key(finding))
+            if source:
+                profile_sources.setdefault(profile_id, set()).add(source)
+
+    pairs: list[dict[str, Any]] = []
+    for left, right in combinations(sorted(profile_findings), 2):
+        left_set = profile_findings[left]
+        right_set = profile_findings[right]
+        union = left_set | right_set
+        intersection = left_set & right_set
+        jaccard_similarity = len(intersection) / len(union) if union else 1.0
+        pairs.append(
+            {
+                "left": left,
+                "right": right,
+                "left_findings": len(left_set),
+                "right_findings": len(right_set),
+                "shared_findings": len(intersection),
+                "union_findings": len(union),
+                "jaccard_similarity": round(jaccard_similarity, 4),
+                "jaccard_distance": round(1.0 - jaccard_similarity, 4),
+            }
+        )
+
+    return {
+        "mode": "code-mower-calibration-overlap",
+        "source_report_count": report_count,
+        "profiles": {
+            profile_id: {
+                "finding_count": len(findings),
+                "sources": sorted(profile_sources.get(profile_id, set())),
+            }
+            for profile_id, findings in sorted(profile_findings.items())
+        },
+        "pairs": pairs,
+        "caveat": (
+            "Exact text overlap is a conservative proxy. Human adjudication or "
+            "semantic clustering is still required before making merge-gate decisions."
+        ),
+    }
+
+
+def render_overlap_text(report: Mapping[str, Any]) -> str:
+    lines = ["Code Mower calibration overlap", "", "Pairs:"]
+    for pair in report.get("pairs", []) or []:
+        if isinstance(pair, Mapping):
+            lines.append(
+                f"- {pair.get('left')} vs {pair.get('right')}: "
+                f"shared={pair.get('shared_findings')} "
+                f"distance={pair.get('jaccard_distance')}"
+            )
+    if not report.get("pairs"):
+        lines.append("- none")
+    lines.extend(["", f"Caveat: {report.get('caveat', '')}"])
+    return "\n".join(lines) + "\n"

code_mower/calibration/planning.py

@@ -0,0 +1,309 @@
+"""Calibration pilot planning and command templates."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .arms import default_arms
+from .identity import head_slug, safe_slug
+
+
+def _run_output_dir(output_dir: Path, item: Mapping[str, Any], arm_id: str, replicate: int) -> Path:
+    repo_slug = safe_slug(str(item["repo"]).replace("/", "__"), "repo")
+    item_head_slug = head_slug(item.get("head_sha", ""))
+    pr_dir = f"pr-{item['pr_number']}" + (f"-{item_head_slug}" if item_head_slug else "")
+    return output_dir / repo_slug / pr_dir / f"r{replicate}" / arm_id
+
+
+def _run_id(item: Mapping[str, Any], *, arm_id: str, replicate: int) -> str:
+    base = f"{safe_slug(str(item['repo']).replace('/', '__'))}-pr-{item['pr_number']}"
+    item_head_slug = head_slug(item.get("head_sha", ""))
+    if item_head_slug:
+        base = f"{base}-{item_head_slug}"
+    return f"{base}-r{replicate}-{arm_id}"
+
+
+def _local_llm_command(
+    item: Mapping[str, Any],
+    *,
+    profiles: Sequence[str],
+    output_dir: Path,
+    jobs: int,
+    repo_path: str = "/path/to/pr-worktree",
+) -> list[str]:
+    command = [
+        "code-mower",
+        "local-llm",
+        "bakeoff",
+        "--repo",
+        str(item["repo"]),
+        "--pr",
+        str(item["pr_number"]),
+        "--profiles",
+        ",".join(profiles),
+        "--output-dir",
+        str(output_dir / "local-llm"),
+        "--jobs",
+        str(jobs),
+        "--json",
+    ]
+    if item.get("head_sha"):
+        command.extend(["--expected-head-sha", str(item["head_sha"])])
+    if item.get("base_ref"):
+        command.extend(["--repo-path", repo_path])
+        command.extend(["--base-ref", str(item["base_ref"])])
+    return command
+
+
+def _local_cli_command(
+    item: Mapping[str, Any],
+    *,
+    lane: str,
+    output_dir: Path,
+    prompt_lenses: Sequence[str] = ("base-audit",),
+    output_leaf: str,
+    repo_path: str = "/path/to/pr-worktree",
+) -> list[str]:
+    command = [
+        "code-mower",
+        lane,
+        "--repo",
+        str(item["repo"]),
+        "--pr",
+        str(item["pr_number"]),
+        "--prompt-lenses",
+        ",".join(prompt_lenses),
+        "--output-dir",
+        str(output_dir / output_leaf),
+        "--json",
+    ]
+    if item.get("head_sha"):
+        command.extend(["--expected-head-sha", str(item["head_sha"])])
+    if item.get("base_ref"):
+        command.extend(["--repo-path", repo_path])
+        command.extend(["--base-ref", str(item["base_ref"])])
+    return command
+
+
+def _coderabbit_cli_command(
+    item: Mapping[str, Any],
+    *,
+    output_dir: Path,
+    repo_path: str = "/path/to/pr-worktree",
+    base_ref: str = "origin/main",
+) -> list[str]:
+    base_ref_value = str(item.get("base_ref") or base_ref)
+    command = [
+        "code-mower",
+        "coderabbit-cli",
+        "--repo",
+        str(item["repo"]),
+        "--pr",
+        str(item["pr_number"]),
+        "--repo-path",
+        repo_path,
+        "--base-ref",
+        base_ref_value,
+        "--output-dir",
+        str(output_dir / "coderabbit-cli"),
+        "--json",
+    ]
+    if item.get("head_sha"):
+        command.extend(["--expected-head-sha", str(item["head_sha"])])
+    return command
+
+
+def _local_cli_output_leaf(*, lane_slug: str, lane_id: str, reviewer_id: str) -> str:
+    if reviewer_id in {lane_slug, lane_id, lane_slug.replace("-", "_")}:
+        return lane_slug
+    return safe_slug(reviewer_id, lane_slug)
+
+
+def render_plan_text(plan: Mapping[str, Any]) -> str:
+    lines = [
+        "Code Mower calibration pilot plan",
+        f"Corpus: {plan.get('corpus_name', '')}",
+        f"Runs: {plan.get('run_count', 0)}",
+        "",
+        "Arms:",
+    ]
+    for arm in plan.get("arms", []) or []:
+        if isinstance(arm, Mapping):
+            lines.append(f"- {arm.get('arm_id')}: {arm.get('kind')} - {arm.get('purpose')}")
+    lines.extend(["", "First commands:"])
+    shown = 0
+    for run in plan.get("runs", []) or []:
+        if not isinstance(run, Mapping):
+            continue
+        if run.get("requires_explicit_arm"):
+            continue
+        for command in run.get("commands", []) or []:
+            if shown >= 3:
+                break
+            lines.append("- " + " ".join(str(part) for part in command))
+            shown += 1
+        if shown >= 3:
+            break
+    if shown == 0:
+        lines.append("- none; this corpus currently needs manual structured audit invocations")
+    return "\n".join(lines) + "\n"
+
+
+def build_pilot_plan(
+    corpus: Mapping[str, Any],
+    *,
+    replicates: int = 1,
+    output_dir: Path = Path(".code-mower/calibration"),
+    jobs: int = 1,
+) -> dict[str, Any]:
+    if replicates <= 0:
+        raise ValueError("replicates must be greater than zero")
+    if jobs <= 0:
+        raise ValueError("jobs must be greater than zero")
+
+    arms = default_arms()
+    runs: list[dict[str, Any]] = []
+    for item in corpus["corpus"]:
+        for replicate in range(1, replicates + 1):
+            for arm in arms:
+                arm_id = str(arm["arm_id"])
+                run_dir = _run_output_dir(output_dir, item, arm_id, replicate)
+                run: dict[str, Any] = {
+                    "run_id": _run_id(item, arm_id=arm_id, replicate=replicate),
+                    "repo": item["repo"],
+                    "pr_number": item["pr_number"],
+                    "head_sha": item.get("head_sha", ""),
+                    "base_ref": item.get("base_ref", ""),
+                    "review_class": item.get("review_class", "general"),
+                    "context_packs": item.get("context_packs", []),
+                    "replicate": replicate,
+                    "arm_id": arm_id,
+                    "kind": arm["kind"],
+                    "reviewers": arm["reviewers"],
+                    "output_dir": str(run_dir),
+                    "blind_review_required": True,
+                    "requires_explicit_arm": bool(arm.get("requires_explicit_arm")),
+                }
+                local_profiles = [
+                    reviewer["profile_id"]
+                    for reviewer in arm["reviewers"]
+                    if reviewer.get("provider") == "local-llm"
+                ]
+                if local_profiles:
+                    commands = run.setdefault("commands", [])
+                    command_metadata = run.setdefault("command_metadata", [])
+                    commands.append(
+                        _local_llm_command(
+                            item,
+                            profiles=local_profiles,
+                            output_dir=run_dir,
+                            jobs=min(jobs, len(local_profiles)),
+                        )
+                    )
+                    command_metadata.append(
+                        {
+                            "lane_id": "local-llm",
+                            "reviewer_ids": list(local_profiles),
+                        }
+                    )
+                cli_reviewers = [
+                    reviewer
+                    for reviewer in arm["reviewers"]
+                    if reviewer.get("provider") == "local-cli"
+                ]
+                if cli_reviewers:
+                    commands = run.setdefault("commands", [])
+                    command_metadata = run.setdefault("command_metadata", [])
+                    notes = run.setdefault("notes", [])
+                    for reviewer in cli_reviewers:
+                        lane_id = str(reviewer["lane_id"])
+                        lane_slug = lane_id.replace("_", "-")
+                        reviewer_id = str(reviewer.get("reviewer_id") or lane_slug)
+                        if reviewer_id == lane_id:
+                            reviewer_id = lane_slug
+                        lenses = [
+                            str(lens)
+                            for lens in reviewer.get("lenses", ["base-audit"])
+                            if str(lens).strip()
+                        ] or ["base-audit"]
+                        if lane_id in {"antigravity_cli", "gemini_cli", "hermes_cli"}:
+                            output_leaf = _local_cli_output_leaf(
+                                lane_slug=lane_slug,
+                                lane_id=lane_id,
+                                reviewer_id=reviewer_id,
+                            )
+                            commands.append(
+                                _local_cli_command(
+                                    item,
+                                    lane=lane_slug,
+                                    output_dir=run_dir,
+                                    prompt_lenses=lenses,
+                                    output_leaf=output_leaf,
+                                )
+                            )
+                            command_metadata.append(
+                                {
+                                    "lane_id": lane_slug,
+                                    "reviewer_id": reviewer_id,
+                                    "lenses": lenses,
+                                }
+                            )
+                        elif lane_id == "coderabbit_cli":
+                            commands.append(
+                                _coderabbit_cli_command(
+                                    item,
+                                    output_dir=run_dir,
+                                )
+                            )
+                            command_metadata.append(
+                                {
+                                    "lane_id": lane_slug,
+                                    "reviewer_id": reviewer_id,
+                                    "lenses": lenses,
+                                }
+                            )
+                            run.setdefault("manual_steps", []).append(
+                                (
+                                    "Check out the PR head in a clean local worktree, then "
+                                    "replace /path/to/pr-worktree in the coderabbit-cli command."
+                                )
+                            )
+                        else:
+                            run.setdefault("manual_steps", []).append(
+                                (
+                                    f"Run {reviewer_id} against {item['repo']}#{item['pr_number']} "
+                                    "under the same head SHA, then store its JSON summary beside this run."
+                                )
+                            )
+                        notes.append(
+                            f"{reviewer_id} is informational calibration evidence, not merge authority."
+                        )
+                if not run.get("commands") and not run.get("manual_steps"):
+                    run["manual_steps"] = [
+                        "Invoke each listed reviewer through its structured audit lane and keep outputs hidden until every reviewer in this arm finishes."
+                    ]
+                if run.get("commands") and len(run.get("commands", [])) != len(
+                    run.get("command_metadata", [])
+                ):
+                    raise ValueError(
+                        f"command/metadata desync in run {run.get('run_id')}"
+                    )
+                runs.append(run)
+
+    return {
+        "mode": "code-mower-calibration-pilot-plan",
+        "corpus_name": corpus.get("name", ""),
+        "description": corpus.get("description", ""),
+        "replicates": replicates,
+        "output_dir": str(output_dir),
+        "arms": arms,
+        "run_count": len(runs),
+        "runs": runs,
+        "guardrails": [
+            "Run all reviewers on the same head SHA for a corpus item.",
+            "Keep arm outputs hidden until every reviewer in that arm completes.",
+            "Use this as calibration evidence, not merge authority.",
+            "Adjudicate findings after collection before comparing accuracy.",
+        ],
+    }

code_mower/calibration/policy.py

@@ -0,0 +1,207 @@
+"""Calibration lane-promotion policy thresholds and report helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .metrics import float_or_zero as _float
+
+MERGE_GATE_USEFUL_RATE = 0.60
+SELECTIVE_USEFUL_RATE = 0.50
+MERGE_GATE_MIN_FINDINGS = 10
+MERGE_GATE_MIN_CLEAN_RUNS = 2
+
+
+def build_lane_policy_report(metrics: Mapping[str, Any]) -> dict[str, Any]:
+    """Build lane-promotion policy recommendations from reviewer metrics."""
+    if metrics.get("mode") != "reviewer-metrics":
+        raise ValueError("lane policy expects a reviewer-metrics report")
+    profiles = metrics.get("profiles", {})
+    if not isinstance(profiles, Mapping):
+        raise ValueError("reviewer-metrics report profiles must be a mapping")
+
+    policies: dict[str, dict[str, Any]] = {}
+    for profile_id, stats in sorted(profiles.items()):
+        if not isinstance(stats, Mapping):
+            continue
+        useful_rate = _float(stats.get("useful_rate"))
+        useful_findings = int(stats.get("useful_findings") or 0)
+        known_findings = int(stats.get("known_disposition_count") or 0)
+        clean_pass_runs = int(stats.get("known_clean_pass_runs") or 0)
+        false_positive_runs = int(stats.get("blocking_false_positive_runs") or 0)
+        known_blocked_missed_runs = int(stats.get("known_blocked_missed_runs") or 0)
+        infra_error_runs = int(stats.get("infra_error_runs") or 0)
+        audit_input_insufficient_runs = int(
+            stats.get("audit_input_insufficient_runs") or 0
+        )
+        review_classes = [
+            str(item)
+            for item in stats.get("review_classes", []) or []
+            if str(item).strip()
+        ]
+        useful_review_classes = [
+            str(item)
+            for item in stats.get("useful_review_classes", []) or []
+            if str(item).strip()
+        ]
+        context_packs = [
+            str(item)
+            for item in stats.get("context_packs", []) or []
+            if str(item).strip()
+        ]
+        useful_context_packs = [
+            str(item)
+            for item in stats.get("useful_context_packs", []) or []
+            if str(item).strip()
+        ]
+        narrow_useful_review_classes = [
+            review_class
+            for review_class in useful_review_classes
+            if review_class not in {"", "general"}
+        ]
+        event_log = stats.get("event_log", {})
+        observed_pr_count = (
+            int(event_log.get("observed_pr_count") or 0)
+            if isinstance(event_log, Mapping)
+            else 0
+        )
+        reasons: list[str] = []
+        if known_findings < MERGE_GATE_MIN_FINDINGS:
+            reasons.append(
+                f"needs at least {MERGE_GATE_MIN_FINDINGS} adjudicated findings"
+            )
+        if clean_pass_runs < MERGE_GATE_MIN_CLEAN_RUNS:
+            reasons.append(
+                f"needs at least {MERGE_GATE_MIN_CLEAN_RUNS} known-clean zero-blocker runs"
+            )
+        if false_positive_runs:
+            reasons.append("has known-clean blocking false positives")
+        if known_blocked_missed_runs:
+            reasons.append("missed known-blocked calibration runs")
+        if infra_error_runs:
+            reasons.append("has infra/setup failures to stabilize before promotion")
+        if audit_input_insufficient_runs:
+            reasons.append("needs richer audit input/context before promotion")
+        if useful_rate < SELECTIVE_USEFUL_RATE:
+            reasons.append("useful-rate below selective-trigger threshold")
+        if (
+            known_findings >= MERGE_GATE_MIN_FINDINGS
+            and clean_pass_runs >= MERGE_GATE_MIN_CLEAN_RUNS
+            and false_positive_runs == 0
+            and known_blocked_missed_runs == 0
+            and infra_error_runs == 0
+            and audit_input_insufficient_runs == 0
+            and useful_rate >= MERGE_GATE_USEFUL_RATE
+        ):
+            classification = "merge_gate_candidate"
+        elif (
+            useful_findings > 0
+            and useful_rate >= SELECTIVE_USEFUL_RATE
+            and bool(narrow_useful_review_classes)
+            and false_positive_runs == 0
+            and clean_pass_runs >= MERGE_GATE_MIN_CLEAN_RUNS
+            and known_blocked_missed_runs == 0
+            and infra_error_runs == 0
+            and audit_input_insufficient_runs == 0
+        ):
+            classification = "selective_trigger_candidate"
+        else:
+            classification = "informational"
+
+        if (
+            classification == "informational"
+            and useful_findings > 0
+            and useful_rate >= SELECTIVE_USEFUL_RATE
+            and not narrow_useful_review_classes
+        ):
+            reasons.append(
+                "needs useful non-general review-class evidence for selective triggers"
+            )
+
+        if classification == "merge_gate_candidate":
+            recommended_role = "merge_gate_eligible"
+            automatic_trigger = "repo_merge_bar_opt_in"
+        elif classification == "selective_trigger_candidate":
+            recommended_role = "selective_trigger"
+            automatic_trigger = "matching_review_class_only"
+        else:
+            recommended_role = "informational"
+            automatic_trigger = "manual_or_calibration_only"
+
+        suggested_trigger_classes = (
+            narrow_useful_review_classes
+            if classification == "selective_trigger_candidate"
+            else []
+        )
+
+        policies[str(profile_id)] = {
+            "profile_id": str(profile_id),
+            "classification": classification,
+            "recommended_role": recommended_role,
+            "automatic_trigger": automatic_trigger,
+            "suggested_trigger_classes": suggested_trigger_classes,
+            "review_classes": review_classes,
+            "context_packs": context_packs,
+            "useful_review_classes": useful_review_classes,
+            "useful_context_packs": useful_context_packs,
+            "useful_rate": (
+                useful_rate if stats.get("useful_rate") is not None else None
+            ),
+            "useful_findings": useful_findings,
+            "known_disposition_count": known_findings,
+            "known_clean_pass_runs": clean_pass_runs,
+            "blocking_false_positive_runs": false_positive_runs,
+            "known_blocked_runs": int(stats.get("known_blocked_runs") or 0),
+            "known_blocked_caught_runs": int(
+                stats.get("known_blocked_caught_runs") or 0
+            ),
+            "known_blocked_missed_runs": known_blocked_missed_runs,
+            "infra_error_runs": infra_error_runs,
+            "audit_input_insufficient_runs": audit_input_insufficient_runs,
+            "observed_pr_count": observed_pr_count,
+            "reasons": reasons
+            or [
+                "evidence meets current threshold heuristics; "
+                "keep human review in the loop"
+            ],
+        }
+
+    return {
+        "mode": "code-mower-lane-policy",
+        "source_mode": metrics.get("mode"),
+        "thresholds": {
+            "merge_gate_useful_rate": MERGE_GATE_USEFUL_RATE,
+            "selective_useful_rate": SELECTIVE_USEFUL_RATE,
+            "merge_gate_min_findings": MERGE_GATE_MIN_FINDINGS,
+            "merge_gate_min_clean_runs": MERGE_GATE_MIN_CLEAN_RUNS,
+        },
+        "policies": policies,
+        "caveat": (
+            "This is a policy recommendation from calibration evidence, not an "
+            "automatic repository merge-rule change."
+        ),
+    }
+
+
+def render_policy_text(report: Mapping[str, Any]) -> str:
+    lines = ["Code Mower lane policy", "", "Policies:"]
+    policies = report.get("policies", {})
+    if isinstance(policies, Mapping) and policies:
+        for profile_id, policy in policies.items():
+            if not isinstance(policy, Mapping):
+                continue
+            lines.append(
+                f"- {profile_id}: {policy.get('classification')} "
+                f"role={policy.get('recommended_role')} "
+                f"trigger={policy.get('automatic_trigger')} "
+                f"useful_rate={policy.get('useful_rate')} "
+                f"clean_passes={policy.get('known_clean_pass_runs', 0)}"
+            )
+            reasons = policy.get("reasons", [])
+            if isinstance(reasons, list) and reasons:
+                lines.append(f"  reasons: {'; '.join(str(reason) for reason in reasons)}")
+    else:
+        lines.append("- none")
+    lines.extend(["", f"Caveat: {report.get('caveat', '')}"])
+    return "\n".join(lines) + "\n"