@pennyfarthing/core 7.8.1 → 7.8.4

package/pennyfarthing_scripts/sprint/validator.py

@@ -0,0 +1,405 @@
+"""
+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"}
+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"}
+
+
+# =============================================================================
+# 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}",
+            )
+
+    # 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_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
+    if "epics" in data:
+        all_story_ids: set[str] = set()
+        for idx, epic in enumerate(data["epics"]):
+            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_sprint_file(file_path: Path) -> ValidationResult:
+    """Validate a sprint YAML file from disk.
+
+    Loads the file and validates its contents.
+
+    Args:
+        file_path: Path to sprint YAML file
+
+    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
+
+    # Try to load YAML
+    try:
+        with open(file_path) as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        result.add_error(
+            f"Failed to parse YAML: {e}",
+            str(file_path),
+        )
+        return result
+
+    # Validate loaded data
+    return validate_full_sprint(data)
+
+
+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 pennyfarthing_scripts.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 pennyfarthing_scripts.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())

package/pennyfarthing_scripts/sprint/work.py

@@ -0,0 +1,192 @@
+"""
+Sprint work session management.
+
+Provides functions for starting and managing work on stories.
+"""
+
+from typing import Any
+
+from pennyfarthing_scripts.sprint.loader import (
+    find_epic,
+    find_story,
+    get_stories_by_status,
+    get_story_by_id,
+    load_sprint,
+)
+
+
+def check_story(story_id: str) -> dict[str, Any]:
+    """Check if a story is available for work.
+
+    Args:
+        story_id: Story ID or Jira key
+
+    Returns:
+        Dict with availability status and story details
+    """
+    story = get_story_by_id(story_id)
+
+    if not story:
+        return {
+            "available": False,
+            "error": f"Story '{story_id}' not found",
+        }
+
+    status = story.get("status", "backlog")
+    assigned = story.get("assigned_to")
+
+    # Check if already in progress
+    if status == "in_progress":
+        return {
+            "available": False,
+            "type": "story",
+            "story": story,
+            "reason": "Already in progress",
+            "assigned_to": assigned,
+        }
+
+    # Check if done
+    if status in ("done", "completed"):
+        return {
+            "available": False,
+            "type": "story",
+            "story": story,
+            "reason": "Already completed",
+        }
+
+    return {
+        "available": True,
+        "type": "story",
+        "story": story,
+        "title": story.get("title"),
+        "points": story.get("points"),
+        "workflow": story.get("workflow", "tdd"),
+    }
+
+
+def get_next_story() -> dict[str, Any]:
+    """Get the highest priority available story.
+
+    Returns:
+        Dict with next story details or error
+    """
+    backlog = get_stories_by_status("backlog")
+
+    if not backlog:
+        return {
+            "available": False,
+            "error": "No stories in backlog",
+        }
+
+    # Sort by priority (P0 > P1 > P2 > P3)
+    priority_order = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
+    sorted_stories = sorted(
+        backlog,
+        key=lambda s: priority_order.get(s.get("priority", "P2"), 2),
+    )
+
+    next_story = sorted_stories[0]
+    return {
+        "available": True,
+        "type": "next",
+        "story": next_story,
+        "title": next_story.get("title"),
+        "points": next_story.get("points"),
+        "priority": next_story.get("priority", "P2"),
+    }
+
+
+def start_work(story_id: str, *, dry_run: bool = False) -> dict[str, Any]:
+    """Start work on a story.
+
+    Args:
+        story_id: Story ID to start
+        dry_run: If True, don't make changes
+
+    Returns:
+        Dict with success status and details
+    """
+    # Check availability
+    check = check_story(story_id)
+    if not check.get("available"):
+        return {
+            "success": False,
+            "error": check.get("reason") or check.get("error"),
+        }
+
+    story = check.get("story")
+
+    if dry_run:
+        return {
+            "success": True,
+            "dry_run": True,
+            "story": story,
+            "message": f"Would start work on {story_id}",
+        }
+
+    # In a real implementation, this would:
+    # 1. Create/update session file
+    # 2. Claim in Jira
+    # 3. Create branch
+    # For now, return success with story info
+    return {
+        "success": True,
+        "story": story,
+        "message": f"Ready to start work on {story_id}",
+    }
+
+
+def main(args: list[str] | None = None) -> int:
+    """CLI entry point for sprint work.
+
+    Args:
+        args: Command line arguments
+
+    Returns:
+        Exit code
+    """
+    import argparse
+    import sys
+
+    parser = argparse.ArgumentParser(description="Start work on a story")
+    parser.add_argument(
+        "story_id",
+        nargs="?",
+        help="Story ID (or 'next' for highest priority)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done",
+    )
+
+    parsed = parser.parse_args(args)
+
+    if not parsed.story_id:
+        # Show backlog
+        backlog = get_stories_by_status("backlog")
+        print(f"Available stories: {len(backlog)}")
+        for story in backlog[:10]:
+            print(f"  {story.get('id')}: {story.get('title')} [{story.get('points', '?')}pts]")
+        return 0
+
+    if parsed.story_id == "next":
+        result = get_next_story()
+    else:
+        result = check_story(parsed.story_id)
+
+    if result.get("available"):
+        story = result.get("story", {})
+        print(f"Story: {story.get('id')}")
+        print(f"Title: {story.get('title')}")
+        print(f"Points: {story.get('points')}")
+        print(f"Status: Available")
+        return 0
+    else:
+        print(f"Not available: {result.get('error') or result.get('reason')}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())

package/pennyfarthing_scripts/story/__init__.py

@@ -0,0 +1,67 @@
+"""
+Story management package for Pennyfarthing scripts.
+
+This package provides:
+- size: Story sizing guidelines
+- template: Story templates
+- create: Story creation
+
+Usage:
+    # Use the modules
+    from pennyfarthing_scripts.story import get_sizing_guidelines, get_template
+
+    # Use CLI
+    python -m pennyfarthing_scripts.story <subcommand> [args]
+"""
+
+# Re-export common functions
+from pennyfarthing_scripts.story.size import (
+    SIZING_GUIDELINES,
+    format_size_info,
+    get_sizing_guidelines,
+)
+from pennyfarthing_scripts.story.template import (
+    TEMPLATES,
+    format_template,
+    get_all_templates,
+    get_template,
+)
+from pennyfarthing_scripts.story.create import (
+    create_story,
+    generate_story_yaml,
+    validate_points,
+)
+
+# Import submodules
+from pennyfarthing_scripts.story import (
+    create,
+    size,
+    template,
+)
+
+# CLI entry point - import module, not function, so "from story import cli" gets the module
+from pennyfarthing_scripts.story import cli
+from pennyfarthing_scripts.story.cli import main
+
+__all__ = [
+    # Size
+    "SIZING_GUIDELINES",
+    "format_size_info",
+    "get_sizing_guidelines",
+    # Template
+    "TEMPLATES",
+    "format_template",
+    "get_all_templates",
+    "get_template",
+    # Create
+    "create_story",
+    "generate_story_yaml",
+    "validate_points",
+    # Submodules
+    "create",
+    "size",
+    "template",
+    # CLI
+    "cli",
+    "main",
+]

package/pennyfarthing_scripts/story/__main__.py

@@ -0,0 +1,10 @@
+"""
+Entry point for python -m pennyfarthing_scripts.story
+"""
+
+import sys
+
+from pennyfarthing_scripts.story.cli import cli
+
+if __name__ == "__main__":
+    sys.exit(cli())