@pennyfarthing/core 10.0.2 → 10.0.5

package/pennyfarthing_scripts/sprint/work.py

@@ -0,0 +1,208 @@
+"""
+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",
+        }
+
+    # Check if canceled
+    if status == "canceled":
+        return {
+            "available": False,
+            "type": "story",
+            "story": story,
+            "reason": "Story is canceled",
+        }
+
+    # Available statuses: backlog, ready, planning
+    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.
+
+    Considers stories with backlog, ready, or planning status.
+
+    Returns:
+        Dict with next story details or error
+    """
+    from pennyfarthing_scripts.sprint.loader import get_all_stories
+
+    all_stories = get_all_stories()
+    available_statuses = {"backlog", "ready", "planning"}
+    backlog = [s for s in all_stories if s.get("status") in available_statuses]
+
+    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/sprint/yaml_io.py

@@ -0,0 +1,367 @@
+"""
+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",
+    "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.
+
+    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)
+
+    epics = data.get("epics", [])
+    if not epics or not isinstance(epics[0], str):
+        return data
+
+    sprint_dir = path.parent
+    merged_epics = CommentedSeq()
+    for ref in epics:
+        if isinstance(ref, str):
+            shard_file = sprint_dir / f"epic-{ref}.yaml"
+            if shard_file.exists():
+                epic_data = _read_yaml_file(shard_file)
+                merged_epics.append(epic_data)
+        else:
+            merged_epics.append(ref)
+
+    data["epics"] = merged_epics
+    return data
+
+
+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
+
+    # Determine which key order to use based on context
+    # Top level
+    result = _sort_mapping(
+        data if isinstance(data, CommentedMap) else _to_commented_map(data),
+        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.
+
+    Mirrors the logic in migrate-to-shards.py: prefer Jira key, fall back to ID.
+    """
+    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
+    return 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()
+
+    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)
+            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)

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())