@pennyfarthing/core 11.4.0 → 12.0.0

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

@@ -0,0 +1,361 @@
+"""
+Sprint YAML parsing utilities for Pennyfarthing scripts.
+
+Provides access to sprint data with support for:
+- Default sprint: sprint/current-sprint.yaml
+- Multi-sprint registry: sprint/sprints.yaml with per-user preference
+  stored in .pennyfarthing/config.local.yaml
+- Sharded per-epic format: epic-{ref}.yaml shard files
+"""
+
+from pathlib import Path
+from typing import Any
+
+from pf.common.config import (
+    get_project_root,
+    load_pennyfarthing_config,
+    load_yaml_config,
+    save_pennyfarthing_config_key,
+)
+from pf.core.resolver import resolve_sprint_context
+
+
+def _merge_epic_shards(data: dict[str, Any], sprint_dir: Path) -> dict[str, Any]:
+    """Merge sharded epic files into the sprint data structure.
+
+    Thin wrapper around shard_merge.merge_epic_shards() that uses
+    load_yaml_config as the file loader. Kept as a named function
+    for any external importers (e.g. validator.py).
+
+    Args:
+        data: Sprint data with possible string refs in epics
+        sprint_dir: Directory containing the shard files
+
+    Returns:
+        Sprint data with full epic dicts
+    """
+    from pf.sprint.shard_merge import merge_epic_shards
+
+    return merge_epic_shards(data, sprint_dir, load_file=load_yaml_config)
+
+
+def load_sprint(project_root: Path | None = None) -> dict[str, Any] | None:
+    """Load sprint data from project root.
+
+    Delegates path resolution to resolve_sprint_context(), which handles
+    default sprint, multi-sprint registry, and per-user preference.
+
+    Supports both monolithic and sharded epic formats. When epics are
+    string references, the corresponding epic-{ref}.yaml files are
+    loaded and merged transparently.
+
+    Args:
+        project_root: Project root path (defaults to auto-detect)
+
+    Returns:
+        Sprint data as dict, or None if not found
+    """
+    root = project_root or get_project_root()
+
+    try:
+        ctx = resolve_sprint_context(str(root))
+    except (FileNotFoundError, ValueError):
+        return None
+
+    sprint_path = Path(ctx.sprint_file)
+    data = load_yaml_config(sprint_path)
+    if data is None:
+        return None
+
+    # Inject registry metadata for non-default contexts
+    if not ctx.is_default:
+        data["_registry"] = {
+            "name": ctx.name,
+            "type": ctx.type,
+            "context_root": ctx.context_root,
+            "session_root": ctx.session_root,
+        }
+
+    return _merge_epic_shards(data, sprint_path.parent)
+
+
+def load_sprint_registry(project_root: Path | None = None) -> dict[str, Any] | None:
+    """Load sprint registry from sprint/sprints.yaml.
+
+    The sprint registry indexes multiple parallel sprints (e.g., a main
+    project sprint and research spike sprints). Each entry maps a sprint
+    name to its YAML file path, type, and metadata.
+
+    Args:
+        project_root: Project root path (defaults to auto-detect)
+
+    Returns:
+        Registry data as dict, or None if no registry exists
+    """
+    root = project_root or get_project_root()
+    registry_path = root / "sprint" / "sprints.yaml"
+    return load_yaml_config(registry_path)
+
+
+def get_active_sprint_name(project_root: Path | None = None) -> str | None:
+    """Get the name of the currently active sprint.
+
+    Reads the per-user preference from .pennyfarthing/config.local.yaml
+    (sprint.active key). Returns None if no preference is set, meaning
+    the default sprint/current-sprint.yaml should be used.
+
+    Args:
+        project_root: Project root path (defaults to auto-detect)
+
+    Returns:
+        Active sprint name, or None if using the default sprint
+    """
+    root = project_root or get_project_root()
+    config = load_pennyfarthing_config(root)
+    sprint_config = config.get("sprint", {})
+    if isinstance(sprint_config, dict):
+        return sprint_config.get("active")
+    return None
+
+
+def switch_sprint(name: str, project_root: Path | None = None) -> dict[str, Any]:
+    """Switch the active sprint by updating the per-user preference.
+
+    Validates the sprint name against sprint/sprints.yaml, then writes
+    the selection to .pennyfarthing/config.local.yaml (gitignored,
+    per-user). Does not modify any shared repo files.
+
+    Use name "default" to clear the preference and revert to the
+    project's sprint/current-sprint.yaml.
+
+    Args:
+        name: Sprint name from the registry (e.g., "main", "ocsf-rs1")
+              or "default" to clear the preference
+        project_root: Project root path (defaults to auto-detect)
+
+    Returns:
+        Dict with 'success', 'message', and optional 'error' or 'sprint'
+    """
+    root = project_root or get_project_root()
+
+    # "default" clears the preference
+    if name == "default":
+        config = load_pennyfarthing_config(root)
+        sprint_config = config.get("sprint", {})
+        if isinstance(sprint_config, dict) and "active" in sprint_config:
+            del sprint_config["active"]
+            if not sprint_config:
+                save_pennyfarthing_config_key("sprint", {}, root)
+            else:
+                save_pennyfarthing_config_key("sprint", sprint_config, root)
+        return {
+            "success": True,
+            "message": "Cleared sprint preference — using default sprint/current-sprint.yaml",
+        }
+
+    registry = load_sprint_registry(root)
+
+    if registry is None:
+        return {"success": False, "error": "No sprint registry found (sprint/sprints.yaml)"}
+
+    sprints = registry.get("sprints", {})
+    if name not in sprints:
+        available = ", ".join(sprints.keys())
+        return {"success": False, "error": f"Unknown sprint: {name}. Available: {available}"}
+
+    sprint_entry = sprints[name]
+    sprint_file = sprint_entry.get("file")
+    if not sprint_file:
+        return {"success": False, "error": f"Sprint '{name}' has no file configured"}
+
+    # Verify the target sprint file exists
+    sprint_dir = root / "sprint"
+    target_path = (sprint_dir / sprint_file).resolve()
+    if not target_path.exists():
+        return {
+            "success": False,
+            "error": f"Sprint file not found: {sprint_file} (resolved to {target_path})",
+        }
+
+    # Write preference to config.local.yaml (per-user, gitignored)
+    config = load_pennyfarthing_config(root)
+    sprint_config = config.get("sprint", {})
+    if not isinstance(sprint_config, dict):
+        sprint_config = {}
+    sprint_config["active"] = name
+    save_pennyfarthing_config_key("sprint", sprint_config, root)
+
+    return {
+        "success": True,
+        "message": f"Switched to sprint: {name}",
+        "sprint": sprint_entry,
+    }
+
+
+def find_epic(sprint_data: dict[str, Any], epic_num: str) -> dict[str, Any] | None:
+    """Find epic in sprint data (handles various ID formats).
+
+    Args:
+        sprint_data: Sprint YAML data
+        epic_num: Epic number (e.g., "63", "epic-63", or "63")
+
+    Returns:
+        Epic dict if found, None otherwise
+    """
+    if not sprint_data or "epics" not in sprint_data:
+        return None
+
+    # Normalize the epic number
+    epic_num_clean = epic_num.replace("epic-", "")
+
+    for epic in sprint_data["epics"]:
+        epic_id = str(epic.get("id", ""))
+        # Match "63", "epic-63", or just the number
+        if epic_id == epic_num or epic_id == f"epic-{epic_num}" or epic_id == epic_num_clean:
+            return epic
+        # Also try without prefix
+        if epic_id.replace("epic-", "") == epic_num_clean:
+            return epic
+
+    return None
+
+
+# Alias for backwards compatibility
+load_current_sprint = load_sprint
+
+
+def get_sprint_info() -> dict[str, Any]:
+    """Get sprint metadata (number, dates, status, etc).
+
+    Returns:
+        Sprint info dict with number, status, goal, etc.
+    """
+    data = load_sprint()
+    if data and "sprint" in data:
+        return data["sprint"]
+    return {}
+
+
+def get_all_stories() -> list[dict[str, Any]]:
+    """Get all stories from all epics.
+
+    Returns:
+        Flat list of all story dicts
+    """
+    data = load_sprint()
+    if not data or "epics" not in data:
+        return []
+
+    stories = []
+    for epic in data["epics"]:
+        if "stories" in epic:
+            stories.extend(epic["stories"])
+    return stories
+
+
+def get_story_by_id(story_id: str) -> dict[str, Any] | None:
+    """Find a story by its ID.
+
+    Args:
+        story_id: The story ID (e.g., "63-4" or "MSSCI-12398")
+
+    Returns:
+        Story dict if found, None otherwise
+    """
+    for story in get_all_stories():
+        if story.get("id") == story_id:
+            return story
+        # Also check jira field
+        if story.get("jira") == story_id:
+            return story
+    return None
+
+
+def get_stories_by_status(status: str) -> list[dict[str, Any]]:
+    """Get all stories with a given status.
+
+    Args:
+        status: Status to filter by (e.g., "backlog", "in_progress", "done")
+
+    Returns:
+        List of stories matching the status
+    """
+    return [s for s in get_all_stories() if s.get("status") == status]
+
+
+def get_epic_by_id(epic_id: str) -> dict[str, Any] | None:
+    """Find an epic by its ID.
+
+    Args:
+        epic_id: The epic ID
+
+    Returns:
+        Epic dict if found, None otherwise
+    """
+    data = load_sprint()
+    if not data or "epics" not in data:
+        return None
+
+    for epic in data["epics"]:
+        if epic.get("id") == epic_id:
+            return epic
+    return None
+
+
+def find_story(epic: dict[str, Any] | None, story_id: str) -> dict[str, Any] | None:
+    """Find a story within an epic by its ID.
+
+    Args:
+        epic: Epic dict containing stories
+        story_id: The story ID (e.g., "63-7")
+
+    Returns:
+        Story dict if found, None otherwise
+    """
+    if not epic or "stories" not in epic:
+        return None
+
+    for story in epic["stories"]:
+        if story.get("id") == story_id:
+            return story
+
+    return None
+
+
+def get_story_field(
+    sprint_data: dict[str, Any], story_id: str, field_name: str
+) -> Any | None:
+    """Get a specific field from a story in sprint data.
+
+    Extracts the epic number from the story ID (e.g., "63-7" -> epic 63)
+    and looks up the story within that epic.
+
+    Args:
+        sprint_data: Sprint YAML data
+        story_id: The story ID (e.g., "63-7")
+        field_name: The field to extract (e.g., "status", "points", "workflow")
+
+    Returns:
+        Field value if found, None otherwise
+    """
+    if not sprint_data or not story_id:
+        return None
+
+    # Extract epic number from story ID (e.g., "63-7" -> "63")
+    parts = story_id.split("-")
+    if len(parts) < 2:
+        return None
+
+    epic_num = parts[0]
+
+    # Find the epic
+    epic = find_epic(sprint_data, epic_num)
+    if not epic:
+        return None
+
+    # Find the story within the epic
+    story = find_story(epic, story_id)
+    if not story:
+        return None
+
+    return story.get(field_name)

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

@@ -0,0 +1,205 @@
+"""Canonical shard merging for sprint YAML files.
+
+Provides a single merge_epic_shards() implementation used by both:
+- yaml_io.py (ruamel.yaml, preserves comments/ordering)
+- loader.py (yaml.safe_load, plain dicts)
+
+The caller passes a `load_file` callable so each consumer keeps
+its preferred YAML library.
+"""
+
+import warnings
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+
+def merge_epic_shards(
+    data: Any,
+    sprint_dir: Path,
+    *,
+    load_file: Callable[[Path], Any],
+    make_list: Callable[[], Any] | None = None,
+) -> Any:
+    """Merge sharded epic files into sprint data.
+
+    When the epics list contains string references (e.g. "MSSCI-14298"
+    or "epic-40"), loads each epic-{ref}.yaml shard and replaces the
+    string with the full epic data.
+
+    Also detects unindexed shard files on disk. Shards owned by
+    initiatives (initiative-*.yaml) are silently skipped; truly
+    orphaned shards emit a warning.
+
+    Args:
+        data: Sprint data with possible string refs in epics.
+        sprint_dir: Directory containing shard files.
+        load_file: Callable that reads a YAML file and returns parsed data.
+            For ruamel.yaml callers this returns CommentedMap;
+            for yaml.safe_load callers this returns plain dicts.
+        make_list: Optional callable returning an empty list-like container.
+            Defaults to ``list``. Pass ``CommentedSeq`` for ruamel.yaml.
+
+    Returns:
+        Sprint data with full epic dicts merged in.
+    """
+    epics = data.get("epics", [])
+    if not epics or not isinstance(epics[0], str):
+        return data
+
+    if make_list is None:
+        make_list = list
+
+    loaded_shard_files: set[Path] = set()
+    loaded_epic_ids: set[str] = set()
+    merged_epics = make_list()
+
+    for ref in epics:
+        if not isinstance(ref, str):
+            merged_epics.append(ref)
+            continue
+
+        shard_file = sprint_dir / f"epic-{ref}.yaml"
+        if shard_file.exists():
+            try:
+                epic_data = load_file(shard_file)
+            except Exception:
+                warnings.warn(
+                    f"Failed to load shard {shard_file.name}",
+                    stacklevel=2,
+                )
+                continue
+
+            if epic_data is None:
+                continue
+
+            merged_epics.append(epic_data)
+            loaded_shard_files.add(shard_file.resolve())
+
+            eid = str(epic_data.get("id", "")).replace("epic-", "")
+            if eid:
+                loaded_epic_ids.add(eid)
+            jira_key = str(epic_data.get("jira", ""))
+            if jira_key:
+                loaded_epic_ids.add(jira_key)
+        else:
+            warnings.warn(
+                f"Sprint epic ref '{ref}' not found: {shard_file}",
+                stacklevel=2,
+            )
+
+    # Collect epic refs owned by initiatives so we don't warn about them.
+    initiative_refs: set[str] = set()
+    for init_file in sorted(sprint_dir.glob("initiative-*.yaml")):
+        try:
+            init_data = load_file(init_file)
+        except Exception:
+            continue
+        if init_data and isinstance(init_data, Mapping):
+            for ref in init_data.get("epics", []):
+                if isinstance(ref, str):
+                    initiative_refs.add(ref)
+                    initiative_refs.add(ref.replace("epic-", ""))
+
+    # Warn about truly orphaned shard files (not in index, not in initiatives).
+    for shard_file in sorted(sprint_dir.glob("epic-*.yaml")):
+        if shard_file.resolve() in loaded_shard_files:
+            continue
+        try:
+            epic_data = load_file(shard_file)
+        except Exception:
+            continue
+        if epic_data is None or not isinstance(epic_data, Mapping) or "id" not in epic_data:
+            continue
+        eid = str(epic_data.get("id", "")).replace("epic-", "")
+        jira_key = str(epic_data.get("jira", ""))
+        if eid in loaded_epic_ids or (jira_key and jira_key in loaded_epic_ids):
+            continue
+        if eid in initiative_refs or jira_key in initiative_refs:
+            continue
+        warnings.warn(
+            f"Unindexed shard {shard_file.name} (epic {eid}) not in epics list — skipping",
+            stacklevel=2,
+        )
+
+    data["epics"] = merged_epics
+    return data
+
+
+def detect_orphan_shards(
+    data: Any,
+    sprint_dir: Path,
+    *,
+    load_file: Callable[[Path], Any],
+) -> list[dict[str, str]]:
+    """Detect orphaned epic shard files not referenced by the sprint index.
+
+    Returns structured orphan entries instead of emitting warnings.
+    Skips shards owned by initiatives.
+
+    Args:
+        data: Sprint data after merging (with full epic dicts in epics list).
+        sprint_dir: Directory containing shard files.
+        load_file: Callable that reads a YAML file and returns parsed data.
+
+    Returns:
+        List of orphan dicts with id, jira, file, and reason fields.
+    """
+    loaded_epic_ids: set[str] = set()
+    loaded_shard_files: set[Path] = set()
+
+    for epic in data.get("epics", []):
+        if not isinstance(epic, Mapping):
+            continue
+        eid = str(epic.get("id", "")).replace("epic-", "")
+        if eid:
+            loaded_epic_ids.add(eid)
+        jira_key = str(epic.get("jira", ""))
+        if jira_key:
+            loaded_epic_ids.add(jira_key)
+        # Reconstruct which shard files were loaded
+        for ref in (eid, jira_key):
+            if ref:
+                shard_file = sprint_dir / f"epic-{ref}.yaml"
+                if shard_file.exists():
+                    loaded_shard_files.add(shard_file.resolve())
+
+    # Collect initiative-owned refs
+    initiative_refs: set[str] = set()
+    for init_file in sorted(sprint_dir.glob("initiative-*.yaml")):
+        try:
+            init_data = load_file(init_file)
+        except Exception:
+            continue
+        if init_data and isinstance(init_data, Mapping):
+            for ref in init_data.get("epics", []):
+                if isinstance(ref, str):
+                    initiative_refs.add(ref)
+                    initiative_refs.add(ref.replace("epic-", ""))
+
+    orphans: list[dict[str, str]] = []
+    for shard_file in sorted(sprint_dir.glob("epic-*.yaml")):
+        if shard_file.resolve() in loaded_shard_files:
+            continue
+        try:
+            epic_data = load_file(shard_file)
+        except Exception:
+            continue
+        if epic_data is None or not isinstance(epic_data, Mapping) or "id" not in epic_data:
+            continue
+        eid = str(epic_data.get("id", "")).replace("epic-", "")
+        jira_key = str(epic_data.get("jira", ""))
+        if eid in loaded_epic_ids or (jira_key and jira_key in loaded_epic_ids):
+            continue
+        if eid in initiative_refs or jira_key in initiative_refs:
+            continue
+        entry: dict[str, str] = {
+            "id": str(epic_data.get("id", "")),
+            "file": shard_file.name,
+            "reason": "unindexed (not in current-sprint.yaml, not in initiative shards)",
+        }
+        if jira_key:
+            entry["jira"] = jira_key
+        orphans.append(entry)
+
+    return orphans

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

@@ -0,0 +1,143 @@
+"""Add standalone stories to current-sprint.yaml.
+
+Provides a CLI command to register done standalone stories
+in the sprint index's ``standalone_stories`` section.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import click
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+
+from pf.sprint.yaml_io import (
+    STORY_KEY_ORDER,
+    read_sprint,
+    write_sprint,
+)
+
+
+def add_standalone_story(
+    sprint_path: Path,
+    jira_key: str,
+    title: str,
+    points: int,
+    *,
+    repos: str = "pennyfarthing",
+    pr: int | None = None,
+    branch: str | None = None,
+) -> dict[str, Any]:
+    """Add a done standalone story to current-sprint.yaml.
+
+    Args:
+        sprint_path: Path to sprint YAML index file
+        jira_key: Jira issue key (e.g., MSSCI-15501)
+        title: Story title
+        points: Story points
+        repos: Target repo (default: pennyfarthing)
+        pr: PR number (optional)
+        branch: Branch name (optional)
+
+    Returns:
+        Dict with success status or error
+    """
+    data = read_sprint(sprint_path)
+
+    # Build story entry
+    story = CommentedMap()
+    fields: dict[str, Any] = {
+        "id": jira_key,
+        "jira": jira_key,
+        "title": title,
+        "points": points,
+        "status": "done",
+        "repos": repos,
+    }
+    if pr is not None:
+        fields["pr"] = pr
+    if branch is not None:
+        fields["branch"] = branch
+
+    # Insert keys in canonical order, then extras
+    for key in STORY_KEY_ORDER:
+        if key in fields:
+            story[key] = fields[key]
+    for key in fields:
+        if key not in STORY_KEY_ORDER:
+            story[key] = fields[key]
+
+    # Ensure standalone_stories section exists
+    if "standalone_stories" not in data:
+        data["standalone_stories"] = CommentedSeq()
+    elif not isinstance(data["standalone_stories"], list):
+        data["standalone_stories"] = CommentedSeq()
+
+    # Check for duplicates
+    for existing in data["standalone_stories"]:
+        if isinstance(existing, dict) and existing.get("id") == jira_key:
+            return {
+                "success": False,
+                "error": f"Standalone story {jira_key} already exists in sprint",
+            }
+
+    data["standalone_stories"].append(story)
+    write_sprint(sprint_path, data)
+
+    return {"success": True, "id": jira_key}
+
+
+@click.command("add")
+@click.argument("jira_key", type=str)
+@click.argument("title", type=str)
+@click.argument("points", type=int)
+@click.option("--repos", type=str, default="pennyfarthing", help="Target repo (default: pennyfarthing)")
+@click.option("--pr", type=int, default=None, help="PR number")
+@click.option("--branch", type=str, default=None, help="Branch name")
+@click.option("--sprint-file", type=click.Path(), default=None, help="Path to sprint YAML file")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def standalone_add_command(
+    jira_key: str,
+    title: str,
+    points: int,
+    repos: str,
+    pr: int | None,
+    branch: str | None,
+    sprint_file: str | None,
+    dry_run: bool,
+) -> None:
+    """Add a done standalone story to current sprint tracking.
+
+    \b
+    Usage:
+      pf sprint standalone add MSSCI-15501 "Auto-pull LFS portraits" 2
+      pf sprint standalone add MSSCI-15501 "Fix bug" 1 --pr 1070 --repos pennyfarthing
+    """
+    if dry_run:
+        click.echo(f"[DRY-RUN] Would add standalone story {jira_key}: {title} [{points}pts]")
+        if pr:
+            click.echo(f"  PR: {pr}")
+        if branch:
+            click.echo(f"  Branch: {branch}")
+        return
+
+    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 = add_standalone_story(
+        sprint_path=path,
+        jira_key=jira_key,
+        title=title,
+        points=points,
+        repos=repos,
+        pr=pr,
+        branch=branch,
+    )
+
+    if result["success"]:
+        click.echo(f"Added standalone story {jira_key}: {title} [{points}pts]")
+    else:
+        raise click.ClickException(result["error"])