@pennyfarthing/core 10.0.5 → 10.2.0

package/pennyfarthing_scripts/context.py

@@ -9,7 +9,6 @@ import os
 import time
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional
 
 try:
     import yaml
@@ -45,8 +44,8 @@ class ContextResult:
 
     # Status
     status: str = "OK"  # OK, HIGH
-    warning: Optional[str] = None  # None, High, Critical
-    recommendation: Optional[str] = None
+    warning: str | None = None  # None, High, Critical
+    recommendation: str | None = None
 
     # Mode settings
     permission_mode: str = "manual"
@@ -56,7 +55,7 @@ class ContextResult:
     is_cyclist: bool = False
 
     # Error state
-    error: Optional[str] = None
+    error: str | None = None
 
     def to_env_vars(self) -> str:
         """Output as shell environment variables."""
@@ -111,7 +110,7 @@ class ContextResult:
         return "\n".join(lines)
 
 
-def load_config(project_dir: Optional[str] = None) -> ContextConfig:
+def load_config(project_dir: str | None = None) -> ContextConfig:
     """Load context configuration from config files.
 
     Checks .pennyfarthing/config.local.yaml first, falls back to
@@ -166,7 +165,7 @@ def _apply_config(config: ContextConfig, data: dict) -> None:
         config.relay_mode = wf.get("relay_mode", False) is True
 
 
-def get_claude_project_path(project_dir: Optional[str] = None) -> Path:
+def get_claude_project_path(project_dir: str | None = None) -> Path:
     """Get the Claude Code project path for transcripts.
 
     Claude Code stores transcripts at ~/.claude/projects/<path-with-dashes>
@@ -184,10 +183,10 @@ def get_claude_project_path(project_dir: Optional[str] = None) -> Path:
 
 def find_transcript(
     project_path: Path,
-    explicit_session: Optional[str] = None,
-    session_id_env: Optional[str] = None,
+    explicit_session: str | None = None,
+    session_id_env: str | None = None,
     stale_threshold_seconds: int = 60,
-) -> Optional[Path]:
+) -> Path | None:
     """Find the appropriate transcript file.
 
     Priority:
@@ -208,7 +207,7 @@ def find_transcript(
         return None
 
     # Helper to find most recent transcript
-    def most_recent() -> Optional[Path]:
+    def most_recent() -> Path | None:
         transcripts = sorted(
             [f for f in project_path.glob("*.jsonl") if "agent-" not in f.name],
             key=lambda f: f.stat().st_mtime,
@@ -236,7 +235,7 @@ def find_transcript(
     return most_recent()
 
 
-def parse_transcript(transcript_path: Path) -> tuple[Optional[int], Optional[int]]:
+def parse_transcript(transcript_path: Path) -> tuple[int | None, int | None]:
     """Parse transcript for first and last usage totals.
 
     Returns:
@@ -265,7 +264,7 @@ def parse_transcript(transcript_path: Path) -> tuple[Optional[int], Optional[int
     return first_total, last_total
 
 
-def detect_cyclist(project_dir: Optional[str] = None) -> bool:
+def detect_cyclist(project_dir: str | None = None) -> bool:
     """Detect if running inside Cyclist.
 
     Checks:
@@ -300,7 +299,7 @@ def detect_cyclist(project_dir: Optional[str] = None) -> bool:
                     result = s.connect_ex(("127.0.0.1", port))
                     if result == 0:
                         return True
-            except (ValueError, OSError, socket.error):
+            except (ValueError, OSError):
                 # Port file invalid or port not responding
                 continue
 
@@ -308,8 +307,8 @@ def detect_cyclist(project_dir: Optional[str] = None) -> bool:
 
 
 def check_context(
-    explicit_session: Optional[str] = None,
-    project_dir: Optional[str] = None,
+    explicit_session: str | None = None,
+    project_dir: str | None = None,
 ) -> ContextResult:
     """Check current context usage.
 

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

package/pennyfarthing_scripts/deadcode/analyze.py

@@ -0,0 +1,322 @@
+"""
+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
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+
+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(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.common.config import get_project_root
+    from pennyfarthing_scripts.deadcode.analyze import analyze_repo
+
+    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.common.config import get_project_root
+    from pennyfarthing_scripts.deadcode.analyze import find_unused_exports
+
+    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)