@pennyfarthing/core 11.3.3 → 11.3.4

package/pennyfarthing-dist/pf/bmad/test_parser.py

@@ -0,0 +1,253 @@
+"""Tests for BMAD markdown parser."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from pf.bmad.parser import (
+    BMAD_TO_PF_STATUS,
+    PF_TO_BMAD_STATUS,
+    discover_bmad_stories,
+    map_bmad_to_pf,
+    map_pf_to_bmad,
+    parse_bmad_epic,
+    parse_bmad_story,
+)
+
+# =============================================================================
+# Sample BMAD content
+# =============================================================================
+
+SAMPLE_STORY = """\
+# Story 2.1: OCSF Event Schema
+
+Status: ready-for-dev
+Story-Key: 2-1-ocsf-event-schema
+Jira: DPGD-24 / DPGD-35
+Epic: 2 - Core Event Ingestion & Storage
+Date: 2026-02-17
+
+## Story
+
+As a **security engineer**,
+I want **a standardized event schema based on OCSF**,
+So that **all ingested events have consistent structure**.
+
+## Acceptance Criteria
+
+**AC-1: Schema Validation**
+**Given** an incoming event
+**When** it is ingested
+**Then** it conforms to the OCSF schema
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Define schema (AC: #1)
+"""
+
+SAMPLE_STORY_COMPLETED = """\
+# Story 1.1: Initialize Cargo Workspace
+
+Status: completed
+Story-Key: 1-1-initialize-cargo-workspace
+Jira: DPGD-10 / DPGD-15
+Epic: 1 - Project Foundation & Developer Experience
+Date: 2026-02-17
+
+## Story
+
+As a **developer**,
+I want **a properly initialized Cargo workspace**,
+So that **I can start developing**.
+
+## Acceptance Criteria
+
+**AC-1: Workspace Initialized**
+**Given** a fresh clone
+**When** I run cargo build
+**Then** it succeeds
+"""
+
+SAMPLE_EPIC = """\
+---
+epicNumber: 2
+title: "Core Event Ingestion & Storage"
+phase: "MVP"
+status: "draft"
+storyCount: 15
+frsAddressed: ["FR25-FR40"]
+nfrsAddressed: ["NFR10-NFR15"]
+---
+
+# Epic 2: Core Event Ingestion & Storage
+
+## Epic Goal
+
+Enable high-throughput event ingestion with columnar storage.
+"""
+
+
+# =============================================================================
+# Status Mapping
+# =============================================================================
+
+
+class TestStatusMapping:
+    def test_bmad_to_pf_all_values(self):
+        assert map_bmad_to_pf("draft") == "planning"
+        assert map_bmad_to_pf("ready-for-dev") == "ready"
+        assert map_bmad_to_pf("in-progress") == "in_progress"
+        assert map_bmad_to_pf("in-review") == "in_progress"
+        assert map_bmad_to_pf("completed") == "done"
+        assert map_bmad_to_pf("blocked") == "backlog"
+
+    def test_bmad_to_pf_unknown_defaults_to_planning(self):
+        assert map_bmad_to_pf("unknown-status") == "planning"
+
+    def test_bmad_to_pf_case_insensitive(self):
+        assert map_bmad_to_pf("Ready-For-Dev") == "ready"
+        assert map_bmad_to_pf("COMPLETED") == "done"
+
+    def test_pf_to_bmad_all_values(self):
+        assert map_pf_to_bmad("planning") == "draft"
+        assert map_pf_to_bmad("ready") == "ready-for-dev"
+        assert map_pf_to_bmad("in_progress") == "in-progress"
+        assert map_pf_to_bmad("done") == "completed"
+        assert map_pf_to_bmad("backlog") == "blocked"
+        assert map_pf_to_bmad("canceled") == "completed"
+
+    def test_pf_to_bmad_unknown_defaults_to_draft(self):
+        assert map_pf_to_bmad("unknown") == "draft"
+
+    def test_roundtrip_bmad_through_pf(self):
+        """BMAD → PF → BMAD should preserve status (except in-review → in-progress → in-progress)."""
+        for bmad_status, pf_status in BMAD_TO_PF_STATUS.items():
+            roundtrip = map_pf_to_bmad(pf_status)
+            # in-review maps to in_progress which maps back to in-progress (not in-review)
+            if bmad_status == "in-review":
+                assert roundtrip == "in-progress"
+            else:
+                assert roundtrip == bmad_status, f"Roundtrip failed for {bmad_status}"
+
+
+# =============================================================================
+# Story Parsing
+# =============================================================================
+
+
+class TestParseStory:
+    def test_parse_basic_story(self, tmp_path: Path):
+        story_file = tmp_path / "2-1-ocsf-event-schema.md"
+        story_file.write_text(SAMPLE_STORY)
+
+        result = parse_bmad_story(story_file)
+
+        assert result["id"] == "2-1"
+        assert result["title"] == "OCSF Event Schema"
+        assert result["status"] == "ready"
+        assert result["bmad_key"] == "2-1-ocsf-event-schema"
+        assert result["bmad_status"] == "ready-for-dev"
+        assert result["jira"] == "DPGD-24 / DPGD-35"
+        assert result["epic_num"] == "2"
+        assert result["points"] == 3
+        assert "AC-1" in result["acceptance_criteria"]
+
+    def test_parse_completed_story(self, tmp_path: Path):
+        story_file = tmp_path / "1-1-initialize-cargo-workspace.md"
+        story_file.write_text(SAMPLE_STORY_COMPLETED)
+
+        result = parse_bmad_story(story_file)
+
+        assert result["id"] == "1-1"
+        assert result["status"] == "done"
+        assert result["bmad_status"] == "completed"
+        assert result["bmad_key"] == "1-1-initialize-cargo-workspace"
+
+    def test_parse_story_with_missing_fields(self, tmp_path: Path):
+        minimal = "# Story 5.3: Retry Logic\n\nSome content\n"
+        story_file = tmp_path / "5-3-retry-logic.md"
+        story_file.write_text(minimal)
+
+        result = parse_bmad_story(story_file)
+
+        # Should still parse with defaults
+        assert result["status"] == "planning"
+        assert result["bmad_status"] == "draft"
+        assert result["points"] == 3
+
+
+# =============================================================================
+# Epic Parsing
+# =============================================================================
+
+
+class TestParseEpic:
+    def test_parse_epic_with_frontmatter(self, tmp_path: Path):
+        epic_file = tmp_path / "epic-02-event-ingestion.md"
+        epic_file.write_text(SAMPLE_EPIC)
+
+        result = parse_bmad_epic(epic_file)
+
+        assert result["epicNumber"] == 2
+        assert result["title"] == "Core Event Ingestion & Storage"
+        assert result["phase"] == "MVP"
+        assert result["status"] == "draft"
+        assert result["storyCount"] == 15
+
+    def test_parse_epic_without_frontmatter(self, tmp_path: Path):
+        epic_file = tmp_path / "epic-99-something.md"
+        epic_file.write_text("# Epic 99: Something\n\nNo frontmatter here.\n")
+
+        result = parse_bmad_epic(epic_file)
+
+        assert result["epicNumber"] == 0
+        assert result["status"] == "draft"
+
+
+# =============================================================================
+# Discovery
+# =============================================================================
+
+
+class TestDiscovery:
+    def test_discover_stories(self, tmp_path: Path):
+        impl = tmp_path / "implementation-artifacts"
+        impl.mkdir()
+
+        (impl / "1-1-workspace.md").write_text(SAMPLE_STORY_COMPLETED)
+        (impl / "2-1-schema.md").write_text(SAMPLE_STORY)
+        # Meta files should be skipped
+        (impl / "0-1-bmad-lifecycle.md").write_text("# Meta file\n")
+        # Non-matching files should be skipped
+        (impl / "readme.md").write_text("# Readme\n")
+
+        stories = discover_bmad_stories(tmp_path)
+
+        assert len(stories) == 2
+        assert stories[0]["id"] == "1-1"
+        assert stories[1]["id"] == "2-1"
+
+    def test_discover_stories_empty_dir(self, tmp_path: Path):
+        stories = discover_bmad_stories(tmp_path)
+        assert stories == []
+
+    def test_discover_epics(self, tmp_path: Path):
+        epics_dir = tmp_path / "planning-artifacts" / "epics"
+        epics_dir.mkdir(parents=True)
+
+        (epics_dir / "epic-01-foundation.md").write_text(
+            "---\nepicNumber: 1\ntitle: Foundation\nphase: MVP\nstatus: draft\nstoryCount: 5\n---\n"
+        )
+        (epics_dir / "epic-02-ingestion.md").write_text(SAMPLE_EPIC)
+        (epics_dir / "index.md").write_text("# Index\n")
+
+        from pf.bmad.parser import discover_bmad_epics
+
+        epics = discover_bmad_epics(tmp_path)
+
+        assert len(epics) == 2
+        assert epics[0]["epicNumber"] == 1
+        assert epics[1]["epicNumber"] == 2

package/pennyfarthing-dist/pf/bmad/test_sync.py

@@ -0,0 +1,223 @@
+"""Tests for BMAD sync engine."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from pf.bmad.sync import (
+    BmadSyncChange,
+    BmadSyncPlan,
+    _update_bmad_file_status,
+    format_sync_plan,
+    generate_sync_plan,
+)
+
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+def _pf_story(story_id: str, bmad_key: str, status: str = "ready") -> dict:
+    return {
+        "id": story_id,
+        "title": f"Story {story_id}",
+        "status": status,
+        "bmad_key": bmad_key,
+        "points": 3,
+    }
+
+
+def _bmad_story(bmad_key: str, bmad_status: str = "ready-for-dev") -> dict:
+    from pf.bmad.parser import map_bmad_to_pf
+
+    parts = bmad_key.split("-", 2)
+    return {
+        "id": f"{parts[0]}-{parts[1]}",
+        "title": f"Story {bmad_key}",
+        "status": map_bmad_to_pf(bmad_status),
+        "bmad_key": bmad_key,
+        "bmad_status": bmad_status,
+        "bmad_path": f"/fake/{bmad_key}.md",
+        "epic_num": parts[0],
+        "points": 3,
+    }
+
+
+# =============================================================================
+# Sync Plan Generation
+# =============================================================================
+
+
+class TestGenerateSyncPlan:
+    def test_all_in_sync(self):
+        pf = [_pf_story("1-1", "1-1-workspace", "ready")]
+        bmad = [_bmad_story("1-1-workspace", "ready-for-dev")]
+
+        plan = generate_sync_plan(pf, bmad, direction="both")
+
+        assert plan.both == ["1-1-workspace"]
+        assert plan.changes == []
+        assert plan.pf_only == []
+        assert plan.bmad_only == []
+
+    def test_pull_detects_bmad_change(self):
+        pf = [_pf_story("1-1", "1-1-workspace", "ready")]
+        bmad = [_bmad_story("1-1-workspace", "completed")]
+
+        plan = generate_sync_plan(pf, bmad, direction="pull")
+
+        assert len(plan.changes) == 1
+        change = plan.changes[0]
+        assert change.action == "update-pf"
+        assert change.pf_value == "ready"
+        assert change.bmad_value == "completed"
+        assert change.target_value == "done"
+
+    def test_push_detects_pf_change(self):
+        pf = [_pf_story("2-1", "2-1-schema", "done")]
+        bmad = [_bmad_story("2-1-schema", "ready-for-dev")]
+
+        plan = generate_sync_plan(pf, bmad, direction="push")
+
+        assert len(plan.changes) == 1
+        change = plan.changes[0]
+        assert change.action == "update-bmad"
+        assert change.target_value == "completed"
+
+    def test_both_pf_wins(self):
+        pf = [_pf_story("1-1", "1-1-workspace", "in_progress")]
+        bmad = [_bmad_story("1-1-workspace", "ready-for-dev")]
+
+        plan = generate_sync_plan(pf, bmad, direction="both", pf_wins=True)
+
+        assert len(plan.changes) == 1
+        assert plan.changes[0].action == "update-bmad"
+        assert plan.changes[0].target_value == "in-progress"
+
+    def test_both_bmad_wins(self):
+        pf = [_pf_story("1-1", "1-1-workspace", "in_progress")]
+        bmad = [_bmad_story("1-1-workspace", "completed")]
+
+        plan = generate_sync_plan(pf, bmad, direction="both", pf_wins=False)
+
+        assert len(plan.changes) == 1
+        assert plan.changes[0].action == "update-pf"
+        assert plan.changes[0].target_value == "done"
+
+    def test_pf_only_stories(self):
+        pf = [_pf_story("1-1", "1-1-workspace"), _pf_story("9-9", "9-9-custom")]
+        bmad = [_bmad_story("1-1-workspace")]
+
+        plan = generate_sync_plan(pf, bmad, direction="both")
+
+        assert plan.pf_only == ["9-9-custom"]
+        assert plan.both == ["1-1-workspace"]
+
+    def test_bmad_only_stories(self):
+        pf = [_pf_story("1-1", "1-1-workspace")]
+        bmad = [_bmad_story("1-1-workspace"), _bmad_story("3-2-rule-parser")]
+
+        plan = generate_sync_plan(pf, bmad, direction="both")
+
+        assert plan.bmad_only == ["3-2-rule-parser"]
+
+    def test_multiple_changes(self):
+        pf = [
+            _pf_story("1-1", "1-1-workspace", "done"),
+            _pf_story("2-1", "2-1-schema", "in_progress"),
+        ]
+        bmad = [
+            _bmad_story("1-1-workspace", "ready-for-dev"),
+            _bmad_story("2-1-schema", "ready-for-dev"),
+        ]
+
+        plan = generate_sync_plan(pf, bmad, direction="push")
+
+        assert len(plan.changes) == 2
+
+    def test_empty_inputs(self):
+        plan = generate_sync_plan([], [], direction="both")
+
+        assert plan.changes == []
+        assert plan.both == []
+        assert plan.pf_only == []
+        assert plan.bmad_only == []
+
+
+# =============================================================================
+# BMAD File Update
+# =============================================================================
+
+
+class TestUpdateBmadFile:
+    def test_update_status_line(self, tmp_path: Path):
+        md_file = tmp_path / "1-1-workspace.md"
+        md_file.write_text(
+            "# Story 1.1: Workspace\n\n"
+            "Status: ready-for-dev\n"
+            "Story-Key: 1-1-workspace\n"
+            "Jira: DPGD-10 / DPGD-15\n\n"
+            "## Story\n\nContent here.\n"
+        )
+
+        result = _update_bmad_file_status(str(md_file), "completed")
+
+        assert result is True
+        content = md_file.read_text()
+        assert "Status: completed" in content
+        assert "ready-for-dev" not in content
+        # Other lines preserved
+        assert "Story-Key: 1-1-workspace" in content
+        assert "Jira: DPGD-10 / DPGD-15" in content
+
+    def test_update_nonexistent_file(self, tmp_path: Path):
+        result = _update_bmad_file_status(str(tmp_path / "missing.md"), "completed")
+        assert result is False
+
+    def test_update_file_without_status_line(self, tmp_path: Path):
+        md_file = tmp_path / "no-status.md"
+        md_file.write_text("# No status\n\nJust content.\n")
+
+        result = _update_bmad_file_status(str(md_file), "completed")
+        assert result is False
+
+
+# =============================================================================
+# Formatting
+# =============================================================================
+
+
+class TestFormatSyncPlan:
+    def test_format_empty_plan(self):
+        plan = BmadSyncPlan()
+        output = format_sync_plan(plan)
+        assert "Everything is in sync" in output
+
+    def test_format_with_changes(self):
+        plan = BmadSyncPlan(
+            changes=[
+                BmadSyncChange(
+                    bmad_key="1-1-workspace",
+                    pf_id="1-1",
+                    field="status",
+                    action="update-pf",
+                    pf_value="ready",
+                    bmad_value="completed",
+                    target_value="done",
+                )
+            ],
+            both=["1-1-workspace"],
+        )
+        output = format_sync_plan(plan)
+        assert "Changes (1)" in output
+        assert "BMAD→PF" in output
+        assert "1-1-workspace" in output
+
+    def test_format_with_new_bmad(self):
+        plan = BmadSyncPlan(bmad_only=["3-2-rule-parser", "3-3-rule-engine"])
+        output = format_sync_plan(plan)
+        assert "New in BMAD (2)" in output
+        assert "3-2-rule-parser" in output

package/pennyfarthing-dist/pf/brownfield/__init__.py

@@ -0,0 +1,35 @@
+"""
+Brownfield discovery module for Pennyfarthing.
+
+Analyzes existing codebases and generates AI-ready documentation.
+"""
+
+from pf.brownfield.discover import (
+    DepthLevel,
+    DiscoveryResult,
+    ProjectType,
+    detect_architecture_patterns,
+    detect_project_type,
+    detect_tech_stack,
+    discover,
+    generate_ai_guidance_doc,
+    generate_project_overview,
+    generate_source_tree_doc,
+    generate_tech_stack_doc,
+    scan_directory_structure,
+)
+
+__all__ = [
+    "DepthLevel",
+    "ProjectType",
+    "DiscoveryResult",
+    "detect_project_type",
+    "detect_tech_stack",
+    "scan_directory_structure",
+    "detect_architecture_patterns",
+    "generate_project_overview",
+    "generate_tech_stack_doc",
+    "generate_source_tree_doc",
+    "generate_ai_guidance_doc",
+    "discover",
+]

package/pennyfarthing-dist/pf/brownfield/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for python -m pf.brownfield."""
+
+import sys
+
+from pf.brownfield.cli import cli
+
+if __name__ == "__main__":
+    sys.exit(cli())

package/pennyfarthing-dist/pf/brownfield/cli.py

@@ -0,0 +1,130 @@
+"""
+Brownfield CLI - Analyze existing codebases.
+
+Usage:
+    python -m pf.brownfield <subcommand> [args]
+
+Subcommands:
+    scan        Scan codebase and generate documentation
+"""
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+from pf.brownfield.discover import (
+    DepthLevel,
+    discover,
+)
+
+
+def scan(args: list[str]) -> int:
+    """Scan codebase and generate documentation."""
+    parser = argparse.ArgumentParser(
+        prog="brownfield scan",
+        description="Scan codebase and generate AI-ready documentation",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Path to scan (default: current directory)",
+    )
+    parser.add_argument(
+        "--depth",
+        choices=["quick", "standard", "deep"],
+        default="standard",
+        help="Scan depth level",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        help="Output directory for generated docs",
+    )
+
+    parsed = parser.parse_args(args)
+
+    path = Path(parsed.path).resolve()
+    depth = DepthLevel(parsed.depth)
+    output_dir = Path(parsed.output) if parsed.output else None
+
+    result = asyncio.run(discover(path, depth, output_dir))
+
+    if not result.success:
+        print(f"Error: {result.error}", file=sys.stderr)
+        return 1
+
+    print(f"Discovery complete: {result.project_name}")
+    print(f"Type: {result.project_type.value}")
+    print(f"Tech stack: {len(result.tech_stack)} items detected")
+
+    return 0
+
+
+# Subcommand registry
+SUBCOMMANDS = {
+    "scan": scan,
+}
+
+
+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="brownfield",
+        description="Brownfield codebase discovery for Pennyfarthing",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Subcommands:
+    scan [path] [opts]      Scan codebase and generate docs
+
+Examples:
+    brownfield scan
+    brownfield scan /path/to/project
+    brownfield scan --depth deep
+    brownfield scan . --output docs/brownfield
+""",
+    )
+
+    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())