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

doit_cli/services/validation_service.py

@@ -0,0 +1,188 @@
+"""Validation service for spec file validation."""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from ..models.validation_models import ValidationConfig, ValidationResult
+from .config_loader import load_validation_config
+from .rule_engine import RuleEngine
+from .score_calculator import ScoreCalculator
+
+
+class ValidationService:
+    """Orchestrates spec file validation.
+
+    Coordinates rule loading, spec parsing, and result aggregation.
+    """
+
+    # Default specs directory name
+    SPECS_DIR = "specs"
+
+    def __init__(
+        self,
+        project_root: Optional[Path] = None,
+        config: Optional[ValidationConfig] = None,
+    ) -> None:
+        """Initialize validation service.
+
+        Args:
+            project_root: Root directory for spec discovery. Defaults to cwd.
+            config: Validation configuration. Uses defaults if None.
+                    If None, attempts to load from .doit/validation-rules.yaml.
+        """
+        self.project_root = project_root or Path.cwd()
+        self.config = config or load_validation_config(self.project_root)
+        self.rule_engine = RuleEngine(config=self.config)
+        self.score_calculator = ScoreCalculator()
+
+    def validate_file(self, spec_path: Path) -> ValidationResult:
+        """Validate a single spec file.
+
+        Args:
+            spec_path: Path to the spec file to validate.
+
+        Returns:
+            ValidationResult with all issues found.
+
+        Raises:
+            FileNotFoundError: If spec_path doesn't exist.
+            ValueError: If file is not a valid markdown file.
+        """
+        # Ensure path is absolute
+        if not spec_path.is_absolute():
+            spec_path = self.project_root / spec_path
+
+        if not spec_path.exists():
+            raise FileNotFoundError(f"Spec file not found: {spec_path}")
+
+        if not spec_path.suffix.lower() == ".md":
+            raise ValueError(f"Not a markdown file: {spec_path}")
+
+        # Read file content
+        try:
+            content = spec_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as e:
+            raise ValueError(f"Could not read file: {e}") from e
+
+        # Handle empty files
+        if not content.strip():
+            result = ValidationResult(
+                spec_path=str(spec_path),
+                validated_at=datetime.now(),
+            )
+            from ..models.validation_models import Severity, ValidationIssue
+
+            result.add_issue(
+                ValidationIssue(
+                    rule_id="empty-file",
+                    severity=Severity.ERROR,
+                    line_number=0,
+                    message="Spec file is empty",
+                    suggestion="Add content following the spec template structure",
+                )
+            )
+            result.quality_score = 0
+            return result
+
+        # Evaluate rules
+        issues = self.rule_engine.evaluate(content, spec_path)
+
+        # Calculate score
+        score = self.score_calculator.calculate(issues)
+
+        # Create result
+        result = ValidationResult(
+            spec_path=str(spec_path),
+            issues=issues,
+            quality_score=score,
+            validated_at=datetime.now(),
+        )
+
+        return result
+
+    def validate_directory(self, specs_dir: Path) -> list[ValidationResult]:
+        """Validate all spec files in a directory.
+
+        Args:
+            specs_dir: Directory containing spec files.
+
+        Returns:
+            List of ValidationResult, one per spec file found.
+        """
+        if not specs_dir.is_absolute():
+            specs_dir = self.project_root / specs_dir
+
+        if not specs_dir.exists():
+            return []
+
+        results: list[ValidationResult] = []
+
+        # Find all spec.md files in subdirectories
+        for spec_file in sorted(specs_dir.rglob("spec.md")):
+            try:
+                result = self.validate_file(spec_file)
+                results.append(result)
+            except (FileNotFoundError, ValueError) as e:
+                # Create error result for unreadable files
+                from ..models.validation_models import Severity, ValidationIssue
+
+                result = ValidationResult(
+                    spec_path=str(spec_file),
+                    validated_at=datetime.now(),
+                )
+                result.add_issue(
+                    ValidationIssue(
+                        rule_id="file-error",
+                        severity=Severity.ERROR,
+                        line_number=0,
+                        message=str(e),
+                        suggestion="Check file permissions and encoding",
+                    )
+                )
+                result.quality_score = 0
+                results.append(result)
+
+        return results
+
+    def validate_all(self) -> list[ValidationResult]:
+        """Validate all specs in project's specs/ directory.
+
+        Returns:
+            List of ValidationResult for all specs found.
+        """
+        specs_dir = self.project_root / self.SPECS_DIR
+        return self.validate_directory(specs_dir)
+
+    def get_summary(self, results: list[ValidationResult]) -> dict:
+        """Generate summary statistics for multiple results.
+
+        Args:
+            results: List of validation results.
+
+        Returns:
+            Dict with total_specs, passed, warned, failed, avg_score.
+        """
+        if not results:
+            return {
+                "total_specs": 0,
+                "passed": 0,
+                "warned": 0,
+                "failed": 0,
+                "average_score": 0,
+            }
+
+        from ..models.validation_models import ValidationStatus
+
+        passed = sum(1 for r in results if r.status == ValidationStatus.PASS)
+        warned = sum(1 for r in results if r.status == ValidationStatus.WARN)
+        failed = sum(1 for r in results if r.status == ValidationStatus.FAIL)
+        avg_score = sum(r.quality_score for r in results) // len(results)
+
+        return {
+            "total_specs": len(results),
+            "passed": passed,
+            "warned": warned,
+            "failed": failed,
+            "average_score": avg_score,
+        }

doit_cli/services/validator.py

@@ -0,0 +1,232 @@
+"""Validator service for checking project setup."""
+
+from pathlib import Path
+from typing import Optional
+
+from ..models.agent import Agent
+from ..models.project import Project
+from ..models.results import VerifyResult, VerifyCheck, VerifyStatus
+from ..models.template import DOIT_COMMANDS
+
+
+class Validator:
+    """Service for validating doit project setup."""
+
+    def __init__(self, project: Project):
+        """Initialize validator.
+
+        Args:
+            project: Project to validate
+        """
+        self.project = project
+        self.checks: list[VerifyCheck] = []
+
+    def check_doit_folder(self) -> VerifyCheck:
+        """Check if .doit/ folder exists and has required subdirectories."""
+        if not self.project.doit_folder.exists():
+            return VerifyCheck(
+                name="doit_folder",
+                status=VerifyStatus.FAIL,
+                message=".doit/ folder does not exist",
+                suggestion="Run 'doit init' to create the project structure",
+            )
+
+        # Check subdirectories
+        missing_subdirs = []
+        for subdir in ["memory", "templates", "scripts"]:
+            if not (self.project.doit_folder / subdir).exists():
+                missing_subdirs.append(subdir)
+
+        if missing_subdirs:
+            return VerifyCheck(
+                name="doit_folder",
+                status=VerifyStatus.WARN,
+                message=f".doit/ exists but missing subdirectories: {', '.join(missing_subdirs)}",
+                suggestion="Run 'doit init --update' to restore missing directories",
+            )
+
+        return VerifyCheck(
+            name="doit_folder",
+            status=VerifyStatus.PASS,
+            message=".doit/ folder structure is complete",
+        )
+
+    def check_agent_directory(self, agent: Agent) -> VerifyCheck:
+        """Check if agent command directory exists.
+
+        Args:
+            agent: Agent to check
+        """
+        cmd_dir = self.project.command_directory(agent)
+
+        if not cmd_dir.exists():
+            return VerifyCheck(
+                name=f"{agent.value}_directory",
+                status=VerifyStatus.FAIL,
+                message=f"{agent.display_name} command directory does not exist",
+                suggestion=f"Run 'doit init --agent {agent.value}' to create it",
+            )
+
+        return VerifyCheck(
+            name=f"{agent.value}_directory",
+            status=VerifyStatus.PASS,
+            message=f"{agent.display_name} command directory exists at {agent.command_directory}",
+        )
+
+    def check_command_files(self, agent: Agent) -> VerifyCheck:
+        """Check if all required command files exist for an agent.
+
+        Args:
+            agent: Agent to check
+        """
+        cmd_dir = self.project.command_directory(agent)
+
+        if not cmd_dir.exists():
+            return VerifyCheck(
+                name=f"{agent.value}_commands",
+                status=VerifyStatus.FAIL,
+                message=f"Cannot check commands - directory does not exist",
+            )
+
+        # Get expected file names
+        if agent == Agent.CLAUDE:
+            expected_files = {f"doit.{cmd}.md" for cmd in DOIT_COMMANDS}
+        else:  # COPILOT
+            expected_files = {f"doit.{cmd}.prompt.md" for cmd in DOIT_COMMANDS}
+
+        # Get actual files
+        actual_files = {f.name for f in cmd_dir.iterdir() if f.is_file()}
+
+        # Check for missing
+        missing = expected_files - actual_files
+
+        if missing:
+            return VerifyCheck(
+                name=f"{agent.value}_commands",
+                status=VerifyStatus.WARN,
+                message=f"Missing {len(missing)} command files: {', '.join(sorted(missing)[:3])}{'...' if len(missing) > 3 else ''}",
+                suggestion="Run 'doit init --update' to restore missing templates",
+            )
+
+        return VerifyCheck(
+            name=f"{agent.value}_commands",
+            status=VerifyStatus.PASS,
+            message=f"All {len(DOIT_COMMANDS)} command files present",
+        )
+
+    def check_constitution(self) -> VerifyCheck:
+        """Check if constitution.md exists in memory folder."""
+        constitution_path = self.project.memory_folder / "constitution.md"
+
+        if not constitution_path.exists():
+            return VerifyCheck(
+                name="constitution",
+                status=VerifyStatus.WARN,
+                message="Project constitution not found",
+                suggestion="Run '/doit.constitution' to create project principles",
+            )
+
+        return VerifyCheck(
+            name="constitution",
+            status=VerifyStatus.PASS,
+            message="Project constitution exists",
+        )
+
+    def check_roadmap(self) -> VerifyCheck:
+        """Check if roadmap.md exists in memory folder."""
+        roadmap_path = self.project.memory_folder / "roadmap.md"
+
+        if not roadmap_path.exists():
+            return VerifyCheck(
+                name="roadmap",
+                status=VerifyStatus.WARN,
+                message="Project roadmap not found",
+                suggestion="Run '/doit.roadmapit' to create a feature roadmap",
+            )
+
+        return VerifyCheck(
+            name="roadmap",
+            status=VerifyStatus.PASS,
+            message="Project roadmap exists",
+        )
+
+    def check_copilot_instructions(self) -> VerifyCheck:
+        """Check if copilot-instructions.md exists for Copilot projects."""
+        instructions_path = self.project.path / ".github" / "copilot-instructions.md"
+        prompts_dir = self.project.path / ".github" / "prompts"
+
+        # Only check if Copilot appears to be configured
+        if not prompts_dir.exists():
+            return VerifyCheck(
+                name="copilot_instructions",
+                status=VerifyStatus.PASS,
+                message="Copilot not configured (skipped)",
+            )
+
+        if not instructions_path.exists():
+            return VerifyCheck(
+                name="copilot_instructions",
+                status=VerifyStatus.WARN,
+                message="copilot-instructions.md not found",
+                suggestion="Run 'doit init --agent copilot' to create it",
+            )
+
+        # Check if it has doit section
+        content = instructions_path.read_text(encoding="utf-8")
+        if "DOIT INSTRUCTIONS" not in content:
+            return VerifyCheck(
+                name="copilot_instructions",
+                status=VerifyStatus.WARN,
+                message="copilot-instructions.md missing doit section",
+                suggestion="Run 'doit init --agent copilot --update' to add doit instructions",
+            )
+
+        return VerifyCheck(
+            name="copilot_instructions",
+            status=VerifyStatus.PASS,
+            message="copilot-instructions.md configured correctly",
+        )
+
+    def run_all_checks(self, agents: Optional[list[Agent]] = None) -> VerifyResult:
+        """Run all validation checks.
+
+        Args:
+            agents: List of agents to check (None = auto-detect)
+
+        Returns:
+            VerifyResult with all check results
+        """
+        self.checks = []
+
+        # Core structure check
+        self.checks.append(self.check_doit_folder())
+
+        # Auto-detect agents if not specified
+        if agents is None:
+            agents = []
+            if (self.project.path / ".claude").exists():
+                agents.append(Agent.CLAUDE)
+            if (self.project.path / ".github" / "prompts").exists():
+                agents.append(Agent.COPILOT)
+
+            # Default to Claude if nothing detected
+            if not agents:
+                agents = [Agent.CLAUDE]
+
+        # Agent-specific checks
+        for agent in agents:
+            self.checks.append(self.check_agent_directory(agent))
+            self.checks.append(self.check_command_files(agent))
+
+        # Memory content checks
+        self.checks.append(self.check_constitution())
+        self.checks.append(self.check_roadmap())
+
+        # Copilot-specific check
+        if Agent.COPILOT in agents:
+            self.checks.append(self.check_copilot_instructions())
+
+        return VerifyResult(
+            project=self.project,
+            checks=self.checks,
+        )

doit_cli/services/velocity_tracker.py

@@ -0,0 +1,173 @@
+"""Velocity tracker service for spec analytics.
+
+Provides weekly velocity aggregation and trend analysis.
+"""
+
+from datetime import date, timedelta
+from typing import Optional
+
+from ..models.analytics_models import SpecMetadata, VelocityDataPoint
+
+
+class VelocityTracker:
+    """Tracker for spec completion velocity.
+
+    Aggregates spec completions by ISO week to enable
+    trend analysis and velocity metrics.
+    """
+
+    def __init__(self, specs: list[SpecMetadata]):
+        """Initialize tracker with spec metadata.
+
+        Args:
+            specs: List of SpecMetadata objects to analyze
+        """
+        self.specs = specs
+        self._weekly_data: Optional[dict[str, VelocityDataPoint]] = None
+
+    @property
+    def weekly_data(self) -> dict[str, VelocityDataPoint]:
+        """Get weekly aggregated velocity data.
+
+        Returns:
+            Dictionary mapping week keys to VelocityDataPoint objects
+        """
+        if self._weekly_data is None:
+            self._weekly_data = self._aggregate_by_week()
+        return self._weekly_data
+
+    def _aggregate_by_week(self) -> dict[str, VelocityDataPoint]:
+        """Aggregate completions by ISO week.
+
+        Returns:
+            Dictionary of week_key -> VelocityDataPoint
+        """
+        weekly: dict[str, VelocityDataPoint] = {}
+
+        for spec in self.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
+
+        return weekly
+
+    def aggregate_by_week(self, weeks: int = 8) -> list[VelocityDataPoint]:
+        """Get velocity data for the specified number of weeks.
+
+        Args:
+            weeks: Number of weeks to include (default 8)
+
+        Returns:
+            List of VelocityDataPoint sorted by week (most recent first)
+        """
+        # Get all weekly data
+        all_weeks = list(self.weekly_data.values())
+
+        # Sort by week key (descending)
+        sorted_weeks = sorted(all_weeks, key=lambda v: v.week_key, reverse=True)
+
+        # Limit to requested number of weeks
+        return sorted_weeks[:weeks]
+
+    def get_velocity_trend(
+        self,
+        weeks: int = 8,
+        fill_missing: bool = True,
+    ) -> list[VelocityDataPoint]:
+        """Get velocity trend with optional gap filling.
+
+        Args:
+            weeks: Number of weeks to analyze
+            fill_missing: If True, include weeks with zero completions
+
+        Returns:
+            List of VelocityDataPoint covering the time range
+        """
+        if not fill_missing:
+            return self.aggregate_by_week(weeks)
+
+        # Generate all weeks in range
+        today = date.today()
+        current_week_start = today - timedelta(days=today.weekday())
+
+        result: list[VelocityDataPoint] = []
+
+        for i in range(weeks):
+            week_date = current_week_start - timedelta(weeks=i)
+            year, week, _ = week_date.isocalendar()
+            week_key = f"{year}-W{week:02d}"
+
+            if week_key in self.weekly_data:
+                result.append(self.weekly_data[week_key])
+            else:
+                # Create empty data point for missing week
+                result.append(
+                    VelocityDataPoint(
+                        week_key=week_key,
+                        week_start=week_date,
+                        specs_completed=0,
+                        spec_names=[],
+                    )
+                )
+
+        return result
+
+    def calculate_average_velocity(self, weeks: int = 8) -> float:
+        """Calculate average specs completed per week.
+
+        Args:
+            weeks: Number of weeks to average over
+
+        Returns:
+            Average completions per week
+        """
+        data = self.aggregate_by_week(weeks)
+        if not data:
+            return 0.0
+
+        total = sum(v.specs_completed for v in data)
+        return total / len(data)
+
+    def get_peak_week(self) -> Optional[VelocityDataPoint]:
+        """Get the week with most completions.
+
+        Returns:
+            VelocityDataPoint for peak week, or None if no data
+        """
+        if not self.weekly_data:
+            return None
+
+        return max(
+            self.weekly_data.values(),
+            key=lambda v: v.specs_completed,
+        )
+
+    def has_sufficient_data(self, min_weeks: int = 2) -> bool:
+        """Check if there's enough data for trend analysis.
+
+        Args:
+            min_weeks: Minimum weeks required
+
+        Returns:
+            True if sufficient data exists
+        """
+        return len(self.weekly_data) >= min_weeks
+
+    def to_csv(self, weeks: int = 8) -> str:
+        """Export velocity data as CSV string.
+
+        Args:
+            weeks: Number of weeks to include
+
+        Returns:
+            CSV formatted string with header
+        """
+        lines = ["week,completed"]
+        for v in self.aggregate_by_week(weeks):
+            lines.append(f"{v.week_key},{v.specs_completed}")
+        return "\n".join(lines)