spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/merge/forecast.py

@@ -0,0 +1,215 @@
+"""Conflict prediction for merge dry-run.
+
+Implements FR-005 through FR-007: predicting which files will conflict
+during merge and identifying auto-resolvable status files.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+__all__ = [
+    "ConflictPrediction",
+    "predict_conflicts",
+    "is_status_file",
+    "build_file_wp_mapping",
+    "display_conflict_forecast",
+]
+
+
+# Patterns for status files that can be auto-resolved
+STATUS_FILE_PATTERNS = [
+    "kitty-specs/*/tasks/*.md",  # WP files: kitty-specs/017-feature/tasks/WP01.md
+    "kitty-specs/*/tasks.md",  # Main tasks: kitty-specs/017-feature/tasks.md
+    "kitty-specs/*/*/tasks/*.md",  # Nested: kitty-specs/features/017/tasks/WP01.md
+    "kitty-specs/*/*/tasks.md",  # Nested main
+]
+
+
+@dataclass
+class ConflictPrediction:
+    """Predicted conflict for a file.
+
+    Attributes:
+        file_path: Path to the file that may conflict
+        conflicting_wps: List of WP IDs that modify this file
+        is_status_file: True if file matches status file pattern
+        confidence: Prediction confidence ("certain", "likely", "possible")
+    """
+
+    file_path: str
+    conflicting_wps: list[str]
+    is_status_file: bool
+    confidence: str  # "certain", "likely", "possible"
+
+    @property
+    def auto_resolvable(self) -> bool:
+        """Status files can be auto-resolved."""
+        return self.is_status_file
+
+
+def is_status_file(file_path: str) -> bool:
+    """Check if file matches status file patterns.
+
+    Status files contain lane/checkbox/history that can be auto-resolved
+    during merge because their content is procedurally generated.
+
+    Args:
+        file_path: Path to check (relative to repo root)
+
+    Returns:
+        True if file matches a status file pattern
+    """
+    for pattern in STATUS_FILE_PATTERNS:
+        if fnmatch.fnmatch(file_path, pattern):
+            return True
+    return False
+
+
+def build_file_wp_mapping(
+    wp_workspaces: list[tuple[Path, str, str]],
+    target_branch: str,
+    repo_root: Path,
+) -> dict[str, list[str]]:
+    """Build mapping of file paths to WPs that modify them.
+
+    Uses git diff to identify which files each WP branch modifies
+    relative to the target branch.
+
+    Args:
+        wp_workspaces: List of (worktree_path, wp_id, branch_name) tuples
+        target_branch: Branch being merged into (e.g., "main")
+        repo_root: Repository root for running git commands
+
+    Returns:
+        Dict mapping file_path → [wp_ids that modify it]
+    """
+    file_to_wps: dict[str, list[str]] = {}
+
+    for _, wp_id, branch_name in wp_workspaces:
+        try:
+            result = subprocess.run(
+                ["git", "diff", "--name-only", f"{target_branch}...{branch_name}"],
+                cwd=str(repo_root),
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            if result.returncode == 0:
+                for line in result.stdout.strip().split("\n"):
+                    if line:
+                        if line not in file_to_wps:
+                            file_to_wps[line] = []
+                        file_to_wps[line].append(wp_id)
+        except Exception:
+            continue  # Skip this WP if diff fails
+
+    return file_to_wps
+
+
+def predict_conflicts(
+    wp_workspaces: list[tuple[Path, str, str]],
+    target_branch: str,
+    repo_root: Path,
+) -> list[ConflictPrediction]:
+    """Predict which files will conflict during merge.
+
+    Identifies files modified by multiple WPs, which may result in
+    merge conflicts. Status files are marked as auto-resolvable.
+
+    Args:
+        wp_workspaces: Ordered list of (worktree_path, wp_id, branch_name) tuples
+        target_branch: Branch being merged into (e.g., "main")
+        repo_root: Repository root for running git commands
+
+    Returns:
+        List of ConflictPrediction for files with potential conflicts
+    """
+    file_to_wps = build_file_wp_mapping(wp_workspaces, target_branch, repo_root)
+
+    predictions = []
+    for file_path, wp_ids in sorted(file_to_wps.items()):
+        if len(wp_ids) >= 2:
+            predictions.append(
+                ConflictPrediction(
+                    file_path=file_path,
+                    conflicting_wps=wp_ids,
+                    is_status_file=is_status_file(file_path),
+                    confidence="possible",  # Can enhance with merge-tree in future
+                )
+            )
+
+    return predictions
+
+
+def display_conflict_forecast(
+    predictions: list[ConflictPrediction],
+    console: Console,
+) -> None:
+    """Display conflict predictions with Rich formatting.
+
+    Groups predictions into auto-resolvable (status files) and
+    manual-required categories for clear user guidance.
+
+    Args:
+        predictions: List of ConflictPrediction objects
+        console: Rich Console instance for output
+    """
+    if not predictions:
+        console.print("\n[green]No conflicts predicted[/green]\n")
+        return
+
+    console.print("\n[bold]Conflict Forecast[/bold]\n")
+
+    auto_resolvable = [p for p in predictions if p.auto_resolvable]
+    manual_required = [p for p in predictions if not p.auto_resolvable]
+
+    # Summary counts
+    total = len(predictions)
+    auto_count = len(auto_resolvable)
+    manual_count = len(manual_required)
+
+    console.print(f"[dim]Found {total} potential conflict(s): {auto_count} auto-resolvable, {manual_count} manual[/dim]\n")
+
+    # Create table for conflicts
+    if manual_required:
+        table = Table(show_header=True, header_style="bold yellow")
+        table.add_column("File")
+        table.add_column("WPs")
+        table.add_column("Confidence")
+
+        for pred in manual_required:
+            wps = ", ".join(pred.conflicting_wps)
+            table.add_row(pred.file_path, wps, pred.confidence)
+
+        console.print("[yellow]May require manual resolution:[/yellow]")
+        console.print(table)
+        console.print()
+
+    if auto_resolvable:
+        table = Table(show_header=True, header_style="bold dim")
+        table.add_column("Status File")
+        table.add_column("WPs")
+
+        for pred in auto_resolvable:
+            wps = ", ".join(pred.conflicting_wps)
+            table.add_row(pred.file_path, wps)
+
+        console.print("[dim]Auto-resolvable (status files):[/dim]")
+        console.print(table)
+        console.print()
+
+    # Summary guidance
+    if manual_count == 0:
+        console.print("[green]All conflicts can be auto-resolved.[/green]\n")
+    else:
+        console.print(
+            f"[yellow]Prepare to resolve {manual_count} conflict(s) manually during merge.[/yellow]\n"
+        )

specify_cli/merge/ordering.py

@@ -0,0 +1,126 @@
+"""Merge ordering based on WP dependencies.
+
+Implements FR-008 through FR-011: determining merge order via topological
+sort of the dependency graph.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from specify_cli.core.dependency_graph import (
+    build_dependency_graph,
+    detect_cycles,
+    topological_sort,
+)
+
+__all__ = ["get_merge_order", "MergeOrderError", "has_dependency_info", "display_merge_order"]
+
+logger = logging.getLogger(__name__)
+
+
+class MergeOrderError(Exception):
+    """Error determining merge order."""
+
+    pass
+
+
+def has_dependency_info(graph: dict[str, list[str]]) -> bool:
+    """Check if any WP has declared dependencies.
+
+    Args:
+        graph: Dependency graph mapping WP ID to list of dependencies
+
+    Returns:
+        True if at least one WP has non-empty dependencies
+    """
+    return any(deps for deps in graph.values())
+
+
+def get_merge_order(
+    wp_workspaces: list[tuple[Path, str, str]],
+    feature_dir: Path,
+) -> list[tuple[Path, str, str]]:
+    """Return WPs in dependency order (topological sort).
+
+    Determines the optimal merge order based on WP dependencies declared
+    in frontmatter. WPs with dependencies will be merged after their
+    dependencies.
+
+    Args:
+        wp_workspaces: List of (worktree_path, wp_id, branch_name) tuples
+        feature_dir: Path to feature directory containing tasks/
+
+    Returns:
+        Same tuples reordered by dependency (dependencies first)
+
+    Raises:
+        MergeOrderError: If circular dependency detected
+    """
+    if not wp_workspaces:
+        return []
+
+    # Build WP ID → workspace mapping
+    wp_map = {wp_id: (path, wp_id, branch) for path, wp_id, branch in wp_workspaces}
+
+    # Build dependency graph from task frontmatter
+    graph = build_dependency_graph(feature_dir)
+
+    # Check for missing WPs in graph (may have no frontmatter)
+    for wp_id in wp_map:
+        if wp_id not in graph:
+            graph[wp_id] = []  # No dependencies
+
+    # Check if we have any dependency info
+    if not has_dependency_info(graph):
+        # No dependency info - fall back to numerical order with warning
+        logger.warning(
+            "No dependency information found in WP frontmatter. "
+            "Falling back to numerical order (WP01, WP02, ...)."
+        )
+        return sorted(wp_workspaces, key=lambda x: x[1])  # Sort by wp_id
+
+    # Detect cycles - show full cycle path in error
+    cycles = detect_cycles(graph)
+    if cycles:
+        # Format the cycle path clearly: WP01 → WP02 → WP03 → WP01
+        cycle = cycles[0]
+        cycle_str = " → ".join(cycle)
+        raise MergeOrderError(
+            f"Circular dependency detected: {cycle_str}\n"
+            "Fix the dependencies in the WP frontmatter to remove this cycle."
+        )
+
+    # Topological sort
+    try:
+        ordered_ids = topological_sort(graph)
+    except ValueError as e:
+        raise MergeOrderError(str(e)) from e
+
+    # Filter to only WPs we have workspaces for, maintaining order
+    result = []
+    for wp_id in ordered_ids:
+        if wp_id in wp_map:
+            result.append(wp_map[wp_id])
+
+    return result
+
+
+def display_merge_order(
+    ordered_workspaces: list[tuple[Path, str, str]],
+    console,
+) -> None:
+    """Display the merge order to the user.
+
+    Args:
+        ordered_workspaces: Ordered list of (path, wp_id, branch) tuples
+        console: Rich Console for output
+    """
+    if not ordered_workspaces:
+        return
+
+    console.print("\n[bold]Merge Order[/bold] (dependency-based):\n")
+    for i, (_, wp_id, branch) in enumerate(ordered_workspaces, 1):
+        console.print(f"  {i}. {wp_id} ({branch})")
+    console.print()

specify_cli/merge/preflight.py

@@ -0,0 +1,230 @@
+"""Pre-flight validation for merge operations.
+
+Implements FR-001 through FR-004: checking worktree status and target branch
+divergence before any merge operation begins.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+from specify_cli.core.dependency_graph import build_dependency_graph
+
+__all__ = [
+    "WPStatus",
+    "PreflightResult",
+    "check_worktree_status",
+    "check_target_divergence",
+    "run_preflight",
+    "display_preflight_result",
+]
+
+
+@dataclass
+class WPStatus:
+    """Status of a single WP worktree during pre-flight."""
+
+    wp_id: str
+    worktree_path: Path
+    branch_name: str
+    is_clean: bool
+    error: str | None = None
+
+
+@dataclass
+class PreflightResult:
+    """Result of pre-merge validation checks."""
+
+    passed: bool
+    wp_statuses: list[WPStatus] = field(default_factory=list)
+    target_diverged: bool = False
+    target_divergence_msg: str | None = None
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def check_worktree_status(worktree_path: Path, wp_id: str, branch_name: str) -> WPStatus:
+    """Check if a worktree has uncommitted changes.
+
+    Args:
+        worktree_path: Path to the worktree directory
+        wp_id: Work package ID (e.g., "WP01")
+        branch_name: Name of the branch
+
+    Returns:
+        WPStatus with is_clean=True if no uncommitted changes
+    """
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=str(worktree_path),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        is_clean = not result.stdout.strip()
+        error = None if is_clean else f"Uncommitted changes in {worktree_path.name}"
+        return WPStatus(
+            wp_id=wp_id,
+            worktree_path=worktree_path,
+            branch_name=branch_name,
+            is_clean=is_clean,
+            error=error,
+        )
+    except Exception as e:
+        return WPStatus(
+            wp_id=wp_id,
+            worktree_path=worktree_path,
+            branch_name=branch_name,
+            is_clean=False,
+            error=str(e),
+        )
+
+
+def check_target_divergence(target_branch: str, repo_root: Path) -> tuple[bool, str | None]:
+    """Check if target branch has diverged from origin.
+
+    Args:
+        target_branch: Name of the target branch (e.g., "main")
+        repo_root: Path to the repository root
+
+    Returns:
+        Tuple of (has_diverged, remediation_message)
+        - has_diverged: True if local branch is behind origin
+        - remediation_message: Instructions for fixing divergence
+    """
+    try:
+        # Fetch latest refs (optional, may fail if offline)
+        subprocess.run(
+            ["git", "fetch", "origin", target_branch],
+            cwd=str(repo_root),
+            capture_output=True,
+            check=False,
+        )
+
+        # Count commits ahead/behind
+        result = subprocess.run(
+            ["git", "rev-list", "--left-right", "--count", f"{target_branch}...origin/{target_branch}"],
+            cwd=str(repo_root),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+        if result.returncode != 0:
+            return False, None  # No remote tracking, assume OK
+
+        parts = result.stdout.strip().split()
+        if len(parts) != 2:
+            return False, None  # Unexpected output, assume OK
+
+        ahead, behind = map(int, parts)
+
+        if behind > 0:
+            return True, f"{target_branch} is {behind} commit(s) behind origin. Run: git checkout {target_branch} && git pull"
+
+        return False, None
+
+    except Exception:
+        return False, None  # Assume OK if check fails
+
+
+def run_preflight(
+    feature_slug: str,
+    target_branch: str,
+    repo_root: Path,
+    wp_workspaces: list[tuple[Path, str, str]],
+) -> PreflightResult:
+    """Run all pre-flight checks before merge.
+
+    Args:
+        feature_slug: Feature identifier (e.g., "017-smarter-feature-merge")
+        target_branch: Branch to merge into (e.g., "main")
+        repo_root: Repository root path
+        wp_workspaces: List of (worktree_path, wp_id, branch_name) tuples
+
+    Returns:
+        PreflightResult with all check outcomes
+    """
+    result = PreflightResult(passed=True)
+
+    # Check for missing worktrees based on tasks in kitty-specs
+    expected_graph = build_dependency_graph(repo_root / "kitty-specs" / feature_slug)
+    expected_wps = set(expected_graph.keys())
+    discovered_wps = {wp_id for _, wp_id, _ in wp_workspaces}
+    missing_wps = sorted(expected_wps - discovered_wps)
+    if missing_wps:
+        result.passed = False
+        for wp_id in missing_wps:
+            expected_path = repo_root / ".worktrees" / f"{feature_slug}-{wp_id}"
+            error = f"Missing worktree for {wp_id}. Expected at {expected_path.name}. Run: spec-kitty agent workflow implement {wp_id}"
+            result.wp_statuses.append(
+                WPStatus(
+                    wp_id=wp_id,
+                    worktree_path=expected_path,
+                    branch_name=f"{feature_slug}-{wp_id}",
+                    is_clean=False,
+                    error=error,
+                )
+            )
+            result.errors.append(error)
+
+    # Check all worktrees
+    for wt_path, wp_id, branch in wp_workspaces:
+        status = check_worktree_status(wt_path, wp_id, branch)
+        result.wp_statuses.append(status)
+        if not status.is_clean:
+            result.passed = False
+            result.errors.append(status.error or f"{wp_id} has uncommitted changes")
+
+    # Check target divergence
+    diverged, msg = check_target_divergence(target_branch, repo_root)
+    result.target_diverged = diverged
+    result.target_divergence_msg = msg
+    if diverged:
+        result.passed = False
+        result.errors.append(msg or f"{target_branch} has diverged from origin")
+
+    return result
+
+
+def display_preflight_result(result: PreflightResult, console: Console) -> None:
+    """Display pre-flight results with Rich formatting.
+
+    Args:
+        result: PreflightResult to display
+        console: Rich Console instance for output
+    """
+    console.print("\n[bold]Pre-flight Check[/bold]\n")
+
+    # WP status table
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("WP")
+    table.add_column("Status")
+    table.add_column("Issue")
+
+    for status in result.wp_statuses:
+        icon = "[green]✓[/green]" if status.is_clean else "[red]✗[/red]"
+        issue = status.error or ""
+        table.add_row(status.wp_id, icon, issue)
+
+    # Target branch status
+    if result.target_diverged:
+        table.add_row("Target", "[red]✗[/red]", result.target_divergence_msg or "Diverged")
+    else:
+        table.add_row("Target", "[green]✓[/green]", "Up to date")
+
+    console.print(table)
+
+    if not result.passed:
+        console.print("\n[bold red]Pre-flight failed.[/bold red] Fix these issues before merging:\n")
+        for i, error in enumerate(result.errors, 1):
+            console.print(f"  {i}. {error}")
+        console.print()
+    else:
+        console.print("\n[green]Pre-flight passed.[/green] Ready to merge.\n")