@pennyfarthing/core 10.0.2 → 10.0.3

package/pennyfarthing_scripts/jira/reconcile.py

@@ -0,0 +1,277 @@
+"""
+Jira vs YAML reconciliation report.
+
+Replaces jira-reconcile.sh (261 lines) with REST API calls.
+
+Compares sprint YAML against Jira to find:
+- Status mismatches
+- Missing Jira keys
+- Orphan issues (in Jira but not YAML)
+- Sprint membership discrepancies
+- Epic sync status
+
+Usage:
+    pf jira reconcile [--fix]
+"""
+
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from pennyfarthing_scripts.jira.client import (
+    JIRA_PROJECT,
+    get_client,
+    get_jira_field,
+    map_jira_to_status,
+    map_status_to_jira,
+)
+from pennyfarthing_scripts.sprint.loader import load_sprint
+
+
+def _normalize_status(status: str) -> str:
+    """Normalize status for comparison."""
+    return status.lower().replace(" ", "_")
+
+
+def reconcile(
+    *,
+    fix: bool = False,
+    sprint_path: Path | None = None,
+) -> dict[str, Any]:
+    """Generate reconciliation report comparing sprint YAML against Jira.
+
+    Args:
+        fix: If True, apply automatic fixes where safe
+        sprint_path: Path to sprint YAML (defaults to auto-detect)
+
+    Returns:
+        {success, report, mismatches, missing, orphans, not_in_sprint, fixed}
+    """
+    sprint_data = load_sprint()
+    if not sprint_data:
+        return {"success": False, "error": "Could not load sprint YAML"}
+
+    sprint_info = sprint_data.get("sprint", {})
+    sprint_name = sprint_info.get("name", "Unknown")
+    sprint_id = sprint_info.get("jira_sprint_id")
+
+    client = get_client()
+
+    # Collect all YAML stories
+    yaml_stories = []
+    for epic in sprint_data.get("epics", []):
+        for story in epic.get("stories", []):
+            yaml_stories.append({
+                "id": story.get("id", ""),
+                "jira": story.get("jira", ""),
+                "status": story.get("status", "backlog"),
+                "title": story.get("title", ""),
+            })
+
+    status_mismatches = []
+    missing_jira = []
+    orphans = []
+    not_in_sprint = []
+
+    # --- Check YAML stories against Jira ---
+    print("## Checking YAML Stories Against Jira...\n")
+
+    for story in yaml_stories:
+        jira_key = story["jira"]
+        if not jira_key:
+            missing_jira.append(story)
+            continue
+
+        issue = client.get_issue_sync(jira_key)
+        if not issue:
+            print(f"[!] {jira_key} not found in Jira", file=sys.stderr)
+            continue
+
+        jira_status = get_jira_field(issue, "fields.status.name", "")
+        yaml_status = story["status"]
+
+        # Compare normalized statuses
+        expected_jira = map_status_to_jira(yaml_status)
+        if _normalize_status(jira_status) != _normalize_status(expected_jira):
+            status_mismatches.append({
+                "jira_key": jira_key,
+                "yaml_status": yaml_status,
+                "jira_status": jira_status,
+            })
+
+    # --- Check Jira sprint against YAML ---
+    print("## Checking Jira Sprint Against YAML...\n")
+
+    if sprint_id:
+        # Find orphans: in Jira sprint but not in YAML
+        sprint_issues = client.search_issues_sync(
+            f"project={JIRA_PROJECT} AND labels=pennyfarthing "
+            f"AND sprint={sprint_id} AND status != Canceled",
+            fields=["key", "summary", "status"],
+        )
+
+        yaml_keys = {s["jira"] for s in yaml_stories if s["jira"]}
+        yaml_ids = {s["id"] for s in yaml_stories}
+
+        for issue in sprint_issues:
+            key = issue.get("key", "")
+            if key not in yaml_keys and key not in yaml_ids:
+                status = get_jira_field(issue, "fields.status.name", "Unknown")
+                summary = get_jira_field(issue, "fields.summary", "Unknown")
+                orphans.append({
+                    "jira_key": key,
+                    "status": status,
+                    "summary": summary,
+                })
+
+        # Find YAML stories not in sprint
+        print("## Checking for Issues Not in Sprint...\n")
+
+        no_sprint_issues = client.search_issues_sync(
+            f"project={JIRA_PROJECT} AND labels=pennyfarthing "
+            f"AND sprint is EMPTY AND status != Canceled",
+            fields=["key", "summary"],
+        )
+
+        for issue in no_sprint_issues:
+            key = issue.get("key", "")
+            if key in yaml_keys or key in yaml_ids:
+                summary = get_jira_field(issue, "fields.summary", "Unknown")
+                not_in_sprint.append({
+                    "jira_key": key,
+                    "summary": summary,
+                })
+
+    # --- Build report ---
+    report_lines = [
+        "# Jira vs YAML Reconciliation Report",
+        "",
+        f"**Sprint:** {sprint_name} (Jira Sprint ID: {sprint_id})",
+        f"**Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M')}",
+        "",
+        "---",
+        "",
+        f"## Status Mismatches ({len(status_mismatches)})",
+        "",
+    ]
+
+    if not status_mismatches:
+        report_lines.append("No status mismatches found.")
+    else:
+        report_lines.append("| Jira Key | YAML Status | Jira Status | Action |")
+        report_lines.append("|----------|-------------|-------------|--------|")
+        for m in status_mismatches:
+            report_lines.append(
+                f"| {m['jira_key']} | {m['yaml_status']} | {m['jira_status']} | Update YAML or Jira |"
+            )
+
+    report_lines.extend([
+        "",
+        f"## YAML Stories Missing Jira Key ({len(missing_jira)})",
+        "",
+    ])
+
+    if not missing_jira:
+        report_lines.append("All YAML stories have Jira keys.")
+    else:
+        report_lines.append("| YAML ID | Title | Status | Action |")
+        report_lines.append("|---------|-------|--------|--------|")
+        for m in missing_jira:
+            title = m["title"][:40]
+            report_lines.append(
+                f"| {m['id']} | {title} | {m['status']} | Create Jira issue |"
+            )
+
+    report_lines.extend([
+        "",
+        f"## Jira Issues Not in YAML ({len(orphans)})",
+        "",
+    ])
+
+    if not orphans:
+        report_lines.append("All sprint issues are tracked in YAML.")
+    else:
+        report_lines.append("| Jira Key | Status | Summary | Action |")
+        report_lines.append("|----------|--------|---------|--------|")
+        for o in orphans:
+            summary = o["summary"][:40]
+            action = (
+                "Info: Completed (not in current YAML)"
+                if o["status"] == "Done"
+                else "Add to YAML or remove from sprint"
+            )
+            report_lines.append(
+                f"| {o['jira_key']} | {o['status']} | {summary} | {action} |"
+            )
+
+    report_lines.extend([
+        "",
+        f"## YAML Stories Not in Jira Sprint ({len(not_in_sprint)})",
+        "",
+    ])
+
+    if not not_in_sprint:
+        report_lines.append("All YAML stories are in Jira sprint.")
+    else:
+        report_lines.append("| Jira Key | Summary | Action |")
+        report_lines.append("|----------|---------|--------|")
+        for n in not_in_sprint:
+            summary = n["summary"][:50]
+            report_lines.append(
+                f"| {n['jira_key']} | {summary} | Add to sprint {sprint_id} |"
+            )
+
+    # Epic sync check
+    report_lines.extend(["", "## Epic Sync Check", ""])
+    report_lines.append("| YAML Epic ID | Jira Field | Title |")
+    report_lines.append("|--------------|------------|-------|")
+    for epic in sprint_data.get("epics", []):
+        eid = epic.get("id", "")
+        jira_key = epic.get("jira", "")
+        title = epic.get("title", "")
+        jira_display = jira_key if jira_key else "MISSING"
+        report_lines.append(f"| {eid} | {jira_display} | {title} |")
+
+    # Summary
+    total = len(status_mismatches) + len(missing_jira) + len(orphans) + len(not_in_sprint)
+    report_lines.extend(["", "---", ""])
+    if total == 0:
+        report_lines.append("Sync Status: CLEAN - No discrepancies found!")
+    else:
+        report_lines.append(f"Sync Status: {total} issue(s) found")
+
+    # Fix mode
+    fixed = []
+    if fix and not_in_sprint and sprint_id:
+        report_lines.extend(["", "## Applying Fixes...", ""])
+        for n in not_in_sprint:
+            key = n["jira_key"]
+            print(f"Adding {key} to sprint {sprint_id}...")
+            result = client.add_to_sprint_sync(sprint_id, key)
+            if result.get("success"):
+                print("  Done")
+                fixed.append(key)
+            else:
+                print(f"  Failed: {result.get('reason', 'unknown')}")
+
+        report_lines.extend([
+            "",
+            "Fix mode completed. Manual review still needed for:",
+            "- Status mismatches (requires decision on which source is correct)",
+            "- Missing Jira keys (requires creating new issues)",
+            "- Orphan issues (requires adding to YAML or removing from sprint)",
+        ])
+
+    report = "\n".join(report_lines)
+    print(report)
+
+    return {
+        "success": True,
+        "report": report,
+        "mismatches": status_mismatches,
+        "missing": missing_jira,
+        "orphans": orphans,
+        "not_in_sprint": not_in_sprint,
+        "fixed": fixed,
+    }

package/pennyfarthing_scripts/jira/story.py

@@ -0,0 +1,219 @@
+"""
+Sync a single story between Pennyfarthing sprint YAML and Jira.
+
+Usage:
+    python -m pennyfarthing_scripts.jira story <story_key> [options]
+
+Options:
+    --transition    Sync status (transition Jira issue)
+    --points        Sync story points
+    --comment MSG   Add comment to issue
+    --dry-run       Show what would be done without making changes
+
+Examples:
+    python -m pennyfarthing_scripts.jira story 63-7 --transition
+    python -m pennyfarthing_scripts.jira story MSSCI-12401 --points --dry-run
+"""
+
+import argparse
+import sys
+from typing import Any
+
+from pennyfarthing_scripts.jira import client as jira_client
+from pennyfarthing_scripts.sprint.loader import (
+    find_epic,
+    find_story,
+    get_story_by_id,
+    load_sprint as load_current_sprint,
+)
+
+
+def parse_args(args: list[str] | None = None) -> argparse.Namespace:
+    """Parse command line arguments.
+
+    Args:
+        args: Command line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Parsed arguments namespace
+    """
+    parser = argparse.ArgumentParser(
+        description="Sync a single story between Pennyfarthing and Jira"
+    )
+    parser.add_argument("story_key", help="Story ID (e.g., 63-7) or Jira key (MSSCI-12401)")
+    parser.add_argument("--transition", action="store_true", help="Sync status")
+    parser.add_argument("--points", action="store_true", help="Sync story points")
+    parser.add_argument("--comment", type=str, help="Add comment to issue")
+    parser.add_argument("--dry-run", action="store_true", help="Show changes without applying")
+
+    return parser.parse_args(args)
+
+
+def get_story_from_sprint(story_key: str) -> dict[str, Any] | None:
+    """Find a story in the sprint YAML.
+
+    Args:
+        story_key: Story ID or Jira key
+
+    Returns:
+        Story dict if found, None otherwise
+    """
+    # Try direct lookup first
+    story = get_story_by_id(story_key)
+    if story:
+        return story
+
+    # If it looks like a local ID (e.g., "63-7"), try finding via epic
+    if "-" in story_key and not story_key.startswith("MSSCI"):
+        sprint_data = load_current_sprint()
+        if sprint_data:
+            parts = story_key.split("-")
+            if len(parts) >= 2:
+                epic_num = parts[0]
+                epic = find_epic(sprint_data, epic_num)
+                if epic:
+                    return find_story(epic, story_key)
+
+    return None
+
+
+def fetch_jira_issue(jira_key: str) -> dict[str, Any] | None:
+    """Fetch issue from Jira.
+
+    Args:
+        jira_key: Jira issue key
+
+    Returns:
+        Issue JSON if found, None otherwise
+    """
+    return jira_client.get_issue(jira_key)
+
+
+def sync_story(
+    story_key: str,
+    *,
+    do_transition: bool = False,
+    sync_points: bool = False,
+    comment: str | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Sync a story between Pennyfarthing and Jira.
+
+    Args:
+        story_key: Story ID or Jira key
+        do_transition: Whether to sync status
+        sync_points: Whether to sync story points
+        comment: Comment to add (optional)
+        dry_run: If True, show changes without applying
+
+    Returns:
+        Result dict with success, actions, error fields
+    """
+    # Find story in sprint YAML
+    story = get_story_from_sprint(story_key)
+    if not story:
+        return {
+            "success": False,
+            "error": f"Story '{story_key}' not found in sprint YAML",
+        }
+
+    jira_key = story.get("jira")
+    if not jira_key:
+        return {
+            "success": False,
+            "error": f"Story '{story_key}' has no Jira key",
+        }
+
+    # Fetch current Jira state
+    issue = fetch_jira_issue(jira_key)
+    if not issue:
+        return {
+            "success": False,
+            "error": f"Could not fetch Jira issue {jira_key}",
+        }
+
+    actions = []
+    errors = []
+
+    # Sync status if requested
+    if do_transition:
+        current_jira_status = jira_client.get_jira_field(issue, "fields.status.name")
+        target_status = jira_client.map_status_to_jira(story.get("status"))
+
+        if current_jira_status != target_status:
+            action = f"transition {jira_key}: {current_jira_status} -> {target_status}"
+            if dry_run:
+                actions.append(f"[DRY-RUN] {action}")
+            else:
+                if jira_client.update_issue_status(jira_key, target_status):
+                    actions.append(action)
+                else:
+                    errors.append(f"Failed to transition {jira_key}")
+        else:
+            actions.append(f"status already {current_jira_status}")
+
+    # Sync points if requested
+    if sync_points:
+        story_points = story.get("points")
+        if story_points is not None:
+            current_points = jira_client.get_story_points(jira_key, issue)
+            if current_points != story_points:
+                action = f"sync points {jira_key}: {current_points} -> {story_points}"
+                if dry_run:
+                    actions.append(f"[DRY-RUN] {action}")
+                else:
+                    # Note: point sync requires REST API, not CLI
+                    actions.append(f"[SKIP] {action} (requires REST API)")
+
+    # Add comment if provided
+    if comment:
+        action = f"add comment to {jira_key}"
+        if dry_run:
+            actions.append(f"[DRY-RUN] {action}")
+        else:
+            if jira_client.add_comment(jira_key, comment):
+                actions.append(action)
+            else:
+                errors.append(f"Failed to add comment to {jira_key}")
+
+    return {
+        "success": len(errors) == 0,
+        "story_id": story.get("id"),
+        "jira_key": jira_key,
+        "actions": actions,
+        "errors": errors if errors else None,
+        "dry_run": dry_run,
+    }
+
+
+def main(args: list[str] | None = None) -> int:
+    """CLI entry point.
+
+    Args:
+        args: Command line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    parsed_args = parse_args(args)
+
+    result = sync_story(
+        parsed_args.story_key,
+        do_transition=parsed_args.transition,
+        sync_points=parsed_args.points,
+        comment=parsed_args.comment,
+        dry_run=parsed_args.dry_run,
+    )
+
+    if result["success"]:
+        print(f"Synced {result.get('story_id', parsed_args.story_key)}")
+        for action in result.get("actions", []):
+            print(f"  {action}")
+        return 0
+    else:
+        print(f"Failed: {result.get('error', 'Unknown error')}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())