@pennyfarthing/core 11.3.2 → 11.3.4

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

@@ -0,0 +1,222 @@
+"""Sprint story update command.
+
+Story: MSSCI-14257 - Sprint story update command
+
+This module provides:
+- update_story(sprint_path, story_id, ...) -> dict
+- story_update_command (Click command for CLI registration)
+"""
+
+import subprocess
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import click
+
+from pf.sprint.loader import find_epic, find_story
+from pf.sprint.validator import VALID_STORY_STATUSES, validate_full_sprint
+from pf.sprint.yaml_io import read_sprint, write_sprint
+
+
+def update_story(
+    sprint_path: Path,
+    story_id: str,
+    *,
+    status: str | None = None,
+    points: int | None = None,
+    priority: str | None = None,
+    assigned_to: str | None = None,
+    completed_date: str | None = None,
+    started_date: str | None = None,
+    workflow: str | None = None,
+    description: str | None = None,
+    review_findings: str | None = None,
+    review_verdict: str | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Update fields on a story in the sprint YAML.
+
+    Args:
+        sprint_path: Path to sprint YAML file
+        story_id: Story ID (e.g., "76-4")
+        status: New status value
+        points: New points value
+        priority: New priority value
+        assigned_to: New assignee
+        completed_date: Completed date (ISO format)
+        started_date: Started date (ISO format)
+        workflow: Workflow type (tdd, trivial, bdd, agent-docs)
+        description: Story description text
+        review_findings: Reviewer findings text
+        review_verdict: Review verdict (approved, rejected, pending)
+        dry_run: If True, report changes without writing
+
+    Returns:
+        Dict with success status and optional error
+    """
+    # Validate status before reading file
+    if status is not None and status not in VALID_STORY_STATUSES:
+        return {
+            "success": False,
+            "error": f"Invalid status '{status}'. Must be one of: {', '.join(sorted(VALID_STORY_STATUSES))}",
+        }
+
+    # Parse story ID to find epic
+    parts = story_id.split("-")
+    if len(parts) < 2:
+        return {
+            "success": False,
+            "error": f"Invalid story ID format '{story_id}'. Expected format: <epic>-<seq> (e.g., '76-4')",
+        }
+
+    epic_num = parts[0]
+
+    data = read_sprint(sprint_path)
+
+    epic = find_epic(data, epic_num)
+    if epic is None:
+        return {
+            "success": False,
+            "error": f"Epic '{epic_num}' not found for story '{story_id}'",
+        }
+
+    story = find_story(epic, story_id)
+    if story is None:
+        return {
+            "success": False,
+            "error": f"Story '{story_id}' not found in epic '{epic_num}'",
+        }
+
+    # Apply field updates
+    if status is not None:
+        story["status"] = status
+    if points is not None:
+        story["points"] = points
+    if priority is not None:
+        story["priority"] = priority
+    if assigned_to is not None:
+        story["assigned_to"] = assigned_to
+    if completed_date is not None:
+        story["completed"] = completed_date
+    if started_date is not None:
+        story["started"] = started_date
+    if workflow is not None:
+        story["workflow"] = workflow
+    if description is not None:
+        story["description"] = description
+    if review_findings is not None:
+        story["review_findings"] = review_findings
+    if review_verdict is not None:
+        if review_verdict not in ("approved", "rejected", "pending"):
+            return {
+                "success": False,
+                "error": f"Invalid review_verdict '{review_verdict}'. Must be one of: approved, rejected, pending",
+            }
+        story["review_verdict"] = review_verdict
+
+    # Auto-cleanup rules
+    if status == "done":
+        # Auto-set completed if not explicitly provided
+        if completed_date is None and "completed" not in story:
+            story["completed"] = date.today().isoformat()
+        elif completed_date is not None:
+            story["completed"] = completed_date
+
+    if status == "in_progress":
+        # Auto-set started if not already present
+        if "started" not in story:
+            story["started"] = date.today().isoformat()
+        # Auto-set assignee from current Jira user if not already assigned
+        if "assigned_to" not in story and assigned_to is None:
+            try:
+                result = subprocess.run(
+                    ["jira", "me"], capture_output=True, text=True
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    story["assigned_to"] = result.stdout.strip()
+            except Exception:
+                pass
+
+    # Validate after mutation
+    result = validate_full_sprint(data)
+    if not result.valid:
+        return {
+            "success": False,
+            "error": f"Validation failed after update: {result.errors}",
+        }
+
+    if dry_run:
+        return {
+            "success": True,
+            "dry_run": True,
+            "story_id": story_id,
+        }
+
+    write_sprint(sprint_path, data)
+
+    return {
+        "success": True,
+        "story_id": story_id,
+    }
+
+
+@click.command("update")
+@click.argument("story_id")
+@click.option("--status", type=click.Choice(["backlog", "ready", "in_progress", "done", "canceled"]))
+@click.option("--completed", "completed_date", default=None)
+@click.option("--assigned-to", default=None)
+@click.option("--points", type=int, default=None)
+@click.option("--priority", default=None)
+@click.option("--started", "started_date", default=None)
+@click.option("--workflow", default=None)
+@click.option("--description", default=None, help="Story description text")
+@click.option("--review-findings", default=None, help="Reviewer findings text")
+@click.option("--review-verdict", type=click.Choice(["approved", "rejected", "pending"]), default=None)
+@click.option("--dry-run", is_flag=True)
+@click.option("--sprint-file", type=click.Path(), default=None, help="Path to sprint YAML file")
+def story_update_command(
+    story_id: str,
+    status: str | None,
+    completed_date: str | None,
+    assigned_to: str | None,
+    points: int | None,
+    priority: str | None,
+    started_date: str | None,
+    workflow: str | None,
+    description: str | None,
+    review_findings: str | None,
+    review_verdict: str | None,
+    dry_run: bool,
+    sprint_file: str | None,
+) -> None:
+    """Update a story's fields by ID."""
+    if sprint_file is None:
+        from pf.common.config import get_project_root
+        path = get_project_root() / "sprint" / "current-sprint.yaml"
+    else:
+        path = Path(sprint_file)
+
+    result = update_story(
+        sprint_path=path,
+        story_id=story_id,
+        status=status,
+        points=points,
+        priority=priority,
+        assigned_to=assigned_to,
+        completed_date=completed_date,
+        started_date=started_date,
+        workflow=workflow,
+        description=description,
+        review_findings=review_findings,
+        review_verdict=review_verdict,
+        dry_run=dry_run,
+    )
+
+    if result["success"]:
+        if result.get("dry_run"):
+            click.echo(f"[DRY-RUN] Would update story {result['story_id']}")
+        else:
+            click.echo(f"Updated story {result['story_id']}")
+    else:
+        raise click.ClickException(result["error"])

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

@@ -0,0 +1,307 @@
+"""Sprint validate command.
+
+Story: MSSCI-14255 - Sprint validate command with --fix flag
+
+This module provides:
+- validate_sprint_yaml(path, fix=False) -> ValidateResult
+- check_format_drift(path) -> list[FormatIssue]
+- validate_command (Click command for CLI registration)
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import click
+import yaml
+
+from pf.sprint.validator import (
+    REQUIRED_INITIATIVE_FIELDS,
+    VALID_INITIATIVE_STATUSES,
+    ValidationResult,
+    validate_epic,
+    validate_full_sprint,
+    validate_future,
+)
+from pf.sprint.yaml_io import (
+    EPIC_KEY_ORDER,
+    SPRINT_KEY_ORDER,
+    STORY_KEY_ORDER,
+    TOP_KEY_ORDER,
+    _canonicalize,
+    read_sprint,
+    write_sprint,
+)
+
+
+@dataclass
+class FormatIssue:
+    """A single format drift issue."""
+
+    message: str
+    path: str  # Field path (e.g., "sprint.status")
+    line: int | None = None
+
+
+@dataclass
+class ValidateError:
+    """A single validation error."""
+
+    message: str
+    path: str  # Field path (e.g., "epics[0].stories[1].status")
+    category: str = "schema"  # "syntax", "schema", or "format"
+    line: int | None = None
+
+
+@dataclass
+class ValidateResult:
+    """Result of sprint YAML validation."""
+
+    valid: bool
+    errors: list[ValidateError] = field(default_factory=list)
+    format_issues: list[FormatIssue] = field(default_factory=list)
+    fixed: bool = False
+
+
+def _check_key_order(
+    data: Mapping,
+    expected_order: list[str],
+    path_prefix: str,
+) -> list[FormatIssue]:
+    """Check if keys in a mapping follow the expected order."""
+    issues: list[FormatIssue] = []
+    actual_keys = [k for k in data.keys() if k in expected_order]
+    expected_filtered = [k for k in expected_order if k in actual_keys]
+
+    if actual_keys != expected_filtered:
+        issues.append(FormatIssue(
+            message=f"Key order drift: expected {expected_filtered}, got {actual_keys}",
+            path=path_prefix,
+        ))
+
+    return issues
+
+
+def _check_string_styles(data: Mapping, path_prefix: str) -> list[FormatIssue]:
+    """Check if multiline strings use block scalar style."""
+    issues: list[FormatIssue] = []
+
+    for key, value in data.items():
+        if isinstance(value, str) and "\n" in value:
+            # Check if it's using block scalar by examining the raw YAML
+            # If it got loaded as a plain string with \n, it wasn't block scalar
+            from ruamel.yaml.scalarstring import LiteralScalarString
+
+            if not isinstance(value, LiteralScalarString):
+                issues.append(FormatIssue(
+                    message=f"Wrong string style for '{key}': multiline text should use block scalar (|)",
+                    path=f"{path_prefix}.{key}",
+                ))
+
+    return issues
+
+
+def check_format_drift(path: Path) -> list[FormatIssue]:
+    """Check a sprint YAML file for format drift.
+
+    Detects:
+    - Key ordering that doesn't match sprint-template.yaml
+    - Wrong string styles (plain vs block scalar for multiline)
+
+    Args:
+        path: Path to sprint YAML file
+
+    Returns:
+        List of FormatIssue objects
+    """
+    try:
+        data = read_sprint(path)
+    except (FileNotFoundError, ValueError):
+        return []
+
+    issues: list[FormatIssue] = []
+
+    # Check top-level key order
+    issues.extend(_check_key_order(data, TOP_KEY_ORDER, ""))
+
+    # Check sprint section key order
+    if "sprint" in data and isinstance(data["sprint"], Mapping):
+        issues.extend(_check_key_order(data["sprint"], SPRINT_KEY_ORDER, "sprint"))
+
+    # Check epics
+    if "epics" in data and isinstance(data["epics"], list):
+        for i, epic in enumerate(data["epics"]):
+            if isinstance(epic, Mapping):
+                epic_path = f"epics[{i}]"
+                issues.extend(_check_key_order(epic, EPIC_KEY_ORDER, epic_path))
+                issues.extend(_check_string_styles(epic, epic_path))
+
+                # Check stories within epic
+                if "stories" in epic and isinstance(epic["stories"], list):
+                    for j, story in enumerate(epic["stories"]):
+                        if isinstance(story, Mapping):
+                            story_path = f"{epic_path}.stories[{j}]"
+                            issues.extend(
+                                _check_key_order(story, STORY_KEY_ORDER, story_path)
+                            )
+                            issues.extend(_check_string_styles(story, story_path))
+
+    return issues
+
+
+def _validate_initiative_shard(data: dict) -> ValidationResult:
+    """Validate a standalone initiative shard file (initiative-*.yaml)."""
+    result = ValidationResult(valid=True)
+    if not isinstance(data, dict):
+        result.add_error("Initiative shard must be a mapping", "")
+        return result
+    for field_name in REQUIRED_INITIATIVE_FIELDS:
+        if field_name not in data:
+            result.add_error(f"Missing required field: {field_name}", field_name)
+    if "status" in data:
+        status = data["status"]
+        if status and status not in VALID_INITIATIVE_STATUSES:
+            result.add_error(
+                f"Invalid initiative status '{status}'. Must be one of: {', '.join(sorted(VALID_INITIATIVE_STATUSES))}",
+                "status",
+            )
+    return result
+
+
+def validate_sprint_yaml(path: Path, fix: bool = False) -> ValidateResult:
+    """Validate a sprint YAML file for syntax, schema, and format issues.
+
+    Args:
+        path: Path to sprint YAML file
+        fix: If True, automatically repair format issues
+
+    Returns:
+        ValidateResult with errors and format issues
+    """
+    result = ValidateResult(valid=True)
+
+    # Check file exists
+    if not path.exists():
+        result.valid = False
+        result.errors.append(ValidateError(
+            message=f"File not found: {path}",
+            path=str(path),
+            category="syntax",
+        ))
+        return result
+
+    # Step 1: Try to parse YAML (catch syntax errors with line numbers)
+    try:
+        with open(path) as f:
+            raw_content = f.read()
+
+        if not raw_content.strip():
+            result.valid = False
+            result.errors.append(ValidateError(
+                message="Empty YAML file",
+                path=str(path),
+                category="syntax",
+                line=1,
+            ))
+            return result
+
+        data = yaml.safe_load(raw_content)
+    except yaml.YAMLError as e:
+        result.valid = False
+        line = None
+        if hasattr(e, "problem_mark") and e.problem_mark is not None:
+            line = e.problem_mark.line + 1  # 0-indexed to 1-indexed
+        result.errors.append(ValidateError(
+            message=f"YAML syntax error: {e}",
+            path=str(path),
+            category="syntax",
+            line=line,
+        ))
+        return result
+
+    if data is None:
+        result.valid = False
+        result.errors.append(ValidateError(
+            message="Empty YAML file",
+            path=str(path),
+            category="syntax",
+            line=1,
+        ))
+        return result
+
+    # Step 2: Schema validation — detect file type and use appropriate validator
+    #
+    # Shard files (epic-*.yaml, initiative-*.yaml) are standalone fragments
+    # that don't have the full sprint/future structure. Validate their
+    # internal structure only — the index files handle cross-references.
+    is_epic_shard = path.name.startswith("epic-") and path.name.endswith(".yaml")
+    is_initiative_shard = path.name.startswith("initiative-") and path.name.endswith(".yaml")
+    is_future = path.name == "future.yaml" or "future" in data
+
+    if is_epic_shard:
+        # Epic shard: validate as a single epic (has id, title, stories)
+        schema_result = validate_epic(data, set(), 0)
+    elif is_initiative_shard:
+        # Initiative shard: validate as a single initiative (has name, status)
+        schema_result = _validate_initiative_shard(data)
+    elif is_future:
+        schema_result = validate_future(data)
+    else:
+        schema_result = validate_full_sprint(data)
+    if not schema_result.valid:
+        result.valid = False
+    for err in schema_result.errors:
+        result.errors.append(ValidateError(
+            message=err.message,
+            path=err.path,
+            category="schema",
+        ))
+
+    # Step 3: Format drift detection (sprint files only — shards and future.yaml have different structure)
+    if not is_future and not is_epic_shard and not is_initiative_shard:
+        format_issues = check_format_drift(path)
+        result.format_issues = format_issues
+
+    # Step 4: Fix if requested (only format issues, not schema; sprint files only)
+    if fix and not is_future and not is_epic_shard and not is_initiative_shard and path.exists():
+        try:
+            canon_data = _canonicalize(read_sprint(path))
+            write_sprint(path, canon_data)
+            result.fixed = True
+        except (FileNotFoundError, ValueError):
+            pass
+
+    return result
+
+
+@click.command("validate")
+@click.argument("file", required=False, type=click.Path(exists=False))
+@click.option("--fix", is_flag=True, help="Automatically repair format issues")
+def validate_command(file: str | None, fix: bool) -> None:
+    """Validate sprint YAML for syntax, schema, and format issues."""
+    if file is None:
+        raise click.ClickException("No file specified")
+
+    path = Path(file)
+    result = validate_sprint_yaml(path, fix=fix)
+
+    if result.errors:
+        for err in result.errors:
+            severity = err.category.upper()
+            line_info = f" (line {err.line})" if err.line else ""
+            click.echo(f"[{severity}] {err.path}: {err.message}{line_info}")
+
+    if result.format_issues:
+        for issue in result.format_issues:
+            click.echo(f"[FORMAT] {issue.path}: {issue.message}")
+
+    if not result.valid:
+        error_count = len(result.errors)
+        click.echo(f"\nFound {error_count} error(s). Sprint YAML is invalid.")
+        raise SystemExit(1)
+
+    if result.format_issues and not fix:
+        click.echo(f"\nFound {len(result.format_issues)} format issue(s). Run with --fix to repair.")
+
+    if result.valid and not result.errors:
+        click.echo("Sprint YAML is valid.")