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

doit_cli/services/score_calculator.py

@@ -0,0 +1,172 @@
+"""Quality score calculator for spec validation."""
+
+from ..models.validation_models import Severity, ValidationIssue
+
+
+class ScoreCalculator:
+    """Calculates quality scores from validation issues.
+
+    Uses weighted category scoring where each issue deducts points
+    based on its category and severity. The score is deterministic -
+    the same issues always produce the same score.
+    """
+
+    # Category weights (how much each category affects score)
+    CATEGORY_WEIGHTS: dict[str, int] = {
+        "structure": 20,  # Missing required sections
+        "requirements": 15,  # Naming convention violations
+        "acceptance": 10,  # Missing scenarios
+        "clarity": 5,  # Unresolved markers
+        "naming": 5,  # Format violations
+    }
+
+    # Severity multipliers
+    SEVERITY_MULTIPLIERS: dict[Severity, float] = {
+        Severity.ERROR: 1.0,  # Full weight deduction
+        Severity.WARNING: 0.5,  # Half weight deduction
+        Severity.INFO: 0.1,  # Minor deduction
+    }
+
+    # Default weight for unknown categories
+    DEFAULT_WEIGHT: int = 5
+
+    def calculate(self, issues: list[ValidationIssue]) -> int:
+        """Calculate quality score from issues.
+
+        Score = 100 - sum(deductions)
+
+        For each issue:
+            deduction = CATEGORY_WEIGHTS[category] * SEVERITY_MULTIPLIERS[severity]
+
+        Multiple issues in same category are additive but capped at category weight.
+
+        Args:
+            issues: List of validation issues found.
+
+        Returns:
+            Integer score 0-100 (100 = perfect, 0 = many issues).
+        """
+        if not issues:
+            return 100
+
+        category_deductions: dict[str, float] = {}
+
+        for issue in issues:
+            category = self._get_category(issue.rule_id)
+            weight = self.CATEGORY_WEIGHTS.get(category, self.DEFAULT_WEIGHT)
+            multiplier = self.SEVERITY_MULTIPLIERS.get(issue.severity, 0.5)
+            deduction = weight * multiplier
+
+            # Accumulate per category (capped at category weight)
+            current = category_deductions.get(category, 0.0)
+            category_deductions[category] = min(current + deduction, float(weight))
+
+        # Sum all category deductions
+        total_deduction = sum(category_deductions.values())
+
+        # Return score clamped to 0-100
+        return max(0, int(100 - total_deduction))
+
+    def get_breakdown(self, issues: list[ValidationIssue]) -> dict[str, int]:
+        """Get score breakdown by category.
+
+        Args:
+            issues: List of validation issues.
+
+        Returns:
+            Dict mapping category to points deducted.
+        """
+        breakdown: dict[str, int] = {}
+
+        for issue in issues:
+            category = self._get_category(issue.rule_id)
+            weight = self.CATEGORY_WEIGHTS.get(category, self.DEFAULT_WEIGHT)
+            multiplier = self.SEVERITY_MULTIPLIERS.get(issue.severity, 0.5)
+            deduction = int(weight * multiplier)
+
+            current = breakdown.get(category, 0)
+            max_for_category = self.CATEGORY_WEIGHTS.get(category, self.DEFAULT_WEIGHT)
+            breakdown[category] = min(current + deduction, max_for_category)
+
+        return breakdown
+
+    def _get_category(self, rule_id: str) -> str:
+        """Determine category from rule ID.
+
+        Args:
+            rule_id: The rule identifier.
+
+        Returns:
+            Category name.
+        """
+        # Map rule IDs to categories based on naming patterns
+        category_patterns = {
+            "structure": [
+                "missing-user-scenarios",
+                "missing-requirements",
+                "missing-success-criteria",
+            ],
+            "requirements": [
+                "fr-naming-convention",
+                "sc-naming-convention",
+            ],
+            "acceptance": [
+                "missing-acceptance-scenarios",
+                "incomplete-given-when-then",
+            ],
+            "clarity": [
+                "unresolved-clarification",
+                "todo-in-approved-spec",
+            ],
+            "naming": [
+                "feature-branch-format",
+            ],
+        }
+
+        for category, rule_ids in category_patterns.items():
+            if rule_id in rule_ids:
+                return category
+
+        # Default to category based on naming heuristics
+        if "missing" in rule_id.lower():
+            return "structure"
+        if "naming" in rule_id.lower() or "convention" in rule_id.lower():
+            return "requirements"
+        if "acceptance" in rule_id.lower() or "scenario" in rule_id.lower():
+            return "acceptance"
+        if "todo" in rule_id.lower() or "clarification" in rule_id.lower():
+            return "clarity"
+
+        return "naming"  # Default category
+
+    def get_score_interpretation(self, score: int) -> str:
+        """Get interpretation text for a score.
+
+        Args:
+            score: Quality score 0-100.
+
+        Returns:
+            Interpretation string.
+        """
+        if score >= 90:
+            return "Excellent - minor or no issues"
+        if score >= 70:
+            return "Good - some warnings, no errors"
+        if score >= 50:
+            return "Fair - has errors or many warnings"
+        return "Poor - multiple critical issues"
+
+    def get_status_from_score(self, score: int) -> str:
+        """Get status string from score.
+
+        Args:
+            score: Quality score 0-100.
+
+        Returns:
+            Status string (PASS, WARN, or FAIL).
+        """
+        if score >= 70:
+            return "PASS"
+        if score >= 50:
+            return "WARN"
+        return "FAIL"

doit_cli/services/section_parser.py

@@ -0,0 +1,204 @@
+"""Parser for AUTO-GENERATED sections in markdown files."""
+
+import re
+from typing import Optional
+
+from ..models.diagram_models import DiagramSection
+
+
+class SectionParser:
+    """Parses AUTO-GENERATED sections from markdown files.
+
+    Finds and extracts content between BEGIN and END markers:
+    <!-- BEGIN:AUTO-GENERATED section="name" -->
+    [content]
+    <!-- END:AUTO-GENERATED -->
+    """
+
+    # Regex pattern for BEGIN marker with section name
+    BEGIN_PATTERN = re.compile(
+        r'<!--\s*BEGIN:AUTO-GENERATED\s+section="([^"]+)"\s*-->', re.IGNORECASE
+    )
+
+    # Regex pattern for END marker
+    END_PATTERN = re.compile(r"<!--\s*END:AUTO-GENERATED\s*-->", re.IGNORECASE)
+
+    def find_sections(self, content: str) -> list[DiagramSection]:
+        """Find all AUTO-GENERATED sections in content.
+
+        Args:
+            content: File content to parse
+
+        Returns:
+            List of DiagramSection objects with section details
+        """
+        sections = []
+        lines = content.split("\n")
+
+        current_section: Optional[DiagramSection] = None
+        section_content_lines: list[str] = []
+
+        for line_num, line in enumerate(lines, start=1):
+            # Check for BEGIN marker
+            begin_match = self.BEGIN_PATTERN.search(line)
+            if begin_match:
+                # Start new section
+                section_name = begin_match.group(1)
+                current_section = DiagramSection(
+                    section_name=section_name,
+                    start_line=line_num,
+                    end_line=0,  # Will be set when END found
+                    content="",
+                )
+                section_content_lines = []
+                continue
+
+            # Check for END marker
+            if current_section is not None and self.END_PATTERN.search(line):
+                # Complete current section
+                current_section.end_line = line_num
+                current_section.content = "\n".join(section_content_lines)
+                sections.append(current_section)
+                current_section = None
+                section_content_lines = []
+                continue
+
+            # Accumulate content within section
+            if current_section is not None:
+                section_content_lines.append(line)
+
+        return sections
+
+    def find_section(self, content: str, section_name: str) -> Optional[DiagramSection]:
+        """Find a specific AUTO-GENERATED section by name.
+
+        Args:
+            content: File content to parse
+            section_name: Name of section to find (e.g., "user-journey")
+
+        Returns:
+            DiagramSection if found, None otherwise
+        """
+        sections = self.find_sections(content)
+        for section in sections:
+            if section.section_name == section_name:
+                return section
+        return None
+
+    def replace_section_content(
+        self, content: str, section_name: str, new_content: str
+    ) -> tuple[str, bool]:
+        """Replace content within an AUTO-GENERATED section.
+
+        Args:
+            content: Original file content
+            section_name: Name of section to update
+            new_content: New content to insert (without markers)
+
+        Returns:
+            Tuple of (updated content, success boolean)
+        """
+        section = self.find_section(content, section_name)
+        if section is None:
+            return content, False
+
+        lines = content.split("\n")
+
+        # Build new content: before + marker + new + marker + after
+        before_lines = lines[: section.start_line]  # Includes BEGIN marker line
+        after_lines = lines[section.end_line - 1 :]  # Starts from END marker line
+
+        # Ensure new content has proper newlines
+        new_content_clean = new_content.strip()
+
+        # Reconstruct
+        result_lines = before_lines + [new_content_clean] + after_lines
+
+        return "\n".join(result_lines), True
+
+    def insert_section_markers(
+        self,
+        content: str,
+        section_name: str,
+        after_heading: str,
+        initial_content: str = "",
+    ) -> tuple[str, bool]:
+        """Insert new AUTO-GENERATED section markers after a heading.
+
+        Args:
+            content: Original file content
+            section_name: Name for the new section
+            after_heading: Heading text to insert after (e.g., "## User Journey")
+            initial_content: Initial content to place between markers
+
+        Returns:
+            Tuple of (updated content, success boolean)
+        """
+        # Check if section already exists
+        if self.find_section(content, section_name) is not None:
+            return content, False  # Section already exists
+
+        lines = content.split("\n")
+        heading_pattern = re.compile(
+            rf"^#+\s*{re.escape(after_heading)}\s*$", re.IGNORECASE
+        )
+
+        insert_index = -1
+        for i, line in enumerate(lines):
+            if heading_pattern.match(line.strip()):
+                insert_index = i + 1
+                break
+
+        if insert_index == -1:
+            return content, False  # Heading not found
+
+        # Build marker block
+        begin_marker = f'<!-- BEGIN:AUTO-GENERATED section="{section_name}" -->'
+        end_marker = "<!-- END:AUTO-GENERATED -->"
+
+        marker_block = [
+            "",
+            begin_marker,
+            initial_content if initial_content else "",
+            end_marker,
+            "",
+        ]
+
+        # Insert after heading
+        result_lines = lines[:insert_index] + marker_block + lines[insert_index:]
+
+        return "\n".join(result_lines), True
+
+    def extract_mermaid_from_section(self, section: DiagramSection) -> Optional[str]:
+        """Extract Mermaid diagram content from a section.
+
+        Args:
+            section: DiagramSection to extract from
+
+        Returns:
+            Mermaid content without code fences, or None if not found
+        """
+        content = section.content
+
+        # Look for ```mermaid ... ``` block
+        mermaid_pattern = re.compile(
+            r"```mermaid\s*\n(.*?)\n```", re.DOTALL | re.IGNORECASE
+        )
+        match = mermaid_pattern.search(content)
+
+        if match:
+            return match.group(1).strip()
+
+        return None
+
+    def has_section(self, content: str, section_name: str) -> bool:
+        """Check if a section exists in content.
+
+        Args:
+            content: File content to check
+            section_name: Name of section to look for
+
+        Returns:
+            True if section exists, False otherwise
+        """
+        return self.find_section(content, section_name) is not None

doit_cli/services/spec_scanner.py

@@ -0,0 +1,327 @@
+"""Spec scanner service for discovering and parsing spec metadata."""
+
+import re
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from ..models.status_models import SpecState, SpecStatus, StatusReport
+from ..models.validation_models import ValidationResult
+
+
+class NotADoitProjectError(Exception):
+    """Raised when project_root lacks .doit/ directory."""
+
+    pass
+
+
+class SpecNotFoundError(Exception):
+    """Raised when a spec directory doesn't exist."""
+
+    pass
+
+
+class SpecScanner:
+    """Scans specs directory and parses spec metadata.
+
+    This service discovers all specification directories in a project,
+    parses their status from spec.md frontmatter, and returns structured
+    SpecStatus objects for each spec found.
+    """
+
+    # Regex pattern to extract status from spec.md
+    # Matches: **Status**: Draft (or In Progress, Complete, Approved)
+    STATUS_PATTERN = re.compile(
+        r"\*\*Status\*\*:\s*([A-Za-z]+(?:\s+[A-Za-z]+)?)", re.IGNORECASE
+    )
+
+    # Default specs directory name
+    SPECS_DIR = "specs"
+
+    def __init__(
+        self,
+        project_root: Optional[Path] = None,
+        validate: bool = True,
+    ) -> None:
+        """Initialize scanner with project root directory.
+
+        Args:
+            project_root: Root directory of the doit project.
+                         Defaults to current working directory.
+            validate: Whether to run validation on specs.
+
+        Raises:
+            NotADoitProjectError: If project_root lacks .doit/ directory.
+        """
+        self.project_root = project_root or Path.cwd()
+        self.validate = validate
+        self._validator = None
+
+        # Validate this is a doit project
+        doit_dir = self.project_root / ".doit"
+        if not doit_dir.exists():
+            raise NotADoitProjectError(
+                f"Not a doit project. Run 'doit init' first. "
+                f"(Missing .doit/ directory in {self.project_root})"
+            )
+
+    @property
+    def validator(self):
+        """Lazy-load the ValidationService."""
+        if self._validator is None and self.validate:
+            try:
+                from .validation_service import ValidationService
+
+                self._validator = ValidationService(self.project_root)
+            except ImportError:
+                # Validation service not available
+                self._validator = None
+        return self._validator
+
+    def scan(self, include_validation: bool = True) -> list[SpecStatus]:
+        """Scan specs/ directory and return all spec statuses.
+
+        Discovers all subdirectories in specs/ that contain a spec.md file
+        and parses their metadata.
+
+        Args:
+            include_validation: Whether to include validation results.
+
+        Returns:
+            List of SpecStatus objects, one per spec directory.
+            Sorted by spec name alphabetically.
+        """
+        specs_dir = self.project_root / self.SPECS_DIR
+
+        if not specs_dir.exists():
+            return []
+
+        statuses: list[SpecStatus] = []
+
+        # Find all spec.md files in subdirectories
+        for spec_file in sorted(specs_dir.rglob("spec.md")):
+            # Get spec name from parent directory
+            spec_name = spec_file.parent.name
+
+            # Skip if this is a nested spec (only want top-level)
+            relative_path = spec_file.parent.relative_to(specs_dir)
+            if len(relative_path.parts) > 1:
+                continue
+
+            status = self._parse_spec(spec_name, spec_file)
+
+            # Add validation if enabled
+            if include_validation and self.validate and self.validator:
+                status = self._add_validation(status)
+                status = self._compute_blocking(status)
+
+            statuses.append(status)
+
+        return statuses
+
+    def scan_single(self, spec_name: str) -> SpecStatus:
+        """Parse status for a single spec by name.
+
+        Args:
+            spec_name: Directory name of the spec (e.g., "032-status-dashboard")
+
+        Returns:
+            SpecStatus for the specified spec.
+
+        Raises:
+            SpecNotFoundError: If spec directory doesn't exist.
+        """
+        spec_dir = self.project_root / self.SPECS_DIR / spec_name
+        spec_file = spec_dir / "spec.md"
+
+        if not spec_dir.exists() or not spec_file.exists():
+            raise SpecNotFoundError(
+                f"Spec not found: {spec_name}. "
+                f"Expected spec.md at {spec_file}"
+            )
+
+        status = self._parse_spec(spec_name, spec_file)
+
+        if self.validate and self.validator:
+            status = self._add_validation(status)
+            status = self._compute_blocking(status)
+
+        return status
+
+    def _parse_spec(self, spec_name: str, spec_file: Path) -> SpecStatus:
+        """Parse a single spec.md file and extract metadata.
+
+        Args:
+            spec_name: Name of the spec (directory name)
+            spec_file: Path to the spec.md file
+
+        Returns:
+            SpecStatus with parsed metadata or error state
+        """
+        try:
+            content = spec_file.read_text(encoding="utf-8")
+            status = self._parse_status(content)
+            last_modified = datetime.fromtimestamp(spec_file.stat().st_mtime)
+
+            return SpecStatus(
+                name=spec_name,
+                path=spec_file,
+                status=status,
+                last_modified=last_modified,
+                validation_result=None,
+                is_blocking=False,
+                error=None,
+            )
+
+        except (OSError, UnicodeDecodeError) as e:
+            # File exists but couldn't be read
+            return SpecStatus(
+                name=spec_name,
+                path=spec_file,
+                status=SpecState.ERROR,
+                last_modified=datetime.now(),
+                validation_result=None,
+                is_blocking=False,
+                error=f"Unable to read file: {e}",
+            )
+
+    def _parse_status(self, content: str) -> SpecState:
+        """Extract status from spec.md content.
+
+        Looks for pattern: **Status**: <value>
+
+        Args:
+            content: Full content of spec.md file
+
+        Returns:
+            SpecState enum value, or ERROR if not found/parseable
+        """
+        match = self.STATUS_PATTERN.search(content)
+        if not match:
+            return SpecState.ERROR
+
+        status_text = match.group(1).strip()
+        return SpecState.from_string(status_text)
+
+    def _add_validation(self, spec_status: SpecStatus) -> SpecStatus:
+        """Add validation result to a SpecStatus.
+
+        Args:
+            spec_status: SpecStatus to add validation to.
+
+        Returns:
+            Updated SpecStatus with validation_result populated.
+        """
+        if self.validator is None or spec_status.error:
+            return spec_status
+
+        try:
+            result = self.validator.validate_file(spec_status.path)
+            return SpecStatus(
+                name=spec_status.name,
+                path=spec_status.path,
+                status=spec_status.status,
+                last_modified=spec_status.last_modified,
+                validation_result=result,
+                is_blocking=spec_status.is_blocking,
+                error=spec_status.error,
+            )
+        except Exception as e:
+            # Validation failed, mark as error
+            return SpecStatus(
+                name=spec_status.name,
+                path=spec_status.path,
+                status=spec_status.status,
+                last_modified=spec_status.last_modified,
+                validation_result=None,
+                is_blocking=spec_status.is_blocking,
+                error=f"Validation error: {e}",
+            )
+
+    def _compute_blocking(self, spec_status: SpecStatus) -> SpecStatus:
+        """Compute whether a spec is blocking commits.
+
+        A spec is blocking if:
+        1. Status is IN_PROGRESS and validation fails, OR
+        2. Status is DRAFT and validation fails AND spec is git-staged
+
+        Args:
+            spec_status: SpecStatus to check.
+
+        Returns:
+            Updated SpecStatus with is_blocking computed.
+        """
+        is_blocking = False
+
+        # Check if validation failed
+        validation_failed = (
+            spec_status.validation_result is not None
+            and spec_status.validation_result.error_count > 0
+        )
+
+        if validation_failed:
+            if spec_status.status == SpecState.IN_PROGRESS:
+                # In Progress specs always block when validation fails
+                is_blocking = True
+            elif spec_status.status == SpecState.DRAFT:
+                # Draft specs only block if they're staged
+                is_blocking = self._is_git_staged(spec_status.path)
+
+        return SpecStatus(
+            name=spec_status.name,
+            path=spec_status.path,
+            status=spec_status.status,
+            last_modified=spec_status.last_modified,
+            validation_result=spec_status.validation_result,
+            is_blocking=is_blocking,
+            error=spec_status.error,
+        )
+
+    def _is_git_staged(self, spec_path: Path) -> bool:
+        """Check if a spec file is staged for commit.
+
+        Args:
+            spec_path: Path to the spec file.
+
+        Returns:
+            True if the file is in git's staging area.
+        """
+        try:
+            result = subprocess.run(
+                ["git", "diff", "--cached", "--name-only"],
+                capture_output=True,
+                text=True,
+                cwd=self.project_root,
+            )
+            if result.returncode != 0:
+                return False
+
+            # Check if spec path (relative) is in staged files
+            try:
+                relative_path = spec_path.relative_to(self.project_root)
+                return str(relative_path) in result.stdout
+            except ValueError:
+                return False
+
+        except (FileNotFoundError, subprocess.SubprocessError):
+            # Git not available or command failed
+            return False
+
+    def generate_report(self, include_validation: bool = True) -> StatusReport:
+        """Scan all specs and generate a StatusReport.
+
+        Convenience method that combines scan() with report generation.
+
+        Args:
+            include_validation: Whether to include validation results.
+
+        Returns:
+            StatusReport containing all spec statuses and computed stats.
+        """
+        specs = self.scan(include_validation=include_validation)
+        return StatusReport(
+            specs=specs,
+            generated_at=datetime.now(),
+            project_root=self.project_root,
+        )