devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/github/pr_reporter.py

@@ -0,0 +1,555 @@
+"""
+Sprint 29 — GitHub PR reasoning-delta comment and merge gate.
+
+Builds a markdown comment that surfaces Θ changes, sensitivity events, new
+concepts, MCS score/trend, and invariant status for a pull request. Also
+provides a merge gate that blocks merge when I3 mismatches on critical
+concepts, MCS is too low, or a consensus lock is active.
+
+No external HTTP dependencies: `post_pr_comment` uses only the standard
+library `urllib`.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+
+
+try:
+    from devtorch_core import GCCRepository
+except ImportError:  # pragma: no cover
+    GCCRepository = None  # type: ignore[misc,assignment]
+
+
+@dataclass
+class MergeGateResult:
+    """Result of a merge-gate check."""
+
+    allowed: bool
+    reasons: List[str] = field(default_factory=list)
+    summary: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_commit(repo: Any, commit_id: Optional[str]) -> Optional[dict]:
+    """Load a commit object from .GCC/commits/<id>.json if it exists."""
+    if not commit_id or not hasattr(repo, "gcc_dir"):
+        return None
+    commit_path = repo.gcc_dir / "commits" / f"{commit_id}.json"
+    if not commit_path.exists():
+        return None
+    try:
+        return json.loads(commit_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _branch_tip(repo: Any, branch: str) -> Optional[str]:
+    """Return the commit id at the tip of *branch*, or None."""
+    if not hasattr(repo, "_read_branch_tip"):
+        return None
+    return repo._read_branch_tip(branch)
+
+
+def _now_utc() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _reconstruct_theta(events: List[dict]) -> Dict[str, dict]:
+    """
+    Reconstruct a Θ coordination vector from a list of sensitivity event dicts.
+    Uses the same rules as RulesBasedAggPhi + ThetaStore.ripple.
+    """
+    from devtorch_core.theta import RulesBasedAggPhi
+
+    aggregator = RulesBasedAggPhi()
+    delta = aggregator.aggregate(events)
+    theta: Dict[str, dict] = {}
+    for concept, entry in delta.items():
+        theta[concept] = dict(entry)
+        theta[concept]["last_updated"] = entry.get("last_updated") or _now_utc()
+    return theta
+
+
+def _compare_theta(
+    base: Dict[str, dict],
+    head: Dict[str, dict],
+) -> Tuple[List[str], List[str], List[Tuple[str, dict, dict]]]:
+    """
+    Compare two Θ coordination vectors.
+
+    Returns:
+        (added_concepts, removed_concepts, modified_concepts)
+        where modified_concepts is a list of (concept, base_entry, head_entry).
+    """
+    base_keys = set(base.keys())
+    head_keys = set(head.keys())
+    added = sorted(head_keys - base_keys)
+    removed = sorted(base_keys - head_keys)
+    modified: List[Tuple[str, dict, dict]] = []
+    for concept in sorted(base_keys & head_keys):
+        b = base[concept]
+        h = head[concept]
+        if any(
+            b.get(k) != h.get(k)
+            for k in ("mean_confidence", "disclosure_level", "event_count")
+        ):
+            modified.append((concept, b, h))
+    return added, removed, modified
+
+
+def _split_events_by_cutoff(
+    events: List[dict],
+    cutoff: Optional[str],
+) -> Tuple[List[dict], List[dict]]:
+    """Split events into (before_or_at_cutoff, after_cutoff)."""
+    if not cutoff:
+        return [], events
+    before: List[dict] = []
+    after: List[dict] = []
+    for ev in events:
+        ts = ev.get("created_at", "") or ""
+        if ts and ts < cutoff:
+            before.append(ev)
+        else:
+            after.append(ev)
+    return before, after
+
+
+def _compute_mcs_proxy(events: List[dict]) -> float:
+    """
+    Compute a proxy MCS score from sensitivity events.
+
+    Since the repo does not store explicit CollisionEvents, we derive a proxy:
+    severity = 1.0 - confidence, resolution_minutes = 0. The returned value is
+    intentionally simple; it is a design assumption documented in the comment.
+    """
+    from devtorch_core.metrics import CollisionEvent, compute_mcs
+
+    if not events:
+        return 0.0
+    collisions = [
+        CollisionEvent(
+            timestamp=ev.get("created_at", _now_utc()),
+            branch_a="head",
+            branch_b="base",
+            concept=ev.get("target_concept", "unknown"),
+            severity=max(0.0, min(1.0, 1.0 - float(ev.get("confidence", 0.5)))),
+            resolution_minutes=0.0,
+        )
+        for ev in events
+    ]
+    return float(compute_mcs(collisions))
+
+
+def _load_sensitivity_events(repo: Any) -> List[dict]:
+    """Return all sensitivity events from the repo as dicts."""
+    if not hasattr(repo, "list_sensitivities"):
+        return []
+    return repo.list_sensitivities()
+
+
+def _load_concepts(repo: Any) -> List[str]:
+    """Return all defined concept names from the repo."""
+    if not hasattr(repo, "concept_list"):
+        return []
+    return repo.concept_list()
+
+
+def _run_invariants(
+    repo: Any,
+    base_branch: str,
+    head_branch: str,
+    critical_concepts: List[str],
+) -> List[Any]:
+    """Run I1/I3 invariants for the merge of base into head."""
+    if not hasattr(repo, "invariant_check"):
+        return []
+    base_tip = _branch_tip(repo, base_branch)
+    head_tip = _branch_tip(repo, head_branch)
+    branch_tips = {base_branch: base_tip or "", head_branch: head_tip or ""}
+    return repo.invariant_check(
+        operation="merge",
+        branch_tips=branch_tips,
+        concepts_used=critical_concepts,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def build_reasoning_delta_comment(
+    repo: Any,
+    base_branch: str,
+    head_branch: str,
+) -> str:
+    """
+    Generate a markdown PR comment describing the reasoning delta between
+    *base_branch* and *head_branch*.
+
+    Assumptions
+    -----------
+    - The repo stores a single current Θ vector; the "base" Θ is reconstructed
+      by replaying sensitivity events whose timestamp is older than the head
+      branch tip commit timestamp.
+    - MCS is a proxy derived from sensitivity-event confidence (severity = 1 -
+      confidence). True collision events are not persisted yet.
+    - New concepts are those defined in the concept store and referenced by
+      sensitivity events introduced on the head branch.
+    """
+    lines: List[str] = []
+
+    # ── Header ──────────────────────────────────────────────────────────────
+    lines.append("## 🛡️ DevTorch Reasoning Delta")
+    lines.append("")
+    lines.append(f"Comparing `{base_branch}` (base) → `{head_branch}` (head).")
+    lines.append("")
+
+    # ── Branch tips ─────────────────────────────────────────────────────────
+    base_tip = _branch_tip(repo, base_branch)
+    head_tip = _branch_tip(repo, head_branch)
+    head_commit = _load_commit(repo, head_tip)
+    head_ts = head_commit.get("timestamp") if head_commit else None
+
+    lines.append("| Branch | Tip |")
+    lines.append("|---|---|")
+    lines.append(f"| `{base_branch}` | `{base_tip or 'none'}` |")
+    lines.append(f"| `{head_branch}` | `{head_tip or 'none'}` |")
+    lines.append("")
+
+    # ── Θ changes ─────────────────────────────────────────────────────────────
+    theta = repo.get_theta() if hasattr(repo, "get_theta") else {"coordination_vector": {}}
+    head_theta = theta.get("coordination_vector", {})
+
+    all_events = _load_sensitivity_events(repo)
+    base_events, head_events = _split_events_by_cutoff(all_events, head_ts)
+    base_theta = _reconstruct_theta(base_events)
+
+    added, removed, modified = _compare_theta(base_theta, head_theta)
+
+    lines.append("### Θ Changes")
+    lines.append("")
+    if added:
+        lines.append("**Added concepts:**")
+        for c in added:
+            entry = head_theta.get(c, {})
+            conf = entry.get("mean_confidence", 0.0)
+            dl = entry.get("disclosure_level", "PUBLIC")
+            lines.append(f"- `{c}` — confidence {conf:.2f}, disclosure `{dl}`")
+        lines.append("")
+    if removed:
+        lines.append("**Removed concepts:**")
+        for c in removed:
+            lines.append(f"- `{c}`")
+        lines.append("")
+    if modified:
+        lines.append("**Modified concepts:**")
+        for c, b, h in modified:
+            bc = b.get("mean_confidence", 0.0)
+            hc = h.get("mean_confidence", 0.0)
+            bd = b.get("disclosure_level", "PUBLIC")
+            hd = h.get("disclosure_level", "PUBLIC")
+            be = b.get("event_count", 0)
+            he = h.get("event_count", 0)
+            lines.append(
+                f"- `{c}` — confidence {bc:.2f} → {hc:.2f}, "
+                f"disclosure `{bd}` → `{hd}`, events {be} → {he}"
+            )
+        lines.append("")
+    if not (added or removed or modified):
+        lines.append("_No Θ changes detected between base and head._")
+        lines.append("")
+
+    # ── Sensitivity events added in this PR ─────────────────────────────────
+    lines.append("### Sensitivity Events Added in This PR")
+    lines.append("")
+    if head_events:
+        lines.append(f"**{len(head_events)}** new sensitivity event(s).")
+        lines.append("")
+        for ev in head_events:
+            concept = ev.get("target_concept", "unknown")
+            conf = ev.get("confidence", 0.0)
+            dl = ev.get("disclosure_level", "PUBLIC")
+            src = ev.get("source_node", "unknown")
+            lines.append(
+                f"- `{concept}` — source `{src}`, confidence `{conf:.2f}`, disclosure `{dl}`"
+            )
+        lines.append("")
+    else:
+        lines.append("_No new sensitivity events detected._")
+        lines.append("")
+
+    # ── New concepts defined ──────────────────────────────────────────────────
+    defined_concepts = set(_load_concepts(repo))
+    new_concepts = sorted(
+        (set(added) & defined_concepts)
+        | {
+            ev.get("target_concept", "")
+            for ev in head_events
+            if ev.get("target_concept", "") in defined_concepts
+        }
+    )
+    lines.append("### New Concepts Defined")
+    lines.append("")
+    if new_concepts:
+        for c in new_concepts:
+            lines.append(f"- `{c}`")
+        lines.append("")
+    else:
+        lines.append("_No new concept definitions detected._")
+        lines.append("")
+
+    # ── MCS score and trend ─────────────────────────────────────────────────
+    head_mcs = _compute_mcs_proxy(head_events)
+    base_mcs = _compute_mcs_proxy(base_events)
+    if head_mcs > base_mcs:
+        trend = "↗️ rising"
+    elif head_mcs < base_mcs:
+        trend = "↘️ falling"
+    else:
+        trend = "➡️ stable"
+
+    lines.append("### MCS Score & Trend")
+    lines.append("")
+    lines.append(f"- **Head MCS:** `{head_mcs:.2f}`")
+    lines.append(f"- **Base MCS:** `{base_mcs:.2f}`")
+    lines.append(f"- **Trend:** {trend}")
+    lines.append("")
+
+    # ── Invariant status (I1/I3) at head ────────────────────────────────────
+    failures = _run_invariants(repo, base_branch, head_branch, [])
+    i1_failures = [f for f in failures if getattr(f, "invariant_id", "") == "I1"]
+    i3_failures = [f for f in failures if getattr(f, "invariant_id", "") == "I3"]
+
+    lines.append("### Invariant Status at Head")
+    lines.append("")
+    i1_status = "✅ OK" if not i1_failures else "❌ FAILED"
+    i3_status = "✅ OK" if not i3_failures else "❌ FAILED"
+    lines.append(f"- **I1 (Commit-backed):** {i1_status} ({len(i1_failures)} failure(s))")
+    lines.append(f"- **I3 (Semantic grounding):** {i3_status} ({len(i3_failures)} failure(s))")
+    lines.append("")
+    if failures:
+        lines.append("**Failures:**")
+        for f in failures:
+            inv_id = getattr(f, "invariant_id", "?")
+            msg = getattr(f, "message", str(f))
+            fix = getattr(f, "actionable_fix", "")
+            lines.append(f"- `{inv_id}`: {msg}")
+            if fix:
+                lines.append(f"  - Fix: {fix}")
+        lines.append("")
+
+    # ── Assumptions ───────────────────────────────────────────────────────────
+    lines.append("### Assumptions")
+    lines.append("")
+    lines.append(
+        "1. Base Θ is reconstructed by replaying sensitivity events whose "
+        "`created_at` is older than the head branch tip commit timestamp."
+    )
+    lines.append(
+        "2. MCS is a proxy derived from sensitivity-event confidence "
+        "(`severity = 1 - confidence`). True collision events are not persisted."
+    )
+    lines.append(
+        "3. New concepts are concept-store definitions referenced by head-branch "
+        "sensitivity events or newly added Θ concepts."
+    )
+    lines.append(
+        "4. The merge gate below uses the same invariant context as a "
+        "fast-forward merge of base into head."
+    )
+    lines.append("")
+
+    # ── Footer ───────────────────────────────────────────────────────────────
+    lines.append(
+        "---\n_Generated by DevTorch | "
+        "[docs](https://github.com/flotorch-ai/devtorch)_"
+    )
+
+    return "\n".join(lines)
+
+
+def check_merge_gate(
+    repo: Any,
+    critical_concepts: List[str],
+    min_mcs: float,
+) -> MergeGateResult:
+    """
+    Check whether a PR can merge.
+
+    Gate conditions:
+    - No unresolved I3 mismatches on *critical_concepts*.
+    - MCS score >= *min_mcs* (when min_mcs > 0).
+    - No unresolved consensus lock.
+    """
+    reasons: List[str] = []
+    current_branch = (
+        repo._current_branch()
+        if hasattr(repo, "_current_branch")
+        else "main"
+    )
+
+    # I3 on critical concepts
+    failures = _run_invariants(
+        repo,
+        base_branch=current_branch,
+        head_branch=current_branch,
+        critical_concepts=critical_concepts,
+    )
+    i3_failures = [f for f in failures if getattr(f, "invariant_id", "") == "I3"]
+    if i3_failures:
+        concepts_missing = [f"`{getattr(f, 'message', str(f))}`" for f in i3_failures]
+        reasons.append(
+            "I3 semantic-grounding failures on critical concepts: "
+            + ", ".join(concepts_missing)
+        )
+
+    # MCS threshold
+    if min_mcs > 0:
+        all_events = _load_sensitivity_events(repo)
+        current_mcs = _compute_mcs_proxy(all_events)
+        if current_mcs < min_mcs:
+            reasons.append(
+                f"MCS score {current_mcs:.2f} is below required minimum {min_mcs:.2f}"
+            )
+
+    # Consensus lock
+    if hasattr(repo, "is_locked") and repo.is_locked():
+        reasons.append("Consensus lock is active; unlock before merging")
+
+    allowed = not reasons
+    if allowed:
+        summary = "Merge gate passed: no I3 mismatches, MCS OK, and no consensus lock."
+    else:
+        summary = "Merge gate blocked: " + "; ".join(reasons)
+
+    return MergeGateResult(allowed=allowed, reasons=reasons, summary=summary)
+
+
+def post_pr_comment(
+    repo_owner: str,
+    repo_name: str,
+    pr_number: int,
+    token: str,
+    body: str,
+) -> bool:
+    """
+    Post *body* as a comment on a GitHub PR using only the standard library.
+
+    Returns True on success (HTTP 2xx), False otherwise.
+    """
+    url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/issues/{pr_number}/comments"
+    payload = json.dumps({"body": body}).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=payload,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "DevTorch-PR-Reporter",
+            "Content-Type": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            return 200 <= resp.status < 300
+    except Exception:
+        return False
+
+
+def run_pr_reporter(
+    gcc_repo_path: str,
+    base_branch: str,
+    head_branch: str,
+    repo_owner: str,
+    repo_name: str,
+    pr_number: int,
+    token: str,
+    critical_concepts: List[str],
+    min_mcs: float,
+) -> MergeGateResult:
+    """
+    Orchestrate building the reasoning-delta comment and merge gate, post the
+    comment, and return the gate result.
+    """
+    if GCCRepository is None:
+        raise RuntimeError("GCCRepository is not available")
+
+    repo = GCCRepository.at(Path(gcc_repo_path))
+    if not repo.is_initialized():
+        raise RuntimeError(f"GCC repository at {gcc_repo_path} is not initialized")
+
+    comment = build_reasoning_delta_comment(repo, base_branch, head_branch)
+    post_pr_comment(repo_owner, repo_name, pr_number, token, comment)
+
+    return check_merge_gate(repo, critical_concepts, min_mcs)
+
+
+def main() -> None:
+    """
+    Lightweight CLI helper for manual invocation.
+
+    Usage example:
+        python -m devtorch_core.github.pr_reporter \
+            /path/to/repo base head owner name 42 token "auth,schema" 0.5
+    """
+    import sys
+
+    args = sys.argv[1:]
+    if len(args) != 9:
+        print(
+            "Usage: python -m devtorch_core.github.pr_reporter "
+            "<gcc_repo_path> <base_branch> <head_branch> "
+            "<repo_owner> <repo_name> <pr_number> <token> "
+            "<critical_concepts_csv> <min_mcs>",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    (
+        gcc_repo_path,
+        base_branch,
+        head_branch,
+        repo_owner,
+        repo_name,
+        pr_number_str,
+        token,
+        critical_concepts_csv,
+        min_mcs_str,
+    ) = args
+
+    pr_number = int(pr_number_str)
+    critical_concepts = [c.strip() for c in critical_concepts_csv.split(",") if c.strip()]
+    min_mcs = float(min_mcs_str)
+
+    result = run_pr_reporter(
+        gcc_repo_path=gcc_repo_path,
+        base_branch=base_branch,
+        head_branch=head_branch,
+        repo_owner=repo_owner,
+        repo_name=repo_name,
+        pr_number=pr_number,
+        token=token,
+        critical_concepts=critical_concepts,
+        min_mcs=min_mcs,
+    )
+    print(result.summary)
+    sys.exit(0 if result.allowed else 1)
+
+
+if __name__ == "__main__":
+    main()