@pennyfarthing/core 10.1.0 → 10.2.0

package/pennyfarthing_scripts/hotspots/analyze.py

@@ -1,17 +1,18 @@
 """
 Core hotspot analysis engine.
 
-Parses git log history, computes per-file metrics, and produces scored hotspot results.
-Reuses async git subprocess pattern from git/status_all.py.
+Uses PyDriller to mine git history, computes per-file metrics, and produces
+scored hotspot results. Falls back to raw git log parsing if PyDriller is unavailable.
 """
 
 from __future__ import annotations
 
 import asyncio
 import fnmatch
+import logging
 import re
 from collections import defaultdict
-from datetime import datetime, timezone
+from datetime import UTC, datetime, timedelta
 from pathlib import Path
 
 from pennyfarthing_scripts.hotspots.models import (
@@ -21,6 +22,8 @@ from pennyfarthing_scripts.hotspots.models import (
     MultiRepoHotspotResult,
 )
 
+logger = logging.getLogger("hotspots")
+
 # Scoring weights (must sum to 1.0)
 WEIGHT_BUG_FIXES = 0.35
 WEIGHT_CHANGES = 0.30
@@ -59,6 +62,30 @@ DEFAULT_EXCLUDES = [
     "*.d.ts.map",
     # CI config
     ".github/*",
+    # Sprint/session operational files (not code quality signals)
+    "sprint/*",
+    ".session/*",
+    # Config/manifest files — high churn but not code quality signals
+    "package.json",
+    "*/package.json",
+    "tsconfig.json",
+    "*/tsconfig.json",
+    "tsconfig.*.json",
+    "*/tsconfig.*.json",
+    # Documentation — frequently edited but not code hotspots
+    "*.md",
+    "CLAUDE.md",
+    "*/CLAUDE.md",
+    "CLAUDE-*.md",
+    "*/CLAUDE-*.md",
+    "README.md",
+    "*/README.md",
+    "CHANGELOG.md",
+    "*/CHANGELOG.md",
+    "docs/*",
+    # YAML config (sprint, workflow, etc.)
+    "*.yaml",
+    "*.yml",
 ]
 
 # Regex for identifying bug-fix commits
@@ -286,6 +313,8 @@ async def analyze_repo(
 ) -> HotspotResult:
     """Analyze a single repository for code hotspots.
 
+    Uses PyDriller for git mining when available, falls back to raw git log parsing.
+
     Args:
         name: Display name for the repository
         path: Path to the git repository
@@ -308,6 +337,87 @@ async def analyze_repo(
             error=f"Path not found: {resolved}",
         )
 
+    try:
+        return await _analyze_repo_pydriller(name, resolved, days, all_excludes)
+    except ImportError:
+        logger.info("[hotspots] PyDriller not available, using git log fallback")
+        return await _analyze_repo_gitlog(name, resolved, days, all_excludes, branch)
+
+
+async def _analyze_repo_pydriller(
+    name: str,
+    resolved: Path,
+    days: int,
+    all_excludes: list[str],
+) -> HotspotResult:
+    """PyDriller-backed hotspot analysis."""
+    from pydriller import Repository
+
+    since = datetime.now(UTC) - timedelta(days=days)
+    now = datetime.now(UTC)
+
+    file_metrics: dict[str, dict] = defaultdict(
+        lambda: {
+            "change_count": 0,
+            "bug_fix_count": 0,
+            "authors": set(),
+            "lines_added": 0,
+            "lines_deleted": 0,
+            "last_changed": "",
+        }
+    )
+
+    def _collect() -> int:
+        commit_count = 0
+        repo = Repository(str(resolved), since=since)
+        for commit in repo.traverse_commits():
+            commit_count += 1
+            is_fix = is_bug_fix_commit(commit.msg)
+            commit_date = commit.committer_date.isoformat()
+
+            for mod in commit.modified_files:
+                fpath = mod.new_path or mod.old_path
+                if not fpath:
+                    continue
+                if _should_exclude(fpath, all_excludes):
+                    continue
+
+                m = file_metrics[fpath]
+                m["change_count"] += 1
+                if is_fix:
+                    m["bug_fix_count"] += 1
+                m["authors"].add(commit.author.name)
+                m["lines_added"] += mod.added_lines
+                m["lines_deleted"] += mod.deleted_lines
+                if not m["last_changed"] or commit_date > m["last_changed"]:
+                    m["last_changed"] = commit_date
+        return commit_count
+
+    loop = asyncio.get_event_loop()
+    commit_count = await loop.run_in_executor(None, _collect)
+    logger.info("[hotspots] PyDriller: %d commits, %d files after filtering",
+                commit_count, len(file_metrics))
+
+    if not file_metrics:
+        return HotspotResult(
+            success=True,
+            repo_name=name,
+            repo_path=str(resolved),
+            time_window_days=days,
+            commit_count=commit_count,
+        )
+
+    return _build_hotspot_result(name, resolved, days, commit_count, file_metrics, now)
+
+
+async def _analyze_repo_gitlog(
+    name: str,
+    resolved: Path,
+    days: int,
+    all_excludes: list[str],
+    branch: str,
+) -> HotspotResult:
+    """Fallback: raw git log parsing."""
     stdout, stderr, rc = await _run_git_log(resolved, days, branch)
 
     if rc != 0:
@@ -330,7 +440,6 @@ async def analyze_repo(
             commit_count=0,
         )
 
-    # Aggregate per-file metrics
     file_metrics: dict[str, dict] = defaultdict(
         lambda: {
             "change_count": 0,
@@ -342,7 +451,7 @@ async def analyze_repo(
         }
     )
 
-    now = datetime.now(timezone.utc)
+    now = datetime.now(UTC)
 
     for commit in commits:
         is_fix = is_bug_fix_commit(commit["message"])
@@ -358,7 +467,6 @@ async def analyze_repo(
             m["authors"].add(commit["author"])
             m["lines_added"] += file_info["added"]
             m["lines_deleted"] += file_info["deleted"]
-            # Track most recent change date
             if not m["last_changed"] or commit["date"] > m["last_changed"]:
                 m["last_changed"] = commit["date"]
 
@@ -371,7 +479,18 @@ async def analyze_repo(
             commit_count=len(commits),
         )
 
-    # Compute normalization maximums
+    return _build_hotspot_result(name, resolved, days, len(commits), file_metrics, now)
+
+
+def _build_hotspot_result(
+    name: str,
+    resolved: Path,
+    days: int,
+    commit_count: int,
+    file_metrics: dict[str, dict],
+    now: datetime,
+) -> HotspotResult:
+    """Build scored HotspotResult from aggregated file metrics."""
     max_changes = max(m["change_count"] for m in file_metrics.values())
     max_bugs = max(m["bug_fix_count"] for m in file_metrics.values()) or 1
     max_authors = max(len(m["authors"]) for m in file_metrics.values())
@@ -379,13 +498,11 @@ async def analyze_repo(
         m["lines_added"] + m["lines_deleted"] for m in file_metrics.values()
     ) or 1
 
-    # Build FileHotspot list with scores
     file_hotspots = []
     for fpath, m in file_metrics.items():
         churn = m["lines_added"] + m["lines_deleted"]
 
-        # Compute age in days
-        age_days = days  # default to full window
+        age_days = days
         if m["last_changed"]:
             try:
                 last_dt = datetime.fromisoformat(m["last_changed"])
@@ -420,10 +537,7 @@ async def analyze_repo(
             )
         )
 
-    # Sort by score descending
     file_hotspots.sort(key=lambda h: h.hotspot_score, reverse=True)
-
-    # Aggregate directories
     directory_hotspots = _aggregate_by_directory(file_hotspots)
 
     return HotspotResult(
@@ -431,7 +545,7 @@ async def analyze_repo(
         repo_name=name,
         repo_path=str(resolved),
         time_window_days=days,
-        commit_count=len(commits),
+        commit_count=commit_count,
         file_hotspots=file_hotspots,
         directory_hotspots=directory_hotspots,
     )

package/pennyfarthing_scripts/hotspots/cli.py

@@ -44,8 +44,8 @@ def _common_options(fn):
 
 def _run_analysis(repo: str | None, repo_path: str | None, days: int, exclude: tuple, branch: str, skip_type: tuple = ()):
     """Run analysis and return result."""
-    from pennyfarthing_scripts.hotspots.analyze import analyze_all_repos, analyze_repo
     from pennyfarthing_scripts.common.config import get_project_root
+    from pennyfarthing_scripts.hotspots.analyze import analyze_all_repos, analyze_repo
 
     excludes = list(exclude) if exclude else None
     skip_types = list(skip_type) if skip_type else None
@@ -90,7 +90,7 @@ def _output_result(result, fmt: str, output_file: str | None, top: int, mode: st
         format_file_table,
         format_summary,
     )
-    from pennyfarthing_scripts.hotspots.models import HotspotResult, MultiRepoHotspotResult
+    from pennyfarthing_scripts.hotspots.models import MultiRepoHotspotResult
 
     # Collect all repo results
     if isinstance(result, MultiRepoHotspotResult):

package/pennyfarthing_scripts/hotspots/models.py

@@ -7,7 +7,6 @@ Follows ADR-0008 result pattern — structured dataclasses with success/error fi
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from datetime import datetime
 
 
 @dataclass

package/pennyfarthing_scripts/jira/__init__.py

@@ -20,6 +20,21 @@ Usage:
 """
 
 # Re-export from client for backwards compatibility
+# Import submodules to make them accessible
+# CLI entry point - import module, not function, so "from jira import cli" gets the module
+from pennyfarthing_scripts.jira import (
+    bidirectional,
+    claim,
+    cli,
+    client,
+    create,
+    epic,
+    operations,
+    reconcile,
+    story,
+    sync,
+)
+from pennyfarthing_scripts.jira.cli import main
 from pennyfarthing_scripts.jira.client import (
     # Constants
     GITHUB_TO_JIRA_MAP,
@@ -44,23 +59,6 @@ from pennyfarthing_scripts.jira.client import (
     update_issue_status,
 )
 
-# Import submodules to make them accessible
-from pennyfarthing_scripts.jira import (
-    bidirectional,
-    claim,
-    client,
-    create,
-    epic,
-    operations,
-    reconcile,
-    story,
-    sync,
-)
-
-# CLI entry point - import module, not function, so "from jira import cli" gets the module
-from pennyfarthing_scripts.jira import cli
-from pennyfarthing_scripts.jira.cli import main
-
 __all__ = [
     # Constants
     "GITHUB_TO_JIRA_MAP",

package/pennyfarthing_scripts/jira/bidirectional.py

@@ -28,11 +28,10 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Literal
 
-from pennyfarthing_scripts.jira.client import JiraClient, map_jira_to_status, map_status_to_jira
 from pennyfarthing_scripts.common.output import error, info, success, warn
+from pennyfarthing_scripts.jira.client import JiraClient, map_jira_to_status, map_status_to_jira
 from pennyfarthing_scripts.sprint.loader import get_all_stories, load_sprint
 
-
 # =============================================================================
 # Data Classes
 # =============================================================================
@@ -520,7 +519,7 @@ async def async_main(args: argparse.Namespace) -> int:
     tasks = [client.get_issue_async(key) for key in jira_keys]
     results = await asyncio.gather(*tasks, return_exceptions=True)
 
-    for key, result in zip(jira_keys, results):
+    for key, result in zip(jira_keys, results, strict=False):
         if isinstance(result, Exception):
             warn(f"Failed to fetch {key}: {result}")
         elif result:

package/pennyfarthing_scripts/jira/claim.py

@@ -162,6 +162,27 @@ def claim_story(issue_key: str) -> dict[str, Any]:
             "exit_code": 3,
         }
 
+    # Update sprint YAML assigned_to field
+    try:
+        from pennyfarthing_scripts.common.config import get_project_root
+        from pennyfarthing_scripts.sprint.yaml_io import read_sprint, write_sprint
+
+        root = get_project_root()
+        sprint_path = root / "sprint" / "current-sprint.yaml"
+        if sprint_path.exists():
+            data = read_sprint(sprint_path)
+            for epic in data.get("epics", []):
+                if not isinstance(epic, dict):
+                    continue
+                for story in epic.get("stories", []):
+                    if story.get("jira") == issue_key:
+                        story["assigned_to"] = current_user
+                        write_sprint(sprint_path, data)
+                        actions.append("Sprint YAML assigned_to set")
+                        break
+    except Exception:
+        pass  # Best-effort — Jira claim already succeeded
+
     return {
         "success": True,
         "actions": actions,

package/pennyfarthing_scripts/jira/cli.py

@@ -206,7 +206,7 @@ def create_standalone(title, points, description, dry_run):
         click.echo(f"[DRY-RUN] Would create: {title}")
         click.echo(f"  Points: {points}")
         click.echo(f"  Sprint: {sprint_id}")
-        click.echo(f"  Actions: create -> add to sprint -> transition to Done")
+        click.echo("  Actions: create -> add to sprint -> transition to Done")
         return
 
     client = get_client()
@@ -241,7 +241,7 @@ def create_standalone(title, points, description, dry_run):
     # 4. Transition to Done
     result = client.transition_sync(jira_key, "Done")
     if result.get("success"):
-        click.echo(f"Transitioned to Done")
+        click.echo("Transitioned to Done")
     else:
         click.echo(f"Warning: could not transition to Done: {result.get('reason')}")
 

package/pennyfarthing_scripts/jira/client.py

@@ -515,7 +515,7 @@ class JiraClient:
                 f"Available: {available}",
             }
 
-        result = self._call_api_sync(
+        self._call_api_sync(
             "POST",
             f"/rest/api/3/issue/{issue_key}/transitions",
             {"transition": {"id": transition_id}},
@@ -553,7 +553,7 @@ class JiraClient:
             account_id = None
 
         payload = {"accountId": account_id}
-        result = self._call_api_sync(
+        self._call_api_sync(
             "PUT", f"/rest/api/3/issue/{issue_key}/assignee", payload
         )
         # Assign PUT returns empty body on success (204)
@@ -569,7 +569,7 @@ class JiraClient:
         Returns:
             Result dict with success status
         """
-        result = self._call_api_sync(
+        self._call_api_sync(
             "POST",
             f"/rest/agile/1.0/sprint/{sprint_id}/issue",
             {"issues": [issue_key]},
@@ -619,7 +619,7 @@ class JiraClient:
         Returns:
             Result dict with success status
         """
-        result = self._call_api_sync(
+        self._call_api_sync(
             "POST",
             "/rest/api/3/issueLink",
             {

package/pennyfarthing_scripts/jira/create.py

@@ -16,7 +16,7 @@ import sys
 from pathlib import Path
 from typing import Any
 
-from pennyfarthing_scripts.jira.client import JIRA_PROJECT, JiraClient, get_client
+from pennyfarthing_scripts.jira.client import JIRA_PROJECT, get_client
 from pennyfarthing_scripts.sprint.loader import find_epic, find_story, load_sprint
 from pennyfarthing_scripts.sprint.yaml_io import read_sprint, write_sprint
 
@@ -150,6 +150,7 @@ def create_epic_in_jira(
     *,
     sprint_path: Path | None = None,
     dry_run: bool = False,
+    force: bool = False,
 ) -> dict[str, Any]:
     """Create a Jira epic and its child stories from sprint YAML.
 
@@ -157,6 +158,7 @@ def create_epic_in_jira(
         epic_id: Epic ID from sprint YAML (e.g., "epic-63" or "63")
         sprint_path: Path to sprint YAML (defaults to auto-detect)
         dry_run: If True, preview without creating
+        force: If True, create even if duplicate title detected
 
     Returns:
         {success, epic_key?, stories: [{id, jira_key}], error?}
@@ -184,6 +186,13 @@ def create_epic_in_jira(
     if not epic_ruamel:
         return {"success": False, "error": f"Epic '{epic_id}' not found in ruamel data"}
 
+    # Validate epic shard before any Jira operations (ADR-0022)
+    from pennyfarthing_scripts.sprint.validator import validate_epic_shard
+    validation = validate_epic_shard(dict(epic_ruamel))
+    if not validation.valid:
+        error_msgs = "; ".join(e.message for e in validation.errors)
+        return {"success": False, "error": f"Epic validation failed: {error_msgs}"}
+
     title = epic.get("title", f"Epic {epic_id}")
     description = epic.get("description", "")
     epic_jira_key = epic.get("jira")
@@ -200,6 +209,41 @@ def create_epic_in_jira(
             epic_jira_key = "MSSCI-XXXXX"
         else:
             client = get_client()
+
+            # Idempotency check: search for existing epic with same title (ADR-0022)
+            try:
+                existing = client.search_issues_sync(
+                    f'project = {JIRA_PROJECT} AND issuetype = Epic AND summary ~ "{title}"'
+                )
+                if existing and not force:
+                    existing_key = existing[0]["key"]
+                    print(f"Found existing epic with same title: {existing_key}")
+                    epic_jira_key = existing_key
+
+                    # Update YAML with existing key
+                    epic_ruamel["jira"] = epic_jira_key
+                    write_sprint(path, data)
+
+                    return {
+                        "success": True,
+                        "epic_key": epic_jira_key,
+                        "duplicate_detected": True,
+                        "stories": [],
+                    }
+                elif existing and force:
+                    import warnings
+                    warnings.warn(
+                        f"Duplicate epic title detected ({existing[0]['key']}), "
+                        "proceeding with --force",
+                        stacklevel=2,
+                    )
+            except Exception as exc:
+                import warnings
+                warnings.warn(
+                    f"Jira search for duplicate titles failed: {exc}",
+                    stacklevel=2,
+                )
+
             payload = {
                 "fields": {
                     "project": {"key": JIRA_PROJECT},

package/pennyfarthing_scripts/jira/epic.py

@@ -17,8 +17,9 @@ import json
 import sys
 from typing import Any
 
-from pennyfarthing_scripts.jira.client import JiraClient, JIRA_PROJECT
-from pennyfarthing_scripts.sprint.loader import find_epic, load_sprint as load_current_sprint
+from pennyfarthing_scripts.jira.client import JIRA_PROJECT, JiraClient
+from pennyfarthing_scripts.sprint.loader import find_epic
+from pennyfarthing_scripts.sprint.loader import load_sprint as load_current_sprint
 
 
 def parse_args(args: list[str] | None = None) -> argparse.Namespace:

package/pennyfarthing_scripts/jira/reconcile.py

@@ -23,7 +23,6 @@ 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

package/pennyfarthing_scripts/jira/story.py

@@ -24,6 +24,8 @@ from pennyfarthing_scripts.sprint.loader import (
     find_epic,
     find_story,
     get_story_by_id,
+)
+from pennyfarthing_scripts.sprint.loader import (
     load_sprint as load_current_sprint,
 )
 

package/pennyfarthing_scripts/jira/sync.py

@@ -17,13 +17,13 @@ from dataclasses import dataclass, field
 from typing import Any
 
 from pennyfarthing_scripts.common.config import get_project_root
+from pennyfarthing_scripts.common.output import error, info, success, warn
 from pennyfarthing_scripts.jira.client import (
     JiraClient,
     extract_jira_key,
     get_jira_field,
     map_status_to_jira,
 )
-from pennyfarthing_scripts.common.output import error, info, success, warn
 from pennyfarthing_scripts.sprint.loader import find_epic, load_sprint
 
 

package/pennyfarthing_scripts/migration/skill.py

@@ -10,7 +10,6 @@ import re
 from dataclasses import dataclass, field
 from pathlib import Path
 
-
 # Tag requirements
 REQUIRED_TAGS = ["run", "output"]
 RECOMMENDED_TAGS = ["args", "example", "when"]

package/pennyfarthing_scripts/migration/step.py

@@ -10,7 +10,6 @@ import re
 from dataclasses import dataclass, field
 from pathlib import Path
 
-
 # Tag requirements
 REQUIRED_TAGS = ["step-meta", "purpose", "instructions", "output"]
 RECOMMENDED_TAGS = ["prerequisites", "actions", "collaboration-menu", "next-step"]

package/pennyfarthing_scripts/migration/validate.py

@@ -20,12 +20,20 @@ from pennyfarthing_scripts.migration.session import (
 )
 from pennyfarthing_scripts.migration.skill import (
     RECOMMENDED_TAGS as SKILL_RECOMMENDED,
+)
+from pennyfarthing_scripts.migration.skill import (
     REQUIRED_TAGS as SKILL_REQUIRED,
+)
+from pennyfarthing_scripts.migration.skill import (
     find_skill_files,
 )
 from pennyfarthing_scripts.migration.step import (
     RECOMMENDED_TAGS as STEP_RECOMMENDED,
+)
+from pennyfarthing_scripts.migration.step import (
     REQUIRED_TAGS as STEP_REQUIRED,
+)
+from pennyfarthing_scripts.migration.step import (
     STEP_META_FIELDS,
     find_step_files,
 )
@@ -119,7 +127,6 @@ def validate_skill_file(file_path: Path) -> ValidationResult:
     Returns:
         ValidationResult with errors/warnings
     """
-    skill_name = file_path.parent.name
     result = ValidationResult(file_path=file_path, file_type="skill")
     content = file_path.read_text()
 
@@ -157,10 +164,6 @@ def validate_step_file(file_path: Path) -> ValidationResult:
     result = ValidationResult(file_path=file_path, file_type="step")
     content = file_path.read_text()
 
-    # Determine workflow/step names from path
-    workflow_name = file_path.parent.parent.name
-    step_name = file_path.stem
-
     # Check required tags
     for tag in STEP_REQUIRED:
         if not _has_tag(content, tag):

package/pennyfarthing_scripts/patch_mode.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 import re
 import subprocess
 import time
-from dataclasses import dataclass, asdict
+from dataclasses import asdict, dataclass
 from datetime import datetime
 from pathlib import Path
 from typing import Any
@@ -38,7 +38,7 @@ class PatchState:
         return yaml.dump(asdict(self), default_flow_style=False)
 
     @classmethod
-    def from_yaml(cls, yaml_str: str) -> "PatchState":
+    def from_yaml(cls, yaml_str: str) -> PatchState:
         """Deserialize state from YAML string."""
         data = yaml.safe_load(yaml_str)
         return cls(**data)

package/pennyfarthing_scripts/preflight/__init__.py

@@ -5,8 +5,8 @@ to validate story completion before finishing.
 """
 
 from pennyfarthing_scripts.preflight.finish import (
-    PreflightResult,
     PreflightIssue,
+    PreflightResult,
     run_finish_preflight,
 )