@pennyfarthing/core 11.4.0 → 12.0.0

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

@@ -0,0 +1,240 @@
+"""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,
+    add_ac: list[str] | None = None,
+    clear_ac: bool = False,
+    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)
+        add_ac: Acceptance criteria to append
+        clear_ac: If True, clear existing ACs before adding
+        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
+    if clear_ac:
+        story["acceptance_criteria"] = []
+    if add_ac:
+        existing = story.get("acceptance_criteria", [])
+        if not isinstance(existing, list):
+            existing = []
+        existing.extend(add_ac)
+        story["acceptance_criteria"] = existing
+
+    # 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("--add-ac", multiple=True, help="Acceptance criterion to append (repeatable)")
+@click.option("--clear-ac", is_flag=True, help="Clear all acceptance criteria (use with --add-ac to replace)")
+@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,
+    add_ac: tuple[str, ...],
+    clear_ac: bool,
+    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,
+        add_ac=list(add_ac) if add_ac else None,
+        clear_ac=clear_ac,
+        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/src/pf/sprint/yaml_io.py

@@ -0,0 +1,407 @@
+"""
+Deterministic YAML I/O for sprint data.
+
+Story: MSSCI-14254 - Core yaml_io module with deterministic serialization
+
+Provides:
+- read_sprint(path) -> CommentedMap (preserves ordering/comments, merges shards)
+- write_sprint(path, data) -> atomic write (shard-aware)
+- canonical_dump(data) -> deterministic YAML string
+"""
+
+import io
+import os
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+from ruamel.yaml.scalarstring import LiteralScalarString
+
+JIRA_PATTERN = re.compile(r"^MSSCI-\d{5}$")
+
+
+# Canonical key ordering derived from sprint-template.yaml
+SPRINT_KEY_ORDER: list[str] = [
+    "name", "jira_sprint_id", "jira_sprint_name", "goal",
+    "start_date", "end_date", "status",
+]
+
+EPIC_KEY_ORDER: list[str] = [
+    "id", "type", "title", "description", "priority", "status",
+    "repos", "jira", "points", "marker", "stories",
+]
+
+STORY_KEY_ORDER: list[str] = [
+    "id", "jira", "title", "description", "points", "priority",
+    "refs", "status", "in_sprint", "assigned_to", "started", "repos",
+    "workflow", "acceptance_criteria", "completed", "pr",
+    "delivered_in", "notes",
+]
+
+# Top-level key ordering
+TOP_KEY_ORDER: list[str] = ["sprint", "epics", "stories"]
+
+
+def _make_yaml() -> YAML:
+    """Create a configured ruamel.yaml instance."""
+    yml = YAML()
+    yml.preserve_quotes = True
+    yml.default_flow_style = False
+    yml.indent(mapping=2, sequence=4, offset=2)
+    yml.width = 4096  # Prevent line wrapping
+    return yml
+
+
+def _read_yaml_file(path: Path) -> CommentedMap:
+    """Read a single YAML file preserving ordering and comments.
+
+    Args:
+        path: Path to YAML file
+
+    Returns:
+        CommentedMap with preserved ordering and comments
+
+    Raises:
+        FileNotFoundError: If path doesn't exist
+        ValueError: If YAML is malformed or empty
+    """
+    if not path.exists():
+        raise FileNotFoundError(f"Sprint YAML file not found: {path}")
+
+    yml = _make_yaml()
+    try:
+        with open(path) as f:
+            data = yml.load(f)
+    except Exception as e:
+        raise ValueError(f"Failed to parse YAML: {e}") from e
+
+    if data is None:
+        raise ValueError(f"Empty YAML file: {path}")
+
+    return data
+
+
+def read_sprint(path: Path) -> CommentedMap:
+    """Read sprint YAML file, merging sharded epic files.
+
+    When the epics list contains string references (sharded format),
+    loads each epic-{ref}.yaml shard file and replaces the strings
+    with full epic CommentedMaps.
+
+    Also discovers unindexed shard files on disk (epic-*.yaml files not
+    referenced in the epics list) and appends them so orphan shards are
+    never invisible to the CLI.
+
+    Args:
+        path: Path to sprint YAML index file
+
+    Returns:
+        CommentedMap with full epic data merged in
+
+    Raises:
+        FileNotFoundError: If path doesn't exist
+        ValueError: If YAML is malformed or empty
+    """
+    data = _read_yaml_file(path)
+
+    from pf.sprint.shard_merge import merge_epic_shards
+
+    return merge_epic_shards(
+        data,
+        path.parent,
+        load_file=_read_yaml_file,
+        make_list=CommentedSeq,
+    )
+
+
+def _sort_mapping(data: CommentedMap, key_order: list[str]) -> CommentedMap:
+    """Reorder keys in a CommentedMap according to key_order.
+
+    Known keys appear in template order, unknown keys are appended at the end.
+    """
+    result = CommentedMap()
+    # First, add known keys in order
+    for key in key_order:
+        if key in data:
+            result[key] = data[key]
+    # Then add any unknown keys at the end
+    for key in data:
+        if key not in key_order:
+            result[key] = data[key]
+    return result
+
+
+def _ensure_block_scalars(data: Any) -> Any:
+    """Convert multiline strings to block scalar style recursively."""
+    if isinstance(data, CommentedMap):
+        result = CommentedMap()
+        for key, value in data.items():
+            result[key] = _ensure_block_scalars(value)
+        return result
+    elif isinstance(data, (list, CommentedSeq)):
+        result_list = CommentedSeq()
+        for item in data:
+            result_list.append(_ensure_block_scalars(item))
+        return result_list
+    elif isinstance(data, str) and "\n" in data:
+        return LiteralScalarString(data)
+    return data
+
+
+def _canonicalize(data: Any) -> Any:
+    """Apply canonical ordering and formatting to sprint data recursively."""
+    if not isinstance(data, Mapping):
+        return data
+
+    cm = data if isinstance(data, CommentedMap) else _to_commented_map(data)
+
+    # Detect epic shard: has 'stories' + 'id' but no 'sprint'/'epics' top-level keys
+    is_epic_shard = "stories" in cm and "id" in cm and "sprint" not in cm and "epics" not in cm
+
+    if is_epic_shard:
+        result = _sort_mapping(cm, EPIC_KEY_ORDER)
+        # Reorder stories within the epic
+        if "stories" in result and isinstance(result["stories"], (list, CommentedSeq)):
+            new_stories = CommentedSeq()
+            for story in result["stories"]:
+                if isinstance(story, Mapping):
+                    story_cm = (
+                        story if isinstance(story, CommentedMap) else _to_commented_map(story)
+                    )
+                    new_stories.append(_sort_mapping(story_cm, STORY_KEY_ORDER))
+                else:
+                    new_stories.append(story)
+            result["stories"] = new_stories
+        result = _ensure_block_scalars(result)
+        return result
+
+    # Full sprint document: sort top-level keys
+    result = _sort_mapping(cm, TOP_KEY_ORDER)
+
+    # Reorder sprint section
+    if "sprint" in result and isinstance(result["sprint"], Mapping):
+        sprint_cm = (
+            result["sprint"]
+            if isinstance(result["sprint"], CommentedMap)
+            else _to_commented_map(result["sprint"])
+        )
+        result["sprint"] = _sort_mapping(sprint_cm, SPRINT_KEY_ORDER)
+
+    # Reorder epics and their stories
+    if "epics" in result and isinstance(result["epics"], (list, CommentedSeq)):
+        new_epics = CommentedSeq()
+        for epic in result["epics"]:
+            if isinstance(epic, Mapping):
+                epic_cm = (
+                    epic if isinstance(epic, CommentedMap) else _to_commented_map(epic)
+                )
+                sorted_epic = _sort_mapping(epic_cm, EPIC_KEY_ORDER)
+
+                # Reorder stories within epic
+                if "stories" in sorted_epic and isinstance(
+                    sorted_epic["stories"], (list, CommentedSeq)
+                ):
+                    new_stories = CommentedSeq()
+                    for story in sorted_epic["stories"]:
+                        if isinstance(story, Mapping):
+                            story_cm = (
+                                story
+                                if isinstance(story, CommentedMap)
+                                else _to_commented_map(story)
+                            )
+                            new_stories.append(
+                                _sort_mapping(story_cm, STORY_KEY_ORDER)
+                            )
+                        else:
+                            new_stories.append(story)
+                    sorted_epic["stories"] = new_stories
+
+                new_epics.append(sorted_epic)
+            else:
+                new_epics.append(epic)
+        result["epics"] = new_epics
+
+    # Apply block scalars to multiline strings
+    result = _ensure_block_scalars(result)
+
+    return result
+
+
+def _to_commented_map(data: Mapping) -> CommentedMap:
+    """Convert a plain dict to CommentedMap recursively."""
+    result = CommentedMap()
+    for key, value in data.items():
+        if isinstance(value, dict):
+            result[key] = _to_commented_map(value)
+        elif isinstance(value, list):
+            seq = CommentedSeq()
+            for item in value:
+                if isinstance(item, dict):
+                    seq.append(_to_commented_map(item))
+                else:
+                    seq.append(item)
+            result[key] = seq
+        else:
+            result[key] = value
+    return result
+
+
+def canonical_dump(data: Any) -> str:
+    """Serialize sprint data to deterministic YAML string.
+
+    Applies:
+    - Fixed key ordering per sprint-template.yaml
+    - Block scalars (|) for multiline strings
+    - 2-space indentation
+    - No trailing whitespace
+
+    Args:
+        data: Sprint data (CommentedMap or dict)
+
+    Returns:
+        Deterministic YAML string
+    """
+    canonicalized = _canonicalize(data)
+
+    yml = _make_yaml()
+    stream = io.StringIO()
+    yml.dump(canonicalized, stream)
+    output = stream.getvalue()
+
+    # Strip trailing whitespace from each line
+    lines = output.split("\n")
+    cleaned = [line.rstrip() for line in lines]
+    result = "\n".join(cleaned)
+
+    # Ensure exactly one trailing newline
+    result = result.rstrip("\n") + "\n"
+
+    return result
+
+
+def _get_epic_ref(epic: Mapping) -> str:
+    """Get the canonical reference ID for an epic shard file.
+
+    Priority: Jira key > numeric ID extracted from epic-N > raw ID.
+    Strips 'epic-' prefix from IDs to prevent double-prefix filenames
+    (e.g., epic-epic-94.yaml). See ADR-0022.
+    """
+    jira = epic.get("jira")
+    epic_id = str(epic.get("id", ""))
+
+    if jira and JIRA_PATTERN.match(str(jira)):
+        return str(jira)
+    if JIRA_PATTERN.match(epic_id):
+        return epic_id
+
+    # Strip epic- prefix to prevent double-prefix filenames
+    # e.g., "epic-94" -> "94" so file becomes "epic-94.yaml" not "epic-epic-94.yaml"
+    stripped = epic_id
+    while stripped.startswith("epic-"):
+        stripped = stripped[5:]
+    return stripped or epic_id
+
+
+def _write_yaml_file(path: Path, data: Any) -> None:
+    """Write data to a single YAML file atomically.
+
+    Uses temp file + os.replace() for atomic writes on POSIX.
+    """
+    if not isinstance(data, Mapping):
+        raise TypeError(f"Expected mapping type, got {type(data).__name__}")
+
+    output = canonical_dump(data)
+
+    tmp_path = path.with_suffix(".yaml.tmp")
+    try:
+        with open(tmp_path, "w") as f:
+            f.write(output)
+        os.replace(tmp_path, path)
+    except Exception:
+        if tmp_path.exists():
+            tmp_path.unlink()
+        raise
+
+
+def _is_sharded_on_disk(path: Path) -> bool:
+    """Check if the on-disk index file uses sharded epic references."""
+    if not path.exists():
+        return False
+    yml = _make_yaml()
+    try:
+        with open(path) as f:
+            on_disk = yml.load(f)
+    except Exception:
+        return False
+    if on_disk is None or not isinstance(on_disk, Mapping):
+        return False
+    epics = on_disk.get("epics", [])
+    return bool(epics) and isinstance(epics[0], str)
+
+
+def write_sprint(path: Path, data: Any) -> None:
+    """Write sprint data to YAML file(s) atomically.
+
+    If the on-disk index uses sharded format (epics as string refs),
+    writes each epic to its shard file and the index with string refs.
+    Otherwise writes the full data to a single file.
+
+    Args:
+        path: Destination path (the index file)
+        data: Sprint data (CommentedMap or dict)
+
+    Raises:
+        TypeError: If data is not a valid mapping type
+        OSError: If write fails
+    """
+    if not isinstance(data, Mapping):
+        raise TypeError(f"Expected mapping type, got {type(data).__name__}")
+
+    if not _is_sharded_on_disk(path):
+        _write_yaml_file(path, data)
+        return
+
+    # Sharded write: each epic goes to its own file
+    sprint_dir = path.parent
+    epic_refs = CommentedSeq()
+
+    # Read old index refs so we can detect renamed shards
+    old_indexed: set[Path] = set()
+    yml = _make_yaml()
+    try:
+        with open(path) as f:
+            old_data = yml.load(f)
+        for ref in old_data.get("epics", []):
+            if isinstance(ref, str):
+                old_indexed.add(sprint_dir / f"epic-{ref}.yaml")
+    except Exception:
+        pass
+
+    written_shards: set[Path] = set()
+    for epic in data.get("epics", []):
+        if isinstance(epic, Mapping):
+            ref = _get_epic_ref(epic)
+            shard_file = sprint_dir / f"epic-{ref}.yaml"
+            _write_yaml_file(shard_file, epic)
+            written_shards.add(shard_file)
+            epic_refs.append(ref)
+        else:
+            epic_refs.append(epic)
+
+    # Write index with string refs instead of full epic dicts
+    index = CommentedMap()
+    for key in data:
+        if key == "epics":
+            index["epics"] = epic_refs
+        else:
+            index[key] = data[key]
+
+    _write_yaml_file(path, index)
+
+    # Remove stale shards that were in the old index but not the new one
+    for stale in old_indexed - written_shards:
+        if stale.exists():
+            stale.unlink()