@pennyfarthing/core 10.0.5 → 10.2.0

package/pennyfarthing_scripts/deadcode/formatters.py

@@ -0,0 +1,106 @@
+"""
+Output formatters for dead code analysis results.
+
+Supports table, JSON, and CSV output formats.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from dataclasses import asdict
+
+from pennyfarthing_scripts.deadcode.models import (
+    DeadCodeResult,
+    StaleFile,
+    UnusedExport,
+    UnusedExportResult,
+)
+
+
+def format_table(stale_files: list[StaleFile], top_n: int = 20) -> str:
+    """Format stale files as a human-readable table."""
+    if not stale_files:
+        return "No stale files found."
+
+    files = stale_files[:top_n]
+
+    # Column widths
+    path_width = max(len("Path"), max(len(f.path) for f in files))
+    header = f"{'Path':<{path_width}}  {'Days':>6}  {'Size':>10}  {'Last Commit'}"
+    separator = "-" * len(header)
+
+    lines = [header, separator]
+    for f in files:
+        size_str = _format_size(f.size_bytes)
+        date_str = f.last_commit_date[:10] if f.last_commit_date else "unknown"
+        lines.append(
+            f"{f.path:<{path_width}}  {f.days_since_last_commit:>6}  {size_str:>10}  {date_str}"
+        )
+
+    return "\n".join(lines)
+
+
+def _format_size(size_bytes: int) -> str:
+    """Format bytes as human-readable size."""
+    if size_bytes < 1024:
+        return f"{size_bytes} B"
+    elif size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.1f} KB"
+    else:
+        return f"{size_bytes / (1024 * 1024):.1f} MB"
+
+
+def export_json(result: DeadCodeResult) -> str:
+    """Export result as JSON."""
+    return json.dumps(asdict(result), indent=2)
+
+
+def export_csv(stale_files: list[StaleFile]) -> str:
+    """Export stale files as CSV."""
+    output = io.StringIO()
+    writer = csv.writer(output)
+    writer.writerow(["path", "last_commit_date", "days_since_last_commit", "size_bytes"])
+    for f in stale_files:
+        writer.writerow([f.path, f.last_commit_date, f.days_since_last_commit, f.size_bytes])
+    return output.getvalue()
+
+
+# ---- Unused export formatters ----
+
+
+def format_exports_table(unused_exports: list[UnusedExport], top_n: int = 20) -> str:
+    """Format unused exports as a human-readable table."""
+    if not unused_exports:
+        return "No unused exports found."
+
+    exports = unused_exports[:top_n]
+
+    file_width = max(len("File"), max(len(ue.file) for ue in exports))
+    symbol_width = max(len("Symbol"), max(len(ue.symbol) for ue in exports))
+    header = f"{'File':<{file_width}}  {'Line':>5}  {'Symbol':<{symbol_width}}  {'Type'}"
+    separator = "-" * len(header)
+
+    lines = [header, separator]
+    for ue in exports:
+        lines.append(
+            f"{ue.file:<{file_width}}  {ue.line:>5}  {ue.symbol:<{symbol_width}}  {ue.export_type}"
+        )
+
+    return "\n".join(lines)
+
+
+def export_exports_json(result: UnusedExportResult) -> str:
+    """Export unused export result as JSON."""
+    return json.dumps(asdict(result), indent=2)
+
+
+def export_exports_csv(unused_exports: list[UnusedExport]) -> str:
+    """Export unused exports as CSV."""
+    output = io.StringIO()
+    writer = csv.writer(output)
+    writer.writerow(["symbol", "file", "line", "export_type"])
+    for ue in unused_exports:
+        writer.writerow([ue.symbol, ue.file, ue.line, ue.export_type])
+    return output.getvalue()

package/pennyfarthing_scripts/deadcode/models.py

@@ -0,0 +1,54 @@
+"""
+Data models for dead code analysis results.
+
+Follows ADR-0008 result pattern — structured dataclasses with success/error fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class StaleFile:
+    """A file detected as stale (no commits within time window)."""
+
+    path: str
+    last_commit_date: str = ""  # ISO 8601
+    days_since_last_commit: int = 0
+    size_bytes: int = 0
+
+
+@dataclass
+class DeadCodeResult:
+    """Analysis result for stale file detection in a single repository."""
+
+    success: bool
+    repo_name: str
+    repo_path: str
+    time_window_days: int
+    stale_files: list[StaleFile] = field(default_factory=list)
+    total_files: int = 0
+    error: str | None = None
+
+
+@dataclass
+class UnusedExport:
+    """An exported symbol with no importers, detected by ts-prune."""
+
+    symbol: str
+    file: str
+    line: int
+    export_type: str = "named"  # named, default, re-export
+
+
+@dataclass
+class UnusedExportResult:
+    """Analysis result for unused export detection in a single repository."""
+
+    success: bool
+    repo_name: str
+    repo_path: str
+    unused_exports: list[UnusedExport] = field(default_factory=list)
+    total_exports_scanned: int = 0
+    error: str | None = None

package/pennyfarthing_scripts/dependencies/__init__.py

@@ -0,0 +1,20 @@
+"""
+Dependency staleness and security analysis for Node.js projects.
+
+Wraps npm outdated and npm audit to detect outdated packages
+and security vulnerabilities.
+"""
+
+from pennyfarthing_scripts.dependencies.analyze import analyze_dependencies
+from pennyfarthing_scripts.dependencies.models import (
+    DependenciesResult,
+    OutdatedPackage,
+    SecurityAdvisory,
+)
+
+__all__ = [
+    "OutdatedPackage",
+    "SecurityAdvisory",
+    "DependenciesResult",
+    "analyze_dependencies",
+]

package/pennyfarthing_scripts/dependencies/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m pennyfarthing_scripts.dependencies"""
+
+from pennyfarthing_scripts.dependencies.cli import dependencies
+
+dependencies()

package/pennyfarthing_scripts/dependencies/analyze.py

@@ -0,0 +1,155 @@
+"""
+Core dependency analysis engine.
+
+Wraps npm outdated --json and npm audit --json.
+Parses output into models following ADR-0008 result pattern.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+from collections import Counter
+from pathlib import Path
+
+from pennyfarthing_scripts.dependencies.models import (
+    DependenciesResult,
+    OutdatedPackage,
+    SecurityAdvisory,
+)
+
+
+def _find_npm(target_path: Path) -> Path | None:
+    """Find npm binary via shutil.which."""
+    npm = shutil.which("npm")
+    return Path(npm) if npm else None
+
+
+def _check_package_json(target_path: Path) -> bool:
+    """Check if package.json exists in target directory."""
+    return (target_path / "package.json").exists()
+
+
+def _parse_outdated_output(output: str) -> list[OutdatedPackage]:
+    """Parse npm outdated --json output into OutdatedPackage models.
+
+    npm outdated --json returns: {pkg_name: {current, wanted, latest, type, ...}}
+    """
+    if not output:
+        return []
+    try:
+        data = json.loads(output)
+    except (json.JSONDecodeError, TypeError):
+        return []
+
+    if not data or not isinstance(data, dict):
+        return []
+
+    packages = []
+    for name, info in data.items():
+        packages.append(OutdatedPackage(
+            name=name,
+            current=info.get("current", ""),
+            wanted=info.get("wanted", ""),
+            latest=info.get("latest", ""),
+            type=info.get("type", ""),
+        ))
+    return packages
+
+
+def _parse_audit_output(output: str) -> list[SecurityAdvisory]:
+    """Parse npm audit --json output into SecurityAdvisory models.
+
+    npm audit --json returns: {vulnerabilities: {name: {severity, ...}}, metadata: ...}
+    Aggregates by severity level.
+    """
+    if not output:
+        return []
+    try:
+        data = json.loads(output)
+    except (json.JSONDecodeError, TypeError):
+        return []
+
+    vulns = data.get("vulnerabilities", {})
+    if not vulns:
+        return []
+
+    severity_counts: Counter[str] = Counter()
+    for info in vulns.values():
+        sev = info.get("severity", "unknown")
+        severity_counts[sev] += 1
+
+    return [
+        SecurityAdvisory(severity=sev, count=count)
+        for sev, count in severity_counts.items()
+    ]
+
+
+async def _run_npm_outdated(npm_bin: Path, target_path: Path) -> tuple[str, str, int]:
+    """Run npm outdated --json subprocess."""
+    proc = await asyncio.create_subprocess_exec(
+        str(npm_bin),
+        "outdated",
+        "--json",
+        cwd=str(target_path),
+        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 _run_npm_audit(npm_bin: Path, target_path: Path) -> tuple[str, str, int]:
+    """Run npm audit --json subprocess."""
+    proc = await asyncio.create_subprocess_exec(
+        str(npm_bin),
+        "audit",
+        "--json",
+        cwd=str(target_path),
+        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 analyze_dependencies(target_path: Path) -> DependenciesResult:
+    """Analyze dependencies of a Node.js project."""
+    resolved = target_path.resolve()
+
+    npm_bin = _find_npm(resolved)
+    if npm_bin is None:
+        return DependenciesResult(
+            success=False,
+            target_path=str(resolved),
+            error="npm not found. Install Node.js to use dependency analysis.",
+        )
+
+    if not _check_package_json(resolved):
+        return DependenciesResult(
+            success=False,
+            target_path=str(resolved),
+            error="No package.json found in target directory.",
+        )
+
+    outdated_stdout, _, _ = await _run_npm_outdated(npm_bin, resolved)
+    audit_stdout, _, _ = await _run_npm_audit(npm_bin, resolved)
+
+    outdated = _parse_outdated_output(outdated_stdout)
+    advisories = _parse_audit_output(audit_stdout)
+
+    return DependenciesResult(
+        success=True,
+        target_path=str(resolved),
+        outdated=outdated,
+        advisories=advisories,
+    )

package/pennyfarthing_scripts/dependencies/cli.py

@@ -0,0 +1,76 @@
+"""
+CLI commands for dependency analysis.
+
+Usage:
+    python -m pennyfarthing_scripts.dependencies analyze [OPTIONS]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+
+if TYPE_CHECKING:
+    from pennyfarthing_scripts.dependencies.models import DependenciesResult
+
+
+@click.group()
+def dependencies():
+    """Dependency staleness and security analysis.
+
+    \b
+    Commands:
+      analyze  - Analyze dependency health
+    """
+    pass
+
+
+def _run_analysis(target_path: str | None) -> DependenciesResult:
+    """Run analysis and return result."""
+    from pennyfarthing_scripts.dependencies.analyze import analyze_dependencies
+
+    p = Path(target_path).resolve() if target_path else Path(".").resolve()
+    return asyncio.run(analyze_dependencies(p))
+
+
+def _output_result(result, fmt: str, output_file: str | None):
+    """Format and output the analysis result."""
+    from pennyfarthing_scripts.dependencies.formatters import (
+        export_csv,
+        export_json,
+        format_audit_table,
+        format_outdated_table,
+    )
+
+    if fmt == "json":
+        text = export_json(result)
+    elif fmt == "csv":
+        text = export_csv(result.outdated)
+    else:
+        parts = [format_outdated_table(result.outdated)]
+        if result.advisories:
+            parts.append("")
+            parts.append(format_audit_table(result.advisories))
+        text = "\n".join(parts)
+
+    if output_file:
+        Path(output_file).write_text(text)
+        click.echo(f"Output written to {output_file}", err=True)
+    else:
+        click.echo(text)
+
+
+@dependencies.command()
+@click.option("--path", "target_path", type=click.Path(exists=True),
+              help="Directory to analyze")
+@click.option("--format", "fmt", type=click.Choice(["table", "json", "csv"]),
+              default="table", show_default=True)
+@click.option("--output", "output_file", type=click.Path(),
+              help="Write output to file")
+def analyze(target_path, fmt, output_file):
+    """Analyze dependency health."""
+    result = _run_analysis(target_path)
+    _output_result(result, fmt, output_file)

package/pennyfarthing_scripts/dependencies/formatters.py

@@ -0,0 +1,63 @@
+"""
+Output formatters for dependency 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.dependencies.models import (
+    DependenciesResult,
+    OutdatedPackage,
+    SecurityAdvisory,
+)
+
+
+def format_outdated_table(packages: list[OutdatedPackage]) -> str:
+    """Format outdated packages as column-aligned table."""
+    if not packages:
+        return "  No outdated packages found."
+
+    hdr = f"{'Package':<30}  {'Current':<12}  {'Wanted':<12}  {'Latest':<12}  Type"
+    sep = f"{'-' * 30}  {'-' * 12}  {'-' * 12}  {'-' * 12}  ----"
+
+    lines = [hdr, sep]
+    for p in packages:
+        lines.append(
+            f"{p.name:<30}  {p.current:<12}  {p.wanted:<12}  {p.latest:<12}  {p.type}"
+        )
+    return "\n".join(lines)
+
+
+def format_audit_table(advisories: list[SecurityAdvisory]) -> str:
+    """Format security advisories as table."""
+    if not advisories:
+        return "  No vulnerabilities found."
+
+    hdr = f"{'Severity':<12}  {'Count':>6}"
+    sep = f"{'-' * 12}  {'-' * 6}"
+
+    lines = [hdr, sep]
+    for a in advisories:
+        lines.append(f"{a.severity:<12}  {a.count:>6}")
+    return "\n".join(lines)
+
+
+def export_json(result: DependenciesResult) -> str:
+    """Serialize result to JSON string."""
+    return json.dumps(asdict(result), indent=2, default=str)
+
+
+def export_csv(packages: list[OutdatedPackage]) -> str:
+    """Export outdated packages as CSV."""
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    writer.writerow(["name", "current", "wanted", "latest", "type"])
+    for p in packages:
+        writer.writerow([p.name, p.current, p.wanted, p.latest, p.type])
+    return buf.getvalue()

package/pennyfarthing_scripts/dependencies/models.py

@@ -0,0 +1,39 @@
+"""
+Data models for dependency analysis results.
+
+Follows ADR-0008 result pattern — structured dataclasses with success/error fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class OutdatedPackage:
+    """A package with available updates."""
+
+    name: str = ""
+    current: str = ""
+    wanted: str = ""
+    latest: str = ""
+    type: str = ""
+
+
+@dataclass
+class SecurityAdvisory:
+    """Aggregated vulnerability count per severity level."""
+
+    severity: str = ""
+    count: int = 0
+
+
+@dataclass
+class DependenciesResult:
+    """Analysis result following ADR-0008 pattern."""
+
+    success: bool = False
+    target_path: str = ""
+    outdated: list[OutdatedPackage] = field(default_factory=list)
+    advisories: list[SecurityAdvisory] = field(default_factory=list)
+    error: str | None = None

package/pennyfarthing_scripts/git/__init__.py

@@ -8,15 +8,15 @@ This package provides async git operations for multi-repo management:
 - create_branches: Create feature branches across repos in parallel
 """
 
+from pennyfarthing_scripts.git.create_branches import (
+    BranchResult,
+    create_feature_branches,
+)
 from pennyfarthing_scripts.git.status_all import (
     RepoStatus,
-    get_all_repo_status,
     format_status_brief,
     format_status_full,
-)
-from pennyfarthing_scripts.git.create_branches import (
-    BranchResult,
-    create_feature_branches,
+    get_all_repo_status,
 )
 
 __all__ = [

package/pennyfarthing_scripts/git/create_branches.py

@@ -14,10 +14,11 @@ Features:
 """
 
 import asyncio
+from collections.abc import Sequence
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import Literal, Sequence
+from typing import Literal
 
 
 class BranchAction(Enum):
@@ -296,7 +297,7 @@ def format_results(results: Sequence[BranchResult], branch_name: str) -> str:
         Multi-line formatted string with results and verification
     """
     lines = []
-    lines.append(f"🌿 Creating/checking out feature branches...")
+    lines.append("🌿 Creating/checking out feature branches...")
     lines.append(f"   Branch: {branch_name}")
     lines.append("")
 

package/pennyfarthing_scripts/git/status_all.py

@@ -13,9 +13,9 @@ Features:
 """
 
 import asyncio
+from collections.abc import Sequence
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Sequence
 
 
 @dataclass

package/pennyfarthing_scripts/healthscore/__init__.py

@@ -0,0 +1,21 @@
+"""
+Composite health score for codebase analysis.
+
+Aggregates 8 dimensions into a single 0-100 weighted score:
+churn, TODO density, complexity, test gaps, dead code,
+deprecation debt, dependency freshness, agent context efficiency.
+"""
+
+from pennyfarthing_scripts.healthscore.analyze import analyze_healthscore
+from pennyfarthing_scripts.healthscore.models import (
+    DEFAULT_WEIGHTS,
+    DimensionScore,
+    HealthscoreResult,
+)
+
+__all__ = [
+    "DimensionScore",
+    "HealthscoreResult",
+    "DEFAULT_WEIGHTS",
+    "analyze_healthscore",
+]

package/pennyfarthing_scripts/healthscore/__main__.py

@@ -0,0 +1,14 @@
+"""Allow running as: python -m pennyfarthing_scripts.healthscore"""
+
+import logging
+import sys
+
+from pennyfarthing_scripts.healthscore.cli import healthscore
+
+if __name__ == "__main__":
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(message)s",
+        stream=sys.stderr,
+    )
+    healthscore()