@pennyfarthing/core 10.0.3 → 10.1.0

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 (
+    OutdatedPackage,
+    SecurityAdvisory,
+    DependenciesResult,
+)
+
+
+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,72 @@
+"""
+CLI commands for dependency analysis.
+
+Usage:
+    python -m pennyfarthing_scripts.dependencies analyze [OPTIONS]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import click
+
+
+@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 (
+        format_outdated_table,
+        format_audit_table,
+        export_json,
+        export_csv,
+    )
+
+    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 (
+    OutdatedPackage,
+    SecurityAdvisory,
+    DependenciesResult,
+)
+
+
+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/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.models import (
+    DimensionScore,
+    HealthscoreResult,
+    DEFAULT_WEIGHTS,
+)
+from pennyfarthing_scripts.healthscore.analyze import analyze_healthscore
+
+__all__ = [
+    "DimensionScore",
+    "HealthscoreResult",
+    "DEFAULT_WEIGHTS",
+    "analyze_healthscore",
+]

package/pennyfarthing_scripts/healthscore/__main__.py

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

package/pennyfarthing_scripts/healthscore/analyze.py

@@ -0,0 +1,161 @@
+"""
+Core health score analysis engine.
+
+Aggregates lightweight dimension scores into a composite 0-100 score.
+Supports caching with a configurable TTL (default 5 minutes).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from pathlib import Path
+
+from pennyfarthing_scripts.healthscore.models import (
+    DEFAULT_WEIGHTS,
+    DimensionScore,
+    HealthscoreResult,
+)
+
+
+async def analyze_healthscore(
+    target_path: Path,
+    weights: dict[str, float] | None = None,
+    cache_ttl: int = 300,
+) -> HealthscoreResult:
+    """Analyze codebase health across all dimensions.
+
+    Args:
+        target_path: Directory to analyze.
+        weights: Custom dimension weights (must sum to 1.0). Uses defaults if None.
+        cache_ttl: Cache time-to-live in seconds (default 300 = 5 minutes).
+
+    Returns:
+        HealthscoreResult with composite score and per-dimension breakdown.
+    """
+    w = weights if weights is not None else DEFAULT_WEIGHTS
+    resolved = target_path.resolve()
+
+    cache_dir = get_cache_path(resolved)
+    any_cached = False
+    raw_scores: dict[str, float | None] = {}
+    dimensions: list[DimensionScore] = []
+
+    for dim_name, dim_weight in w.items():
+        score: float | None = None
+        error: str | None = None
+
+        # Try cache if ttl > 0
+        if cache_ttl > 0:
+            cached = read_cached_score(cache_dir, dim_name, cache_ttl)
+            if cached is not None:
+                score = cached
+                any_cached = True
+
+        # If no cached value, run lightweight probe
+        if score is None:
+            score = _probe_dimension(dim_name, resolved)
+            # Cache result if we got one and caching is enabled
+            if score is not None and cache_ttl > 0:
+                cache_dir.mkdir(parents=True, exist_ok=True)
+                write_cached_score(cache_dir, dim_name, score)
+
+        if score is None:
+            error = f"{dim_name} not available"
+
+        raw_scores[dim_name] = score
+        dimensions.append(DimensionScore(
+            name=dim_name,
+            score=score,
+            weight=dim_weight,
+            error=error,
+        ))
+
+    composite = compute_composite_score(raw_scores, w)
+
+    return HealthscoreResult(
+        success=True,
+        composite_score=composite,
+        target_path=str(resolved),
+        dimensions=dimensions,
+        cached=any_cached,
+    )
+
+
+def _probe_dimension(name: str, target_path: Path) -> float | None:
+    """Run a lightweight probe for a single dimension.
+
+    Returns a score 0-100 or None if the dimension cannot be assessed.
+    These are intentionally simple heuristics — full analysis is deferred
+    to each dimension's own module when available.
+    """
+    # For now, return None for all dimensions.
+    # Each dimension will be wired to its respective analyzer in future stories.
+    return None
+
+
+def compute_composite_score(
+    dimension_scores: dict[str, float | None],
+    weights: dict[str, float],
+) -> float:
+    """Compute weighted average from dimension scores.
+
+    Dimensions with None scores are excluded and remaining weights
+    are renormalized.
+
+    Args:
+        dimension_scores: Map of dimension name to score (0-100 or None).
+        weights: Map of dimension name to weight.
+
+    Returns:
+        Composite score 0-100.
+    """
+    total_weight = 0.0
+    weighted_sum = 0.0
+
+    for name, score in dimension_scores.items():
+        if score is not None:
+            w = weights.get(name, 0.0)
+            weighted_sum += score * w
+            total_weight += w
+
+    if total_weight == 0.0:
+        return 0.0
+
+    return weighted_sum / total_weight
+
+
+def get_cache_path(target_path: Path) -> Path:
+    """Return the cache directory for a given target path."""
+    path_hash = hashlib.md5(str(target_path).encode()).hexdigest()[:12]
+    return target_path / ".pennyfarthing" / ".cache" / "healthscore" / path_hash
+
+
+def read_cached_score(cache_dir: Path, dimension: str, ttl: int) -> float | None:
+    """Read a cached dimension score if still valid.
+
+    Returns None if cache miss or expired.
+    """
+    cache_file = cache_dir / f"{dimension}.json"
+    if not cache_file.exists():
+        return None
+
+    try:
+        data = json.loads(cache_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    ts = data.get("timestamp", 0)
+    if ttl <= 0 or (time.time() - ts) > ttl:
+        return None
+
+    return data.get("score")
+
+
+def write_cached_score(cache_dir: Path, dimension: str, score: float) -> None:
+    """Write a dimension score to cache."""
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    cache_file = cache_dir / f"{dimension}.json"
+    data = {"score": score, "timestamp": time.time()}
+    cache_file.write_text(json.dumps(data))

package/pennyfarthing_scripts/healthscore/cli.py

@@ -0,0 +1,76 @@
+"""
+CLI commands for health score analysis.
+
+Usage:
+    pf healthscore analyze [OPTIONS]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import click
+
+
+@click.group()
+def healthscore():
+    """Composite codebase health score.
+
+    \b
+    Commands:
+      analyze  - Compute health score across all dimensions
+    """
+    pass
+
+
+def _common_options(fn):
+    """Shared options for healthscore 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("--output", "output_file", type=click.Path(),
+                       help="Write output to file")(fn)
+    fn = click.option("--no-cache", is_flag=True,
+                       help="Bypass cache, force fresh analysis")(fn)
+    return fn
+
+
+def _run_analysis(target_path: str | None, no_cache: bool) -> "HealthscoreResult":
+    """Run analysis and return result."""
+    from pennyfarthing_scripts.healthscore.analyze import analyze_healthscore
+
+    p = Path(target_path).resolve() if target_path else Path(".").resolve()
+    cache_ttl = 0 if no_cache else 300
+    return asyncio.run(analyze_healthscore(p, cache_ttl=cache_ttl))
+
+
+def _output_result(result, fmt: str, output_file: str | None):
+    """Format and output the analysis result."""
+    from pennyfarthing_scripts.healthscore.formatters import (
+        export_csv,
+        export_json,
+        format_table,
+    )
+
+    if fmt == "json":
+        text = export_json(result)
+    elif fmt == "csv":
+        text = export_csv(result)
+    else:
+        text = format_table(result)
+
+    if output_file:
+        Path(output_file).write_text(text)
+        click.echo(f"Output written to {output_file}", err=True)
+    else:
+        click.echo(text)
+
+
+@healthscore.command()
+@_common_options
+def analyze(target_path, fmt, output_file, no_cache):
+    """Compute composite health score."""
+    result = _run_analysis(target_path, no_cache)
+    _output_result(result, fmt, output_file)

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