canopy-cli 3.1.0__py3-none-any.whl

canopy/actions/feature_state.py

@@ -0,0 +1,607 @@
+"""feature_state(feature) — single source of truth for the dashboard CTAs.
+
+Composes drift detection (P1) + dirty/branch state (workspace) + ahead/behind
+(git) + temporal-filtered review comments (P4) + recorded preflight result
+(``preflight_state``) + GitHub PR data (gh CLI fallback or MCP) into one
+of these states:
+
+    drifted          -- branches not on the feature; first thing to fix
+    needs_work       -- review feedback exists (CHANGES_REQUESTED or
+                        actionable threads from any reviewer)
+    in_progress      -- aligned, dirty tree, no fresh preflight
+    ready_to_commit  -- aligned, dirty tree, preflight passed for current HEAD
+    ready_to_push    -- aligned, clean, ahead of remote
+    awaiting_review  -- aligned, clean, pushed, PRs open, no actionable threads
+    approved         -- all PRs approved
+    no_prs           -- aligned, clean, no PRs anywhere
+
+The state result also carries a ``next_actions`` list — the dashboard
+renders the first one as the primary CTA, the rest as secondary. Same
+data the agent uses to decide what to do next, so the human and the
+agent stay in lockstep.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..git import repo as git
+from ..integrations import github as gh
+from ..workspace.workspace import Workspace
+from .aliases import (
+    repos_for_feature, resolve_feature, _resolve_owner_slug,
+)
+from .augments import bot_authors
+from .bot_resolutions import resolutions_for_feature
+from .preflight_state import is_fresh
+from .review_filter import classify_threads
+
+
+def feature_state(workspace: Workspace, feature: str) -> dict[str, Any]:
+    """Compute the feature's current state + suggested next actions.
+
+    Args:
+        workspace: loaded workspace.
+        feature: feature alias (resolved through the standard alias layer).
+
+    Returns ``{feature, state, summary, next_actions, warnings}`` —
+    summary fields aggregate per-repo state so the dashboard can render
+    a feature card without re-querying.
+    """
+    feature_name = resolve_feature(workspace, feature)
+    workspace.refresh()
+
+    repo_branches = repos_for_feature(workspace, feature_name)
+    if not repo_branches:
+        return _shell_result(feature_name, "no_prs",
+                              note="no repos resolved for feature")
+
+    # A worktree-backed feature physically lives at its worktree path,
+    # regardless of which feature is "active" right now. Resolve per-repo
+    # paths up front so drift + per-repo facts both check the right tree.
+    repo_paths, has_worktrees = resolve_repo_paths(
+        workspace, feature_name, repo_branches,
+    )
+
+    # Drift check from LIVE git state (not heads.json, which may be empty
+    # if the post-checkout hook hasn't run). The hook + heads.json power
+    # canopy drift's fast path; feature_state prefers correctness.
+    drift_info = _live_drift(workspace, repo_branches, repo_paths)
+    if drift_info["drifted_repos"] or drift_info["missing_repos"]:
+        return _drifted_result(feature_name, drift_info, has_worktrees=has_worktrees)
+
+    # Aligned. Gather per-repo facts.
+    per_repo = _per_repo_facts(workspace, feature_name, repo_branches, repo_paths)
+    summary = _summarize(per_repo)
+    preflight_fresh, preflight_entry = is_fresh(
+        workspace, feature_name, repo_branches,
+    )
+    summary["preflight"] = _preflight_summary(preflight_entry, preflight_fresh)
+
+    state, next_actions, warnings = _decide_state(
+        feature_name, per_repo, summary, preflight_fresh, preflight_entry,
+    )
+
+    return {
+        "feature": feature_name,
+        "state": state,
+        "summary": summary,
+        "next_actions": next_actions,
+        "warnings": warnings,
+    }
+
+
+def resolve_repo_paths(
+    workspace: Workspace, feature_name: str, repo_branches: dict[str, str],
+) -> tuple[dict[str, Path], bool]:
+    """Per-repo path resolution for state derivation.
+
+    Worktree-backed features always resolve to the worktree path, regardless
+    of activation status — a worktree IS the feature's home, the active flag
+    only governs implicit cwd in canopy_run/IDE openers.
+
+    Returns (paths_by_repo, has_any_worktrees). The flag drives downstream
+    UX choices (e.g. drifted-state next-action: switch vs realign).
+    """
+    from ..features.coordinator import FeatureCoordinator
+    coord = FeatureCoordinator(workspace)
+    try:
+        lane = coord.status(feature_name)
+    except Exception:
+        lane = None
+
+    paths: dict[str, Path] = {}
+    has_worktrees = False
+    for repo_name in repo_branches:
+        try:
+            state = workspace.get_repo(repo_name)
+        except KeyError:
+            continue
+        wt_path: Path | None = None
+        if lane is not None:
+            wt_str = (lane.repo_states.get(repo_name) or {}).get("worktree_path")
+            if wt_str:
+                candidate = Path(wt_str).resolve()
+                # ``worktree_for_branch`` returns the main repo path when the
+                # branch is checked out there, so candidate == state.abs_path
+                # means "no linked worktree — feature lives in the main tree."
+                if candidate.exists() and candidate != state.abs_path.resolve():
+                    wt_path = candidate
+                    has_worktrees = True
+        paths[repo_name] = wt_path if wt_path is not None else state.abs_path
+    return paths, has_worktrees
+
+
+def _per_repo_facts(
+    workspace: Workspace, feature_name: str, repo_branches: dict[str, str],
+    repo_paths: dict[str, Path],
+) -> dict[str, dict]:
+    """Gather facts per repo: dirty, ahead/behind, PR, comments.
+
+    ``repo_paths`` resolves to the worktree path for worktree-backed
+    features, the main repo path otherwise. Without it, dirty/ahead/branch
+    checks would target main even when the feature lives in a worktree.
+    """
+    out: dict[str, dict] = {}
+    for repo_name, branch in repo_branches.items():
+        try:
+            state = workspace.get_repo(repo_name)
+        except KeyError:
+            continue
+        repo_path = repo_paths.get(repo_name, state.abs_path)
+
+        facts: dict[str, Any] = {
+            "branch": branch,
+            "exists_locally": git.branch_exists(repo_path, branch),
+        }
+        if not facts["exists_locally"]:
+            out[repo_name] = facts
+            continue
+
+        try:
+            facts["is_dirty"] = git.is_dirty(repo_path)
+            facts["dirty_count"] = git.dirty_file_count(repo_path)
+        except git.GitError:
+            facts["is_dirty"] = False
+            facts["dirty_count"] = 0
+
+        try:
+            facts["head_sha"] = git.sha_of(repo_path, branch)
+        except git.GitError:
+            facts["head_sha"] = ""
+
+        remote_ref = f"origin/{branch}"
+        facts["has_upstream"] = bool(git.sha_of(repo_path, remote_ref))
+        if facts["has_upstream"]:
+            try:
+                ahead, behind = git.divergence(repo_path, branch, remote_ref)
+                facts["ahead"] = ahead
+                facts["behind"] = behind
+            except Exception:
+                facts["ahead"] = 0
+                facts["behind"] = 0
+        else:
+            facts["ahead"] = 0
+            facts["behind"] = 0
+
+        # PR + comment data.
+        try:
+            owner, slug = _resolve_owner_slug(workspace, repo_name)
+        except Exception:
+            owner, slug = "", ""
+        facts["owner"] = owner
+        facts["repo_slug"] = slug
+        facts["pr"] = None
+        facts["actionable_count"] = 0
+        facts["actionable_human_count"] = 0
+        facts["actionable_bot_count"] = 0
+        facts["actionable_bot_threads"] = []
+        facts["likely_resolved_count"] = 0
+        facts["review_decision"] = ""
+        if owner and slug:
+            try:
+                pr = gh.find_pull_request(
+                    workspace.config.root, owner, slug, branch,
+                )
+            except gh.GitHubNotConfiguredError:
+                pr = None
+            if pr:
+                facts["pr"] = pr
+                facts["review_decision"] = pr.get("review_decision", "")
+                # M10: CI check rollup. Best-effort — failures here
+                # default to ``no_checks`` rather than blocking the
+                # whole feature_state read.
+                try:
+                    ci_status, _raw = gh.get_pr_checks(
+                        workspace.config.root, owner, slug, pr["number"],
+                    )
+                    facts["ci_status"] = ci_status
+                except Exception:
+                    facts["ci_status"] = {"status": "no_checks"}
+                try:
+                    comments, _ = gh.get_review_comments(
+                        workspace.config.root, owner, slug, pr["number"],
+                    )
+                    classification = classify_threads(comments, repo_path, branch)
+                    actionable = classification["actionable_threads"]
+                    facts["likely_resolved_count"] = len(
+                        classification["likely_resolved_threads"],
+                    )
+                    bot_subs = bot_authors(workspace.config)
+                    resolved_ids = set(
+                        resolutions_for_feature(
+                            workspace.config.root, feature_name,
+                        ).keys()
+                    )
+                    bot_threads = [
+                        t for t in actionable
+                        if _is_bot_comment(t, bot_subs)
+                        and str(t.get("id", "")) not in resolved_ids
+                    ]
+                    human_threads = [
+                        t for t in actionable
+                        if not _is_bot_comment(t, bot_subs)
+                    ]
+                    facts["actionable_human_count"] = len(human_threads)
+                    facts["actionable_bot_count"] = len(bot_threads)
+                    facts["actionable_bot_threads"] = bot_threads
+                    facts["actionable_count"] = (
+                        facts["actionable_human_count"] + facts["actionable_bot_count"]
+                    )
+                except Exception:
+                    pass
+
+        out[repo_name] = facts
+    return out
+
+
+def _is_bot_comment(comment: dict, bot_substrings: list[str]) -> bool:
+    """Determine if a normalized review comment came from a bot.
+
+    With ``review_bots`` configured (M2 augment), require both
+    ``author_type == "Bot"`` AND a substring match against the configured
+    list. Without it, fall back to the GitHub-provided ``author_type``
+    alone — so unconfigured workspaces still benefit from basic bot
+    detection.
+    """
+    author_type = (comment.get("author_type") or "").lower()
+    is_typed_bot = author_type == "bot"
+    if not bot_substrings:
+        return is_typed_bot
+    author = (comment.get("author") or "").lower()
+    return is_typed_bot and any(sub in author for sub in bot_substrings)
+
+
+def _summarize(per_repo: dict[str, dict]) -> dict[str, Any]:
+    dirty_repos = [r for r, f in per_repo.items() if f.get("is_dirty")]
+    ahead_repos = {
+        r: f.get("ahead", 0) for r, f in per_repo.items() if f.get("ahead", 0) > 0
+    }
+    actionable_total = sum(f.get("actionable_count", 0) for f in per_repo.values())
+    actionable_human_total = sum(
+        f.get("actionable_human_count", 0) for f in per_repo.values()
+    )
+    actionable_bot_total = sum(
+        f.get("actionable_bot_count", 0) for f in per_repo.values()
+    )
+    likely_resolved_total = sum(
+        f.get("likely_resolved_count", 0) for f in per_repo.values()
+    )
+    decisions = {
+        r: f.get("review_decision", "") for r, f in per_repo.items() if f.get("pr")
+    }
+    pr_count = sum(1 for f in per_repo.values() if f.get("pr"))
+    ci_per_repo = {
+        r: f["ci_status"] for r, f in per_repo.items()
+        if f.get("pr") and f.get("ci_status")
+    }
+    return {
+        "dirty_repos": dirty_repos,
+        "ahead_repos": ahead_repos,
+        "actionable_count": actionable_total,
+        "actionable_human_count": actionable_human_total,
+        "actionable_bot_count": actionable_bot_total,
+        "likely_resolved_count": likely_resolved_total,
+        "review_decisions": decisions,
+        "pr_count": pr_count,
+        "repos": {r: {k: v for k, v in f.items() if k not in ("pr", "actionable_bot_threads")}
+                   for r, f in per_repo.items()},
+        "prs": {r: f["pr"] for r, f in per_repo.items() if f.get("pr")},
+        # M10: per-repo CI rollup + a feature-level aggregate. The
+        # aggregate picks the worst across repos so a feature whose api
+        # is passing but ui is failing reports as "failing."
+        "ci_per_repo": ci_per_repo,
+        "ci_aggregate": _aggregate_ci(ci_per_repo),
+    }
+
+
+def _aggregate_ci(ci_per_repo: dict[str, dict]) -> str:
+    """Worst-state-wins reduction across repos (M10)."""
+    if not ci_per_repo:
+        return "no_checks"
+    statuses = {(c.get("status") or "no_checks") for c in ci_per_repo.values()}
+    for severe in ("failing", "pending", "passing"):
+        if severe in statuses:
+            return severe
+    return "no_checks"
+
+
+def _preflight_summary(entry, fresh: bool) -> dict[str, Any]:
+    if not entry:
+        return {"ran": False, "fresh": False}
+    return {
+        "ran": True,
+        "fresh": fresh,
+        "passed": entry.get("passed", False),
+        "ran_at": entry.get("ran_at", ""),
+    }
+
+
+def _decide_state(
+    feature_name: str,
+    per_repo: dict[str, dict],
+    summary: dict[str, Any],
+    preflight_fresh: bool,
+    preflight_entry,
+) -> tuple[str, list[dict], list[dict]]:
+    decisions = summary["review_decisions"]
+    actionable = summary["actionable_count"]
+    actionable_human = summary.get("actionable_human_count", actionable)
+    actionable_bot = summary.get("actionable_bot_count", 0)
+    dirty = bool(summary["dirty_repos"])
+    ahead = bool(summary["ahead_repos"])
+    pr_count = summary["pr_count"]
+    warnings: list[dict] = []
+    next_actions: list[dict] = []
+
+    if dirty:
+        if preflight_fresh and preflight_entry and preflight_entry.get("passed"):
+            state = "ready_to_commit"
+            next_actions = [
+                {"action": "commit", "args": {"feature": feature_name},
+                 "primary": True, "label": "Commit",
+                 "preview": f"{len(summary['dirty_repos'])} repo(s) staged"},
+                {"action": "preflight", "args": {"feature": feature_name},
+                 "primary": False, "label": "Re-run preflight"},
+            ]
+        else:
+            state = "in_progress"
+            if preflight_entry and not preflight_fresh:
+                warnings.append({
+                    "code": "preflight_stale",
+                    "what": "preflight result is stale (HEAD has moved since last run)",
+                })
+            next_actions = [
+                {"action": "preflight", "args": {"feature": feature_name},
+                 "primary": True, "label": "Run preflight"},
+                {"action": "stash", "args": {"feature": feature_name},
+                 "primary": False, "label": "Stash changes"},
+            ]
+        return state, next_actions, warnings
+
+    # Clean working tree from here on.
+    if ahead:
+        # If branch isn't pushed yet (no upstream OR ahead > 0),
+        # the next action is push.
+        next_actions = [
+            {"action": "push", "args": {"feature": feature_name},
+             "primary": True, "label": "Push",
+             "preview": ", ".join(f"{r}: +{n}" for r, n in summary['ahead_repos'].items())},
+        ]
+        # If PRs already exist + we have actionable comments, also surface
+        # 'address review comments' as secondary.
+        if actionable > 0:
+            next_actions.append({
+                "action": "address_review_comments",
+                "args": {"feature": feature_name},
+                "primary": False,
+                "label": "Address review comments",
+            })
+        return "ready_to_push", next_actions, warnings
+
+    # Aligned, clean, caught up to remote (or nothing to push).
+    # Human signals (CHANGES_REQUESTED reviews, or actionable human threads)
+    # block on `needs_work`; bot threads alone route to `awaiting_bot_resolution`.
+    if actionable_human > 0 or _any_changes_requested(decisions):
+        next_actions = [
+            {"action": "address_review_comments",
+             "args": {"feature": feature_name},
+             "primary": True, "label": "Address review comments",
+             "preview": f"{actionable_human} human thread(s), {actionable_bot} bot thread(s)"
+                          if actionable_bot else f"{actionable_human} human thread(s)"},
+            {"action": "comments", "args": {"feature": feature_name},
+             "primary": False, "label": "View comments"},
+        ]
+        return "needs_work", next_actions, warnings
+
+    if pr_count == 0:
+        # Aligned, clean, but no PRs — likely needs PR creation
+        next_actions = [
+            {"action": "pr_create", "args": {"feature": feature_name},
+             "primary": True, "label": "Open PR(s)"},
+        ]
+        return "no_prs", next_actions, warnings
+
+    ci_aggregate = summary.get("ci_aggregate", "no_checks")
+    ci_per_repo = summary.get("ci_per_repo") or {}
+    non_empty = {d for d in decisions.values() if d}
+    if non_empty and non_empty <= {"APPROVED"}:
+        # M10 CI matrix: approved + CI is the merge gate.
+        if ci_aggregate == "failing":
+            failing_names = sorted(
+                name for repo, ci in ci_per_repo.items()
+                for name in (ci.get("required_failing") or [])
+            )
+            next_actions = [
+                {"action": "investigate_ci",
+                 "args": {"feature": feature_name},
+                 "primary": True, "label": "Investigate failing CI",
+                 "preview": ", ".join(failing_names) or "see Checks tab"},
+                {"action": "comments", "args": {"feature": feature_name},
+                 "primary": False, "label": "View comments"},
+            ]
+            # Failing CI overrides the "approved" badge — same intent as
+            # a CHANGES_REQUESTED review.
+            return "needs_work", next_actions, warnings
+        if ci_aggregate == "pending":
+            pending_names = sorted(
+                name for repo, ci in ci_per_repo.items()
+                for name in (ci.get("required_pending") or [])
+            )
+            next_actions = [
+                {"action": "wait_for_ci",
+                 "args": {"feature": feature_name},
+                 "primary": True, "label": "Waiting on CI",
+                 "preview": ", ".join(pending_names) or "checks running"},
+                {"action": "refresh", "args": {"feature": feature_name},
+                 "primary": False, "label": "Refresh"},
+            ]
+            return "awaiting_ci", next_actions, warnings
+
+        next_actions = [
+            {"action": "merge", "args": {"feature": feature_name},
+             "primary": True, "label": "Merge",
+             "preview": "all PRs approved (manual or via UI)"},
+        ]
+        # Bots may still have unresolved nits — surface as a non-gating
+        # secondary CTA. State stays `approved` (human approval is the merge
+        # gate; bot nits are a side-channel).
+        if actionable_bot > 0:
+            next_actions.append({
+                "action": "address_bot_comments",
+                "args": {"feature": feature_name},
+                "primary": False, "label": "Address bot comments",
+                "preview": f"{actionable_bot} unresolved bot thread(s)",
+            })
+        return "approved", next_actions, warnings
+
+    # No human action pending, PR open, not yet approved. Bot nits get their
+    # own state so the agent + dashboard can distinguish "still review-pending"
+    # from "human is silent but bots flagged things."
+    if actionable_bot > 0:
+        next_actions = [
+            {"action": "address_bot_comments",
+             "args": {"feature": feature_name},
+             "primary": True, "label": "Address bot comments",
+             "preview": f"{actionable_bot} bot thread(s)"},
+            {"action": "comments", "args": {"feature": feature_name},
+             "primary": False, "label": "View comments"},
+        ]
+        return "awaiting_bot_resolution", next_actions, warnings
+
+    next_actions = [
+        {"action": "refresh", "args": {"feature": feature_name},
+         "primary": True, "label": "Refresh",
+         "preview": "waiting on review"},
+    ]
+    return "awaiting_review", next_actions, warnings
+
+
+def _any_changes_requested(decisions: dict[str, str]) -> bool:
+    return "CHANGES_REQUESTED" in decisions.values()
+
+
+def _live_drift(
+    workspace: Workspace, repo_branches: dict[str, str],
+    repo_paths: dict[str, Path],
+) -> dict[str, Any]:
+    """Check actual git state vs expected per repo against the resolved path.
+
+    For worktree-backed features the resolved path is the worktree, so the
+    branch check is against the worktree's HEAD. For main-tree features it's
+    the main repo. Either way, the branch check is targeted correctly.
+
+    Returns ``{drifted_repos, missing_repos, expected, actual}``.
+    """
+    drifted: list[str] = []
+    missing: list[str] = []
+    expected: dict[str, str] = {}
+    actual: dict[str, str | None] = {}
+    for repo_name, expected_branch in repo_branches.items():
+        expected[repo_name] = expected_branch
+        try:
+            state = workspace.get_repo(repo_name)
+        except KeyError:
+            missing.append(repo_name)
+            actual[repo_name] = None
+            continue
+        check_path = repo_paths.get(repo_name, state.abs_path)
+        if not git.branch_exists(check_path, expected_branch):
+            missing.append(repo_name)
+            actual[repo_name] = None
+            continue
+        try:
+            current = git.current_branch(check_path)
+        except git.GitError:
+            current = None
+        actual[repo_name] = current
+        if current != expected_branch:
+            drifted.append(repo_name)
+    return {
+        "drifted_repos": drifted,
+        "missing_repos": missing,
+        "expected": expected,
+        "actual": actual,
+    }
+
+
+def _drifted_result(
+    feature_name: str, drift_info: dict, *, has_worktrees: bool = False,
+) -> dict[str, Any]:
+    drifted = drift_info["drifted_repos"]
+    missing = drift_info["missing_repos"]
+
+    # F-12: post-Wave 2.9, the canonical-slot model handles both worktree
+    # and main-tree recovery via ``switch``. The deprecated ``realign``
+    # action is no longer surfaced as the primary CTA for either case;
+    # ``switch`` re-establishes the feature context regardless of where
+    # the feature lives. ``done`` stays as a secondary CTA on the
+    # worktree path so users can intentionally drop a broken worktree.
+    if has_worktrees:
+        next_actions = [
+            {"action": "switch", "args": {"feature": feature_name},
+             "primary": True, "label": "Switch",
+             "preview": (
+                 "worktree is on the wrong branch — switch to re-establish"
+                 " the feature context"
+             )},
+            {"action": "done", "args": {"feature": feature_name},
+             "primary": False, "label": "Clean up worktree",
+             "preview": "remove the worktree if you no longer need it"},
+        ]
+    else:
+        next_actions = [
+            {"action": "switch", "args": {"feature": feature_name},
+             "primary": True, "label": "Switch",
+             "preview": (
+                 f"checkout expected branch in "
+                 f"{', '.join(drifted + missing)}"
+             )},
+        ]
+
+    return {
+        "feature": feature_name,
+        "state": "drifted",
+        "summary": {
+            "alignment": {
+                "aligned": False,
+                "expected": drift_info["expected"],
+                "actual": drift_info["actual"],
+                "drifted_repos": drifted,
+                "missing_repos": missing,
+                "has_worktrees": has_worktrees,
+            },
+        },
+        "next_actions": next_actions,
+        "warnings": [],
+    }
+
+
+def _shell_result(feature_name: str, state: str, *, note: str = "") -> dict[str, Any]:
+    return {
+        "feature": feature_name,
+        "state": state,
+        "summary": {"note": note} if note else {},
+        "next_actions": [],
+        "warnings": [],
+    }