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

doit_cli/services/coverage_calculator.py

@@ -0,0 +1,142 @@
+"""Calculator for requirement coverage metrics."""
+
+from pathlib import Path
+from typing import Optional
+
+from ..models.crossref_models import (
+    CoverageReport,
+    Requirement,
+    RequirementCoverage,
+    Task,
+)
+from .requirement_parser import RequirementParser
+from .task_parser import TaskParser
+
+
+class CoverageCalculator:
+    """Calculates coverage metrics for requirements.
+
+    This service matches requirements from spec.md to tasks from tasks.md
+    and computes coverage percentages and identifies gaps.
+    """
+
+    def __init__(
+        self,
+        requirement_parser: Optional[RequirementParser] = None,
+        task_parser: Optional[TaskParser] = None,
+    ) -> None:
+        """Initialize calculator with optional parsers.
+
+        Args:
+            requirement_parser: Parser for spec.md. Created if not provided.
+            task_parser: Parser for tasks.md. Created if not provided.
+        """
+        self.requirement_parser = requirement_parser or RequirementParser()
+        self.task_parser = task_parser or TaskParser()
+
+    def calculate(
+        self,
+        spec_path: Path,
+        tasks_path: Optional[Path] = None,
+    ) -> CoverageReport:
+        """Calculate coverage for a specification.
+
+        Args:
+            spec_path: Path to spec.md file.
+            tasks_path: Path to tasks.md file. Defaults to tasks.md in same directory.
+
+        Returns:
+            CoverageReport with all coverage metrics.
+
+        Raises:
+            FileNotFoundError: If spec.md doesn't exist.
+        """
+        spec_path = Path(spec_path)
+        if not spec_path.exists():
+            raise FileNotFoundError(f"Spec file not found: {spec_path}")
+
+        # Default tasks path to same directory as spec
+        if tasks_path is None:
+            tasks_path = spec_path.parent / "tasks.md"
+
+        # Parse requirements from spec
+        requirements = self.requirement_parser.parse(spec_path)
+
+        # Parse tasks (empty list if tasks.md doesn't exist)
+        tasks: list[Task] = []
+        if tasks_path.exists():
+            tasks = self.task_parser.parse(tasks_path)
+
+        # Build coverage data
+        return self._build_coverage_report(
+            spec_path=str(spec_path),
+            requirements=requirements,
+            tasks=tasks,
+        )
+
+    def _build_coverage_report(
+        self,
+        spec_path: str,
+        requirements: list[Requirement],
+        tasks: list[Task],
+    ) -> CoverageReport:
+        """Build a CoverageReport from parsed data.
+
+        Args:
+            spec_path: Path to spec.md file.
+            requirements: List of requirements from spec.
+            tasks: List of tasks from tasks.md.
+
+        Returns:
+            CoverageReport with requirement-task mappings.
+        """
+        # Build map of requirement ID -> requirement
+        req_map: dict[str, Requirement] = {r.id: r for r in requirements}
+
+        # Build requirement coverage entries
+        coverage_list: list[RequirementCoverage] = []
+        for req in requirements:
+            # Find tasks that reference this requirement
+            matching_tasks = [t for t in tasks if req.id in t.requirement_ids]
+            coverage_list.append(
+                RequirementCoverage(
+                    requirement=req,
+                    tasks=matching_tasks,
+                )
+            )
+
+        # Find orphaned references (tasks referencing non-existent requirements)
+        orphaned: list[tuple[Task, str]] = []
+        for task in tasks:
+            for ref in task.references:
+                if ref.requirement_id not in req_map:
+                    orphaned.append((task, ref.requirement_id))
+
+        return CoverageReport(
+            spec_path=spec_path,
+            requirements=coverage_list,
+            orphaned_references=orphaned,
+        )
+
+    def calculate_for_feature(
+        self,
+        feature_dir: Path,
+    ) -> CoverageReport:
+        """Calculate coverage for a feature directory.
+
+        Convenience method that finds spec.md and tasks.md in the feature directory.
+
+        Args:
+            feature_dir: Path to feature directory (e.g., specs/033-my-feature/)
+
+        Returns:
+            CoverageReport for the feature.
+
+        Raises:
+            FileNotFoundError: If spec.md doesn't exist in feature directory.
+        """
+        feature_dir = Path(feature_dir)
+        spec_path = feature_dir / "spec.md"
+        tasks_path = feature_dir / "tasks.md"
+
+        return self.calculate(spec_path, tasks_path)

doit_cli/services/crossref_service.py

@@ -0,0 +1,237 @@
+"""Cross-reference service for spec-task traceability."""
+
+from pathlib import Path
+from typing import Optional
+
+from ..models.crossref_models import (
+    CoverageReport,
+    Requirement,
+    RequirementCoverage,
+    Task,
+)
+from .coverage_calculator import CoverageCalculator
+from .requirement_parser import RequirementParser
+from .task_parser import TaskParser
+
+
+class CrossReferenceService:
+    """Service for managing cross-references between specs and tasks.
+
+    This service provides a unified API for:
+    - Getting coverage reports
+    - Finding tasks for requirements
+    - Finding requirements for tasks
+    - Locating requirement definitions
+    """
+
+    def __init__(
+        self,
+        project_root: Optional[Path] = None,
+        specs_dir: str = "specs",
+    ) -> None:
+        """Initialize the service.
+
+        Args:
+            project_root: Root directory of the project. Defaults to cwd.
+            specs_dir: Name of the specs directory.
+        """
+        self.project_root = Path(project_root) if project_root else Path.cwd()
+        self.specs_dir = specs_dir
+        self.requirement_parser = RequirementParser()
+        self.task_parser = TaskParser()
+        self.coverage_calculator = CoverageCalculator(
+            self.requirement_parser,
+            self.task_parser,
+        )
+
+    def get_coverage(
+        self,
+        spec_name: Optional[str] = None,
+        spec_path: Optional[Path] = None,
+    ) -> CoverageReport:
+        """Get coverage report for a specification.
+
+        Args:
+            spec_name: Name of spec directory (e.g., "033-my-feature").
+            spec_path: Direct path to spec.md. Overrides spec_name.
+
+        Returns:
+            CoverageReport for the specification.
+
+        Raises:
+            FileNotFoundError: If spec doesn't exist.
+            ValueError: If neither spec_name nor spec_path provided.
+        """
+        if spec_path:
+            return self.coverage_calculator.calculate(spec_path)
+
+        if spec_name:
+            feature_dir = self.project_root / self.specs_dir / spec_name
+            return self.coverage_calculator.calculate_for_feature(feature_dir)
+
+        raise ValueError("Either spec_name or spec_path must be provided")
+
+    def get_tasks_for_requirement(
+        self,
+        requirement_id: str,
+        spec_name: Optional[str] = None,
+        tasks_path: Optional[Path] = None,
+    ) -> list[Task]:
+        """Get all tasks that implement a specific requirement.
+
+        Args:
+            requirement_id: The FR-XXX ID to search for.
+            spec_name: Name of spec directory.
+            tasks_path: Direct path to tasks.md.
+
+        Returns:
+            List of tasks that reference the requirement.
+
+        Raises:
+            ValueError: If neither spec_name nor tasks_path provided.
+        """
+        if tasks_path:
+            return self.task_parser.get_tasks_for_requirement(
+                requirement_id, tasks_path
+            )
+
+        if spec_name:
+            feature_dir = self.project_root / self.specs_dir / spec_name
+            tasks_file = feature_dir / "tasks.md"
+            if not tasks_file.exists():
+                return []
+            return self.task_parser.get_tasks_for_requirement(
+                requirement_id, tasks_file
+            )
+
+        raise ValueError("Either spec_name or tasks_path must be provided")
+
+    def locate_requirement(
+        self,
+        requirement_id: str,
+        spec_name: Optional[str] = None,
+        spec_path: Optional[Path] = None,
+    ) -> Optional[Requirement]:
+        """Find a requirement definition in a spec.
+
+        Args:
+            requirement_id: The FR-XXX ID to find.
+            spec_name: Name of spec directory.
+            spec_path: Direct path to spec.md.
+
+        Returns:
+            Requirement if found, None otherwise.
+
+        Raises:
+            ValueError: If neither spec_name nor spec_path provided.
+        """
+        if spec_path:
+            return self.requirement_parser.get_requirement(requirement_id, spec_path)
+
+        if spec_name:
+            feature_dir = self.project_root / self.specs_dir / spec_name
+            spec_file = feature_dir / "spec.md"
+            if not spec_file.exists():
+                return None
+            return self.requirement_parser.get_requirement(requirement_id, spec_file)
+
+        raise ValueError("Either spec_name or spec_path must be provided")
+
+    def get_requirement_coverage(
+        self,
+        requirement_id: str,
+        spec_name: Optional[str] = None,
+        spec_path: Optional[Path] = None,
+    ) -> Optional[RequirementCoverage]:
+        """Get coverage details for a specific requirement.
+
+        Args:
+            requirement_id: The FR-XXX ID to check.
+            spec_name: Name of spec directory.
+            spec_path: Direct path to spec.md.
+
+        Returns:
+            RequirementCoverage if requirement exists, None otherwise.
+        """
+        report = self.get_coverage(spec_name=spec_name, spec_path=spec_path)
+        return report.get_requirement_coverage(requirement_id)
+
+    def validate_references(
+        self,
+        spec_name: Optional[str] = None,
+        spec_path: Optional[Path] = None,
+    ) -> tuple[list[str], list[tuple[Task, str]]]:
+        """Validate cross-references and find issues.
+
+        Args:
+            spec_name: Name of spec directory.
+            spec_path: Direct path to spec.md.
+
+        Returns:
+            Tuple of (uncovered_requirement_ids, orphaned_references).
+            orphaned_references is list of (task, invalid_requirement_id) tuples.
+        """
+        report = self.get_coverage(spec_name=spec_name, spec_path=spec_path)
+
+        # Find uncovered requirements
+        uncovered = [r.id for r in report.get_uncovered_requirements()]
+
+        return uncovered, report.orphaned_references
+
+    def get_all_requirements(
+        self,
+        spec_name: Optional[str] = None,
+        spec_path: Optional[Path] = None,
+    ) -> list[Requirement]:
+        """Get all requirements from a spec.
+
+        Args:
+            spec_name: Name of spec directory.
+            spec_path: Direct path to spec.md.
+
+        Returns:
+            List of all requirements in the spec.
+
+        Raises:
+            ValueError: If neither spec_name nor spec_path provided.
+        """
+        if spec_path:
+            return self.requirement_parser.parse(spec_path)
+
+        if spec_name:
+            feature_dir = self.project_root / self.specs_dir / spec_name
+            spec_file = feature_dir / "spec.md"
+            return self.requirement_parser.parse(spec_file)
+
+        raise ValueError("Either spec_name or spec_path must be provided")
+
+    def get_all_tasks(
+        self,
+        spec_name: Optional[str] = None,
+        tasks_path: Optional[Path] = None,
+    ) -> list[Task]:
+        """Get all tasks from a tasks file.
+
+        Args:
+            spec_name: Name of spec directory.
+            tasks_path: Direct path to tasks.md.
+
+        Returns:
+            List of all tasks. Empty list if tasks.md doesn't exist.
+
+        Raises:
+            ValueError: If neither spec_name nor tasks_path provided.
+        """
+        if tasks_path:
+            if not tasks_path.exists():
+                return []
+            return self.task_parser.parse(tasks_path)
+
+        if spec_name:
+            feature_dir = self.project_root / self.specs_dir / spec_name
+            tasks_file = feature_dir / "tasks.md"
+            if not tasks_file.exists():
+                return []
+            return self.task_parser.parse(tasks_file)
+
+        raise ValueError("Either spec_name or tasks_path must be provided")

doit_cli/services/cycle_time_calculator.py

@@ -0,0 +1,134 @@
+"""Cycle time calculator service for spec analytics.
+
+Provides statistical analysis of spec completion cycle times.
+"""
+
+from datetime import date, timedelta
+from typing import Optional
+
+from ..models.analytics_models import (
+    CycleTimeRecord,
+    CycleTimeStats,
+    SpecMetadata,
+)
+
+
+class CycleTimeCalculator:
+    """Calculator for cycle time statistics.
+
+    Processes SpecMetadata to extract cycle time records and
+    calculate statistical summaries.
+    """
+
+    def __init__(self, specs: list[SpecMetadata]):
+        """Initialize calculator with spec metadata.
+
+        Args:
+            specs: List of SpecMetadata objects to analyze
+        """
+        self.specs = specs
+        self._records: Optional[list[CycleTimeRecord]] = None
+
+    @property
+    def records(self) -> list[CycleTimeRecord]:
+        """Get all cycle time records from completed specs.
+
+        Returns:
+            List of CycleTimeRecord for specs with both dates
+        """
+        if self._records is None:
+            self._records = []
+            for spec in self.specs:
+                record = CycleTimeRecord.from_metadata(spec)
+                if record:
+                    self._records.append(record)
+        return self._records
+
+    def calculate_stats(
+        self,
+        days: Optional[int] = None,
+        since: Optional[date] = None,
+    ) -> Optional[CycleTimeStats]:
+        """Calculate cycle time statistics.
+
+        Args:
+            days: Filter to specs completed in last N days
+            since: Filter to specs completed since this date
+
+        Returns:
+            CycleTimeStats or None if no matching records
+        """
+        filtered = self.filter_records(days=days, since=since)
+        return CycleTimeStats.calculate(filtered)
+
+    def filter_records(
+        self,
+        days: Optional[int] = None,
+        since: Optional[date] = None,
+    ) -> list[CycleTimeRecord]:
+        """Filter cycle time records by time period.
+
+        Args:
+            days: Filter to specs completed in last N days
+            since: Filter to specs completed since this date (overrides days)
+
+        Returns:
+            Filtered list of CycleTimeRecord objects
+        """
+        records = self.records
+
+        if since is not None:
+            records = [r for r in records if r.end_date >= since]
+        elif days is not None:
+            cutoff = date.today() - timedelta(days=days)
+            records = [r for r in records if r.end_date >= cutoff]
+
+        # Sort by end date (most recent first)
+        return sorted(records, key=lambda r: r.end_date, reverse=True)
+
+    def get_recent_completions(self, limit: int = 10) -> list[CycleTimeRecord]:
+        """Get most recently completed specs.
+
+        Args:
+            limit: Maximum number of records to return
+
+        Returns:
+            List of CycleTimeRecord sorted by completion date
+        """
+        sorted_records = sorted(
+            self.records,
+            key=lambda r: r.end_date,
+            reverse=True,
+        )
+        return sorted_records[:limit]
+
+    def get_slowest_completions(self, limit: int = 5) -> list[CycleTimeRecord]:
+        """Get specs with longest cycle times.
+
+        Args:
+            limit: Maximum number of records to return
+
+        Returns:
+            List of CycleTimeRecord sorted by cycle time descending
+        """
+        sorted_records = sorted(
+            self.records,
+            key=lambda r: r.days_to_complete,
+            reverse=True,
+        )
+        return sorted_records[:limit]
+
+    def get_fastest_completions(self, limit: int = 5) -> list[CycleTimeRecord]:
+        """Get specs with shortest cycle times.
+
+        Args:
+            limit: Maximum number of records to return
+
+        Returns:
+            List of CycleTimeRecord sorted by cycle time ascending
+        """
+        sorted_records = sorted(
+            self.records,
+            key=lambda r: r.days_to_complete,
+        )
+        return sorted_records[:limit]