@pennyfarthing/core 10.0.3 → 10.1.0

package/pennyfarthing_scripts/codemarkers/formatters.py

@@ -0,0 +1,89 @@
+"""
+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 pennyfarthing_scripts.codemarkers.models import (
+    CodeMarker,
+    CodeMarkersResult,
+    MarkerSummary,
+)
+
+
+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 pennyfarthing_scripts.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_scripts/codemarkers/models.py

@@ -0,0 +1,45 @@
+"""
+Data models for code marker analysis results.
+
+Follows ADR-0008 result pattern — structured dataclasses with success/error fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CodeMarker:
+    """A single code marker (TODO, FIXME, HACK, XXX) found in source."""
+
+    path: str
+    line: int
+    marker_type: str  # TODO, FIXME, HACK, XXX
+    text: str  # Full comment text
+    author: str = ""  # From git blame
+    date: str = ""  # ISO date from git blame
+    age_days: float = 0.0  # Computed from blame date
+    is_stale: bool = False  # age_days > stale_threshold
+
+
+@dataclass
+class MarkerSummary:
+    """Aggregate counts of markers by type."""
+
+    total_markers: int = 0
+    stale_markers: int = 0
+    by_type: dict[str, int] = field(default_factory=dict)
+
+
+@dataclass
+class CodeMarkersResult:
+    """Analysis result for a single repository."""
+
+    success: bool
+    repo_name: str
+    repo_path: str
+    stale_threshold_days: int
+    markers: list[CodeMarker] = field(default_factory=list)
+    summary: MarkerSummary | None = None
+    error: str | None = None

package/pennyfarthing_scripts/common/config.py

@@ -57,7 +57,8 @@ def get_project_root(start_dir: Path | None = None) -> Path:
         check = check.parent
 
     raise FileNotFoundError(
-        "Could not find project root (no pennyfarthing-dist/ or .pennyfarthing/ directory found)"
+        "Could not find project root (no pennyfarthing-dist/ or .pennyfarthing/ directory found).\n"
+        "If this is a fresh clone, run: just setup"
     )
 
 

package/pennyfarthing_scripts/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 pennyfarthing_scripts.complexity.models import FileComplexity, ComplexityResult
+from pennyfarthing_scripts.complexity.analyze import analyze_complexity
+
+__all__ = [
+    "FileComplexity",
+    "ComplexityResult",
+    "analyze_complexity",
+]

package/pennyfarthing_scripts/complexity/__main__.py

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

package/pennyfarthing_scripts/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 pennyfarthing_scripts.complexity.models import FileComplexity, ComplexityResult
+
+# 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,
+    )

package/pennyfarthing_scripts/complexity/cli.py

@@ -0,0 +1,78 @@
+"""
+CLI commands for complexity analysis.
+
+Usage:
+    python -m pennyfarthing_scripts.complexity analyze [OPTIONS]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import click
+
+
+@click.group()
+def complexity():
+    """Code complexity analysis.
+
+    \b
+    Commands:
+      analyze  - Analyze code complexity metrics
+    """
+    pass
+
+
+def _common_options(fn):
+    """Shared options for complexity commands."""
+    fn = click.option("--path", "target_path", type=click.Path(exists=True),
+                       help="Directory to analyze")(fn)
+    fn = click.option("--format", "fmt", type=click.Choice(["table", "json", "csv"]),
+                       default="table", show_default=True)(fn)
+    fn = click.option("--top", default=20, show_default=True,
+                       help="Number of top results")(fn)
+    fn = click.option("--output", "output_file", type=click.Path(),
+                       help="Write output to file")(fn)
+    fn = click.option("--exclude", multiple=True,
+                       help="Exclude patterns (repeatable)")(fn)
+    return fn
+
+
+def _run_analysis(target_path: str | None, exclude: tuple) -> "ComplexityResult":
+    """Run analysis and return result."""
+    from pennyfarthing_scripts.complexity.analyze import analyze_complexity
+
+    excludes = list(exclude) if exclude else None
+    p = Path(target_path).resolve() if target_path else Path(".").resolve()
+    return asyncio.run(analyze_complexity(p, excludes))
+
+
+def _output_result(result, fmt: str, output_file: str | None, top: int):
+    """Format and output the analysis result."""
+    from pennyfarthing_scripts.complexity.formatters import (
+        export_csv,
+        export_json,
+        format_file_table,
+    )
+
+    if fmt == "json":
+        text = export_json(result)
+    elif fmt == "csv":
+        text = export_csv(result.files[:top])
+    else:
+        text = format_file_table(result.files, top)
+
+    if output_file:
+        Path(output_file).write_text(text)
+        click.echo(f"Output written to {output_file}", err=True)
+    else:
+        click.echo(text)
+
+
+@complexity.command()
+@_common_options
+def analyze(target_path, fmt, top, output_file, exclude):
+    """Analyze code complexity."""
+    result = _run_analysis(target_path, exclude)
+    _output_result(result, fmt, output_file, top)

package/pennyfarthing_scripts/complexity/formatters.py

@@ -0,0 +1,64 @@
+"""
+Output formatters for complexity analysis 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.complexity.models import FileComplexity, ComplexityResult
+
+
+def format_file_table(files: list[FileComplexity], top_n: int = 20) -> str:
+    """Format complexity results as column-aligned table."""
+    if not files:
+        return "  No complexity results found."
+
+    items = files[:top_n]
+
+    hdr = f"{'Complexity':>11}  {'Longest Fn':>11}  {'Nesting':>8}  {'Functions':>10}  {'Lines':>6}  File"
+    sep = f"{'-----------':>11}  {'-----------':>11}  {'--------':>8}  {'----------':>10}  {'------':>6}  ----"
+
+    lines = [hdr, sep]
+    for f in items:
+        lines.append(
+            f"{f.avg_cyclomatic_complexity:>11.1f}  {f.longest_function:>11}  "
+            f"{f.max_nesting_depth:>8}  {f.function_count:>10}  "
+            f"{f.total_lines:>6}  {f.path}"
+        )
+
+    return "\n".join(lines)
+
+
+def export_json(result: ComplexityResult) -> str:
+    """Serialize result to JSON string."""
+    return json.dumps(asdict(result), indent=2, default=str)
+
+
+def export_csv(files: list[FileComplexity]) -> str:
+    """Export file complexity data as CSV."""
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    writer.writerow([
+        "path",
+        "total_lines",
+        "longest_function",
+        "avg_cyclomatic_complexity",
+        "max_nesting_depth",
+        "function_count",
+    ])
+    for f in files:
+        writer.writerow([
+            f.path,
+            f.total_lines,
+            f.longest_function,
+            f.avg_cyclomatic_complexity,
+            f.max_nesting_depth,
+            f.function_count,
+        ])
+    return buf.getvalue()

package/pennyfarthing_scripts/complexity/models.py

@@ -0,0 +1,32 @@
+"""
+Data models for complexity analysis results.
+
+Follows ADR-0008 result pattern — structured dataclasses with success/error fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class FileComplexity:
+    """Complexity metrics for a single file."""
+
+    path: str
+    total_lines: int = 0
+    longest_function: int = 0
+    avg_cyclomatic_complexity: float = 0.0
+    max_nesting_depth: int = 0
+    function_count: int = 0
+
+
+@dataclass
+class ComplexityResult:
+    """Analysis result following ADR-0008 pattern."""
+
+    success: bool
+    target_path: str = ""
+    file_count: int = 0
+    files: list[FileComplexity] = field(default_factory=list)
+    error: str | None = None

package/pennyfarthing_scripts/deadcode/__init__.py

@@ -0,0 +1,6 @@
+"""
+Dead code detection module.
+
+Layer 1: Git-based stale file detection.
+Layer 2: Unused TypeScript export detection via ts-prune.
+"""

package/pennyfarthing_scripts/deadcode/__main__.py

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