@pennyfarthing/core 10.0.2 → 10.0.3

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/sprint/yaml_io.py

@@ -0,0 +1,258 @@
+"""
+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)
+- write_sprint(path, data) -> atomic write
+- canonical_dump(data) -> deterministic YAML string
+"""
+
+import io
+import os
+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
+
+
+# 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_sprint(path: Path) -> CommentedMap:
+    """Read sprint YAML file preserving ordering and comments.
+
+    Args:
+        path: Path to sprint 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 _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 write_sprint(path: Path, data: Any) -> None:
+    """Write sprint data to YAML file atomically.
+
+    Uses temp file + os.replace() for atomic writes on POSIX.
+
+    Args:
+        path: Destination path
+        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__}")
+
+    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:
+        # Clean up temp file if it exists
+        if tmp_path.exists():
+            tmp_path.unlink()
+        raise

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

package/pennyfarthing_scripts/story/cli.py

@@ -0,0 +1,105 @@
+"""
+Story CLI - Fan-out CLI for story operations.
+
+Usage:
+    python -m pennyfarthing_scripts.story <subcommand> [args]
+
+Subcommands:
+    size        Show sizing guidelines
+    template    Show story templates
+    create      Create a new story
+"""
+
+import argparse
+import sys
+
+
+def size(args: list[str]) -> int:
+    """Show sizing guidelines."""
+    from pennyfarthing_scripts.story.size import main as size_main
+    return size_main(args)
+
+
+def template(args: list[str]) -> int:
+    """Show story templates."""
+    from pennyfarthing_scripts.story.template import main as template_main
+    return template_main(args)
+
+
+def create(args: list[str]) -> int:
+    """Create a new story."""
+    from pennyfarthing_scripts.story.create import main as create_main
+    return create_main(args)
+
+
+# Subcommand registry
+SUBCOMMANDS = {
+    "size": size,
+    "template": template,
+    "create": create,
+}
+
+
+def cli(args: list[str] | None = None) -> int:
+    """Main CLI entry point.
+
+    Args:
+        args: Command line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code
+    """
+    if args is None:
+        args = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="story",
+        description="Story CLI for Pennyfarthing",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Subcommands:
+    size [points]       Show sizing guidelines (optionally for specific points)
+    template [type]     Show story templates (optionally for specific type)
+    create              Create a new story
+
+Examples:
+    story size
+    story size 3
+    story template feature
+    story create MSSCI-12000 "Add feature" 3 --type feature
+""",
+    )
+
+    parser.add_argument(
+        "subcommand",
+        nargs="?",
+        choices=list(SUBCOMMANDS.keys()),
+        help="Subcommand to run",
+    )
+    parser.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="Arguments for subcommand",
+    )
+
+    parsed = parser.parse_args(args)
+
+    if not parsed.subcommand:
+        parser.print_help()
+        return 0
+
+    handler = SUBCOMMANDS.get(parsed.subcommand)
+    if handler:
+        return handler(parsed.args)
+    else:
+        print(f"Unknown subcommand: {parsed.subcommand}", file=sys.stderr)
+        return 1
+
+
+def main(args: list[str] | None = None) -> int:
+    """Alias for cli()."""
+    return cli(args)
+
+
+if __name__ == "__main__":
+    sys.exit(cli())