@pennyfarthing/core 11.3.3 → 11.3.4

package/pennyfarthing-dist/pf/sprint/validator.py

@@ -0,0 +1,694 @@
+"""
+Sprint and Story YAML validators for Pennyfarthing.
+
+Story: MSSCI-12394 - Sprint and Story YAML validators
+
+This module provides validation for:
+- Sprint-level structure and required fields
+- Story-level required fields and values
+- Epic-level validation with story references
+- Archived sprint validation
+
+All functions raise NO errors - they return ValidationResult objects
+with success status and error messages.
+"""
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class ValidationSeverity(Enum):
+    """Severity level for validation errors."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass
+class ValidationError:
+    """A single validation error."""
+
+    message: str
+    path: str  # JSON path to the error location (e.g., "epics[0].stories[1].status")
+    severity: ValidationSeverity = ValidationSeverity.ERROR
+
+
+@dataclass
+class ValidationResult:
+    """Result of validation with errors and warnings."""
+
+    valid: bool
+    errors: list[ValidationError] = field(default_factory=list)
+
+    def add_error(
+        self, message: str, path: str, severity: ValidationSeverity = ValidationSeverity.ERROR
+    ) -> None:
+        """Add an error to the result."""
+        self.errors.append(ValidationError(message, path, severity))
+        if severity == ValidationSeverity.ERROR:
+            self.valid = False
+
+    def merge(self, other: "ValidationResult") -> None:
+        """Merge another result into this one."""
+        self.errors.extend(other.errors)
+        if not other.valid:
+            self.valid = False
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+VALID_SPRINT_STATUSES = {"active", "closed"}
+VALID_STORY_STATUSES = {"backlog", "ready", "in_progress", "done", "canceled", "planning"}
+JIRA_KEY_PATTERN = re.compile(r"^MSSCI-\d{5}$")
+ISO_DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+# Required fields for sprint section
+REQUIRED_SPRINT_FIELDS = {"number", "jira_sprint_id", "goal", "start_date", "end_date", "status"}
+
+# Required fields for story
+REQUIRED_STORY_FIELDS = {"id", "title", "status", "points"}
+
+# Required fields for epic
+REQUIRED_EPIC_FIELDS = {"id", "title"}
+
+# Required fields for epic shard files (write-time validation, ADR-0022)
+REQUIRED_EPIC_SHARD_FIELDS = {"id", "title", "status", "stories"}
+REQUIRED_SHARD_STORY_FIELDS = {"id", "title", "points", "status"}
+
+# Required fields for future.yaml initiative
+REQUIRED_INITIATIVE_FIELDS = {"name", "status"}
+
+# Required fields for future.yaml epic (what promote-epic.sh needs)
+REQUIRED_FUTURE_EPIC_FIELDS = {"id", "title", "points"}
+
+# Required fields for future.yaml story (what promote-epic.sh transforms)
+REQUIRED_FUTURE_STORY_FIELDS = {"id", "title", "points"}
+
+VALID_INITIATIVE_STATUSES = {"ready", "planning", "blocked", "research_complete", "backlog", "complete", "canceled"}
+
+
+# =============================================================================
+# Validation Functions
+# =============================================================================
+
+
+def validate_sprint(data: dict[str, Any]) -> ValidationResult:
+    """Validate sprint-level structure and fields.
+
+    Validates:
+    - Required fields present (number, jira_sprint_id, goal, start_date, end_date, status)
+    - status is valid value (active, closed)
+    - dates are ISO format
+
+    Args:
+        data: Sprint YAML data (full document)
+
+    Returns:
+        ValidationResult with any errors found
+    """
+    result = ValidationResult(valid=True)
+
+    # Check for sprint section
+    if "sprint" not in data:
+        result.add_error("Missing required 'sprint' section", "sprint")
+        return result
+
+    sprint = data["sprint"]
+
+    # Check required fields
+    for field_name in REQUIRED_SPRINT_FIELDS:
+        if field_name not in sprint:
+            result.add_error(
+                f"Missing required field: {field_name}",
+                f"sprint.{field_name}",
+            )
+
+    # Validate status if present
+    if "status" in sprint:
+        status = sprint["status"]
+        if status not in VALID_SPRINT_STATUSES:
+            result.add_error(
+                f"Invalid status '{status}'. Must be one of: {', '.join(sorted(VALID_SPRINT_STATUSES))}",
+                "sprint.status",
+            )
+
+    # Validate date formats
+    for date_field in ["start_date", "end_date"]:
+        if date_field in sprint:
+            date_val = str(sprint[date_field])
+            if not ISO_DATE_PATTERN.match(date_val):
+                result.add_error(
+                    f"Invalid date format for {date_field}: '{date_val}'. Expected YYYY-MM-DD",
+                    f"sprint.{date_field}",
+                )
+
+    return result
+
+
+def validate_story(story: dict[str, Any], epic_id: str, story_index: int = 0) -> ValidationResult:
+    """Validate a single story's structure and fields.
+
+    Validates:
+    - Required fields present (id, title, status, points)
+    - status is valid value (backlog, ready, in_progress, done, canceled)
+    - points is numeric
+    - jira key follows pattern MSSCI-NNNNN if present
+    - branch follows convention if present
+
+    Args:
+        story: Story dict from YAML
+        epic_id: Parent epic ID for path generation
+        story_index: Index of story in epic's stories array
+
+    Returns:
+        ValidationResult with any errors found
+    """
+    result = ValidationResult(valid=True)
+    base_path = f"{epic_id}.stories[{story_index}]"
+
+    # Check required fields
+    for field_name in REQUIRED_STORY_FIELDS:
+        if field_name not in story:
+            result.add_error(
+                f"Missing required field: {field_name}",
+                f"{base_path}.{field_name}",
+            )
+
+    # Validate status if present
+    if "status" in story:
+        status = story["status"]
+        if status not in VALID_STORY_STATUSES:
+            result.add_error(
+                f"Invalid status '{status}'. Must be one of: {', '.join(sorted(VALID_STORY_STATUSES))}",
+                f"{base_path}.status",
+            )
+
+    # Validate points is numeric
+    if "points" in story:
+        points = story["points"]
+        if not isinstance(points, (int, float)):
+            result.add_error(
+                f"Invalid points value '{points}'. Must be numeric",
+                f"{base_path}.points",
+            )
+
+    # Validate jira key format if present
+    if "jira" in story:
+        jira_key = str(story["jira"])
+        if not JIRA_KEY_PATTERN.match(jira_key):
+            result.add_error(
+                f"Invalid Jira key format '{jira_key}'. Expected MSSCI-NNNNN",
+                f"{base_path}.jira",
+            )
+
+    return result
+
+
+def validate_epic(epic: dict[str, Any], all_story_ids: set[str], epic_index: int = 0) -> ValidationResult:
+    """Validate an epic's structure and story references.
+
+    Validates:
+    - Required fields present (id, title)
+    - All story IDs are unique within epic
+    - No orphaned story references (if stories present)
+
+    Args:
+        epic: Epic dict from YAML
+        all_story_ids: Set of all story IDs in the sprint (for uniqueness check)
+        epic_index: Index of epic for path generation
+
+    Returns:
+        ValidationResult with any errors found
+    """
+    result = ValidationResult(valid=True)
+    base_path = f"epics[{epic_index}]"
+    epic_id = epic.get("id", f"epics[{epic_index}]")
+
+    # Check required fields
+    for field_name in REQUIRED_EPIC_FIELDS:
+        if field_name not in epic:
+            result.add_error(
+                f"Missing required field: {field_name}",
+                f"{base_path}.{field_name}",
+            )
+
+    # Reject non-string IDs (YAML parses bare integers like `id: 87` as int,
+    # which crashes Cyclist's sprint-data.ts — epicId.match() fails on non-strings)
+    if "id" in epic and not isinstance(epic["id"], str):
+        result.add_error(
+            f"Epic ID must be a string, got {type(epic['id']).__name__} ({epic['id']!r}). "
+            "Quote it in YAML (e.g., id: \"87\" not id: 87)",
+            f"{base_path}.id",
+        )
+
+    # Validate stories if present
+    if "stories" in epic:
+        seen_in_epic: set[str] = set()
+        for idx, story in enumerate(epic["stories"]):
+            story_id = story.get("id")
+            if story_id:
+                # Check for duplicates within this epic
+                if story_id in seen_in_epic:
+                    result.add_error(
+                        f"Duplicate story ID '{story_id}' within epic",
+                        f"{base_path}.stories[{idx}].id",
+                    )
+                # Check for duplicates across epics
+                elif story_id in all_story_ids:
+                    result.add_error(
+                        f"Duplicate story ID '{story_id}' - already exists in another epic",
+                        f"{base_path}.stories[{idx}].id",
+                    )
+                seen_in_epic.add(story_id)
+
+            # Validate story structure
+            story_result = validate_story(story, epic_id, idx)
+            result.merge(story_result)
+
+    return result
+
+
+def validate_epic_shard(epic: dict[str, Any]) -> ValidationResult:
+    """Validate an epic shard dict before writing to disk.
+
+    Enforces stricter requirements than validate_epic() since shards
+    are standalone files that must be self-contained.
+
+    Validates:
+    - Required fields present (id, title, status, stories)
+    - stories is a list
+    - Each story has required fields (id, title, points, status)
+    - No duplicate story IDs within the epic
+    - jira key follows MSSCI-NNNNN pattern if present
+
+    Args:
+        epic: Epic shard dict to validate
+
+    Returns:
+        ValidationResult with any errors found
+    """
+    result = ValidationResult(valid=True)
+
+    # Check required shard fields
+    for field_name in REQUIRED_EPIC_SHARD_FIELDS:
+        if field_name not in epic:
+            result.add_error(
+                f"Missing required field: {field_name}",
+                f"epic.{field_name}",
+            )
+
+    # Reject non-string IDs (YAML parses bare integers like `id: 87` as int,
+    # which crashes Cyclist's sprint-data.ts checkEpicContext — epicId.match() fails)
+    if "id" in epic and not isinstance(epic["id"], str):
+        result.add_error(
+            f"Epic ID must be a string, got {type(epic['id']).__name__} ({epic['id']!r}). "
+            "Quote it in YAML (e.g., id: \"87\" not id: 87)",
+            "epic.id",
+        )
+
+    # Reject epic- prefix in ID (ADR-0022: reference prefix should not be baked into value)
+    if "id" in epic:
+        epic_id_val = str(epic["id"])
+        if epic_id_val.startswith("epic-"):
+            result.add_error(
+                f"Epic ID '{epic_id_val}' starts with 'epic-' prefix. "
+                "Use the numeric ID (e.g., '94' not 'epic-94')",
+                "epic.id",
+            )
+
+    # Validate jira key format if present
+    if "jira" in epic:
+        jira_key = str(epic["jira"])
+        if not JIRA_KEY_PATTERN.match(jira_key):
+            result.add_error(
+                f"Invalid Jira key format '{jira_key}'. Expected MSSCI-NNNNN",
+                "epic.jira",
+            )
+
+    # Validate stories field
+    if "stories" in epic:
+        stories = epic["stories"]
+        if not isinstance(stories, list):
+            result.add_error(
+                "'stories' must be a list",
+                "epic.stories",
+            )
+        else:
+            seen_ids: set[str] = set()
+            epic_id = epic.get("id", "epic")
+            for idx, story in enumerate(stories):
+                story_id = story.get("id")
+                if story_id:
+                    if story_id in seen_ids:
+                        result.add_error(
+                            f"Duplicate story ID '{story_id}' within epic",
+                            f"epic.stories[{idx}].id",
+                        )
+                    seen_ids.add(story_id)
+
+                # Check required story fields
+                for field_name in REQUIRED_SHARD_STORY_FIELDS:
+                    if field_name not in story:
+                        result.add_error(
+                            f"Missing required field: {field_name}",
+                            f"{epic_id}.stories[{idx}].{field_name}",
+                        )
+
+    return result
+
+
+def validate_full_sprint(data: dict[str, Any]) -> ValidationResult:
+    """Validate complete sprint YAML including all epics and stories.
+
+    Validates:
+    - Sprint-level structure
+    - All epics and their stories
+    - Cross-cutting constraints (no duplicate story IDs)
+
+    Args:
+        data: Full sprint YAML data
+
+    Returns:
+        Combined ValidationResult with all errors
+    """
+    result = ValidationResult(valid=True)
+
+    # Validate sprint section
+    sprint_result = validate_sprint(data)
+    result.merge(sprint_result)
+
+    # Validate epics (skip if sharded — epics are string refs to shard files)
+    if "epics" in data:
+        all_story_ids: set[str] = set()
+        for idx, epic in enumerate(data["epics"]):
+            # Sharded format: epics are string refs, not dicts
+            if isinstance(epic, str):
+                continue
+            epic_result = validate_epic(epic, all_story_ids, idx)
+            result.merge(epic_result)
+
+            # Collect story IDs for cross-epic duplicate detection
+            if "stories" in epic:
+                for story in epic["stories"]:
+                    story_id = story.get("id")
+                    if story_id:
+                        all_story_ids.add(story_id)
+
+    return result
+
+
+def validate_archived_sprint(data: dict[str, Any]) -> ValidationResult:
+    """Validate an archived sprint file.
+
+    Archived sprints have the same structure as current sprints
+    but allow done/canceled status for all stories.
+
+    Args:
+        data: Archived sprint YAML data
+
+    Returns:
+        ValidationResult with any errors found
+    """
+    # For archived sprints, use the same validation as full sprint
+    # The key difference is that all story statuses are valid
+    # (done/canceled are expected in archived sprints)
+    return validate_full_sprint(data)
+
+
+def validate_future(data: dict[str, Any]) -> ValidationResult:
+    """Validate future.yaml structure.
+
+    Validates the structure that promote-epic.sh and list-future.sh depend on:
+    - future.initiatives[] array exists
+    - Each initiative has name, status
+    - Each epic has id, title, points (required by promote-epic.sh)
+    - Each story has id, title, points (required by promote-epic.sh)
+
+    Args:
+        data: Future YAML data (full document)
+
+    Returns:
+        ValidationResult with any errors found
+    """
+    result = ValidationResult(valid=True)
+
+    if "future" not in data:
+        result.add_error("Missing required 'future' section", "future")
+        return result
+
+    future = data["future"]
+    if "initiatives" not in future:
+        result.add_error("Missing required 'initiatives' array", "future.initiatives")
+        return result
+
+    initiatives = future["initiatives"]
+    if not isinstance(initiatives, list):
+        result.add_error("'initiatives' must be an array", "future.initiatives")
+        return result
+
+    for i, initiative in enumerate(initiatives):
+        # Sharded format: initiatives are string slugs, not dicts
+        if isinstance(initiative, str):
+            continue
+        if not isinstance(initiative, dict):
+            result.add_error("Initiative must be a mapping", f"future.initiatives[{i}]")
+            continue
+
+        base_path = f"future.initiatives[{i}]"
+
+        # Check required initiative fields
+        for field_name in REQUIRED_INITIATIVE_FIELDS:
+            if field_name not in initiative:
+                result.add_error(
+                    f"Missing required field: {field_name}",
+                    f"{base_path}.{field_name}",
+                )
+
+        # Validate initiative status
+        if "status" in initiative:
+            status = initiative["status"]
+            if status not in VALID_INITIATIVE_STATUSES:
+                result.add_error(
+                    f"Invalid initiative status '{status}'. Must be one of: {', '.join(sorted(VALID_INITIATIVE_STATUSES))}",
+                    f"{base_path}.status",
+                )
+
+        # Validate epics if present
+        if "epics" in initiative and isinstance(initiative["epics"], list):
+            seen_epic_ids: set[str] = set()
+            for j, epic in enumerate(initiative["epics"]):
+                if not isinstance(epic, dict):
+                    continue
+                epic_path = f"{base_path}.epics[{j}]"
+
+                for field_name in REQUIRED_FUTURE_EPIC_FIELDS:
+                    if field_name not in epic:
+                        result.add_error(
+                            f"Missing required field: {field_name}",
+                            f"{epic_path}.{field_name}",
+                        )
+
+                # Check duplicate epic IDs
+                epic_id = epic.get("id")
+                if epic_id:
+                    if epic_id in seen_epic_ids:
+                        result.add_error(
+                            f"Duplicate epic ID '{epic_id}'",
+                            f"{epic_path}.id",
+                        )
+                    seen_epic_ids.add(epic_id)
+
+                # Validate points is numeric
+                if "points" in epic and not isinstance(epic["points"], (int, float)):
+                    result.add_error(
+                        f"Invalid points value '{epic['points']}'. Must be numeric",
+                        f"{epic_path}.points",
+                    )
+
+                # Validate stories if present
+                if "stories" in epic and isinstance(epic["stories"], list):
+                    for k, story in enumerate(epic["stories"]):
+                        if not isinstance(story, dict):
+                            continue
+                        story_path = f"{epic_path}.stories[{k}]"
+
+                        for field_name in REQUIRED_FUTURE_STORY_FIELDS:
+                            if field_name not in story:
+                                result.add_error(
+                                    f"Missing required field: {field_name}",
+                                    f"{story_path}.{field_name}",
+                                )
+
+                        if "points" in story and not isinstance(story["points"], (int, float)):
+                            result.add_error(
+                                f"Invalid points value '{story['points']}'. Must be numeric",
+                                f"{story_path}.points",
+                            )
+
+    return result
+
+
+def validate_sprint_file(file_path: Path, *, strict: bool = False) -> ValidationResult:
+    """Validate a sprint YAML file from disk.
+
+    Loads the file and validates its contents. In strict mode, loader
+    warnings (e.g., unresolvable shard refs) are promoted to errors.
+
+    Args:
+        file_path: Path to sprint YAML file
+        strict: If True, treat loader warnings as validation errors
+
+    Returns:
+        ValidationResult with any errors (including load errors)
+    """
+    result = ValidationResult(valid=True)
+
+    # Check file exists
+    if not file_path.exists():
+        result.add_error(
+            f"File not found: {file_path}",
+            str(file_path),
+        )
+        return result
+
+    # Read raw content for cross-parser compatibility check
+    raw_content = file_path.read_text()
+
+    # Detect single-quoted YAML values spanning blank lines. These parse in
+    # Python's yaml but fail in Node's yaml library (used by Cyclist's panel).
+    # Walk lines tracking whether we're inside a single-quoted value.
+    in_sq = False
+    sq_start_line = 0
+    has_blank = False
+    for line_num, line in enumerate(raw_content.splitlines(), 1):
+        if not in_sq:
+            # Look for a value starting with single quote: "key: 'text..."
+            # Must be a YAML value position (after colon+space), not inside
+            # block scalars (|, >) or comments.
+            stripped = line.lstrip()
+            if stripped.startswith("#"):
+                continue
+            colon_match = re.search(r":\s+'", line)
+            if colon_match:
+                after = line[colon_match.end() - 1:]  # from the opening quote
+                # Count unescaped quotes ('' is escape for ' in YAML)
+                clean = after.replace("''", "")
+                if clean.count("'") == 1:
+                    # Opening quote without closing — multiline single-quoted string
+                    in_sq = True
+                    sq_start_line = line_num
+                    has_blank = False
+        else:
+            if line.strip() == "":
+                has_blank = True
+            # Check if this line closes the single-quoted string
+            clean = line.replace("''", "")
+            if "'" in clean:
+                if has_blank:
+                    result.add_error(
+                        "Single-quoted string contains blank lines (breaks Cyclist panel parser). "
+                        "Use block scalar (|) or flow-style double-quoted string instead.",
+                        f"{file_path}:{sq_start_line}",
+                    )
+                in_sq = False
+                has_blank = False
+
+    if result.errors:
+        return result
+
+    # Try to load YAML
+    try:
+        data = yaml.safe_load(raw_content)
+    except yaml.YAMLError as e:
+        result.add_error(
+            f"Failed to parse YAML: {e}",
+            str(file_path),
+        )
+        return result
+
+    # Merge sharded epic files if present, capturing warnings in strict mode
+    from pf.sprint.loader import _merge_epic_shards
+    if strict:
+        import warnings as _warnings
+        with _warnings.catch_warnings(record=True) as caught:
+            _warnings.simplefilter("always")
+            data = _merge_epic_shards(data, file_path.parent)
+        for w in caught:
+            result.add_error(str(w.message), str(file_path))
+    else:
+        data = _merge_epic_shards(data, file_path.parent)
+
+    # Validate loaded data
+    full_result = validate_full_sprint(data)
+    result.merge(full_result)
+    return result
+
+
+def format_validation_errors(result: ValidationResult) -> str:
+    """Format validation errors for human-readable output.
+
+    Args:
+        result: ValidationResult to format
+
+    Returns:
+        Multi-line string with formatted errors
+    """
+    if not result.errors:
+        return "No validation errors"
+
+    lines = []
+    for error in result.errors:
+        severity_label = error.severity.value.upper()
+        lines.append(f"[{severity_label}] {error.path}: {error.message}")
+
+    return "\n".join(lines)
+
+
+# =============================================================================
+# CLI Entry Point
+# =============================================================================
+
+
+def main() -> int:
+    """CLI entry point for sprint validation.
+
+    Usage:
+        python -m pf.sprint.validator [file_path]
+
+    If no file_path is provided, validates sprint/current-sprint.yaml.
+
+    Returns:
+        0 if valid, 1 if invalid
+    """
+    import sys
+
+    from pf.common.config import get_project_root
+
+    # Determine file to validate
+    if len(sys.argv) > 1:
+        file_path = Path(sys.argv[1])
+    else:
+        file_path = get_project_root() / "sprint" / "current-sprint.yaml"
+
+    print(f"Validating: {file_path}")
+    result = validate_sprint_file(file_path)
+
+    if result.valid:
+        print("✓ Sprint YAML is valid")
+        return 0
+    else:
+        print(f"✗ Found {len(result.errors)} validation error(s):\n")
+        print(format_validation_errors(result))
+        return 1
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())