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

doit_cli/services/date_inferrer.py

@@ -0,0 +1,349 @@
+"""Date inference service for spec analytics.
+
+This module extracts creation and completion dates for specifications using
+a multi-tier fallback strategy:
+1. Parse dates from spec.md metadata (e.g., **Created**: YYYY-MM-DD)
+2. Extract dates from git history
+3. Fall back to file system timestamps
+"""
+
+import re
+import subprocess
+from datetime import date, datetime
+from pathlib import Path
+from typing import Optional
+
+
+class DateInferrer:
+    """Service for inferring spec lifecycle dates.
+
+    Uses a multi-tier fallback strategy to extract creation and completion
+    dates from various sources.
+    """
+
+    # Patterns for extracting dates from spec metadata
+    CREATED_PATTERN = re.compile(
+        r"\*\*Created\*\*:\s*(\d{4}-\d{2}-\d{2})", re.IGNORECASE
+    )
+    DATE_PATTERN = re.compile(
+        r"\*\*Date\*\*:\s*(\d{4}-\d{2}-\d{2})", re.IGNORECASE
+    )
+    STATUS_COMPLETE_PATTERN = re.compile(
+        r"\*\*Status\*\*:\s*(Complete|Completed|Approved)", re.IGNORECASE
+    )
+
+    def __init__(self, project_root: Path):
+        """Initialize the date inferrer.
+
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = project_root
+        self._git_available: Optional[bool] = None
+
+    def _is_git_available(self) -> bool:
+        """Check if git is available and project is a git repo."""
+        if self._git_available is not None:
+            return self._git_available
+
+        try:
+            result = subprocess.run(
+                ["git", "rev-parse", "--git-dir"],
+                cwd=self.project_root,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            self._git_available = result.returncode == 0
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            self._git_available = False
+
+        return self._git_available
+
+    def infer_created_date(self, spec_path: Path) -> Optional[date]:
+        """Infer the creation date for a spec.
+
+        Tries sources in order:
+        1. **Created**: in spec.md metadata
+        2. **Date**: in spec.md metadata (fallback)
+        3. Git first commit date for the file
+        4. File system creation time
+
+        Args:
+            spec_path: Path to the spec.md file
+
+        Returns:
+            Inferred creation date or None if cannot determine
+        """
+        # Tier 1: Parse from metadata
+        if spec_path.exists():
+            metadata_date = self._parse_created_from_metadata(spec_path)
+            if metadata_date:
+                return metadata_date
+
+        # Tier 2: Git first commit
+        if self._is_git_available():
+            git_date = self._get_git_first_commit_date(spec_path)
+            if git_date:
+                return git_date
+
+        # Tier 3: File system
+        return self._get_file_creation_date(spec_path)
+
+    def infer_completed_date(self, spec_path: Path) -> Optional[date]:
+        """Infer the completion date for a spec.
+
+        Tries sources in order:
+        1. Git commit that changed status to Complete/Approved
+        2. Git last modification date (if status is Complete/Approved)
+        3. File modification time (if status is Complete/Approved)
+
+        Args:
+            spec_path: Path to the spec.md file
+
+        Returns:
+            Inferred completion date or None if not completed
+        """
+        if not spec_path.exists():
+            return None
+
+        # Check if spec is actually completed
+        if not self._is_spec_completed(spec_path):
+            return None
+
+        # Tier 1: Git commit that changed status to Complete
+        if self._is_git_available():
+            status_change_date = self._get_git_status_change_date(spec_path)
+            if status_change_date:
+                return status_change_date
+
+            # Tier 2: Git last modification date
+            last_mod_date = self._get_git_last_modified_date(spec_path)
+            if last_mod_date:
+                return last_mod_date
+
+        # Tier 3: File modification time
+        return self._get_file_modification_date(spec_path)
+
+    def _parse_created_from_metadata(self, spec_path: Path) -> Optional[date]:
+        """Parse creation date from spec metadata.
+
+        Args:
+            spec_path: Path to spec.md file
+
+        Returns:
+            Parsed date or None
+        """
+        try:
+            content = spec_path.read_text(encoding="utf-8")
+
+            # Try **Created**: first
+            match = self.CREATED_PATTERN.search(content)
+            if match:
+                return self._parse_date_string(match.group(1))
+
+            # Fall back to **Date**:
+            match = self.DATE_PATTERN.search(content)
+            if match:
+                return self._parse_date_string(match.group(1))
+
+        except (OSError, UnicodeDecodeError):
+            pass
+
+        return None
+
+    def _is_spec_completed(self, spec_path: Path) -> bool:
+        """Check if spec has Complete or Approved status.
+
+        Args:
+            spec_path: Path to spec.md file
+
+        Returns:
+            True if completed, False otherwise
+        """
+        try:
+            content = spec_path.read_text(encoding="utf-8")
+            return bool(self.STATUS_COMPLETE_PATTERN.search(content))
+        except (OSError, UnicodeDecodeError):
+            return False
+
+    def _get_git_first_commit_date(self, spec_path: Path) -> Optional[date]:
+        """Get the date of the first git commit for a file.
+
+        Args:
+            spec_path: Path to the file
+
+        Returns:
+            Date of first commit or None
+        """
+        try:
+            result = subprocess.run(
+                [
+                    "git",
+                    "log",
+                    "--follow",
+                    "--diff-filter=A",
+                    "--format=%aI",
+                    "--",
+                    str(spec_path),
+                ],
+                cwd=self.project_root,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+
+            if result.returncode == 0 and result.stdout.strip():
+                # Get the last line (first commit) if multiple
+                lines = result.stdout.strip().split("\n")
+                first_commit_date = lines[-1] if lines else None
+                if first_commit_date:
+                    return self._parse_iso_datetime(first_commit_date)
+
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            pass
+
+        return None
+
+    def _get_git_last_modified_date(self, spec_path: Path) -> Optional[date]:
+        """Get the date of the last git modification for a file.
+
+        Args:
+            spec_path: Path to the file
+
+        Returns:
+            Date of last modification or None
+        """
+        try:
+            result = subprocess.run(
+                [
+                    "git",
+                    "log",
+                    "-1",
+                    "--format=%aI",
+                    "--",
+                    str(spec_path),
+                ],
+                cwd=self.project_root,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+
+            if result.returncode == 0 and result.stdout.strip():
+                return self._parse_iso_datetime(result.stdout.strip())
+
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            pass
+
+        return None
+
+    def _get_git_status_change_date(self, spec_path: Path) -> Optional[date]:
+        """Get the date when status changed to Complete/Approved.
+
+        Args:
+            spec_path: Path to the file
+
+        Returns:
+            Date of status change or None
+        """
+        try:
+            # Search git log for commits that mention status change
+            result = subprocess.run(
+                [
+                    "git",
+                    "log",
+                    "-p",
+                    "--format=%aI",
+                    "-S",
+                    "Status**: Complete",
+                    "--",
+                    str(spec_path),
+                ],
+                cwd=self.project_root,
+                capture_output=True,
+                text=True,
+                timeout=15,
+            )
+
+            if result.returncode == 0 and result.stdout.strip():
+                # Extract the first date (most recent change)
+                lines = result.stdout.strip().split("\n")
+                for line in lines:
+                    if line.startswith("20") and "T" in line:  # ISO date
+                        return self._parse_iso_datetime(line)
+
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+            pass
+
+        return None
+
+    def _get_file_creation_date(self, spec_path: Path) -> Optional[date]:
+        """Get file system creation date.
+
+        Args:
+            spec_path: Path to the file
+
+        Returns:
+            Creation date or None
+        """
+        try:
+            if spec_path.exists():
+                stat = spec_path.stat()
+                # Try birth time (macOS), fall back to ctime
+                timestamp = getattr(stat, "st_birthtime", stat.st_ctime)
+                return date.fromtimestamp(timestamp)
+        except (OSError, ValueError):
+            pass
+
+        return None
+
+    def _get_file_modification_date(self, spec_path: Path) -> Optional[date]:
+        """Get file system modification date.
+
+        Args:
+            spec_path: Path to the file
+
+        Returns:
+            Modification date or None
+        """
+        try:
+            if spec_path.exists():
+                stat = spec_path.stat()
+                return date.fromtimestamp(stat.st_mtime)
+        except (OSError, ValueError):
+            pass
+
+        return None
+
+    @staticmethod
+    def _parse_date_string(date_str: str) -> Optional[date]:
+        """Parse a YYYY-MM-DD date string.
+
+        Args:
+            date_str: Date string in YYYY-MM-DD format
+
+        Returns:
+            Parsed date or None
+        """
+        try:
+            return datetime.strptime(date_str.strip(), "%Y-%m-%d").date()
+        except ValueError:
+            return None
+
+    @staticmethod
+    def _parse_iso_datetime(iso_str: str) -> Optional[date]:
+        """Parse an ISO 8601 datetime string to date.
+
+        Args:
+            iso_str: ISO datetime string (e.g., 2026-01-16T14:30:00-08:00)
+
+        Returns:
+            Parsed date or None
+        """
+        try:
+            # Handle timezone offset by truncating to date portion
+            date_part = iso_str.split("T")[0]
+            return datetime.strptime(date_part, "%Y-%m-%d").date()
+        except (ValueError, IndexError):
+            return None

doit_cli/services/diagram_service.py

@@ -0,0 +1,337 @@
+"""Main orchestration service for diagram generation."""
+
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from ..models.diagram_models import (
+    DiagramResult,
+    DiagramSection,
+    DiagramType,
+    GeneratedDiagram,
+    ValidationResult,
+)
+from .entity_parser import EntityParser
+from .er_diagram_generator import ERDiagramGenerator
+from .mermaid_validator import MermaidValidator
+from .section_parser import SectionParser
+from .user_journey_generator import UserJourneyGenerator
+from .user_story_parser import UserStoryParser
+
+
+class DiagramService:
+    """Service for generating Mermaid diagrams from specifications.
+
+    Orchestrates the full workflow:
+    1. Parse spec content (user stories, entities)
+    2. Generate diagrams (flowcharts, ER diagrams)
+    3. Validate Mermaid syntax
+    4. Insert/replace in AUTO-GENERATED sections
+    """
+
+    # Section name mappings
+    SECTION_NAMES = {
+        DiagramType.USER_JOURNEY: "user-journey",
+        DiagramType.ER_DIAGRAM: "entity-relationships",
+        DiagramType.ARCHITECTURE: "architecture",
+    }
+
+    def __init__(self, strict: bool = False, backup: bool = True):
+        """Initialize diagram service.
+
+        Args:
+            strict: If True, fail on validation errors
+            backup: If True, create backup before modifying files
+        """
+        self.strict = strict
+        self.backup = backup
+
+        # Initialize components
+        self.section_parser = SectionParser()
+        self.user_story_parser = UserStoryParser()
+        self.entity_parser = EntityParser()
+        self.user_journey_generator = UserJourneyGenerator()
+        self.er_diagram_generator = ERDiagramGenerator()
+        self.validator = MermaidValidator()
+
+    def generate(
+        self,
+        file_path: Path,
+        diagram_types: Optional[list[DiagramType]] = None,
+        insert: bool = True,
+    ) -> DiagramResult:
+        """Generate diagrams for a specification file.
+
+        Args:
+            file_path: Path to spec.md or plan.md file
+            diagram_types: Types to generate (default: auto-detect applicable)
+            insert: If True, insert diagrams into file
+
+        Returns:
+            DiagramResult with generated diagrams and status
+        """
+        result = DiagramResult(file_path=file_path)
+
+        # Validate file exists
+        if not file_path.exists():
+            result.success = False
+            result.error = f"File not found: {file_path}"
+            return result
+
+        # Read file content
+        try:
+            content = file_path.read_text(encoding="utf-8")
+        except Exception as e:
+            result.success = False
+            result.error = f"Error reading file: {e}"
+            return result
+
+        # Find existing AUTO-GENERATED sections
+        result.sections_found = self.section_parser.find_sections(content)
+
+        # Auto-detect diagram types if not specified
+        if diagram_types is None:
+            diagram_types = self._detect_applicable_types(content)
+
+        # Generate each diagram type
+        for diagram_type in diagram_types:
+            diagram = self._generate_diagram(content, diagram_type)
+            if diagram:
+                # Validate
+                validation = self.validator.validate(
+                    diagram.mermaid_content, diagram_type
+                )
+                diagram.validation = validation
+                diagram.is_valid = validation.passed
+
+                if self.strict and not validation.passed:
+                    result.success = False
+                    result.error = f"Validation failed for {diagram_type.value}: {validation.errors}"
+                    return result
+
+                result.diagrams.append(diagram)
+
+        # Insert diagrams into file if requested
+        if insert and result.diagrams:
+            updated_content, sections_updated = self._insert_diagrams(
+                content, result.diagrams
+            )
+            result.sections_updated = sections_updated
+
+            if sections_updated:
+                # Create backup and write file
+                try:
+                    self._write_file(file_path, updated_content)
+                except Exception as e:
+                    result.success = False
+                    result.error = f"Error writing file: {e}"
+                    return result
+
+        return result
+
+    def validate(
+        self, content: str, diagram_type: Optional[DiagramType] = None
+    ) -> ValidationResult:
+        """Validate Mermaid diagram syntax.
+
+        Args:
+            content: Mermaid diagram content
+            diagram_type: Type of diagram (auto-detected if None)
+
+        Returns:
+            ValidationResult with pass/fail and errors
+        """
+        return self.validator.validate(content, diagram_type)
+
+    def insert_diagram(
+        self, file_path: Path, section_name: str, diagram_content: str
+    ) -> bool:
+        """Insert or replace diagram in AUTO-GENERATED section.
+
+        Args:
+            file_path: Path to target file
+            section_name: Section identifier (e.g., "user-journey")
+            diagram_content: Mermaid diagram to insert (wrapped in code fence)
+
+        Returns:
+            True if successful, False if markers not found
+        """
+        if not file_path.exists():
+            return False
+
+        content = file_path.read_text(encoding="utf-8")
+
+        # Check if section exists
+        if not self.section_parser.has_section(content, section_name):
+            return False
+
+        # Replace section content
+        updated_content, success = self.section_parser.replace_section_content(
+            content, section_name, diagram_content
+        )
+
+        if success:
+            self._write_file(file_path, updated_content)
+
+        return success
+
+    def _detect_applicable_types(self, content: str) -> list[DiagramType]:
+        """Detect which diagram types are applicable for content.
+
+        Args:
+            content: File content
+
+        Returns:
+            List of applicable DiagramType values
+        """
+        types = []
+
+        # Check for user stories
+        if self.user_story_parser.count_stories(content) > 0:
+            types.append(DiagramType.USER_JOURNEY)
+
+        # Check for entities
+        if self.entity_parser.count_entities(content) > 0:
+            types.append(DiagramType.ER_DIAGRAM)
+
+        return types
+
+    def _generate_diagram(
+        self, content: str, diagram_type: DiagramType
+    ) -> Optional[GeneratedDiagram]:
+        """Generate a single diagram type.
+
+        Args:
+            content: File content
+            diagram_type: Type of diagram to generate
+
+        Returns:
+            GeneratedDiagram or None if content not found
+        """
+        if diagram_type == DiagramType.USER_JOURNEY:
+            stories = self.user_story_parser.parse(content)
+            if not stories:
+                return None
+            return self.user_journey_generator.generate_diagram(stories)
+
+        elif diagram_type == DiagramType.ER_DIAGRAM:
+            entities = self.entity_parser.parse(content)
+            if not entities:
+                return None
+            return self.er_diagram_generator.generate_diagram(entities)
+
+        elif diagram_type == DiagramType.ARCHITECTURE:
+            # Architecture generation would be handled by ArchitectureGenerator
+            # For now, return None (to be implemented in Phase 8)
+            return None
+
+        return None
+
+    def _insert_diagrams(
+        self, content: str, diagrams: list[GeneratedDiagram]
+    ) -> tuple[str, list[str]]:
+        """Insert diagrams into AUTO-GENERATED sections.
+
+        Args:
+            content: Original file content
+            diagrams: List of generated diagrams
+
+        Returns:
+            Tuple of (updated content, list of section names updated)
+        """
+        updated_content = content
+        sections_updated = []
+
+        for diagram in diagrams:
+            section_name = self.SECTION_NAMES.get(diagram.diagram_type)
+            if not section_name:
+                continue
+
+            # Check if section exists
+            if not self.section_parser.has_section(updated_content, section_name):
+                # Try to find alternate section names
+                alt_names = self._get_alternate_section_names(diagram.diagram_type)
+                for alt_name in alt_names:
+                    if self.section_parser.has_section(updated_content, alt_name):
+                        section_name = alt_name
+                        break
+                else:
+                    # Section not found, skip
+                    continue
+
+            # Replace section content
+            wrapped_content = diagram.wrapped_content
+            updated_content, success = self.section_parser.replace_section_content(
+                updated_content, section_name, wrapped_content
+            )
+
+            if success:
+                sections_updated.append(section_name)
+
+        return updated_content, sections_updated
+
+    def _get_alternate_section_names(self, diagram_type: DiagramType) -> list[str]:
+        """Get alternate section names for a diagram type.
+
+        Args:
+            diagram_type: Type of diagram
+
+        Returns:
+            List of alternate section name possibilities
+        """
+        alternates = {
+            DiagramType.USER_JOURNEY: ["user-journey", "userjourney", "user_journey", "flowchart"],
+            DiagramType.ER_DIAGRAM: ["entity-relationships", "er-diagram", "erdiagram", "entities"],
+            DiagramType.ARCHITECTURE: ["architecture", "arch", "system-architecture"],
+        }
+        return alternates.get(diagram_type, [])
+
+    def _write_file(self, file_path: Path, content: str) -> None:
+        """Write content to file with optional backup.
+
+        Args:
+            file_path: Path to write to
+            content: Content to write
+        """
+        if self.backup and file_path.exists():
+            # Create backup with timestamp
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            backup_path = file_path.with_suffix(f".{timestamp}.bak")
+            shutil.copy2(file_path, backup_path)
+
+        # Write atomically by writing to temp file first
+        temp_path = file_path.with_suffix(".tmp")
+        try:
+            temp_path.write_text(content, encoding="utf-8")
+            temp_path.replace(file_path)
+        finally:
+            if temp_path.exists():
+                temp_path.unlink()
+
+    def get_diagram_content(
+        self, file_path: Path, diagram_type: DiagramType
+    ) -> Optional[str]:
+        """Get existing diagram content from a file.
+
+        Args:
+            file_path: Path to file
+            diagram_type: Type of diagram to find
+
+        Returns:
+            Diagram content if found, None otherwise
+        """
+        if not file_path.exists():
+            return None
+
+        content = file_path.read_text(encoding="utf-8")
+        section_name = self.SECTION_NAMES.get(diagram_type)
+
+        if not section_name:
+            return None
+
+        section = self.section_parser.find_section(content, section_name)
+        if not section:
+            return None
+
+        return self.section_parser.extract_mermaid_from_section(section)