@pennyfarthing/core 10.0.5 → 10.2.0

package/pennyfarthing_scripts/healthscore/formatters.py

@@ -0,0 +1,46 @@
+"""
+Output formatters for health score results.
+
+Supports table, JSON, and CSV output — no external dependencies.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from dataclasses import asdict
+
+from pennyfarthing_scripts.healthscore.models import HealthscoreResult
+
+
+def format_table(result: HealthscoreResult) -> str:
+    """Format health score results as column-aligned table."""
+    lines = [
+        f"Health Score: {result.composite_score:.1f} / 100",
+        "",
+        f"{'Dimension':<30}  {'Score':>6}  {'Weight':>6}",
+        f"{'-' * 30}  {'------':>6}  {'------':>6}",
+    ]
+
+    for dim in result.dimensions:
+        score_str = f"{dim.score:.1f}" if dim.score is not None else "N/A"
+        weight_pct = f"{dim.weight * 100:.0f}%"
+        lines.append(f"{dim.name:<30}  {score_str:>6}  {weight_pct:>6}")
+
+    return "\n".join(lines)
+
+
+def export_json(result: HealthscoreResult) -> str:
+    """Serialize result to JSON string."""
+    return json.dumps(asdict(result), indent=2, default=str)
+
+
+def export_csv(result: HealthscoreResult) -> str:
+    """Export dimension scores as CSV."""
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    writer.writerow(["dimension", "score", "weight", "error"])
+    for dim in result.dimensions:
+        writer.writerow([dim.name, dim.score, dim.weight, dim.error or ""])
+    return buf.getvalue()

package/pennyfarthing_scripts/healthscore/models.py

@@ -0,0 +1,43 @@
+"""
+Data models for health score analysis results.
+
+Follows ADR-0008 result pattern — structured dataclasses with success/error fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# Default weights for each dimension (must sum to 1.0)
+DEFAULT_WEIGHTS: dict[str, float] = {
+    "churn": 0.15,
+    "todo_density": 0.15,
+    "complexity": 0.15,
+    "test_gaps": 0.15,
+    "dead_code": 0.10,
+    "deprecation_debt": 0.10,
+    "dependency_freshness": 0.10,
+    "agent_context_efficiency": 0.10,
+}
+
+
+@dataclass
+class DimensionScore:
+    """Score for a single health dimension."""
+
+    name: str
+    score: float | None = None  # 0-100, None if unavailable
+    weight: float = 0.0
+    error: str | None = None
+
+
+@dataclass
+class HealthscoreResult:
+    """Composite health score following ADR-0008 pattern."""
+
+    success: bool
+    composite_score: float = 0.0  # 0-100 weighted average
+    target_path: str = ""
+    dimensions: list[DimensionScore] = field(default_factory=list)
+    cached: bool = False
+    error: str | None = None

package/pennyfarthing_scripts/hooks.py

@@ -16,15 +16,14 @@ Story: MSSCI-12409 - Hook consistency and relay mode compatibility
 import json
 import os
 import sys
-import urllib.request
 import urllib.error
+import urllib.request
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
 import yaml
 
-
 # =============================================================================
 # Port File Constants
 # =============================================================================
@@ -413,19 +412,17 @@ def read_stdin_json() -> dict[str, Any]:
 def is_cyclist_running(project_root: Path | None = None) -> bool:
     """Check if Cyclist server is running.
 
-    Checks for .cyclist-port file existence. No HTTP calls — this runs on
-    every tool invocation and must be fast.
+    Checks the CYCLIST environment variable set by ClaudeService when
+    spawning Claude inside Cyclist. No file I/O, no HTTP, no signals —
+    this runs on every tool invocation and must be instant.
 
-    Args:
-        project_root: Project root directory (auto-detected if not provided)
+    The project_root parameter is kept for backward compatibility but
+    is no longer used.
 
     Returns:
-        True if .cyclist-port file exists at project root
+        True if running inside a Cyclist-spawned Claude process
     """
-    root = project_root or find_project_root()
-    if not root:
-        return False
-    return (root / CYCLIST_PORT_FILE).exists()
+    return os.environ.get("CYCLIST") == "1"
 
 
 def should_auto_approve(settings: CyclistSettings) -> bool:

package/pennyfarthing_scripts/hotspots/__init__.py

@@ -6,18 +6,18 @@ bug fix concentration, and multi-author churn — indicators of code hotspots th
 may benefit from refactoring attention.
 """
 
+from pennyfarthing_scripts.hotspots.analyze import (
+    analyze_all_repos,
+    analyze_repo,
+    calculate_hotspot_score,
+    is_bug_fix_commit,
+)
 from pennyfarthing_scripts.hotspots.models import (
     DirectoryHotspot,
     FileHotspot,
     HotspotResult,
     MultiRepoHotspotResult,
 )
-from pennyfarthing_scripts.hotspots.analyze import (
-    analyze_repo,
-    analyze_all_repos,
-    calculate_hotspot_score,
-    is_bug_fix_commit,
-)
 
 __all__ = [
     "DirectoryHotspot",

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
@@ -39,6 +42,50 @@ DEFAULT_EXCLUDES = [
     "*.map",
     "package-lock.json",
     "pnpm-lock.yaml",
+    # Dotfiles
+    ".*",
+    # Images
+    "*.png",
+    "*.jpg",
+    "*.jpeg",
+    "*.gif",
+    "*.svg",
+    "*.ico",
+    # Fonts
+    "*.woff",
+    "*.woff2",
+    "*.ttf",
+    "*.eot",
+    # Generated files
+    "*.d.ts",
+    "*.snap",
+    "*.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
@@ -266,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
@@ -288,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:
@@ -310,7 +440,6 @@ async def analyze_repo(
             commit_count=0,
         )
 
-    # Aggregate per-file metrics
     file_metrics: dict[str, dict] = defaultdict(
         lambda: {
             "change_count": 0,
@@ -322,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"])
@@ -338,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"]
 
@@ -351,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())
@@ -359,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"])
@@ -400,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(
@@ -411,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,
     )
@@ -422,6 +556,7 @@ async def analyze_all_repos(
     days: int = 90,
     excludes: list[str] | None = None,
     branch: str = "--all",
+    skip_types: list[str] | None = None,
 ) -> MultiRepoHotspotResult:
     """Analyze all repos found under project root in parallel.
 
@@ -432,6 +567,7 @@ async def analyze_all_repos(
         days: Time window in days
         excludes: Additional file patterns to exclude
         branch: Branch spec
+        skip_types: Repo types to exclude (e.g. ["orchestrator"])
 
     Returns:
         MultiRepoHotspotResult with per-repo results
@@ -446,6 +582,11 @@ async def analyze_all_repos(
         # Extract repos from repos.yaml
         for repo_name, repo_config in repos_yaml.items():
             if isinstance(repo_config, dict):
+                # Filter by type if skip_types is provided
+                if skip_types:
+                    repo_type = repo_config.get("type")
+                    if repo_type and repo_type in skip_types:
+                        continue
                 repo_path = repo_config.get("path", repo_name)
             else:
                 repo_path = str(repo_config)

package/pennyfarthing_scripts/hotspots/cli.py

@@ -38,15 +38,17 @@ def _common_options(fn):
     fn = click.option("--output", "output_file", type=click.Path(), help="Write output to file")(fn)
     fn = click.option("--exclude", multiple=True, help="Additional exclude patterns (repeatable)")(fn)
     fn = click.option("--branch", default="--all", show_default=True, help="Branch spec for git log")(fn)
+    fn = click.option("--skip-type", "skip_type", multiple=True, help="Skip repos by type (repeatable, e.g. --skip-type orchestrator)")(fn)
     return fn
 
 
-def _run_analysis(repo: str | None, repo_path: str | None, days: int, exclude: tuple, branch: str):
+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
 
     if repo_path:
         # Standalone analysis of a specific path
@@ -75,7 +77,7 @@ def _run_analysis(repo: str | None, repo_path: str | None, days: int, exclude: t
         # All repos
         project_root = get_project_root()
         return asyncio.run(
-            analyze_all_repos(project_root, days, excludes, branch)
+            analyze_all_repos(project_root, days, excludes, branch, skip_types)
         )
 
 
@@ -88,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):
@@ -130,23 +132,23 @@ def _output_result(result, fmt: str, output_file: str | None, top: int, mode: st
 
 @hotspots.command()
 @_common_options
-def analyze(repo, repo_path, days, top, fmt, output_file, exclude, branch):
+def analyze(repo, repo_path, days, top, fmt, output_file, exclude, branch, skip_type):
     """Full hotspot analysis — files and directories."""
-    result = _run_analysis(repo, repo_path, days, exclude, branch)
+    result = _run_analysis(repo, repo_path, days, exclude, branch, skip_type)
     _output_result(result, fmt, output_file, top, "analyze")
 
 
 @hotspots.command()
 @_common_options
-def files(repo, repo_path, days, top, fmt, output_file, exclude, branch):
+def files(repo, repo_path, days, top, fmt, output_file, exclude, branch, skip_type):
     """File-level hotspot report."""
-    result = _run_analysis(repo, repo_path, days, exclude, branch)
+    result = _run_analysis(repo, repo_path, days, exclude, branch, skip_type)
     _output_result(result, fmt, output_file, top, "files")
 
 
 @hotspots.command()
 @_common_options
-def dirs(repo, repo_path, days, top, fmt, output_file, exclude, branch):
+def dirs(repo, repo_path, days, top, fmt, output_file, exclude, branch, skip_type):
     """Directory-level hotspot report."""
-    result = _run_analysis(repo, repo_path, days, exclude, branch)
+    result = _run_analysis(repo, repo_path, days, exclude, branch, skip_type)
     _output_result(result, fmt, output_file, top, "dirs")

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",