htmlgraph 0.9.3__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/types.py

@@ -0,0 +1,323 @@
+"""
+Type definitions for HtmlGraph SDK return types.
+
+Provides TypedDict definitions for SDK methods that return dictionaries,
+improving developer experience with better type hints and IDE autocomplete.
+
+These complement the Pydantic models in dependency_models.py by providing
+type hints for dict-based return values used in the SDK for backward compatibility.
+"""
+
+import sys
+from typing import Literal, TypedDict
+
+# NotRequired was added in Python 3.11
+if sys.version_info >= (3, 11):
+    from typing import NotRequired
+else:
+    from typing_extensions import NotRequired
+
+# ============================================================================
+# Analytics Return Types
+# ============================================================================
+
+
+class BottleneckDict(TypedDict):
+    """Bottleneck task information from find_bottlenecks()."""
+
+    id: str
+    title: str
+    status: str
+    priority: str
+    blocks_count: int  # Number of tasks this blocks (transitive)
+    impact_score: float  # Weighted impact score
+    blocked_tasks: list[str]  # List of blocked task IDs
+
+
+class WorkRecommendation(TypedDict):
+    """Work recommendation from recommend_next_work()."""
+
+    id: str
+    title: str
+    priority: str
+    score: float  # Priority score
+    reasons: list[str]  # Human-readable reasons for recommendation
+    estimated_hours: NotRequired[float]  # Effort estimate
+    unlocks_count: int  # Number of tasks this unlocks
+    unlocks: list[str]  # Task IDs that become available
+
+
+class ParallelWorkInfo(TypedDict):
+    """Parallel work opportunities from get_parallel_work()."""
+
+    max_parallelism: int  # Maximum number of parallel tasks
+    ready_now: list[str]  # Tasks ready to start immediately
+    total_ready: int  # Total count of ready tasks
+    level_count: int  # Number of dependency levels
+    next_level: list[str]  # Tasks in next dependency level
+
+
+class RiskAssessmentDict(TypedDict):
+    """Risk assessment from assess_risks()."""
+
+    high_risk_count: int
+    high_risk_tasks: list["HighRiskTask"]
+    circular_dependencies: list[list[str]]
+    orphaned_count: int
+    orphaned_tasks: list[str]
+    recommendations: list[str]
+
+
+class HighRiskTask(TypedDict):
+    """Individual high-risk task information."""
+
+    id: str
+    title: str
+    risk_score: float
+    risk_factors: list[str]
+
+
+class ImpactAnalysisDict(TypedDict):
+    """Impact analysis from analyze_impact()."""
+
+    node_id: str
+    direct_dependents: int
+    total_impact: int  # Transitive dependents
+    completion_impact: float  # Percentage of work this unlocks
+    unlocks_count: int
+    affected_tasks: list[str]
+
+
+# ============================================================================
+# Session Management Return Types
+# ============================================================================
+
+
+class SessionStartInfo(TypedDict):
+    """Comprehensive session start information from get_session_start_info()."""
+
+    status: "ProjectStatus"
+    active_work: NotRequired["ActiveWorkItem"]  # None if no active work
+    features: list["FeatureSummary"]
+    sessions: list["SessionSummary"]
+    git_log: NotRequired[list[str]]  # Recent commit messages
+    analytics: "SessionAnalytics"
+
+
+class ProjectStatus(TypedDict):
+    """Project status metrics."""
+
+    total_nodes: int
+    in_progress_count: int
+    todo_count: int
+    done_count: int
+    blocked_count: int
+
+
+class ActiveWorkItem(TypedDict):
+    """Currently active work item details."""
+
+    id: str
+    title: str
+    type: Literal["feature", "bug", "spike", "chore", "epic"]
+    status: str
+    agent: NotRequired[str]  # Assigned agent
+    steps_total: int
+    steps_completed: int
+    auto_generated: NotRequired[bool]  # For spikes
+    spike_subtype: NotRequired[str]  # For spikes
+
+
+class FeatureSummary(TypedDict):
+    """Feature summary for session start."""
+
+    id: str
+    title: str
+    status: str
+    priority: str
+    steps_total: int
+    steps_completed: int
+
+
+class SessionSummary(TypedDict):
+    """Session summary information."""
+
+    id: str
+    status: str
+    agent: str
+    event_count: int
+    started: NotRequired[str]  # ISO timestamp
+
+
+class SessionAnalytics(TypedDict):
+    """Strategic analytics for session start."""
+
+    bottlenecks: list[BottleneckDict]
+    recommendations: list[WorkRecommendation]
+    parallel: ParallelWorkInfo
+
+
+# ============================================================================
+# Work Queue Return Types
+# ============================================================================
+
+
+class WorkQueueItem(TypedDict):
+    """Work queue item from get_work_queue()."""
+
+    task_id: str
+    title: str
+    status: str
+    priority: str
+    score: float  # Routing score
+    type: str  # Work item type
+    complexity: NotRequired[str]
+    effort: NotRequired[float]
+    agent_assigned: NotRequired[str]
+    blocks_count: int
+    blocked_by: list[str]
+
+
+# ============================================================================
+# Planning Return Types
+# ============================================================================
+
+
+class SmartPlanResult(TypedDict):
+    """Result from smart_plan()."""
+
+    type: Literal["spike", "track"]
+    spike_id: NotRequired[str]  # Present if type="spike"
+    track_id: NotRequired[str]  # Present if type="track"
+    title: str
+    status: NotRequired[str]  # For spikes
+    timebox_hours: NotRequired[float]  # For spikes
+    has_spec: NotRequired[bool]  # For tracks
+    has_plan: NotRequired[bool]  # For tracks
+    priority: NotRequired[str]  # For tracks
+    project_context: "PlanningContext"
+    research_informed: bool
+    next_steps: list[str]
+    warnings: NotRequired[list[str]]
+
+
+class PlanningContext(TypedDict):
+    """Project context for planning."""
+
+    bottlenecks_count: int
+    high_risk_count: int
+    parallel_capacity: int
+    description: str
+
+
+class TrackCreationResult(TypedDict):
+    """Result from create_track_from_plan()."""
+
+    track_id: str
+    title: str
+    has_spec: bool
+    has_plan: bool
+    spike_id: NotRequired[str]  # Original planning spike
+    priority: str
+
+
+# ============================================================================
+# Orchestration Return Types
+# ============================================================================
+
+
+class SubagentPrompt(TypedDict):
+    """Subagent prompt from spawn_explorer() or spawn_coder().
+
+    This TypedDict represents the return value from SDK methods that spawn
+    subagents for specialized tasks like code exploration or implementation.
+
+    Fields:
+        prompt: The full prompt text for the subagent
+        description: Short description of the subagent's task
+        subagent_type: Type of subagent ("Explore", "Code", etc.)
+    """
+
+    prompt: str
+    description: str
+    subagent_type: str
+
+
+class OrchestrationResult(TypedDict):
+    """Result from orchestrate() method.
+
+    Contains prompts for a two-phase feature implementation workflow:
+    1. Explorer discovers relevant code and patterns
+    2. Coder implements the feature based on explorer findings
+
+    Fields:
+        explorer: Prompt for the explorer subagent
+        coder: Prompt for the coder subagent
+        workflow: Step-by-step workflow instructions
+    """
+
+    explorer: SubagentPrompt
+    coder: SubagentPrompt
+    workflow: list[str]  # Step-by-step workflow
+
+
+# Type aliases for specific spawning methods
+SpawnExplorerResult = SubagentPrompt
+"""Return type for spawn_explorer() - same structure as SubagentPrompt."""
+
+SpawnCoderResult = SubagentPrompt
+"""Return type for spawn_coder() - same structure as SubagentPrompt."""
+
+
+# ============================================================================
+# Parallel Work Return Types
+# ============================================================================
+
+
+class ParallelPlanResult(TypedDict):
+    """Result from plan_parallel_work()."""
+
+    can_parallelize: bool
+    max_parallelism: int
+    ready_tasks: list[str]
+    blocked_tasks: list[str]
+    speedup_factor: float
+    recommendation: str
+    warnings: list[str]
+    prompts: list["TaskPrompt"]
+    task_count: NotRequired[int]
+    guidelines: NotRequired["ParallelGuidelines"]
+    reason: NotRequired[str]  # If can_parallelize=False
+
+
+class TaskPrompt(TypedDict):
+    """Individual task prompt for parallel execution."""
+
+    prompt: str
+    description: str
+    task_id: str
+
+
+class ParallelGuidelines(TypedDict):
+    """Guidelines for parallel execution."""
+
+    dispatch: str
+    patterns: list[str]
+    avoid: list[str]
+
+
+class AggregateResultsDict(TypedDict):
+    """Result from aggregate_parallel_results()."""
+
+    total_agents: int
+    successful: int
+    failed: int
+    total_duration_seconds: float
+    parallel_speedup: float
+    avg_health_score: float
+    total_anti_patterns: int
+    files_modified: list[str]
+    conflicts: list[str]
+    recommendations: list[str]
+    validation: dict[str, bool]
+    all_passed: bool

htmlgraph/validation.py

@@ -0,0 +1,115 @@
+"""
+Rich CLI validation error formatting and utilities.
+
+Provides beautiful error display for Pydantic validation failures.
+"""
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from pydantic import ValidationError
+from rich.console import Console
+
+console = Console()
+
+T = TypeVar("T")
+
+
+def display_validation_error(error: ValidationError) -> None:
+    """
+    Display a Pydantic validation error in Rich format.
+
+    Args:
+        error: ValidationError from Pydantic model validation
+
+    Example:
+        try:
+            input_data = FeatureCreateInput(title="", priority="invalid")
+        except ValidationError as e:
+            display_validation_error(e)
+    """
+    console.print("[red]✗ Validation Error[/red]")
+    console.print()
+
+    for err in error.errors():
+        field = ".".join(str(loc) for loc in err["loc"])
+        msg = err["msg"]
+        error_type = err["type"]
+
+        # Color code by error type for better UX
+        if "at least" in msg.lower() or "at most" in msg.lower():
+            # Length/range constraint violation
+            console.print(f"  [yellow]{field}:[/yellow] {msg}")
+        elif "must be" in msg.lower() or "is not valid" in msg.lower():
+            # Type/value constraint violation
+            console.print(f"  [cyan]{field}:[/cyan] {msg}")
+        elif error_type == "string_pattern":
+            # Pattern validation failed
+            console.print(f"  [magenta]{field}:[/magenta] {msg}")
+        else:
+            # Generic validation error
+            console.print(f"  [red]{field}:[/red] {msg}")
+
+    console.print()
+
+
+def validate_input(
+    validator_class: type[T],
+    **kwargs: object,
+) -> T | None:
+    """
+    Validate input and display rich error messages on failure.
+
+    Args:
+        validator_class: Pydantic model class to validate against
+        **kwargs: Input data to validate
+
+    Returns:
+        Validated model instance, or None if validation failed
+
+    Example:
+        input_data = validate_input(FeatureCreateInput, title="My Feature", priority="high")
+        if input_data is None:
+            sys.exit(1)
+        # Use input_data.title, input_data.priority, etc.
+    """
+    try:
+        return validator_class(**kwargs)
+    except ValidationError as e:
+        display_validation_error(e)
+        return None
+
+
+def wrap_command_validation(func: Callable[..., None]) -> Callable[..., None]:
+    """
+    Decorator to wrap CLI command functions with validation error handling.
+
+    This decorator catches ValidationError and displays it in Rich format,
+    then exits gracefully.
+
+    Args:
+        func: CLI command function
+
+    Returns:
+        Wrapped function with validation error handling
+
+    Example:
+        @wrap_command_validation
+        def cmd_feature_create(args: argparse.Namespace) -> None:
+            input_data = FeatureCreateInput(
+                title=args.title,
+                priority=args.priority
+            )
+            # Rest of command logic
+    """
+
+    def wrapper(*args: object, **kwargs: object) -> None:
+        import sys
+
+        try:
+            return func(*args, **kwargs)
+        except ValidationError as e:
+            display_validation_error(e)
+            sys.exit(1)
+
+    return wrapper

htmlgraph/watch.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 File-change watcher for HtmlGraph.
 
@@ -7,7 +9,6 @@ native "PostToolUse" hooks (e.g. editors/agents that write files directly).
 It batches filesystem changes and records them as activity events.
 """
 
-from __future__ import annotations
 
 import os
 import time
@@ -16,7 +17,6 @@ from pathlib import Path
 
 from htmlgraph.session_manager import SessionManager
 
-
 DEFAULT_IGNORE_DIRS = {
     ".git",
     ".venv",
@@ -69,7 +69,9 @@ def watch_and_track(
     ignore = set(ignore_dirs or DEFAULT_IGNORE_DIRS)
 
     manager = SessionManager(graph_dir)
-    session = manager.start_session(session_id=session_id, agent=agent, title=f"Watch: {agent}")
+    session = manager.start_session(
+        session_id=session_id, agent=agent, title=f"Watch: {agent}"
+    )
 
     last_snapshot = _snapshot(root, ignore)
     pending: set[str] = set()
@@ -123,6 +125,7 @@ def watch_and_track(
             last_snapshot = current
     except KeyboardInterrupt:
         print("\nStopping watcher…")
-        manager.track_activity(session_id=session.id, tool="Stop", summary="Watcher stopped")
+        manager.track_activity(
+            session_id=session.id, tool="Stop", summary="Watcher stopped"
+        )
         manager.end_session(session.id)
-

htmlgraph/work_type_utils.py

@@ -1,14 +1,15 @@
+from __future__ import annotations
+
 """
 Utility functions for work type inference and classification.
 
 Provides automatic work type detection based on active work items.
 """
 
-from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from htmlgraph.models import WorkType
     from htmlgraph import SDK