@pennyfarthing/core 10.0.3 → 10.1.0

package/pennyfarthing_scripts/deadcode/analyze.py

@@ -0,0 +1,323 @@
+"""
+Core dead code detection engine.
+
+Layer 1: Compares git ls-files against git log --since to find files with no recent commits.
+Layer 2: Runs ts-prune to find unused TypeScript exports.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import fnmatch
+from datetime import datetime, timezone
+from pathlib import Path
+
+import re
+
+from pennyfarthing_scripts.deadcode.models import (
+    DeadCodeResult,
+    StaleFile,
+    UnusedExport,
+    UnusedExportResult,
+)
+
+# Default file patterns to exclude from analysis
+DEFAULT_EXCLUDES = [
+    "node_modules/*",
+    "dist/*",
+    "build/*",
+    "*.lock",
+    "*.min.js",
+    "*.min.css",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+]
+
+# Source file extensions to include
+SOURCE_EXTENSIONS = {
+    ".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs",
+    ".java", ".kt", ".swift", ".rb", ".sh", ".bash",
+    ".css", ".scss", ".less", ".html", ".md", ".yaml", ".yml",
+    ".json", ".toml",
+}
+
+
+async def _run_git_command(args: list[str], cwd: Path) -> tuple[str, str, int]:
+    """Run a git command asynchronously.
+
+    Args:
+        args: Git command arguments (without 'git')
+        cwd: Working directory
+
+    Returns:
+        (stdout, stderr, return_code)
+    """
+    proc = await asyncio.create_subprocess_exec(
+        "git",
+        *args,
+        cwd=cwd,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout, stderr = await proc.communicate()
+    return (
+        stdout.decode("utf-8", errors="replace").strip(),
+        stderr.decode("utf-8", errors="replace").strip(),
+        proc.returncode or 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
+        if fnmatch.fnmatch(path.split("/")[-1], pattern):
+            return True
+    return False
+
+
+def _is_source_file(path: str) -> bool:
+    """Check if a file has a recognized source extension."""
+    suffix = Path(path).suffix.lower()
+    return suffix in SOURCE_EXTENSIONS
+
+
+async def find_stale_files(
+    repo_path: Path,
+    days: int = 180,
+    excludes: list[str] | None = None,
+    branch: str = "--all",
+) -> DeadCodeResult:
+    """Find files with no commits in the given time window.
+
+    Args:
+        repo_path: Path to the git repository
+        days: Time window in days
+        excludes: Additional file patterns to exclude
+        branch: Branch spec (default --all)
+
+    Returns:
+        DeadCodeResult with stale files
+    """
+    all_excludes = DEFAULT_EXCLUDES + (excludes or [])
+    resolved = Path(repo_path).resolve()
+
+    # Get all tracked files
+    ls_stdout, ls_stderr, ls_rc = await _run_git_command(["ls-files"], resolved)
+
+    if ls_rc != 0:
+        return DeadCodeResult(
+            success=False,
+            repo_name=resolved.name,
+            repo_path=str(resolved),
+            time_window_days=days,
+            error=f"git ls-files failed: {ls_stderr}",
+        )
+
+    all_files = set()
+    for line in ls_stdout.split("\n"):
+        line = line.strip()
+        if line:
+            all_files.add(line)
+
+    if not all_files:
+        return DeadCodeResult(
+            success=True,
+            repo_name=resolved.name,
+            repo_path=str(resolved),
+            time_window_days=days,
+            total_files=0,
+        )
+
+    # Get recently touched files
+    log_stdout, log_stderr, log_rc = await _run_git_command(
+        ["log", f"--since={days} days ago", branch, "--name-only", "--pretty=format:"],
+        resolved,
+    )
+
+    recent_files = set()
+    if log_rc == 0 and log_stdout:
+        for line in log_stdout.split("\n"):
+            line = line.strip()
+            if line:
+                recent_files.add(line)
+
+    # Set difference: stale = all - recent
+    candidate_stale = all_files - recent_files
+
+    # Filter: exclude patterns and non-source files
+    filtered = []
+    for fpath in candidate_stale:
+        if _should_exclude(fpath, all_excludes):
+            continue
+        if not _is_source_file(fpath):
+            continue
+        filtered.append(fpath)
+
+    # Enrich each stale file
+    now = datetime.now(timezone.utc)
+    stale_files = []
+    for fpath in sorted(filtered):
+        # Get last commit date
+        date_stdout, _, _ = await _run_git_command(
+            ["log", "-1", "--format=%aI", "--", fpath],
+            resolved,
+        )
+        last_commit_date = date_stdout.strip()
+
+        # Calculate days since last commit
+        days_since = 0
+        if last_commit_date:
+            try:
+                last_dt = datetime.fromisoformat(last_commit_date)
+                days_since = int((now - last_dt).total_seconds() / 86400)
+            except (ValueError, TypeError):
+                pass
+
+        # Get file size
+        size_bytes = 0
+        try:
+            full_path = resolved / fpath
+            size_bytes = full_path.stat().st_size
+        except (OSError, FileNotFoundError):
+            pass
+
+        stale_files.append(
+            StaleFile(
+                path=fpath,
+                last_commit_date=last_commit_date,
+                days_since_last_commit=days_since,
+                size_bytes=size_bytes,
+            )
+        )
+
+    return DeadCodeResult(
+        success=True,
+        repo_name=resolved.name,
+        repo_path=str(resolved),
+        time_window_days=days,
+        stale_files=stale_files,
+        total_files=len(all_files),
+    )
+
+
+async def analyze_repo(
+    name: str,
+    path: Path,
+    days: int = 180,
+    excludes: list[str] | None = None,
+    branch: str = "--all",
+) -> DeadCodeResult:
+    """Analyze a single repository for stale files.
+
+    Args:
+        name: Display name for the repository
+        path: Path to the git repository
+        days: Time window in days
+        excludes: Additional file patterns to exclude
+        branch: Branch spec (default --all)
+
+    Returns:
+        DeadCodeResult with stale files
+    """
+    resolved = Path(path).resolve()
+
+    if not resolved.exists():
+        return DeadCodeResult(
+            success=False,
+            repo_name=name,
+            repo_path=str(resolved),
+            time_window_days=days,
+            error=f"Path not found: {resolved}",
+        )
+
+    result = await find_stale_files(resolved, days, excludes, branch)
+    # Override repo_name with the provided name
+    result.repo_name = name
+    return result
+
+
+# ts-prune output line pattern: "path/to/file.ts:line - symbolName"
+_TS_PRUNE_LINE_RE = re.compile(r"^(.+):(\d+) - (.+)$")
+
+
+def _parse_ts_prune_output(output: str) -> list[UnusedExport]:
+    """Parse ts-prune stdout into UnusedExport instances.
+
+    ts-prune format: ``path/to/file.ts:10 - symbolName``
+    Lines ending with ``(used in module)`` are skipped (not truly unused).
+    """
+    exports: list[UnusedExport] = []
+    for line in output.strip().split("\n"):
+        line = line.strip()
+        if not line:
+            continue
+        # Skip "used in module" markers — these are re-exported and consumed
+        if line.endswith("(used in module)"):
+            continue
+
+        m = _TS_PRUNE_LINE_RE.match(line)
+        if not m:
+            continue
+
+        file_path, line_no, symbol = m.group(1), int(m.group(2)), m.group(3).strip()
+        export_type = "default" if symbol == "default" else "named"
+        exports.append(
+            UnusedExport(
+                symbol=symbol,
+                file=file_path,
+                line=line_no,
+                export_type=export_type,
+            )
+        )
+    return exports
+
+
+async def find_unused_exports(repo_path: Path) -> UnusedExportResult:
+    """Find unused TypeScript exports via ts-prune.
+
+    Runs ``npx ts-prune`` in the repo and parses the output.
+
+    Args:
+        repo_path: Path to a TypeScript project with tsconfig.json
+
+    Returns:
+        UnusedExportResult with unused exports
+    """
+    resolved = Path(repo_path).resolve()
+
+    if not resolved.exists():
+        return UnusedExportResult(
+            success=False,
+            repo_name=resolved.name,
+            repo_path=str(resolved),
+            error=f"Path not found: {resolved}",
+        )
+
+    proc = await asyncio.create_subprocess_exec(
+        "npx", "ts-prune",
+        cwd=resolved,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout_bytes, stderr_bytes = await proc.communicate()
+    stdout = stdout_bytes.decode("utf-8", errors="replace").strip()
+    stderr = stderr_bytes.decode("utf-8", errors="replace").strip()
+
+    if proc.returncode and proc.returncode != 0:
+        return UnusedExportResult(
+            success=False,
+            repo_name=resolved.name,
+            repo_path=str(resolved),
+            error=f"ts-prune failed (exit {proc.returncode}): {stderr}",
+        )
+
+    exports = _parse_ts_prune_output(stdout)
+    return UnusedExportResult(
+        success=True,
+        repo_name=resolved.name,
+        repo_path=str(resolved),
+        unused_exports=exports,
+        total_exports_scanned=0,  # ts-prune doesn't report total count
+    )

package/pennyfarthing_scripts/deadcode/cli.py

@@ -0,0 +1,163 @@
+"""
+CLI commands for dead code detection.
+
+Usage:
+    pf deadcode stale [OPTIONS]
+    pf deadcode exports [OPTIONS]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import click
+
+
+@click.group()
+def deadcode():
+    """Dead code detection tools.
+
+    \b
+    Commands:
+      stale    - Find files with no recent commits
+      exports  - Find unused TypeScript exports via ts-prune
+    """
+    pass
+
+
+def _common_options(fn):
+    """Shared options for deadcode commands."""
+    fn = click.option("--repo", help="Analyze a single named repo from repos.yaml")(fn)
+    fn = click.option("--path", "repo_path", type=click.Path(exists=True), help="Analyze a standalone repo path")(fn)
+    fn = click.option("--days", default=180, show_default=True, help="Time window in days")(fn)
+    fn = click.option("--top", default=20, show_default=True, help="Number of top results to show")(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("--exclude", multiple=True, help="Additional exclude patterns (repeatable)")(fn)
+    fn = click.option("--branch", default="--all", show_default=True, help="Branch spec for git log")(fn)
+    return fn
+
+
+def _run_analysis(repo: str | None, repo_path: str | None, days: int, exclude: tuple, branch: str):
+    """Run analysis and return result."""
+    from pennyfarthing_scripts.deadcode.analyze import analyze_repo, find_stale_files
+    from pennyfarthing_scripts.common.config import get_project_root
+
+    excludes = list(exclude) if exclude else None
+
+    if repo_path:
+        p = Path(repo_path).resolve()
+        return asyncio.run(analyze_repo(p.name, p, days, excludes, branch))
+    elif repo:
+        project_root = get_project_root()
+        from pennyfarthing_scripts.common.config import load_yaml_config
+        repos_yaml = load_yaml_config(project_root / ".pennyfarthing" / "repos.yaml")
+        if repos_yaml and repo in repos_yaml:
+            cfg = repos_yaml[repo]
+            rpath = cfg.get("path", repo) if isinstance(cfg, dict) else str(cfg)
+            return asyncio.run(analyze_repo(repo, project_root / rpath, days, excludes, branch))
+        else:
+            candidate = project_root / repo
+            if candidate.exists():
+                return asyncio.run(analyze_repo(repo, candidate, days, excludes, branch))
+            raise click.ClickException(f"Repo not found: {repo}")
+    else:
+        project_root = get_project_root()
+        return asyncio.run(analyze_repo(project_root.name, project_root, days, excludes, branch))
+
+
+def _output_result(result, fmt: str, output_file: str | None, top: int):
+    """Format and output the analysis result."""
+    from pennyfarthing_scripts.deadcode.formatters import (
+        export_csv,
+        export_json,
+        format_table,
+    )
+
+    if fmt == "json":
+        text = export_json(result)
+    elif fmt == "csv":
+        text = export_csv(result.stale_files[:top])
+    else:
+        text = format_table(result.stale_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)
+
+
+@deadcode.command()
+@_common_options
+def stale(repo, repo_path, days, top, fmt, output_file, exclude, branch):
+    """Find files with no recent git commits."""
+    result = _run_analysis(repo, repo_path, days, exclude, branch)
+    _output_result(result, fmt, output_file, top)
+
+
+def _exports_options(fn):
+    """Shared options for exports subcommand."""
+    fn = click.option("--repo", help="Analyze a single named repo from repos.yaml")(fn)
+    fn = click.option("--path", "repo_path", type=click.Path(exists=True), help="Analyze a standalone repo path")(fn)
+    fn = click.option("--top", default=20, show_default=True, help="Number of top results to show")(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)
+    return fn
+
+
+def _run_exports_analysis(repo: str | None, repo_path: str | None):
+    """Run unused export analysis and return result."""
+    from pennyfarthing_scripts.deadcode.analyze import find_unused_exports
+    from pennyfarthing_scripts.common.config import get_project_root
+
+    if repo_path:
+        p = Path(repo_path).resolve()
+        return asyncio.run(find_unused_exports(p))
+    elif repo:
+        project_root = get_project_root()
+        from pennyfarthing_scripts.common.config import load_yaml_config
+        repos_yaml = load_yaml_config(project_root / ".pennyfarthing" / "repos.yaml")
+        if repos_yaml and repo in repos_yaml:
+            cfg = repos_yaml[repo]
+            rpath = cfg.get("path", repo) if isinstance(cfg, dict) else str(cfg)
+            return asyncio.run(find_unused_exports(project_root / rpath))
+        else:
+            candidate = project_root / repo
+            if candidate.exists():
+                return asyncio.run(find_unused_exports(candidate))
+            raise click.ClickException(f"Repo not found: {repo}")
+    else:
+        project_root = get_project_root()
+        return asyncio.run(find_unused_exports(project_root))
+
+
+def _output_exports_result(result, fmt: str, output_file: str | None, top: int):
+    """Format and output the exports analysis result."""
+    from pennyfarthing_scripts.deadcode.formatters import (
+        export_exports_csv,
+        export_exports_json,
+        format_exports_table,
+    )
+
+    if fmt == "json":
+        text = export_exports_json(result)
+    elif fmt == "csv":
+        text = export_exports_csv(result.unused_exports[:top])
+    else:
+        text = format_exports_table(result.unused_exports, top)
+
+    if output_file:
+        Path(output_file).write_text(text)
+        click.echo(f"Output written to {output_file}", err=True)
+    else:
+        click.echo(text)
+
+
+@deadcode.command()
+@_exports_options
+def exports(repo, repo_path, top, fmt, output_file):
+    """Find unused TypeScript exports via ts-prune."""
+    result = _run_exports_analysis(repo, repo_path)
+    _output_exports_result(result, fmt, output_file, top)

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.models import (
+    OutdatedPackage,
+    SecurityAdvisory,
+    DependenciesResult,
+)
+from pennyfarthing_scripts.dependencies.analyze import analyze_dependencies
+
+__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()