@pennyfarthing/core 10.0.5 → 10.1.0

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()