canopy-cli 3.1.0__py3-none-any.whl

canopy/actions/draft_replies.py

@@ -0,0 +1,185 @@
+"""``canopy draft_replies`` — auto-draft "Done in <sha>" replies (M9).
+
+For each unresolved PR review comment in the feature's repos, walk the
+file's commit history since the comment was anchored. If anything
+changed, the comment is "addressed" — render a template-based draft
+reply the user can review and post.
+
+This is template-based on purpose. The user reviews the draft before
+posting; an LLM-generated reply isn't worth the cost/latency for text
+they'll edit anyway. Future ``draft_replies --llm`` is reserved.
+
+Read-only — generates text, never posts. Posting is a separate (future)
+``post_replies`` action.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ..git import repo as git
+from ..integrations import github as gh
+from ..workspace.workspace import Workspace
+from .aliases import resolve_pr_targets
+
+
+def draft_replies(
+    workspace: Workspace,
+    alias: str,
+    *,
+    include_likely_resolved: bool = False,
+) -> dict[str, Any]:
+    """Per-PR draft-reply set for ``alias``.
+
+    Args:
+        workspace: loaded workspace.
+        alias: feature name, ``<repo>#<n>``, or PR URL — same surface as
+            the existing ``review_comments`` read.
+        include_likely_resolved: also draft for the temporal classifier's
+            ``likely_resolved`` set (weaker signal — comment looks
+            resolved but no commit directly touched the line). Off by
+            default; surface as `confidence: low` when on.
+
+    Returns:
+        ``{alias, repos: {<repo>: {pr_number, pr_url, addressed: [<draft>],
+        unaddressed: [<comment>]}}, addressed_total, unaddressed_total}``.
+    """
+    from .review_filter import classify_threads
+
+    targets = resolve_pr_targets(workspace, alias)
+    repos: dict[str, dict] = {}
+    addressed_total = 0
+    unaddressed_total = 0
+
+    for t in targets:
+        comments, _ = gh.get_review_comments(
+            workspace.config.root, t.owner, t.repo_slug, t.pr_number,
+        )
+        state = workspace.get_repo(t.repo)
+        pr = gh.get_pull_request_by_number(
+            workspace.config.root, t.owner, t.repo_slug, t.pr_number,
+        )
+        branch = (pr or {}).get("head_branch") or state.current_branch
+        classification = classify_threads(comments, state.abs_path, branch)
+
+        candidate_threads = list(classification.get("actionable_threads") or [])
+        if include_likely_resolved:
+            candidate_threads += list(classification.get("likely_resolved_threads") or [])
+
+        addressed: list[dict] = []
+        unaddressed: list[dict] = []
+        for thread in candidate_threads:
+            commit_id = thread.get("commit_id")
+            path = thread.get("path") or ""
+            if not commit_id or not path:
+                # Old comment without anchor info — surface as low-confidence
+                # unaddressed. Don't pretend we know.
+                unaddressed.append({**thread, "reason": "missing_anchor"})
+                continue
+            history = git.log_for_path(state.abs_path, commit_id, path)
+            classified = classify_comment(thread, history)
+            if classified["status"] == "addressed":
+                draft_text = render_reply(thread, classified["addressing_commits"],
+                                          classified["confidence"])
+                addressed.append({
+                    "comment_id": thread.get("id"),
+                    "comment_url": thread.get("url"),
+                    "original_comment": {
+                        "author": thread.get("author"),
+                        "path": path,
+                        "line": thread.get("line"),
+                        "body": thread.get("body"),
+                    },
+                    "addressing_commits": classified["addressing_commits"],
+                    "draft_reply": draft_text,
+                    "confidence": classified["confidence"],
+                })
+            else:
+                unaddressed.append({**thread, "reason": classified.get("reason", "no_commits")})
+
+        addressed_total += len(addressed)
+        unaddressed_total += len(unaddressed)
+        repos[t.repo] = {
+            "pr_number": t.pr_number,
+            "pr_url": (pr or {}).get("url", ""),
+            "addressed": addressed,
+            "unaddressed": unaddressed,
+        }
+
+    return {
+        "alias": alias,
+        "addressed_total": addressed_total,
+        "unaddressed_total": unaddressed_total,
+        "repos": repos,
+    }
+
+
+# ── Pure helpers (testable in isolation) ────────────────────────────────
+
+def classify_comment(comment: dict, history: list[dict]) -> dict[str, Any]:
+    """Decide ``addressed`` vs ``unaddressed`` + a confidence tier.
+
+    Confidence rules:
+      - ``high``   single addressing commit, subject mentions a keyword
+                   from the comment body
+      - ``medium`` single addressing commit, no keyword overlap
+      - ``low``    multiple addressing commits, OR likely-resolved
+                   classifier promotion (caller signals via comment
+                   metadata)
+    """
+    if not history:
+        return {"status": "unaddressed", "addressing_commits": [],
+                "confidence": "low", "reason": "no_commits"}
+
+    if len(history) == 1:
+        keyword_match = _has_keyword_overlap(comment.get("body") or "",
+                                              history[0].get("subject") or "")
+        confidence = "high" if keyword_match else "medium"
+    else:
+        confidence = "low"
+
+    return {
+        "status": "addressed",
+        "addressing_commits": history,
+        "confidence": confidence,
+    }
+
+
+def render_reply(comment: dict, commits: list[dict], confidence: str) -> str:
+    """Generate a template-based draft reply.
+
+    Three branches per the plan:
+      1. Specific subject match    → "Done — <subject>. (<sha>)"
+      2. Single commit fallback    → "Addressed in <sha>: <subject>."
+      3. Multiple commits          → "Addressed across <N> commits — <shas>."
+    """
+    if not commits:
+        return ""
+    if len(commits) > 1:
+        shas = ", ".join(c["sha"][:8] for c in commits)
+        return f"Addressed across {len(commits)} commits — {shas}."
+
+    commit = commits[0]
+    subject = (commit.get("subject") or "").strip()
+    short = (commit.get("sha") or "")[:8]
+    if confidence == "high":
+        # Keyword match → drop the redundant lead-in.
+        return f"Done — {subject}. ({short})"
+    return f"Addressed in {short}: {subject}."
+
+
+# ── Internal ────────────────────────────────────────────────────────────
+
+_TOKEN_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]+")
+
+
+def _has_keyword_overlap(body: str, subject: str) -> bool:
+    """True iff body and subject share an identifier-shaped token (≥ 4 chars).
+
+    Cheap proxy for "the commit subject mentions what the comment was
+    about." Avoids stop-words by sticking to identifier shape and a
+    minimum length threshold.
+    """
+    body_tokens = {t.lower() for t in _TOKEN_RE.findall(body) if len(t) >= 4}
+    subj_tokens = {t.lower() for t in _TOKEN_RE.findall(subject) if len(t) >= 4}
+    return bool(body_tokens & subj_tokens)

canopy/actions/drift.py

@@ -0,0 +1,241 @@
+"""Drift detection: compare recorded heads vs feature lane expectations.
+
+Reads ground truth from ``.canopy/state/heads.json`` (written by the
+post-checkout hook) and compares it to ``FeatureLane.repos`` from
+``.canopy/features.json``. Returns a structured report; ``assert_aligned``
+raises a ``BlockerError`` so any action that has alignment as a precondition
+can use the same primitive.
+
+v1 assumes ``expected_branch == feature_name`` per repo. Per-repo branch
+overrides (e.g., ``auth-flow`` in api vs ``auth-flow-v2`` in ui) will be
+added when the feature lane schema gains per-repo branch mapping. For
+now, exact match against feature name.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ..git.hooks import read_heads_state
+from ..workspace.workspace import Workspace
+from .errors import BlockerError, FixAction
+
+
+@dataclass
+class RepoAlignment:
+    repo: str
+    expected: str
+    actual: str | None
+    aligned: bool
+    state_recorded_at: str | None = None
+    state_age_seconds: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "repo": self.repo,
+            "expected": self.expected,
+            "actual": self.actual,
+            "aligned": self.aligned,
+            "state_recorded_at": self.state_recorded_at,
+            "state_age_seconds": self.state_age_seconds,
+        }
+
+
+@dataclass
+class FeatureDrift:
+    feature: str
+    aligned: bool
+    repos: list[RepoAlignment] = field(default_factory=list)
+    drifted_repos: list[str] = field(default_factory=list)
+    untracked_repos: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "feature": self.feature,
+            "aligned": self.aligned,
+            "repos": [r.to_dict() for r in self.repos],
+            "drifted_repos": list(self.drifted_repos),
+            "untracked_repos": list(self.untracked_repos),
+        }
+
+
+@dataclass
+class DriftReport:
+    workspace_root: str
+    overall_aligned: bool
+    features: list[FeatureDrift] = field(default_factory=list)
+    note: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "workspace_root": self.workspace_root,
+            "overall_aligned": self.overall_aligned,
+            "features": [f.to_dict() for f in self.features],
+        }
+        if self.note:
+            out["note"] = self.note
+        return out
+
+
+def detect_drift(workspace: Workspace, feature_name: str | None = None) -> DriftReport:
+    """Compute drift across one or all active features.
+
+    Args:
+        workspace: loaded ``Workspace``.
+        feature_name: if set, scope to one feature (resolved through coordinator
+            alias logic). If None, report all active features.
+
+    The expected branch for each repo is the feature name. Repos in
+    ``feature.repos`` but missing from heads.json are reported as
+    ``untracked_repos`` — usually because the post-checkout hook hasn't
+    fired in that repo since install (e.g., a fresh workspace where ui
+    hasn't been switched yet).
+    """
+    from ..features.coordinator import FeatureCoordinator
+
+    coordinator = FeatureCoordinator(workspace)
+    heads = read_heads_state(workspace.config.root)
+
+    # list_active() returns only active lanes from features.json + implicit
+    # branches present across multiple repos.
+    active_lanes = coordinator.list_active()
+
+    if feature_name is not None:
+        resolved = coordinator._resolve_name(feature_name)
+        active_lanes = [l for l in active_lanes if l.name == resolved]
+        if not active_lanes:
+            return DriftReport(
+                workspace_root=str(workspace.config.root),
+                overall_aligned=False,
+                note=f"feature '{feature_name}' is not an active feature lane",
+            )
+
+    if not active_lanes:
+        return DriftReport(
+            workspace_root=str(workspace.config.root),
+            overall_aligned=True,
+            note="no active features",
+        )
+
+    feature_drifts: list[FeatureDrift] = []
+    overall = True
+    for lane in active_lanes:
+        fd = _compute_feature_drift(lane, heads)
+        feature_drifts.append(fd)
+        if not fd.aligned:
+            overall = False
+
+    return DriftReport(
+        workspace_root=str(workspace.config.root),
+        overall_aligned=overall,
+        features=feature_drifts,
+    )
+
+
+def assert_aligned(workspace: Workspace, feature_name: str) -> None:
+    """Raise ``BlockerError(code="drift_detected")`` if the feature has drift.
+
+    Used by mutating actions (commit, push, ship) as a precondition. The
+    error's ``fix_actions`` always includes a ``realign`` suggestion for
+    the feature.
+    """
+    report = detect_drift(workspace, feature_name=feature_name)
+    if report.note and "not an active" in report.note:
+        raise BlockerError(
+            code="unknown_feature",
+            what=report.note,
+            details={"feature": feature_name},
+        )
+    drifted = [f for f in report.features if not f.aligned]
+    if not drifted:
+        return
+    fd = drifted[0]
+    expected = {r.repo: r.expected for r in fd.repos}
+    actual = {r.repo: r.actual for r in fd.repos}
+    raise BlockerError(
+        code="drift_detected",
+        what=f"branches don't match feature lane '{fd.feature}'",
+        expected={"feature": fd.feature, "branches": expected},
+        actual={"branches": actual},
+        fix_actions=[
+            FixAction(
+                action="realign",
+                args={"feature": fd.feature},
+                safe=_realign_is_safe(fd),
+                preview=_realign_preview(fd),
+            ),
+        ],
+        details={
+            "drifted_repos": fd.drifted_repos,
+            "untracked_repos": fd.untracked_repos,
+        },
+    )
+
+
+def _compute_feature_drift(lane, heads: dict) -> FeatureDrift:
+    repos: list[RepoAlignment] = []
+    drifted: list[str] = []
+    untracked: list[str] = []
+
+    for repo_name in lane.repos:
+        # Use lane.branch_for to honor per-repo branch overrides
+        # (handles cases like auth-flow vs auth-flow-v2 across repos).
+        expected = lane.branch_for(repo_name)
+        head = heads.get(repo_name)
+        if head is None:
+            ra = RepoAlignment(
+                repo=repo_name, expected=expected,
+                actual=None, aligned=False,
+            )
+            untracked.append(repo_name)
+        else:
+            actual = head.get("branch")
+            aligned = actual == expected
+            ts = head.get("ts")
+            age = _age_seconds(ts) if ts else None
+            ra = RepoAlignment(
+                repo=repo_name, expected=expected,
+                actual=actual, aligned=aligned,
+                state_recorded_at=ts, state_age_seconds=age,
+            )
+            if not aligned:
+                drifted.append(repo_name)
+        repos.append(ra)
+
+    return FeatureDrift(
+        feature=lane.name,
+        aligned=not drifted and not untracked,
+        repos=repos,
+        drifted_repos=drifted,
+        untracked_repos=untracked,
+    )
+
+
+def _age_seconds(iso_ts: str) -> float | None:
+    try:
+        # Hook writes ISO with trailing 'Z'.
+        ts = datetime.strptime(iso_ts, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    except ValueError:
+        return None
+    return (datetime.now(timezone.utc) - ts).total_seconds()
+
+
+def _realign_is_safe(fd: FeatureDrift) -> bool:
+    """Untracked repos are safe to realign (we don't know their state, but
+    realign will check for dirty trees itself before mutating). Drifted
+    repos are also safe — realign refuses to act on dirty trees."""
+    return True
+
+
+def _realign_preview(fd: FeatureDrift) -> str:
+    parts = []
+    for r in fd.repos:
+        if r.aligned:
+            continue
+        if r.actual is None:
+            parts.append(f"{r.repo} (no recorded state; will checkout {r.expected})")
+        else:
+            parts.append(f"{r.repo}: {r.actual} → {r.expected}")
+    return "; ".join(parts)

canopy/actions/errors.py

@@ -0,0 +1,115 @@
+"""Structured, actionable errors for canopy actions.
+
+The design contract: every action error carries enough machine-readable
+context that the consumer (a human reading CLI output, or an agent reading
+MCP JSON) can act on it without parsing prose. Same shape across surfaces.
+
+A BlockerError is a precondition failure: the action refused to start.
+A FailedError is a mid-flight failure: the action started but couldn't
+complete. Both serialize identically; consumers tell them apart by ``status``.
+
+Error contract::
+
+    {
+      "status":      "blocked" | "failed",
+      "code":        "drift_detected" | "preflight_failed" | ...,
+      "what":        "human-readable summary",
+      "expected":    {...},          # action-specific
+      "actual":      {...},          # action-specific
+      "fix_actions": [FixAction...], # ordered, most-recommended first
+      "details":     {...},          # extra context
+    }
+
+CLI renders this via ``canopy.cli.render.render_blocker``. MCP returns the
+dict from ``to_dict`` directly to the agent.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class FixAction:
+    """A suggested next step the user or agent can take to unblock the action.
+
+    ``safe=True`` means an agent can run this without further user
+    confirmation (e.g., a clean realign). ``safe=False`` means the fix
+    might lose work or affect remote state, and a human should approve
+    first (e.g., ``--force`` deletes, force-push).
+    """
+    action: str                       # canopy action name, e.g., "realign"
+    args: dict[str, Any] = field(default_factory=dict)
+    safe: bool = True
+    preview: str | None = None        # one-line description of what'd happen
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "action": self.action,
+            "args": dict(self.args),
+            "safe": self.safe,
+            "preview": self.preview,
+        }
+
+
+class ActionError(Exception):
+    """Base class for canopy action errors.
+
+    Subclasses set ``STATUS`` (``"blocked"`` or ``"failed"``) and provide
+    a ``code`` plus the structured fields. Raise; the calling layer catches
+    and either re-raises (Python consumers), serializes (MCP), or renders
+    (CLI).
+    """
+    STATUS: str = "failed"
+
+    def __init__(
+        self,
+        code: str,
+        what: str,
+        *,
+        expected: Any = None,
+        actual: Any = None,
+        fix_actions: list[FixAction] | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        super().__init__(f"{self.STATUS}: {code}: {what}")
+        self.code = code
+        self.what = what
+        self.expected = expected
+        self.actual = actual
+        self.fix_actions: list[FixAction] = list(fix_actions or [])
+        self.details: dict[str, Any] = dict(details or {})
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "status": self.STATUS,
+            "code": self.code,
+            "what": self.what,
+            "fix_actions": [f.to_dict() for f in self.fix_actions],
+        }
+        if self.expected is not None:
+            out["expected"] = self.expected
+        if self.actual is not None:
+            out["actual"] = self.actual
+        if self.details:
+            out["details"] = self.details
+        return out
+
+
+class BlockerError(ActionError):
+    """Action refused to start because a precondition failed.
+
+    Raised before any side effects. The action's state hasn't changed.
+    Callers should rely on ``fix_actions`` to recover.
+    """
+    STATUS = "blocked"
+
+
+class FailedError(ActionError):
+    """Action started but couldn't complete cleanly.
+
+    May have partial side effects (some repos updated, others not). The
+    ``details`` field SHOULD include per-repo status so the caller can
+    reason about what's left to do.
+    """
+    STATUS = "failed"