doit-toolkit-cli 0.1.9__py3-none-any.whl

doit_cli/services/agent_detector.py

@@ -0,0 +1,168 @@
+"""Agent detector service for detecting existing AI agent configuration."""
+
+from pathlib import Path
+from typing import Optional
+
+from ..models.agent import Agent
+from ..models.project import Project
+
+
+class AgentDetector:
+    """Service for detecting which AI agents are configured in a project."""
+
+    def __init__(self, project: Project):
+        """Initialize agent detector.
+
+        Args:
+            project: Project to detect agents for
+        """
+        self.project = project
+
+    def detect_agents(self) -> list[Agent]:
+        """Detect which agents are already configured in the project.
+
+        Detection order:
+        1. Check for existing .claude/ directory -> Claude
+        2. Check for existing .github/copilot-instructions.md -> Copilot
+        3. Check for existing .github/prompts/ directory -> Copilot
+
+        Returns:
+            List of detected agents
+        """
+        detected = []
+
+        if self._has_claude_setup():
+            detected.append(Agent.CLAUDE)
+
+        if self._has_copilot_setup():
+            detected.append(Agent.COPILOT)
+
+        return detected
+
+    def _has_claude_setup(self) -> bool:
+        """Check if project has Claude setup.
+
+        Returns:
+            True if .claude/ or .claude/commands/ exists
+        """
+        claude_dir = self.project.path / ".claude"
+        claude_commands = claude_dir / "commands"
+
+        return claude_dir.exists() or claude_commands.exists()
+
+    def _has_copilot_setup(self) -> bool:
+        """Check if project has Copilot setup.
+
+        Returns:
+            True if .github/copilot-instructions.md or .github/prompts/ exists
+        """
+        copilot_instructions = self.project.path / ".github" / "copilot-instructions.md"
+        copilot_prompts = self.project.path / ".github" / "prompts"
+
+        return copilot_instructions.exists() or copilot_prompts.exists()
+
+    def has_claude(self) -> bool:
+        """Check if project has Claude agent configured.
+
+        Returns:
+            True if Claude is configured
+        """
+        return self._has_claude_setup()
+
+    def has_copilot(self) -> bool:
+        """Check if project has Copilot agent configured.
+
+        Returns:
+            True if Copilot is configured
+        """
+        return self._has_copilot_setup()
+
+    def detect_primary_agent(self) -> Optional[Agent]:
+        """Detect the primary (most likely) agent for this project.
+
+        Returns:
+            Primary agent or None if none detected
+        """
+        agents = self.detect_agents()
+
+        if not agents:
+            return None
+
+        # Prefer Claude if both are detected
+        if Agent.CLAUDE in agents:
+            return Agent.CLAUDE
+
+        return agents[0]
+
+    def get_agent_status(self) -> dict:
+        """Get detailed status for each agent.
+
+        Returns:
+            Dict with agent status information
+        """
+        return {
+            "claude": {
+                "detected": self._has_claude_setup(),
+                "directory": str(self.project.path / ".claude"),
+                "commands_dir": str(self.project.command_directory(Agent.CLAUDE)),
+                "has_commands": self._has_doit_commands(Agent.CLAUDE),
+            },
+            "copilot": {
+                "detected": self._has_copilot_setup(),
+                "instructions": str(self.project.path / ".github" / "copilot-instructions.md"),
+                "prompts_dir": str(self.project.command_directory(Agent.COPILOT)),
+                "has_prompts": self._has_doit_commands(Agent.COPILOT),
+            },
+        }
+
+    def _has_doit_commands(self, agent: Agent) -> bool:
+        """Check if project has any doit commands for an agent.
+
+        Args:
+            agent: Agent to check
+
+        Returns:
+            True if any doit-prefixed command files exist
+        """
+        cmd_dir = self.project.command_directory(agent)
+
+        if not cmd_dir.exists():
+            return False
+
+        # Check for any doit-prefixed files
+        for file in cmd_dir.iterdir():
+            if file.is_file():
+                if agent == Agent.CLAUDE:
+                    if file.name.startswith("doit.") and file.name.endswith(".md"):
+                        return True
+                else:  # COPILOT
+                    if file.name.startswith("doit.") and file.name.endswith(".prompt.md"):
+                        return True
+
+        return False
+
+    def count_doit_commands(self, agent: Agent) -> int:
+        """Count doit command files for an agent.
+
+        Args:
+            agent: Agent to count commands for
+
+        Returns:
+            Number of doit command files
+        """
+        cmd_dir = self.project.command_directory(agent)
+
+        if not cmd_dir.exists():
+            return 0
+
+        count = 0
+        for file in cmd_dir.iterdir():
+            if file.is_file():
+                if agent == Agent.CLAUDE:
+                    if file.name.startswith("doit.") and file.name.endswith(".md"):
+                        count += 1
+                else:  # COPILOT
+                    if file.name.startswith("doit.") and file.name.endswith(".prompt.md"):
+                        count += 1
+
+        return count

doit_cli/services/analytics_service.py

@@ -0,0 +1,218 @@
+"""Analytics service for spec metrics and reporting.
+
+This service orchestrates the generation of analytics reports by:
+1. Using SpecScanner to discover specs
+2. Using DateInferrer to enrich specs with dates
+3. Building AnalyticsReport with aggregated metrics
+"""
+
+from datetime import date
+from pathlib import Path
+from typing import Optional
+
+from ..models.analytics_models import (
+    AnalyticsReport,
+    CycleTimeRecord,
+    CycleTimeStats,
+    SpecMetadata,
+    VelocityDataPoint,
+)
+from ..models.status_models import SpecState
+from .date_inferrer import DateInferrer
+from .spec_scanner import NotADoitProjectError, SpecNotFoundError, SpecScanner
+
+
+class AnalyticsService:
+    """Service for generating spec analytics and metrics.
+
+    Composes SpecScanner and DateInferrer to produce enriched
+    SpecMetadata and aggregated analytics reports.
+    """
+
+    def __init__(self, project_root: Optional[Path] = None):
+        """Initialize the analytics service.
+
+        Args:
+            project_root: Root directory of the project. Defaults to cwd.
+
+        Raises:
+            NotADoitProjectError: If not a valid doit project
+        """
+        self.project_root = project_root or Path.cwd()
+        self.scanner = SpecScanner(self.project_root, validate=False)
+        self.date_inferrer = DateInferrer(self.project_root)
+
+    def get_all_specs(self) -> list[SpecMetadata]:
+        """Get all specs with enriched metadata.
+
+        Returns:
+            List of SpecMetadata objects with date information
+        """
+        spec_statuses = self.scanner.scan(include_validation=False)
+
+        return [self._enrich_with_dates(status) for status in spec_statuses]
+
+    def get_spec_details(self, spec_name: str) -> SpecMetadata:
+        """Get detailed metadata for a single spec.
+
+        Args:
+            spec_name: Name of the spec directory (e.g., "036-analytics")
+
+        Returns:
+            SpecMetadata with enriched date information
+
+        Raises:
+            SpecNotFoundError: If spec doesn't exist
+        """
+        spec_status = self.scanner.scan_single(spec_name)
+        return self._enrich_with_dates(spec_status)
+
+    def get_completion_summary(self) -> dict:
+        """Get completion metrics summary.
+
+        Returns:
+            Dictionary with total_specs, by_status counts, and completion_pct
+        """
+        specs = self.get_all_specs()
+
+        total = len(specs)
+        by_status: dict[str, int] = {}
+
+        for spec in specs:
+            status_name = spec.status.display_name
+            by_status[status_name] = by_status.get(status_name, 0) + 1
+
+        completed = sum(
+            1 for s in specs if s.status in (SpecState.COMPLETE, SpecState.APPROVED)
+        )
+        completion_pct = (completed / total * 100) if total > 0 else 0.0
+
+        return {
+            "total_specs": total,
+            "by_status": by_status,
+            "completion_pct": round(completion_pct, 1),
+            "draft_count": by_status.get("Draft", 0),
+            "in_progress_count": by_status.get("In Progress", 0),
+            "complete_count": by_status.get("Complete", 0),
+            "approved_count": by_status.get("Approved", 0),
+        }
+
+    def get_cycle_time_stats(
+        self,
+        days: Optional[int] = None,
+        since: Optional[date] = None,
+    ) -> tuple[Optional[CycleTimeStats], list[CycleTimeRecord]]:
+        """Get cycle time statistics for completed specs.
+
+        Args:
+            days: Filter to specs completed in the last N days
+            since: Filter to specs completed since this date
+
+        Returns:
+            Tuple of (CycleTimeStats or None, list of CycleTimeRecords)
+        """
+        specs = self.get_all_specs()
+
+        # Filter to completed specs with dates
+        records: list[CycleTimeRecord] = []
+        for spec in specs:
+            record = CycleTimeRecord.from_metadata(spec)
+            if record:
+                # Apply time filter
+                if days is not None:
+                    cutoff = date.today().replace(day=date.today().day)
+                    from datetime import timedelta
+
+                    cutoff = date.today() - timedelta(days=days)
+                    if record.end_date < cutoff:
+                        continue
+                elif since is not None:
+                    if record.end_date < since:
+                        continue
+
+                records.append(record)
+
+        # Sort by end date (most recent first)
+        records.sort(key=lambda r: r.end_date, reverse=True)
+
+        stats = CycleTimeStats.calculate(records)
+        return stats, records
+
+    def get_velocity_data(self, weeks: int = 8) -> list[VelocityDataPoint]:
+        """Get weekly velocity data.
+
+        Args:
+            weeks: Number of weeks to include (default 8)
+
+        Returns:
+            List of VelocityDataPoint sorted by week (most recent first)
+        """
+        specs = self.get_all_specs()
+
+        # Build velocity points from completed specs
+        weekly: dict[str, VelocityDataPoint] = {}
+
+        for spec in specs:
+            if spec.completed_at:
+                point = VelocityDataPoint.from_completion(spec.completed_at, spec.name)
+                if point.week_key in weekly:
+                    weekly[point.week_key] = weekly[point.week_key].merge(point)
+                else:
+                    weekly[point.week_key] = point
+
+        # Sort by week (descending) and limit
+        sorted_points = sorted(weekly.values(), key=lambda v: v.week_key, reverse=True)
+        return sorted_points[:weeks]
+
+    def generate_report(self) -> AnalyticsReport:
+        """Generate a complete analytics report.
+
+        Returns:
+            AnalyticsReport with all metrics calculated
+        """
+        specs = self.get_all_specs()
+        return AnalyticsReport.generate(specs, self.project_root)
+
+    def _enrich_with_dates(self, spec_status) -> SpecMetadata:
+        """Enrich a SpecStatus with inferred dates.
+
+        Args:
+            spec_status: SpecStatus from scanner
+
+        Returns:
+            SpecMetadata with date information
+        """
+        created_at = self.date_inferrer.infer_created_date(spec_status.path)
+        completed_at = self.date_inferrer.infer_completed_date(spec_status.path)
+
+        return SpecMetadata.from_spec_status(
+            spec_status,
+            created_at=created_at,
+            completed_at=completed_at,
+        )
+
+    def find_spec(self, partial_name: str) -> list[str]:
+        """Find specs matching a partial name.
+
+        Args:
+            partial_name: Partial spec name to search for
+
+        Returns:
+            List of matching spec names
+        """
+        specs = self.scanner.scan(include_validation=False)
+        matches = [
+            s.name
+            for s in specs
+            if partial_name.lower() in s.name.lower()
+        ]
+        return matches
+
+    def list_all_spec_names(self) -> list[str]:
+        """List all available spec names.
+
+        Returns:
+            List of spec directory names
+        """
+        specs = self.scanner.scan(include_validation=False)
+        return [s.name for s in specs]

doit_cli/services/architecture_generator.py

@@ -0,0 +1,290 @@
+"""Generator for Architecture diagrams from plan.md files."""
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+from ..models.diagram_models import DiagramType, GeneratedDiagram
+
+
+@dataclass
+class ComponentInfo:
+    """Information about an architecture component.
+
+    Attributes:
+        name: Component name
+        layer: Layer it belongs to (CLI, Service, Model, etc.)
+        description: Component description
+        dependencies: Other components it depends on
+    """
+
+    name: str
+    layer: str = ""
+    description: str = ""
+    dependencies: list[str] = field(default_factory=list)
+
+
+class ArchitectureGenerator:
+    """Generates Mermaid architecture diagrams from plan.md content.
+
+    Parses Technical Context and Project Structure sections to create
+    a flowchart showing system layers and component relationships.
+    """
+
+    # Pattern for project structure code blocks
+    STRUCTURE_PATTERN = re.compile(
+        r"```(?:text)?\s*\n((?:src/|tests/).*?)```", re.DOTALL
+    )
+
+    # Pattern for extracting file paths from structure
+    FILE_PATTERN = re.compile(r"^[\s│├└─]*([a-zA-Z_][a-zA-Z0-9_/]*\.py)", re.MULTILINE)
+
+    # Layer classification patterns
+    LAYER_PATTERNS = [
+        (re.compile(r"cli/|command", re.IGNORECASE), "CLI Layer"),
+        (re.compile(r"services?/", re.IGNORECASE), "Service Layer"),
+        (re.compile(r"models?/", re.IGNORECASE), "Data Layer"),
+        (re.compile(r"tests?/unit", re.IGNORECASE), "Unit Tests"),
+        (re.compile(r"tests?/integration", re.IGNORECASE), "Integration Tests"),
+        (re.compile(r"formatters?/", re.IGNORECASE), "Formatters"),
+        (re.compile(r"prompts?/", re.IGNORECASE), "Prompts"),
+        (re.compile(r"rules?/", re.IGNORECASE), "Rules"),
+    ]
+
+    def __init__(self, direction: str = "TB"):
+        """Initialize generator.
+
+        Args:
+            direction: Flowchart direction (TB, LR, etc.)
+        """
+        self.direction = direction
+
+    def generate(self, content: str) -> str:
+        """Generate Mermaid architecture diagram from plan.md content.
+
+        Args:
+            content: Full content of plan.md file
+
+        Returns:
+            Mermaid flowchart syntax
+        """
+        components = self._extract_components(content)
+        if not components:
+            return ""
+
+        # Group components by layer
+        layers: dict[str, list[ComponentInfo]] = {}
+        for comp in components:
+            layer = comp.layer or "Other"
+            if layer not in layers:
+                layers[layer] = []
+            layers[layer].append(comp)
+
+        # Generate diagram
+        lines = [f"flowchart {self.direction}"]
+
+        # Add subgraphs for each layer
+        layer_order = [
+            "CLI Layer",
+            "Service Layer",
+            "Data Layer",
+            "Formatters",
+            "Rules",
+            "Prompts",
+            "Unit Tests",
+            "Integration Tests",
+            "Other",
+        ]
+
+        for layer_name in layer_order:
+            if layer_name not in layers:
+                continue
+
+            layer_id = self._to_id(layer_name)
+            lines.append(f'    subgraph {layer_id}["{layer_name}"]')
+
+            for comp in layers[layer_name]:
+                comp_id = self._to_id(comp.name)
+                lines.append(f'        {comp_id}["{comp.name}"]')
+
+            lines.append("    end")
+            lines.append("")
+
+        # Add connections based on common patterns
+        connections = self._infer_connections(components)
+        if connections:
+            lines.append("    %% Component connections")
+            for source, target in connections:
+                source_id = self._to_id(source)
+                target_id = self._to_id(target)
+                lines.append(f"    {source_id} --> {target_id}")
+
+        return "\n".join(lines)
+
+    def generate_diagram(self, content: str) -> GeneratedDiagram:
+        """Generate a GeneratedDiagram object from plan content.
+
+        Args:
+            content: Plan.md content
+
+        Returns:
+            GeneratedDiagram with content and metadata
+        """
+        mermaid_content = self.generate(content)
+
+        # Count components
+        components = self._extract_components(content)
+
+        return GeneratedDiagram(
+            id="architecture",
+            diagram_type=DiagramType.ARCHITECTURE,
+            mermaid_content=mermaid_content,
+            is_valid=bool(mermaid_content),
+            node_count=len(components),
+        )
+
+    def _extract_components(self, content: str) -> list[ComponentInfo]:
+        """Extract component information from plan content.
+
+        Args:
+            content: Plan content
+
+        Returns:
+            List of ComponentInfo objects
+        """
+        components = []
+        seen_names: set[str] = set()
+
+        # Find project structure blocks
+        for match in self.STRUCTURE_PATTERN.finditer(content):
+            structure_text = match.group(1)
+
+            # Extract file paths
+            for file_match in self.FILE_PATTERN.finditer(structure_text):
+                file_path = file_match.group(1)
+
+                # Get component name from filename
+                name = self._path_to_component_name(file_path)
+                if name in seen_names or name == "__init__":
+                    continue
+                seen_names.add(name)
+
+                # Determine layer
+                layer = self._classify_layer(file_path)
+
+                components.append(
+                    ComponentInfo(name=name, layer=layer, description="")
+                )
+
+        return components
+
+    def _path_to_component_name(self, path: str) -> str:
+        """Convert file path to component name.
+
+        Args:
+            path: File path (e.g., "src/doit_cli/services/diagram_service.py")
+
+        Returns:
+            Component name (e.g., "DiagramService")
+        """
+        # Get filename without extension
+        filename = path.split("/")[-1].replace(".py", "")
+
+        # Convert snake_case to PascalCase
+        parts = filename.split("_")
+        return "".join(part.capitalize() for part in parts)
+
+    def _classify_layer(self, path: str) -> str:
+        """Classify which layer a file belongs to.
+
+        Args:
+            path: File path
+
+        Returns:
+            Layer name
+        """
+        for pattern, layer_name in self.LAYER_PATTERNS:
+            if pattern.search(path):
+                return layer_name
+        return "Other"
+
+    def _to_id(self, name: str) -> str:
+        """Convert name to valid Mermaid node ID.
+
+        Args:
+            name: Component or layer name
+
+        Returns:
+            Valid node ID
+        """
+        # Remove spaces and special characters
+        clean = re.sub(r"[^A-Za-z0-9]", "", name)
+        return clean
+
+    def _infer_connections(
+        self, components: list[ComponentInfo]
+    ) -> list[tuple[str, str]]:
+        """Infer connections between components based on naming patterns.
+
+        Args:
+            components: List of components
+
+        Returns:
+            List of (source, target) connection tuples
+        """
+        connections = []
+        comp_names = {c.name for c in components}
+
+        # Common connection patterns
+        patterns = [
+            # Command -> Service
+            (r"(.+)Command$", r"\1Service"),
+            # Service -> Parser
+            (r"(.+)Service$", r"\1Parser"),
+            # Generator -> Models
+            (r"(.+)Generator$", "DiagramModels"),
+            # Parser -> Models
+            (r"(.+)Parser$", "DiagramModels"),
+            # Service -> Generator
+            (r"(.+)Service$", r"\1Generator"),
+            # Service -> Validator
+            (r"(.+)Service$", r"\1Validator"),
+        ]
+
+        for comp in components:
+            for src_pattern, tgt_pattern in patterns:
+                match = re.match(src_pattern, comp.name)
+                if match:
+                    # Try to find matching target
+                    if r"\1" in tgt_pattern:
+                        target = re.sub(src_pattern, tgt_pattern, comp.name)
+                    else:
+                        target = tgt_pattern
+
+                    if target in comp_names and target != comp.name:
+                        connections.append((comp.name, target))
+
+        # Deduplicate
+        return list(set(connections))
+
+    def generate_from_sections(
+        self,
+        tech_context: Optional[str] = None,
+        project_structure: Optional[str] = None,
+    ) -> str:
+        """Generate architecture diagram from specific sections.
+
+        Args:
+            tech_context: Technical Context section content
+            project_structure: Project Structure section content
+
+        Returns:
+            Mermaid diagram syntax
+        """
+        combined = ""
+        if tech_context:
+            combined += tech_context + "\n"
+        if project_structure:
+            combined += project_structure
+
+        return self.generate(combined)