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

specify_cli/core/context_validation.py

@@ -0,0 +1,362 @@
+"""Context validation for location-aware commands.
+
+This module provides runtime validation to ensure commands are executed
+in the correct location (main repository vs worktree). Prevents common
+mistakes like running 'implement' from inside a worktree.
+
+Example:
+    from specify_cli.core.context_validation import (
+        require_main_repo,
+        require_worktree,
+        get_current_context,
+    )
+
+    @require_main_repo
+    def implement(wp_id: str):
+        # This function can only run from main repo
+        pass
+
+    @require_worktree
+    def some_workspace_command():
+        # This function can only run from inside a worktree
+        pass
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Callable, TypeVar
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+class ExecutionContext(str, Enum):
+    """Execution context for a command."""
+
+    MAIN_REPO = "main"  # Command runs in main repository
+    WORKTREE = "worktree"  # Command runs inside a worktree
+    EITHER = "either"  # Command can run in either location
+
+
+@dataclass
+class CurrentContext:
+    """Current execution context information."""
+
+    location: ExecutionContext
+    cwd: Path
+    repo_root: Path | None
+    worktree_name: str | None  # e.g., "010-feature-WP02" if in worktree
+    worktree_path: Path | None  # Absolute path to worktree directory
+
+
+def detect_execution_context(cwd: Path | None = None) -> CurrentContext:
+    """Detect current execution context.
+
+    Args:
+        cwd: Current working directory (defaults to Path.cwd())
+
+    Returns:
+        CurrentContext with location, paths, and worktree info
+
+    Example:
+        >>> ctx = detect_execution_context()
+        >>> if ctx.location == ExecutionContext.WORKTREE:
+        ...     print(f"In worktree: {ctx.worktree_name}")
+    """
+    if cwd is None:
+        cwd = Path.cwd().resolve()
+    else:
+        cwd = cwd.resolve()
+
+    # Check if .worktrees is in path
+    if ".worktrees" in cwd.parts:
+        # Extract worktree information
+        for i, part in enumerate(cwd.parts):
+            if part == ".worktrees" and i + 1 < len(cwd.parts):
+                worktree_name = cwd.parts[i + 1]
+                worktree_path = Path(*cwd.parts[: i + 2])
+                repo_root = Path(*cwd.parts[:i])
+
+                return CurrentContext(
+                    location=ExecutionContext.WORKTREE,
+                    cwd=cwd,
+                    repo_root=repo_root,
+                    worktree_name=worktree_name,
+                    worktree_path=worktree_path,
+                )
+
+    # Not in worktree - assume main repo
+    # Try to find repo root (directory containing .kittify or .git)
+    repo_root = None
+    search_path = cwd
+    for _ in range(10):  # Limit depth
+        if (search_path / ".kittify").exists() or (search_path / ".git").exists():
+            repo_root = search_path
+            break
+        if search_path.parent == search_path:
+            break  # Reached filesystem root
+        search_path = search_path.parent
+
+    return CurrentContext(
+        location=ExecutionContext.MAIN_REPO,
+        cwd=cwd,
+        repo_root=repo_root,
+        worktree_name=None,
+        worktree_path=None,
+    )
+
+
+def get_current_context() -> CurrentContext:
+    """Get current execution context.
+
+    Convenience function that detects context from current working directory.
+
+    Returns:
+        CurrentContext with location and path information
+    """
+    return detect_execution_context()
+
+
+def format_location_error(
+    required: ExecutionContext,
+    actual: ExecutionContext,
+    command_name: str,
+    current_ctx: CurrentContext,
+) -> str:
+    """Format a clear error message for location mismatch.
+
+    Args:
+        required: Required execution context
+        actual: Actual execution context
+        command_name: Name of command being run
+        current_ctx: Current context information
+
+    Returns:
+        Formatted error message with actionable instructions
+    """
+    if required == ExecutionContext.MAIN_REPO and actual == ExecutionContext.WORKTREE:
+        # Command needs main repo, but in worktree
+        if current_ctx.repo_root:
+            return (
+                f"[bold red]Error:[/bold red] '{command_name}' must run from the main repository\n\n"
+                f"[yellow]Current location:[/yellow] Inside worktree [cyan]{current_ctx.worktree_name}[/cyan]\n"
+                f"[yellow]Required location:[/yellow] Main repository\n\n"
+                f"[bold]Change to main repository:[/bold]\n"
+                f"  cd {current_ctx.repo_root}\n\n"
+                f"[dim]This command creates/manages worktrees and must run from the main repository.\n"
+                f"Running from inside a worktree would create nested worktrees, corrupting git state.[/dim]"
+            )
+        else:
+            return (
+                f"[bold red]Error:[/bold red] '{command_name}' must run from the main repository\n\n"
+                f"[yellow]Current location:[/yellow] Inside worktree [cyan]{current_ctx.worktree_name}[/cyan]\n"
+                f"[yellow]Required location:[/yellow] Main repository\n\n"
+                f"[bold]Change to main repository:[/bold]\n"
+                f"  cd ../..  # Navigate up from worktree\n\n"
+                f"[dim]This command must run from the main repository.[/dim]"
+            )
+
+    elif required == ExecutionContext.WORKTREE and actual == ExecutionContext.MAIN_REPO:
+        # Command needs worktree, but in main repo
+        return (
+            f"[bold red]Error:[/bold red] '{command_name}' must run from inside a worktree\n\n"
+            f"[yellow]Current location:[/yellow] Main repository\n"
+            f"[yellow]Required location:[/yellow] Inside a worktree\n\n"
+            f"[bold]Change to a worktree:[/bold]\n"
+            f"  cd .worktrees/###-feature-WP##/\n\n"
+            f"[dim]This command operates on workspace files and must run from inside a worktree.[/dim]"
+        )
+
+    else:
+        # Generic error
+        return (
+            f"[bold red]Error:[/bold red] '{command_name}' cannot run in current location\n\n"
+            f"[yellow]Current location:[/yellow] {actual.value}\n"
+            f"[yellow]Required location:[/yellow] {required.value}\n"
+        )
+
+
+# Type variable for function decoration
+F = TypeVar("F", bound=Callable)
+
+
+def require_main_repo(func: F) -> F:
+    """Decorator to require command runs from main repository.
+
+    Prevents commands from running inside worktrees, which could cause
+    nested worktrees or other git corruption.
+
+    Example:
+        @require_main_repo
+        def implement(wp_id: str):
+            # Can only run from main repo
+            create_worktree(...)
+
+    Args:
+        func: Function to decorate
+
+    Returns:
+        Decorated function that validates location before executing
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        ctx = get_current_context()
+
+        if ctx.location == ExecutionContext.WORKTREE:
+            error_msg = format_location_error(
+                required=ExecutionContext.MAIN_REPO,
+                actual=ctx.location,
+                command_name=func.__name__,
+                current_ctx=ctx,
+            )
+            console.print(error_msg)
+            raise typer.Exit(1)
+
+        return func(*args, **kwargs)
+
+    return wrapper  # type: ignore
+
+
+def require_worktree(func: F) -> F:
+    """Decorator to require command runs from inside a worktree.
+
+    Prevents commands from running in main repo when they need workspace context.
+
+    Example:
+        @require_worktree
+        def workspace_status():
+            # Can only run from inside worktree
+            show_workspace_info(...)
+
+    Args:
+        func: Function to decorate
+
+    Returns:
+        Decorated function that validates location before executing
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        ctx = get_current_context()
+
+        if ctx.location == ExecutionContext.MAIN_REPO:
+            error_msg = format_location_error(
+                required=ExecutionContext.WORKTREE,
+                actual=ctx.location,
+                command_name=func.__name__,
+                current_ctx=ctx,
+            )
+            console.print(error_msg)
+            raise typer.Exit(1)
+
+        return func(*args, **kwargs)
+
+    return wrapper  # type: ignore
+
+
+def require_either(func: F) -> F:
+    """Decorator for commands that can run in either location.
+
+    This is primarily for documentation - the decorator doesn't enforce
+    anything, just marks the function as location-agnostic.
+
+    Example:
+        @require_either
+        def status():
+            # Can run from main repo or worktree
+            ctx = get_current_context()
+            if ctx.location == ExecutionContext.WORKTREE:
+                show_worktree_status()
+            else:
+                show_main_repo_status()
+
+    Args:
+        func: Function to decorate
+
+    Returns:
+        Original function (no validation added)
+    """
+    return func
+
+
+def set_context_env_vars(ctx: CurrentContext) -> None:
+    """Set environment variables for current context.
+
+    Makes context information available to subprocesses and scripts.
+
+    Environment variables set:
+        SPEC_KITTY_CONTEXT: "main" or "worktree"
+        SPEC_KITTY_CWD: Current working directory
+        SPEC_KITTY_REPO_ROOT: Repository root (if detected)
+        SPEC_KITTY_WORKTREE_NAME: Worktree name (if in worktree)
+        SPEC_KITTY_WORKTREE_PATH: Worktree path (if in worktree)
+
+    Args:
+        ctx: Current context information
+
+    Example:
+        >>> ctx = get_current_context()
+        >>> set_context_env_vars(ctx)
+        >>> print(os.environ.get("SPEC_KITTY_CONTEXT"))
+        "main"
+    """
+    os.environ["SPEC_KITTY_CONTEXT"] = ctx.location.value
+    os.environ["SPEC_KITTY_CWD"] = str(ctx.cwd)
+
+    if ctx.repo_root:
+        os.environ["SPEC_KITTY_REPO_ROOT"] = str(ctx.repo_root)
+    else:
+        os.environ.pop("SPEC_KITTY_REPO_ROOT", None)
+
+    if ctx.worktree_name:
+        os.environ["SPEC_KITTY_WORKTREE_NAME"] = ctx.worktree_name
+    else:
+        os.environ.pop("SPEC_KITTY_WORKTREE_NAME", None)
+
+    if ctx.worktree_path:
+        os.environ["SPEC_KITTY_WORKTREE_PATH"] = str(ctx.worktree_path)
+    else:
+        os.environ.pop("SPEC_KITTY_WORKTREE_PATH", None)
+
+
+def get_context_env_vars() -> dict[str, str]:
+    """Get current context environment variables.
+
+    Returns:
+        Dictionary of context environment variables
+    """
+    env_vars = {}
+
+    for key in [
+        "SPEC_KITTY_CONTEXT",
+        "SPEC_KITTY_CWD",
+        "SPEC_KITTY_REPO_ROOT",
+        "SPEC_KITTY_WORKTREE_NAME",
+        "SPEC_KITTY_WORKTREE_PATH",
+    ]:
+        value = os.environ.get(key)
+        if value:
+            env_vars[key] = value
+
+    return env_vars
+
+
+__all__ = [
+    "ExecutionContext",
+    "CurrentContext",
+    "detect_execution_context",
+    "get_current_context",
+    "require_main_repo",
+    "require_worktree",
+    "require_either",
+    "set_context_env_vars",
+    "get_context_env_vars",
+]

specify_cli/core/dependency_graph.py

@@ -0,0 +1,351 @@
+"""Dependency graph utilities for work package relationships.
+
+This module provides functions for parsing, validating, and analyzing
+dependency relationships between work packages in Spec Kitty features.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+from specify_cli.frontmatter import FrontmatterError, read_frontmatter
+
+
+def parse_wp_dependencies(wp_file: Path) -> list[str]:
+    """Parse dependencies from WP frontmatter.
+
+    Uses FrontmatterManager for consistent parsing across CLI.
+
+    Args:
+        wp_file: Path to work package markdown file
+
+    Returns:
+        List of WP IDs this WP depends on (e.g., ["WP01", "WP02"])
+        Returns empty list if no dependencies or parsing fails
+
+    Examples:
+        >>> wp_file = Path("tasks/WP02.md")
+        >>> deps = parse_wp_dependencies(wp_file)
+        >>> print(deps)  # ["WP01"]
+    """
+    try:
+        # Use FrontmatterManager for consistent parsing
+        frontmatter, _ = read_frontmatter(wp_file)
+
+        # Extract dependencies field (FrontmatterManager already defaults to [])
+        dependencies = frontmatter.get("dependencies", [])
+
+        # Validate dependencies is a list
+        if not isinstance(dependencies, list):
+            return []
+
+        return dependencies
+
+    except (FrontmatterError, OSError):
+        # Return empty list on any parsing error
+        return []
+
+
+def build_dependency_graph(feature_dir: Path) -> dict[str, list[str]]:
+    """Build dependency graph from all WPs in feature.
+
+    Scans tasks/ directory for WP files and parses their dependencies.
+    Validates that filename WP ID matches frontmatter work_package_id.
+
+    Args:
+        feature_dir: Path to feature directory (contains tasks/ subdirectory)
+                    OR path to tasks directory directly
+
+    Returns:
+        Adjacency list mapping WP ID to list of dependencies
+        Example: {"WP01": [], "WP02": ["WP01"], "WP03": ["WP01"]}
+
+    Examples:
+        >>> feature_dir = Path("kitty-specs/010-feature")
+        >>> graph = build_dependency_graph(feature_dir)
+        >>> print(graph)  # {"WP01": [], "WP02": ["WP01"]}
+    """
+    graph = {}
+
+    # Support both feature_dir and tasks_dir as input
+    if feature_dir.name == "tasks":
+        # Already pointing to tasks directory
+        tasks_dir = feature_dir
+    else:
+        # Pointing to feature directory, append tasks/
+        tasks_dir = feature_dir / "tasks"
+
+    if not tasks_dir.exists():
+        return graph
+
+    # Find all WP markdown files
+    for wp_file in sorted(tasks_dir.glob("WP*.md")):
+        # Extract WP ID from filename (e.g., WP01-title.md → WP01)
+        filename_wp_id = extract_wp_id_from_filename(wp_file.name)
+        if not filename_wp_id:
+            continue
+
+        # Parse frontmatter to get canonical work_package_id
+        try:
+            frontmatter, _ = read_frontmatter(wp_file)
+            frontmatter_wp_id = frontmatter.get("work_package_id")
+
+            # Verify filename matches frontmatter (catch misnamed files)
+            if frontmatter_wp_id and frontmatter_wp_id != filename_wp_id:
+                raise ValueError(
+                    f"WP ID mismatch: filename {filename_wp_id} vs frontmatter {frontmatter_wp_id} "
+                    f"in {wp_file}"
+                )
+
+            wp_id = frontmatter_wp_id or filename_wp_id
+
+        except (FrontmatterError, OSError):
+            # If frontmatter read fails, skip this file
+            continue
+
+        # Parse dependencies from frontmatter
+        dependencies = parse_wp_dependencies(wp_file)
+        graph[wp_id] = dependencies
+
+    return graph
+
+
+def extract_wp_id_from_filename(filename: str) -> Optional[str]:
+    """Extract WP ID from filename.
+
+    Args:
+        filename: WP file name (e.g., "WP01-title.md" or "WP02.md")
+
+    Returns:
+        WP ID (e.g., "WP01") or None if invalid format
+
+    Examples:
+        >>> extract_wp_id_from_filename("WP01-setup.md")
+        'WP01'
+        >>> extract_wp_id_from_filename("invalid.md")
+        None
+    """
+    match = re.match(r"^(WP\d{2})", filename)
+    return match.group(1) if match else None
+
+
+def detect_cycles(graph: dict[str, list[str]]) -> list[list[str]] | None:
+    """Detect circular dependencies using DFS with coloring.
+
+    Uses depth-first search with three-color marking (white/gray/black)
+    to detect back edges, which indicate cycles.
+
+    Args:
+        graph: Adjacency list mapping WP ID to dependencies
+
+    Returns:
+        List of cycles (each cycle is a list of WP IDs) or None if acyclic
+
+    Complexity:
+        O(V + E) where V = vertices (WPs), E = edges (dependencies)
+
+    Examples:
+        >>> graph = {"WP01": ["WP02"], "WP02": ["WP01"]}
+        >>> cycles = detect_cycles(graph)
+        >>> print(cycles)  # [["WP01", "WP02", "WP01"]]
+
+        >>> graph = {"WP01": [], "WP02": ["WP01"]}
+        >>> cycles = detect_cycles(graph)
+        >>> print(cycles)  # None (acyclic)
+    """
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color = {wp: WHITE for wp in graph}
+    cycles = []
+
+    def dfs(node: str, path: list[str]) -> None:
+        """DFS traversal with cycle detection."""
+        color[node] = GRAY
+        path.append(node)
+
+        for neighbor in graph.get(node, []):
+            neighbor_color = color.get(neighbor, WHITE)
+
+            if neighbor_color == GRAY:
+                # Back edge found - cycle detected
+                if neighbor in path:
+                    cycle_start = path.index(neighbor)
+                    cycles.append(path[cycle_start:] + [neighbor])
+            elif neighbor_color == WHITE:
+                dfs(neighbor, path)
+
+        path.pop()
+        color[node] = BLACK
+
+    # Run DFS from each unvisited node
+    for wp in graph:
+        if color[wp] == WHITE:
+            dfs(wp, [])
+
+    return cycles if cycles else None
+
+
+def validate_dependencies(
+    wp_id: str,
+    declared_deps: list[str],
+    graph: dict[str, list[str]]
+) -> tuple[bool, list[str]]:
+    """Validate that WP's dependencies are valid.
+
+    Checks:
+    - Dependencies exist in graph
+    - No self-dependencies
+    - No circular dependencies
+    - Valid WP ID format
+
+    Args:
+        wp_id: Work package ID being validated
+        declared_deps: List of dependency WP IDs
+        graph: Complete dependency graph
+
+    Returns:
+        Tuple of (is_valid, error_messages)
+        - is_valid: True if all validations pass
+        - error_messages: List of error descriptions (empty if valid)
+
+    Examples:
+        >>> graph = {"WP01": [], "WP02": ["WP01"]}
+        >>> is_valid, errors = validate_dependencies("WP02", ["WP01"], graph)
+        >>> print(is_valid)  # True
+
+        >>> is_valid, errors = validate_dependencies("WP02", ["WP99"], graph)
+        >>> print(is_valid)  # False
+        >>> print(errors)  # ["Dependency WP99 not found in graph"]
+    """
+    errors = []
+    wp_pattern = re.compile(r"^WP\d{2}$")
+
+    # Validate each dependency
+    for dep in declared_deps:
+        # Check format
+        if not wp_pattern.match(dep):
+            errors.append(f"Invalid WP ID format: {dep} (must be WP## like WP01)")
+            continue
+
+        # Check self-dependency
+        if dep == wp_id:
+            errors.append(f"Cannot depend on self: {wp_id} → {wp_id}")
+            continue
+
+        # Check dependency exists in graph
+        if dep not in graph:
+            errors.append(f"Dependency {dep} not found in graph")
+
+    # Check for circular dependencies
+    # Build temporary graph with this WP's dependencies to check for cycles
+    test_graph = graph.copy()
+    test_graph[wp_id] = declared_deps
+
+    cycles = detect_cycles(test_graph)
+    if cycles:
+        for cycle in cycles:
+            if wp_id in cycle:
+                errors.append(f"Circular dependency detected: {' → '.join(cycle)}")
+                break
+
+    is_valid = len(errors) == 0
+    return is_valid, errors
+
+
+def topological_sort(graph: dict[str, list[str]]) -> list[str]:
+    """Return nodes in topological order (dependencies before dependents).
+
+    Uses Kahn's algorithm:
+    1. Find all nodes with no incoming edges (no dependencies)
+    2. Remove them from graph, add to result
+    3. Repeat until graph is empty
+
+    Args:
+        graph: Adjacency list where graph[node] = [dependencies]
+               Note: This is REVERSE of typical adjacency (edges point to deps)
+
+    Returns:
+        List of node IDs in topological order
+
+    Raises:
+        ValueError: If graph contains a cycle (use detect_cycles() first)
+
+    Example:
+        >>> graph = {"WP01": [], "WP02": ["WP01"], "WP03": ["WP01", "WP02"]}
+        >>> topological_sort(graph)
+        ['WP01', 'WP02', 'WP03']
+    """
+    # Build in-degree map and reverse adjacency
+    in_degree: dict[str, int] = {node: 0 for node in graph}
+    reverse_adj: dict[str, list[str]] = {node: [] for node in graph}
+
+    for node, deps in graph.items():
+        in_degree[node] = len(deps)
+        for dep in deps:
+            if dep in reverse_adj:
+                reverse_adj[dep].append(node)
+
+    # Start with nodes that have no dependencies
+    queue = [node for node, degree in in_degree.items() if degree == 0]
+    queue.sort()  # Stable ordering for determinism
+
+    result = []
+    while queue:
+        node = queue.pop(0)
+        result.append(node)
+
+        # "Remove" this node by decrementing in-degree of dependents
+        for dependent in sorted(reverse_adj.get(node, [])):
+            in_degree[dependent] -= 1
+            if in_degree[dependent] == 0:
+                queue.append(dependent)
+                queue.sort()  # Maintain sorted order
+
+    if len(result) != len(graph):
+        raise ValueError("Graph contains a cycle - cannot topologically sort")
+
+    return result
+
+
+def get_dependents(wp_id: str, graph: dict[str, list[str]]) -> list[str]:
+    """Get list of WPs that depend on this WP (inverse graph query).
+
+    Builds inverse graph and returns direct dependents only (not transitive).
+
+    Args:
+        wp_id: Work package ID to query
+        graph: Dependency graph (adjacency list)
+
+    Returns:
+        List of WP IDs that directly depend on wp_id
+        Returns empty list if no dependents or WP not in graph
+
+    Examples:
+        >>> graph = {"WP01": [], "WP02": ["WP01"], "WP03": ["WP01"]}
+        >>> deps = get_dependents("WP01", graph)
+        >>> print(sorted(deps))  # ["WP02", "WP03"]
+
+        >>> deps = get_dependents("WP02", graph)
+        >>> print(deps)  # []
+    """
+    # Build inverse graph: wp -> list of wps that depend on it
+    inverse_graph: dict[str, list[str]] = {wp: [] for wp in graph}
+
+    for wp, dependencies in graph.items():
+        for dependency in dependencies:
+            if dependency not in inverse_graph:
+                inverse_graph[dependency] = []
+            inverse_graph[dependency].append(wp)
+
+    return inverse_graph.get(wp_id, [])
+
+
+__all__ = [
+    "build_dependency_graph",
+    "detect_cycles",
+    "get_dependents",
+    "parse_wp_dependencies",
+    "topological_sort",
+    "validate_dependencies",
+]