@pennyfarthing/core 11.4.0 → 12.0.0

package/pennyfarthing-dist/src/pf/bmad/parser.py

@@ -0,0 +1,238 @@
+"""
+BMAD markdown parser for Pennyfarthing sprint adapter.
+
+Reads BMAD story and epic markdown files and returns PF-compatible dicts.
+Story files: implementation-artifacts/{epic}-{story}-{slug}.md
+Epic files:  planning-artifacts/epics/epic-{nn}-{slug}.md
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+# =============================================================================
+# Status Mapping
+# =============================================================================
+
+BMAD_TO_PF_STATUS: dict[str, str] = {
+    "draft": "planning",
+    "ready-for-dev": "ready",
+    "in-progress": "in_progress",
+    "in-review": "in_progress",
+    "completed": "done",
+    "blocked": "backlog",
+}
+
+PF_TO_BMAD_STATUS: dict[str, str] = {
+    "planning": "draft",
+    "ready": "ready-for-dev",
+    "in_progress": "in-progress",
+    "done": "completed",
+    "backlog": "blocked",
+    "canceled": "completed",
+}
+
+
+def map_bmad_to_pf(bmad_status: str) -> str:
+    """Map a BMAD status string to a PF status."""
+    return BMAD_TO_PF_STATUS.get(bmad_status.strip().lower(), "planning")
+
+
+def map_pf_to_bmad(pf_status: str) -> str:
+    """Map a PF status string to a BMAD status."""
+    return PF_TO_BMAD_STATUS.get(pf_status.strip().lower(), "draft")
+
+
+# =============================================================================
+# Story Parsing
+# =============================================================================
+
+# Header patterns: flat Key: value lines after the # title
+_HEADER_PATTERNS: dict[str, re.Pattern[str]] = {
+    "status": re.compile(r"^Status:\s*(.+)$", re.MULTILINE),
+    "story_key": re.compile(r"^Story-Key:\s*(.+)$", re.MULTILINE),
+    "jira": re.compile(r"^Jira:\s*(.+)$", re.MULTILINE),
+    "epic_line": re.compile(r"^Epic:\s*(.+)$", re.MULTILINE),
+    "date": re.compile(r"^Date:\s*(.+)$", re.MULTILINE),
+}
+
+_TITLE_RE = re.compile(r"^#\s+Story\s+\d+\.\d+(?:\.\d+)?:\s*(.+)$", re.MULTILINE)
+
+# AC block: everything between ## Acceptance Criteria and the next ## heading
+_AC_RE = re.compile(
+    r"## Acceptance Criteria\s*\n(.*?)(?=\n## |\Z)", re.DOTALL
+)
+
+
+def parse_bmad_story(path: Path) -> dict[str, Any]:
+    """Parse a single BMAD story markdown file.
+
+    Args:
+        path: Path to the .md file in implementation-artifacts/
+
+    Returns:
+        PF-compatible story dict with extra bmad_key and bmad_path fields.
+    """
+    content = path.read_text()
+
+    # Extract header fields
+    fields: dict[str, str] = {}
+    for name, pattern in _HEADER_PATTERNS.items():
+        match = pattern.search(content)
+        if match:
+            fields[name] = match.group(1).strip()
+
+    story_key = fields.get("story_key", "")
+    # Consume all leading numeric segments as the ID
+    # e.g. "1-5-testing-framework" → "1-5", "2-8-1-claroty-plugin" → "2-8-1"
+    key_parts = story_key.split("-")
+    id_segments: list[str] = []
+    for seg in key_parts:
+        if seg.isdigit():
+            id_segments.append(seg)
+        else:
+            break
+    pf_id = "-".join(id_segments) if len(id_segments) >= 2 else "0-0"
+    epic_num = id_segments[0] if id_segments else "0"
+
+    # Title from # heading
+    title_match = _TITLE_RE.search(content)
+    title = title_match.group(1).strip() if title_match else path.stem
+
+    # BMAD status → PF status
+    bmad_status = fields.get("status", "draft")
+    pf_status = map_bmad_to_pf(bmad_status)
+
+    # Jira references (format: "DPGD-14 / DPGD-21")
+    jira_raw = fields.get("jira", "")
+
+    # Acceptance criteria summary
+    ac_match = _AC_RE.search(content)
+    ac_text = ac_match.group(1).strip() if ac_match else ""
+
+    return {
+        "id": pf_id,
+        "title": title,
+        "status": pf_status,
+        "points": 3,  # Default; BMAD stories don't carry points in impl artifacts
+        "priority": "P1",
+        "workflow": "tdd",
+        "bmad_key": story_key,
+        "bmad_status": bmad_status,
+        "bmad_path": str(path),
+        "jira": jira_raw,
+        "epic_num": epic_num,
+        "acceptance_criteria": ac_text,
+    }
+
+
+# =============================================================================
+# Epic Parsing
+# =============================================================================
+
+
+def parse_bmad_epic(path: Path) -> dict[str, Any]:
+    """Parse a BMAD epic markdown file with YAML frontmatter.
+
+    Args:
+        path: Path to epic-{nn}-{slug}.md in planning-artifacts/epics/
+
+    Returns:
+        Dict with epicNumber, title, phase, status, storyCount.
+    """
+    content = path.read_text()
+
+    # Extract YAML frontmatter between --- markers
+    fm_match = re.match(r"^---\s*\n(.*?)\n---", content, re.DOTALL)
+    if not fm_match:
+        return {
+            "epicNumber": 0,
+            "title": path.stem,
+            "phase": "MVP",
+            "status": "draft",
+            "storyCount": 0,
+        }
+
+    fm = yaml.safe_load(fm_match.group(1)) or {}
+    return {
+        "epicNumber": fm.get("epicNumber", 0),
+        "title": fm.get("title", path.stem),
+        "phase": fm.get("phase", "MVP"),
+        "status": fm.get("status", "draft"),
+        "storyCount": fm.get("storyCount", 0),
+    }
+
+
+# =============================================================================
+# Discovery
+# =============================================================================
+
+
+def discover_bmad_stories(
+    source_root: Path,
+    story_dir: str = "implementation-artifacts",
+) -> list[dict[str, Any]]:
+    """Scan BMAD implementation-artifacts/ and return parsed stories.
+
+    Args:
+        source_root: Path to _bmad-output/ (or equivalent)
+        story_dir: Subdirectory name for story files
+
+    Returns:
+        List of parsed story dicts, sorted by (epic_num, story_num).
+    """
+    artifacts_dir = source_root / story_dir
+    if not artifacts_dir.is_dir():
+        return []
+
+    stories: list[dict[str, Any]] = []
+    for md_file in sorted(artifacts_dir.glob("*.md")):
+        # Skip non-story files (e.g. 0-1-bmad-method-lifecycle.md is meta)
+        if md_file.name.startswith("0-"):
+            continue
+        # Must match {digit}-{digit}-*.md pattern
+        if not re.match(r"^\d+-\d+-", md_file.name):
+            continue
+        story = parse_bmad_story(md_file)
+        stories.append(story)
+
+    # Sort by epic number, then story number (supports variable-length IDs like 2-8-1)
+    def sort_key(s: dict) -> tuple[int, ...]:
+        return tuple(int(p) for p in s["id"].split("-"))
+
+    stories.sort(key=sort_key)
+    return stories
+
+
+def discover_bmad_epics(
+    source_root: Path,
+    epic_dir: str = "planning-artifacts/epics",
+) -> list[dict[str, Any]]:
+    """Scan BMAD planning-artifacts/epics/ and return parsed epics.
+
+    Args:
+        source_root: Path to _bmad-output/ (or equivalent)
+        epic_dir: Subdirectory path for epic files
+
+    Returns:
+        List of parsed epic dicts, sorted by epicNumber.
+    """
+    epics_dir = source_root / epic_dir
+    if not epics_dir.is_dir():
+        return []
+
+    epics: list[dict[str, Any]] = []
+    for md_file in sorted(epics_dir.glob("epic-*.md")):
+        # Skip index.md or non-epic files
+        if md_file.name == "index.md":
+            continue
+        epic = parse_bmad_epic(md_file)
+        if epic["epicNumber"] > 0:
+            epics.append(epic)
+
+    epics.sort(key=lambda e: e["epicNumber"])
+    return epics

package/pennyfarthing-dist/src/pf/bmad/sync.py

@@ -0,0 +1,462 @@
+"""
+Bidirectional sync between BMAD markdown and PF sprint YAML.
+
+Modeled on pf/jira/bidirectional.py — same
+SyncPlan/SyncChange/SyncResult pattern, adapted for BMAD's flat
+markdown header format instead of a REST API.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from pf.bmad.parser import (
+    discover_bmad_stories,
+    map_bmad_to_pf,
+    map_pf_to_bmad,
+)
+from pf.common.config import load_pennyfarthing_config
+
+# =============================================================================
+# Data Classes
+# =============================================================================
+
+
+@dataclass
+class BmadSyncChange:
+    """A single sync change to apply."""
+
+    bmad_key: str
+    pf_id: str
+    field: Literal["status"]
+    action: Literal["update-pf", "update-bmad"]
+    pf_value: Any
+    bmad_value: Any
+    target_value: Any
+
+
+@dataclass
+class BmadSyncPlan:
+    """Result of comparing PF YAML and BMAD markdown."""
+
+    changes: list[BmadSyncChange] = field(default_factory=list)
+    pf_only: list[str] = field(default_factory=list)
+    bmad_only: list[str] = field(default_factory=list)
+    both: list[str] = field(default_factory=list)
+    conflicts: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class BmadSyncResult:
+    """Result of executing a sync plan."""
+
+    dry_run: bool
+    changes_planned: int
+    changes_applied: int
+    pf_modified: bool
+    bmad_modified: bool
+    new_stories_imported: int = 0
+    errors: list[str] = field(default_factory=list)
+
+
+# =============================================================================
+# Sync Plan Generation
+# =============================================================================
+
+
+def _collect_pf_stories(sprint_path: Path) -> list[dict[str, Any]]:
+    """Load all PF stories that have a bmad_key field."""
+    from pf.sprint.yaml_io import read_sprint
+
+    data = read_sprint(sprint_path)
+    stories: list[dict[str, Any]] = []
+    for epic in data.get("epics", []):
+        for story in epic.get("stories", []):
+            if story.get("bmad_key"):
+                stories.append(dict(story))
+    return stories
+
+
+def generate_sync_plan(
+    pf_stories: list[dict[str, Any]],
+    bmad_stories: list[dict[str, Any]],
+    *,
+    direction: Literal["pull", "push", "both"] = "both",
+    pf_wins: bool = True,
+) -> BmadSyncPlan:
+    """Compare PF and BMAD stories and build a sync plan.
+
+    Args:
+        pf_stories: Stories from PF YAML (must have bmad_key field)
+        bmad_stories: Stories parsed from BMAD markdown
+        direction: "pull" (BMAD→PF), "push" (PF→BMAD), or "both"
+        pf_wins: If True, PF status wins on conflict (default for push)
+
+    Returns:
+        BmadSyncPlan with changes, conflicts, and set membership.
+    """
+    plan = BmadSyncPlan()
+
+    # Build lookup maps keyed on bmad_key
+    pf_by_key: dict[str, dict] = {}
+    for story in pf_stories:
+        key = story.get("bmad_key", "")
+        if key:
+            pf_by_key[key] = story
+
+    bmad_by_key: dict[str, dict] = {}
+    for story in bmad_stories:
+        key = story.get("bmad_key", "")
+        if key:
+            bmad_by_key[key] = story
+
+    pf_keys = set(pf_by_key.keys())
+    bmad_keys = set(bmad_by_key.keys())
+
+    plan.pf_only = sorted(pf_keys - bmad_keys)
+    plan.bmad_only = sorted(bmad_keys - pf_keys)
+    plan.both = sorted(pf_keys & bmad_keys)
+
+    # Compare matched stories
+    for key in plan.both:
+        pf_story = pf_by_key[key]
+        bmad_story = bmad_by_key[key]
+
+        pf_status = pf_story.get("status", "planning")
+        bmad_status_raw = bmad_story.get("bmad_status", "draft")
+        bmad_status_as_pf = map_bmad_to_pf(bmad_status_raw)
+
+        if pf_status == bmad_status_as_pf:
+            continue  # In sync
+
+        pf_id = pf_story.get("id", key)
+
+        if direction == "pull":
+            # BMAD → PF
+            plan.changes.append(
+                BmadSyncChange(
+                    bmad_key=key,
+                    pf_id=pf_id,
+                    field="status",
+                    action="update-pf",
+                    pf_value=pf_status,
+                    bmad_value=bmad_status_raw,
+                    target_value=bmad_status_as_pf,
+                )
+            )
+        elif direction == "push":
+            # PF → BMAD
+            target_bmad = map_pf_to_bmad(pf_status)
+            plan.changes.append(
+                BmadSyncChange(
+                    bmad_key=key,
+                    pf_id=pf_id,
+                    field="status",
+                    action="update-bmad",
+                    pf_value=pf_status,
+                    bmad_value=bmad_status_raw,
+                    target_value=target_bmad,
+                )
+            )
+        else:
+            # Both directions — resolve by pf_wins flag
+            if pf_wins:
+                target_bmad = map_pf_to_bmad(pf_status)
+                plan.changes.append(
+                    BmadSyncChange(
+                        bmad_key=key,
+                        pf_id=pf_id,
+                        field="status",
+                        action="update-bmad",
+                        pf_value=pf_status,
+                        bmad_value=bmad_status_raw,
+                        target_value=target_bmad,
+                    )
+                )
+            else:
+                plan.changes.append(
+                    BmadSyncChange(
+                        bmad_key=key,
+                        pf_id=pf_id,
+                        field="status",
+                        action="update-pf",
+                        pf_value=pf_status,
+                        bmad_value=bmad_status_raw,
+                        target_value=bmad_status_as_pf,
+                    )
+                )
+
+    return plan
+
+
+# =============================================================================
+# Sync Plan Execution
+# =============================================================================
+
+
+def _update_bmad_file_status(bmad_path: str, new_status: str) -> bool:
+    """Rewrite the Status: line in a BMAD markdown file.
+
+    Args:
+        bmad_path: Absolute path to the .md file
+        new_status: New BMAD status string (e.g. "completed")
+
+    Returns:
+        True if the file was modified.
+    """
+    path = Path(bmad_path)
+    if not path.exists():
+        return False
+
+    content = path.read_text()
+    new_content, count = re.subn(
+        r"^(Status:\s*)(.+)$",
+        rf"\g<1>{new_status}",
+        content,
+        count=1,
+        flags=re.MULTILINE,
+    )
+    if count == 0:
+        return False
+
+    path.write_text(new_content)
+    return True
+
+
+def execute_sync_plan(
+    plan: BmadSyncPlan,
+    *,
+    dry_run: bool = False,
+    sprint_path: Path | None = None,
+    bmad_root: Path | None = None,
+    import_new: bool = False,
+    repos: str = "axiathon",
+) -> BmadSyncResult:
+    """Execute a sync plan.
+
+    Args:
+        plan: The sync plan to execute
+        dry_run: If True, report without applying
+        sprint_path: Path to PF sprint YAML
+        bmad_root: Path to BMAD _bmad-output/ root
+        import_new: If True, import bmad_only stories as new PF stories
+        repos: Default repos for new story imports
+
+    Returns:
+        BmadSyncResult with counts and errors.
+    """
+    result = BmadSyncResult(
+        dry_run=dry_run,
+        changes_planned=len(plan.changes),
+        changes_applied=0,
+        pf_modified=False,
+        bmad_modified=False,
+    )
+
+    if dry_run:
+        return result
+
+    # Apply PF updates (YAML)
+    pf_updates = [c for c in plan.changes if c.action == "update-pf"]
+    if pf_updates and sprint_path:
+        from pf.sprint.story_update import update_story
+
+        for change in pf_updates:
+            update_result = update_story(
+                sprint_path,
+                change.pf_id,
+                status=change.target_value,
+            )
+            if update_result.get("success"):
+                result.changes_applied += 1
+                result.pf_modified = True
+            else:
+                result.errors.append(
+                    f"{change.pf_id}: PF update failed — {update_result.get('error', 'unknown')}"
+                )
+
+    # Apply BMAD updates (markdown files)
+    bmad_updates = [c for c in plan.changes if c.action == "update-bmad"]
+    if bmad_updates:
+        # Need bmad story data to find file paths
+        # Re-discover to get bmad_path for each key
+        bmad_paths: dict[str, str] = {}
+        if bmad_root:
+            config = load_pennyfarthing_config()
+            bmad_config = config.get("bmad", {})
+            story_subdir = bmad_config.get("story_dir", "implementation-artifacts")
+            from pf.bmad.parser import discover_bmad_stories as _discover
+
+            all_bmad = _discover(bmad_root, story_dir=story_subdir)
+            bmad_paths = {s["bmad_key"]: s["bmad_path"] for s in all_bmad}
+
+        for change in bmad_updates:
+            file_path = bmad_paths.get(change.bmad_key)
+            if not file_path:
+                result.errors.append(f"{change.bmad_key}: BMAD file not found")
+                continue
+            if _update_bmad_file_status(file_path, change.target_value):
+                result.changes_applied += 1
+                result.bmad_modified = True
+            else:
+                result.errors.append(f"{change.bmad_key}: Failed to update Status line")
+
+    # Import new BMAD stories not yet in PF
+    if import_new and plan.bmad_only and sprint_path and bmad_root:
+        result.new_stories_imported = _import_new_stories(
+            plan.bmad_only, bmad_root, sprint_path, repos, result
+        )
+
+    return result
+
+
+def _import_new_stories(
+    bmad_keys: list[str],
+    bmad_root: Path,
+    sprint_path: Path,
+    repos: str,
+    result: BmadSyncResult,
+) -> int:
+    """Import stories that exist in BMAD but not PF.
+
+    Returns count of successfully imported stories.
+    """
+    from pf.bmad.parser import discover_bmad_stories as _discover
+    from pf.sprint.yaml_io import read_sprint, write_sprint
+
+    config = load_pennyfarthing_config()
+    bmad_config = config.get("bmad", {})
+    story_subdir = bmad_config.get("story_dir", "implementation-artifacts")
+
+    all_bmad = _discover(bmad_root, story_dir=story_subdir)
+    bmad_by_key = {s["bmad_key"]: s for s in all_bmad}
+
+    data = read_sprint(sprint_path)
+    imported = 0
+
+    for key in bmad_keys:
+        bmad_story = bmad_by_key.get(key)
+        if not bmad_story:
+            continue
+
+        epic_num = int(bmad_story["epic_num"])
+
+        # Find or create the epic in sprint data
+        target_epic = None
+        for epic in data.get("epics", []):
+            epic_id = str(epic.get("id", "")).replace("epic-", "")
+            if epic_id == str(epic_num):
+                target_epic = epic
+                break
+
+        if target_epic is None:
+            # Create new epic shard
+            target_epic = {
+                "id": str(epic_num),
+                "title": f"Epic {epic_num}",
+                "status": "planning",
+                "priority": "P1",
+                "marker": "bmad",
+                "repos": repos,
+                "stories": [],
+            }
+            data.setdefault("epics", []).append(target_epic)
+
+        # Add story
+        pf_story = {
+            "id": bmad_story["id"],
+            "title": bmad_story["title"],
+            "points": bmad_story.get("points", 3),
+            "priority": bmad_story.get("priority", "P1"),
+            "status": bmad_story["status"],
+            "repos": repos,
+            "workflow": bmad_story.get("workflow", "tdd"),
+            "bmad_key": key,
+        }
+        target_epic.setdefault("stories", []).append(pf_story)
+        imported += 1
+
+    if imported > 0:
+        write_sprint(sprint_path, data)
+        result.pf_modified = True
+
+    return imported
+
+
+# =============================================================================
+# Formatting
+# =============================================================================
+
+
+def format_sync_plan(plan: BmadSyncPlan) -> str:
+    """Format a sync plan for human-readable display.
+
+    Args:
+        plan: The plan to format
+
+    Returns:
+        Formatted string.
+    """
+    lines: list[str] = []
+
+    lines.append(f"Matched: {len(plan.both)}  |  PF-only: {len(plan.pf_only)}  |  BMAD-only: {len(plan.bmad_only)}")
+    lines.append("")
+
+    if plan.changes:
+        lines.append(f"Changes ({len(plan.changes)}):")
+        for c in plan.changes:
+            arrow = "BMAD→PF" if c.action == "update-pf" else "PF→BMAD"
+            lines.append(
+                f"  {c.pf_id} ({c.bmad_key}): {c.field} {arrow}  "
+                f"{c.pf_value!r} / {c.bmad_value!r} → {c.target_value!r}"
+            )
+        lines.append("")
+
+    if plan.bmad_only:
+        lines.append(f"New in BMAD ({len(plan.bmad_only)}):")
+        for key in plan.bmad_only:
+            lines.append(f"  {key}")
+        lines.append("")
+
+    if plan.pf_only:
+        lines.append(f"PF-only ({len(plan.pf_only)}):")
+        for key in plan.pf_only:
+            lines.append(f"  {key}")
+        lines.append("")
+
+    if not plan.changes and not plan.bmad_only and not plan.pf_only:
+        lines.append("Everything is in sync.")
+
+    return "\n".join(lines)
+
+
+# =============================================================================
+# Drift Report
+# =============================================================================
+
+
+def drift_report(
+    sprint_path: Path,
+    bmad_root: Path,
+) -> str:
+    """Generate a drift report showing what's out of sync.
+
+    Args:
+        sprint_path: Path to PF sprint YAML
+        bmad_root: Path to BMAD _bmad-output/ root
+
+    Returns:
+        Formatted drift report string.
+    """
+    config = load_pennyfarthing_config()
+    bmad_config = config.get("bmad", {})
+    story_subdir = bmad_config.get("story_dir", "implementation-artifacts")
+
+    pf_stories = _collect_pf_stories(sprint_path)
+    bmad_stories = discover_bmad_stories(bmad_root, story_dir=story_subdir)
+
+    plan = generate_sync_plan(pf_stories, bmad_stories, direction="both")
+    return format_sync_plan(plan)