@pennyfarthing/core 11.3.3 → 11.3.4

package/pennyfarthing-dist/pf/codemarkers/formatters.py

@@ -0,0 +1,88 @@
+"""
+Output formatters for code marker analysis results.
+
+Supports table, JSON, and CSV output — no external dependencies.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import sys
+from dataclasses import asdict
+from typing import TextIO
+
+from pf.codemarkers.models import (
+    CodeMarker,
+    CodeMarkersResult,
+)
+
+
+def format_marker_table(markers: list[CodeMarker], top_n: int = 20) -> str:
+    """Format code markers as a column-aligned table."""
+    if not markers:
+        return "  No markers found."
+
+    items = markers[:top_n]
+
+    hdr = f"{'Type':>6}  {'Age':>6}  {'Stale':>5}  {'Author':>12}  {'Line':>5}  File"
+    sep = f"{'------':>6}  {'------':>6}  {'-----':>5}  {'------------':>12}  {'-----':>5}  ----"
+
+    lines = [hdr, sep]
+    for m in items:
+        stale = "YES" if m.is_stale else ""
+        age = f"{m.age_days:.0f}d" if m.age_days > 0 else ""
+        author = (m.author[:12] if len(m.author) > 12 else m.author) if m.author else ""
+        lines.append(
+            f"{m.marker_type:>6}  {age:>6}  {stale:>5}  {author:>12}  {m.line:>5}  {m.path}"
+        )
+
+    return "\n".join(lines)
+
+
+def format_summary(result: CodeMarkersResult, file: TextIO = sys.stderr) -> None:
+    """Print a summary header for a single repo result."""
+    from pf.common.output import header, info
+
+    header(f"  Code Markers: {result.repo_name}", char="=", width=60, file=file)
+    info(f"Path: {result.repo_path}", file=file)
+    info(f"Stale threshold: {result.stale_threshold_days} days", file=file)
+    if result.summary:
+        info(f"Total markers: {result.summary.total_markers}", file=file)
+        info(f"Stale markers: {result.summary.stale_markers}", file=file)
+        for mtype, count in sorted(result.summary.by_type.items()):
+            info(f"  {mtype}: {count}", file=file)
+
+
+def export_json(result: CodeMarkersResult) -> str:
+    """Serialize result to JSON string."""
+    return json.dumps(asdict(result), indent=2, default=str)
+
+
+def export_csv(markers: list[CodeMarker]) -> str:
+    """Export markers as CSV."""
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    writer.writerow([
+        "path",
+        "line",
+        "marker_type",
+        "text",
+        "author",
+        "date",
+        "age_days",
+        "is_stale",
+    ])
+    for m in markers:
+        writer.writerow([
+            m.path,
+            m.line,
+            m.marker_type,
+            m.text,
+            m.author,
+            m.date,
+            m.age_days,
+            m.is_stale,
+        ])
+    return buf.getvalue()

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

@@ -0,0 +1,48 @@
+"""Common utilities for Pennyfarthing scripts.
+
+This package provides shared utilities used across all CLI tools:
+- output: Colored console output functions
+- config: Project configuration loading
+"""
+
+from pf.common.config import (
+    find_project_root,
+    get_project_root,
+    load_pennyfarthing_config,
+    load_yaml_config,
+)
+from pf.common.output import (
+    Colors,
+    _colorize,
+    _supports_color,
+    bold,
+    debug,
+    dim,
+    divider,
+    error,
+    header,
+    info,
+    success,
+    warn,
+)
+
+__all__ = [
+    # Output
+    "Colors",
+    "bold",
+    "debug",
+    "dim",
+    "divider",
+    "error",
+    "header",
+    "info",
+    "success",
+    "warn",
+    "_colorize",
+    "_supports_color",
+    # Config
+    "find_project_root",
+    "get_project_root",
+    "load_pennyfarthing_config",
+    "load_yaml_config",
+]

package/pennyfarthing-dist/pf/common/pr_config.py

@@ -0,0 +1,38 @@
+"""PR mode configuration reader.
+
+Reads the pr_mode preference from .pennyfarthing/config.local.yaml.
+
+Values: draft | ready | none (default: draft)
+"""
+
+from __future__ import annotations
+
+from pf.common.config import load_pennyfarthing_config
+
+VALID_PR_MODES = {"draft", "ready", "none"}
+DEFAULT_PR_MODE = "draft"
+
+
+def get_pr_mode() -> str:
+    """Read pr_mode from pennyfarthing config.
+
+    Looks for workflow.pr_mode in .pennyfarthing/config.local.yaml.
+    Falls back to 'draft' if not set or invalid.
+
+    Returns:
+        One of: 'draft', 'ready', 'none'
+    """
+    config = load_pennyfarthing_config()
+    workflow = config.get("workflow", {})
+    if not isinstance(workflow, dict):
+        return DEFAULT_PR_MODE
+
+    mode = workflow.get("pr_mode", DEFAULT_PR_MODE)
+    if mode not in VALID_PR_MODES:
+        return DEFAULT_PR_MODE
+
+    return mode
+
+
+if __name__ == "__main__":
+    print(get_pr_mode())

package/pennyfarthing-dist/pf/common/themes.py

@@ -0,0 +1,253 @@
+"""
+Theme discovery and listing for Pennyfarthing.
+
+Python implementation of the canonical theme discovery algorithm
+(spec lives in @pennyfarthing/shared theme-loader.ts).
+
+Discovery order (deduped by theme ID, first source wins):
+  1. Core themes: .pennyfarthing/personas/themes/ and pennyfarthing-dist/personas/themes/
+  2. Theme packages: node_modules/@pennyfarthing/themes-*/themes/
+  3. Monorepo packages: packages/themes-*/themes/ (workspace dev)
+  4. Project custom: .claude/pennyfarthing/themes/
+  5. User custom: ~/.claude/pennyfarthing/themes/
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from pf.common.config import get_project_root, load_yaml_config
+
+
+def discover_all_theme_dirs(project_root: Path | None = None) -> list[Path]:
+    """Discover all directories containing theme YAML files.
+
+    Returns dirs in priority order matching the canonical spec.
+
+    Args:
+        project_root: Project root (auto-detected if not provided)
+
+    Returns:
+        List of Path objects for directories containing theme YAMLs
+    """
+    root = project_root or get_project_root()
+    dirs: list[Path] = []
+
+    # 1a. Core themes via .pennyfarthing symlink
+    symlink_themes = root / ".pennyfarthing" / "personas" / "themes"
+    if symlink_themes.is_dir():
+        dirs.append(symlink_themes)
+
+    # 1b. Core themes via pennyfarthing-dist (development)
+    dist_themes = root / "pennyfarthing-dist" / "personas" / "themes"
+    if dist_themes.is_dir() and dist_themes not in dirs:
+        dirs.append(dist_themes)
+
+    # 2. Theme packages via node_modules
+    nm_pf = root / "node_modules" / "@pennyfarthing"
+    if nm_pf.is_dir():
+        for entry in sorted(nm_pf.iterdir()):
+            if entry.name.startswith("themes-") and entry.is_dir():
+                if _is_theme_pack(entry):
+                    themes_dir = entry / "themes"
+                    if themes_dir.is_dir():
+                        dirs.append(themes_dir)
+
+    # 3. Monorepo workspace packages (development)
+    packages_dir = root / "packages"
+    if packages_dir.is_dir():
+        for entry in sorted(packages_dir.iterdir()):
+            if entry.name.startswith("themes-") and entry.is_dir():
+                if _is_theme_pack(entry):
+                    themes_dir = entry / "themes"
+                    if themes_dir.is_dir() and themes_dir not in dirs:
+                        dirs.append(themes_dir)
+
+    # 4. Project-level custom themes
+    project_custom = root / ".claude" / "pennyfarthing" / "themes"
+    if project_custom.is_dir():
+        dirs.append(project_custom)
+
+    # 5. User-level custom themes
+    user_custom = Path.home() / ".claude" / "pennyfarthing" / "themes"
+    if user_custom.is_dir():
+        dirs.append(user_custom)
+
+    return dirs
+
+
+def _is_theme_pack(pkg_dir: Path) -> bool:
+    """Check if a directory is a valid pennyfarthing theme pack."""
+    pkg_json = pkg_dir / "package.json"
+    if not pkg_json.exists():
+        return False
+    try:
+        pkg = json.loads(pkg_json.read_text())
+        return pkg.get("pennyfarthing-theme-pack") is True
+    except Exception:
+        return False
+
+
+def list_themes(project_root: Path | None = None) -> list[str]:
+    """List all available theme IDs across all sources.
+
+    Deduplicates by theme ID (first source wins).
+
+    Args:
+        project_root: Project root (auto-detected if not provided)
+
+    Returns:
+        Sorted list of theme ID strings
+    """
+    seen: set[str] = set()
+    theme_ids: list[str] = []
+
+    for theme_dir in discover_all_theme_dirs(project_root):
+        try:
+            for f in sorted(theme_dir.iterdir()):
+                if f.suffix == ".yaml" and f.is_file():
+                    theme_id = f.stem
+                    if theme_id not in seen:
+                        seen.add(theme_id)
+                        theme_ids.append(theme_id)
+        except OSError:
+            continue
+
+    return sorted(theme_ids)
+
+
+def resolve_theme_path(theme: str, project_root: Path | None = None) -> Path | None:
+    """Resolve the file path for a specific theme across all sources.
+
+    Args:
+        theme: Theme ID (e.g., 'classical-composers')
+        project_root: Project root (auto-detected if not provided)
+
+    Returns:
+        Path to the theme YAML, or None if not found
+    """
+    filename = f"{theme}.yaml"
+    for theme_dir in discover_all_theme_dirs(project_root):
+        candidate = theme_dir / filename
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def get_current_theme(project_root: Path | None = None) -> str | None:
+    """Get the currently configured theme.
+
+    Checks config files in priority order:
+    1. .pennyfarthing/config.local.yaml
+    2. .pennyfarthing/persona-config.yaml
+
+    Args:
+        project_root: Project root (auto-detected if not provided)
+
+    Returns:
+        Theme name, or None if not configured
+    """
+    root = project_root or get_project_root()
+
+    config_paths = [
+        root / ".pennyfarthing" / "config.local.yaml",
+        root / ".pennyfarthing" / "persona-config.yaml",
+    ]
+
+    for config_path in config_paths:
+        config = load_yaml_config(config_path)
+        if config and "theme" in config:
+            return config["theme"]
+
+    return None
+
+
+def load_theme_metadata(project_root: Path | None = None) -> list[dict[str, Any]]:
+    """Load metadata for all discoverable themes.
+
+    Extracts id, name, tier from each theme YAML.
+    Deduplicates by theme ID (first source wins).
+
+    Args:
+        project_root: Project root (auto-detected if not provided)
+
+    Returns:
+        List of theme metadata dicts with keys: id, name, tier
+    """
+    seen: set[str] = set()
+    metadata: list[dict[str, Any]] = []
+
+    for theme_dir in discover_all_theme_dirs(project_root):
+        try:
+            for f in sorted(theme_dir.iterdir()):
+                if f.suffix != ".yaml" or not f.is_file():
+                    continue
+                theme_id = f.stem
+                if theme_id in seen:
+                    continue
+                seen.add(theme_id)
+
+                try:
+                    data = yaml.safe_load(f.read_text())
+                    if not data or "theme" not in data:
+                        continue
+                    theme_info = data["theme"]
+                    metadata.append({
+                        "id": theme_id,
+                        "name": theme_info.get("name", theme_id),
+                        "tier": theme_info.get("tier", "U"),
+                    })
+                except Exception:
+                    continue
+        except OSError:
+            continue
+
+    return sorted(metadata, key=lambda m: m["id"])
+
+
+def format_theme_list(
+    current_theme: str | None = None,
+    project_root: Path | None = None,
+) -> str:
+    """Format theme listing for CLI output.
+
+    Produces the same 3-column, tier-annotated output that list-themes.sh
+    previously generated in pure bash.
+
+    Args:
+        current_theme: Currently active theme (will be starred)
+        project_root: Project root (auto-detected if not provided)
+
+    Returns:
+        Formatted string for terminal display
+    """
+    themes = load_theme_metadata(project_root)
+    if not themes:
+        return "No themes found."
+
+    current = current_theme or get_current_theme(project_root) or ""
+
+    lines: list[str] = []
+    lines.append(
+        f"**{len(themes)} themes available.** Current: **{current or 'none'}**"
+    )
+    lines.append("")
+
+    col_width = 28
+    row: list[str] = []
+    for t in themes:
+        tid = t["id"]
+        tier = t.get("tier", "U")
+        label = f"*{tid} [{tier}]" if tid == current else f"{tid} [{tier}]"
+        row.append(f"{label:<{col_width}}")
+        if len(row) == 3:
+            lines.append("".join(row))
+            row = []
+    if row:
+        lines.append("".join(row))
+
+    return "\n".join(lines)

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

@@ -0,0 +1,15 @@
+"""
+Code complexity analysis for TypeScript/JavaScript projects.
+
+Wraps eslint with complexity rules to extract per-file metrics:
+cyclomatic complexity, function length, nesting depth, and line counts.
+"""
+
+from pf.complexity.analyze import analyze_complexity
+from pf.complexity.models import ComplexityResult, FileComplexity
+
+__all__ = [
+    "FileComplexity",
+    "ComplexityResult",
+    "analyze_complexity",
+]

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

@@ -0,0 +1,6 @@
+"""Allow running as: python -m pf.complexity"""
+
+from pf.complexity.cli import complexity
+
+if __name__ == "__main__":
+    complexity()

package/pennyfarthing-dist/pf/complexity/analyze.py

@@ -0,0 +1,207 @@
+"""
+Core complexity analysis engine.
+
+Wraps eslint --format json with complexity/max-depth/max-lines-per-function rules.
+Parses output into per-file metrics following ADR-0008 result pattern.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import fnmatch
+import json
+import re
+from pathlib import Path
+
+from pf.complexity.models import ComplexityResult, FileComplexity
+
+# Regex patterns for extracting numeric values from ESLint messages
+COMPLEXITY_RE = re.compile(r"complexity of (\d+)")
+MAX_DEPTH_RE = re.compile(r"too deeply \((\d+)\)")
+MAX_LINES_RE = re.compile(r"too many lines \((\d+)\)")
+
+
+def _find_eslint(target_path: Path) -> Path | None:
+    """Find eslint binary in node_modules/.bin/.
+
+    Walks up from target_path looking for node_modules/.bin/eslint.
+    """
+    candidate = target_path / "node_modules" / ".bin" / "eslint"
+    if candidate.exists():
+        return candidate
+
+    for parent in target_path.parents:
+        candidate = parent / "node_modules" / ".bin" / "eslint"
+        if candidate.exists():
+            return candidate
+
+    return None
+
+
+def _parse_eslint_output(output: str, target_path: Path) -> list[FileComplexity]:
+    """Parse eslint JSON output into FileComplexity models.
+
+    Extracts per-file metrics from ESLint rule violations:
+    - complexity rule → cyclomatic complexity per function
+    - max-depth rule → nesting depth
+    - max-lines-per-function rule → function line count
+    """
+    try:
+        data = json.loads(output)
+    except (json.JSONDecodeError, TypeError):
+        return []
+
+    if not data:
+        return []
+
+    target_str = str(target_path)
+    if not target_str.endswith("/"):
+        target_str += "/"
+
+    files = []
+    for file_entry in data:
+        file_path = file_entry.get("filePath", "")
+        messages = file_entry.get("messages", [])
+
+        # Make path relative to target directory
+        if file_path.startswith(target_str):
+            rel_path = file_path[len(target_str):]
+        else:
+            rel_path = file_path
+
+        complexities = []
+        depths = []
+        line_counts = []
+
+        for msg in messages:
+            rule_id = msg.get("ruleId", "")
+            message = msg.get("message", "")
+
+            if rule_id == "complexity":
+                m = COMPLEXITY_RE.search(message)
+                if m:
+                    complexities.append(int(m.group(1)))
+
+            elif rule_id == "max-depth":
+                m = MAX_DEPTH_RE.search(message)
+                if m:
+                    depths.append(int(m.group(1)))
+
+            elif rule_id == "max-lines-per-function":
+                m = MAX_LINES_RE.search(message)
+                if m:
+                    line_counts.append(int(m.group(1)))
+
+        function_count = len(complexities)
+        avg_complexity = (
+            sum(complexities) / len(complexities) if complexities else 0.0
+        )
+        max_nesting = max(depths) if depths else 0
+        longest_fn = max(line_counts) if line_counts else 0
+
+        files.append(FileComplexity(
+            path=rel_path,
+            total_lines=0,  # populated by _count_file_lines
+            longest_function=longest_fn,
+            avg_cyclomatic_complexity=round(avg_complexity, 1),
+            max_nesting_depth=max_nesting,
+            function_count=function_count,
+        ))
+
+    return files
+
+
+async def _run_eslint(eslint_bin: Path, target_path: Path) -> tuple[str, str, int]:
+    """Run eslint subprocess with complexity rules enabled."""
+    proc = await asyncio.create_subprocess_exec(
+        str(eslint_bin),
+        str(target_path),
+        "--format", "json",
+        "--no-config-lookup",
+        "--rule", 'complexity: ["warn", 1]',
+        "--rule", 'max-depth: ["warn", 1]',
+        "--rule", 'max-lines-per-function: ["warn", 1]',
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout, stderr = await proc.communicate()
+    return (
+        stdout.decode("utf-8", errors="replace"),
+        stderr.decode("utf-8", errors="replace"),
+        proc.returncode or 0,
+    )
+
+
+async def _count_file_lines(file_path: Path) -> int:
+    """Count lines in a file."""
+    try:
+        content = file_path.read_bytes()
+        return content.count(b"\n") + (1 if content and not content.endswith(b"\n") else 0)
+    except OSError:
+        return 0
+
+
+def _should_exclude(path: str, patterns: list[str]) -> bool:
+    """Check if a file path matches any exclusion pattern."""
+    for pattern in patterns:
+        if fnmatch.fnmatch(path, pattern):
+            return True
+        # Check basename
+        if fnmatch.fnmatch(path.split("/")[-1], pattern):
+            return True
+        # Check if any parent directory matches (e.g. node_modules/* matches node_modules/lib/foo.ts)
+        parts = path.split("/")
+        for i in range(len(parts)):
+            partial = "/".join(parts[: i + 1])
+            if fnmatch.fnmatch(partial, pattern):
+                return True
+    return False
+
+
+async def analyze_complexity(
+    target_path: Path,
+    excludes: list[str] | None = None,
+) -> ComplexityResult:
+    """Analyze complexity of files in the target directory."""
+    resolved = target_path.resolve()
+
+    eslint_bin = _find_eslint(resolved)
+    if eslint_bin is None:
+        return ComplexityResult(
+            success=False,
+            target_path=str(resolved),
+            error="eslint not found. Install with: npm install -D eslint",
+        )
+
+    stdout, stderr, rc = await _run_eslint(eslint_bin, resolved)
+
+    # Try resolved path first, fall back to original (handles /tmp → /private/tmp on macOS)
+    files = _parse_eslint_output(stdout, resolved)
+    if not files or (files and files[0].path.startswith("/")):
+        alt_files = _parse_eslint_output(stdout, target_path)
+        if alt_files and (not files or not alt_files[0].path.startswith("/")):
+            files = alt_files
+
+    if not files:
+        return ComplexityResult(
+            success=True,
+            target_path=str(resolved),
+            file_count=0,
+            files=[],
+        )
+
+    # Apply exclude filters
+    if excludes:
+        files = [f for f in files if not _should_exclude(f.path, excludes)]
+
+    # Count lines for each file
+    for fc in files:
+        full_path = resolved / fc.path
+        fc.total_lines = await _count_file_lines(full_path)
+
+    return ComplexityResult(
+        success=True,
+        target_path=str(resolved),
+        file_count=len(files),
+        files=files,
+    )