@pennyfarthing/core 11.3.3 → 11.3.4

package/pennyfarthing-dist/pf/complexity/cli.py

@@ -0,0 +1,82 @@
+"""
+CLI commands for complexity analysis.
+
+Usage:
+    python -m pf.complexity analyze [OPTIONS]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+
+if TYPE_CHECKING:
+    from pf.complexity.models import ComplexityResult
+
+
+@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 pf.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 pf.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-dist/pf/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 pf.complexity.models import ComplexityResult, FileComplexity
+
+
+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-dist/pf/config.py

@@ -0,0 +1,21 @@
+"""
+Configuration loading utilities for Pennyfarthing scripts.
+
+This module re-exports from pf.common.config for
+backwards compatibility. New code should import from common.config directly.
+"""
+
+# Re-export everything from the new location
+from pf.common.config import (
+    find_project_root,
+    get_project_root,
+    load_pennyfarthing_config,
+    load_yaml_config,
+)
+
+__all__ = [
+    "find_project_root",
+    "get_project_root",
+    "load_pennyfarthing_config",
+    "load_yaml_config",
+]

package/pennyfarthing-dist/pf/consultation/cli.py

@@ -0,0 +1,149 @@
+"""Click CLI for consultation dialogue management.
+
+Provides `pf consultation` group with subcommands matching
+the bash wrapper dialogue-manager.sh interface.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+import click
+
+
+@click.group()
+def consultation():
+    """Tandem consultation dialogue management.
+
+    \b
+    Subcommands:
+      init       - Create dialogue file
+      append     - Append exchange
+      outcome    - Update outcome
+      summarize  - Refresh summary
+      archive    - Archive dialogue file
+    """
+    pass
+
+
+@consultation.command()
+@click.argument("story_id")
+@click.argument("workflow")
+@click.argument("leader")
+@click.argument("partner")
+def init(story_id: str, workflow: str, leader: str, partner: str) -> None:
+    """Create a new dialogue file."""
+    from pf.consultation.dialogue_manager import (
+        DialogueHeader,
+        create_dialogue_content,
+    )
+
+    header = DialogueHeader(
+        story_id=story_id,
+        workflow=workflow,
+        leader=leader,
+        partner=partner,
+        started_at=datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    )
+
+    content = create_dialogue_content(header)
+    session_dir = Path(".session")
+    session_dir.mkdir(parents=True, exist_ok=True)
+    dialogue_path = session_dir / f"{story_id}-dialogue.md"
+    dialogue_path.write_text(content, encoding="utf-8")
+
+    click.echo(f"Created {dialogue_path}")
+
+
+@consultation.command()
+@click.argument("story_id")
+@click.argument("question")
+@click.argument("recommendation")
+@click.argument("confidence")
+def append(story_id: str, question: str, recommendation: str, confidence: str) -> None:
+    """Append an exchange to a dialogue file."""
+    from pf.consultation.dialogue_manager import (
+        DialogueExchange,
+        append_exchange_to_file,
+        parse_dialogue_exchanges,
+    )
+
+    dialogue_path = Path(".session") / f"{story_id}-dialogue.md"
+    if not dialogue_path.exists():
+        click.echo(f"Dialogue file not found: {dialogue_path}", err=True)
+        raise SystemExit(1)
+
+    content = dialogue_path.read_text(encoding="utf-8")
+    existing = parse_dialogue_exchanges(content)
+    next_num = len(existing) + 1
+
+    exchange = DialogueExchange(
+        number=next_num,
+        timestamp=datetime.now(UTC).strftime("%H:%M"),
+        leader="",
+        partner="",
+        question=question,
+        recommendation=recommendation,
+        confidence=confidence,
+    )
+
+    result = append_exchange_to_file(dialogue_path, exchange)
+    if result.success:
+        click.echo(f"Appended exchange {next_num}")
+    else:
+        click.echo(f"Error: {result.error}", err=True)
+        raise SystemExit(1)
+
+
+@consultation.command()
+@click.argument("story_id")
+@click.argument("exchange_num", type=int)
+@click.argument("outcome_value")
+@click.option("--note", default=None, help="Outcome note")
+def outcome(story_id: str, exchange_num: int, outcome_value: str, note: str | None) -> None:
+    """Update outcome of an exchange."""
+    from pf.consultation.dialogue_manager import (
+        update_outcome_in_file,
+    )
+
+    dialogue_path = Path(".session") / f"{story_id}-dialogue.md"
+    result = update_outcome_in_file(dialogue_path, exchange_num, outcome_value, note)  # type: ignore[arg-type]
+    if result.success:
+        click.echo(f"Updated exchange {exchange_num} outcome to {outcome_value}")
+    else:
+        click.echo(f"Error: {result.error}", err=True)
+        raise SystemExit(1)
+
+
+@consultation.command()
+@click.argument("story_id")
+def summarize(story_id: str) -> None:
+    """Refresh dialogue summary."""
+    from pf.consultation.dialogue_manager import refresh_summary
+
+    dialogue_path = Path(".session") / f"{story_id}-dialogue.md"
+    result = refresh_summary(dialogue_path)
+    if result.success:
+        total = result.data.get("totalExchanges", 0) if result.data else 0
+        click.echo(f"Summary refreshed ({total} exchanges)")
+    else:
+        click.echo(f"Error: {result.error}", err=True)
+        raise SystemExit(1)
+
+
+@consultation.command()
+@click.argument("story_id")
+@click.option("--jira-key", default=None, help="Jira key for archive filename")
+def archive(story_id: str, jira_key: str | None) -> None:
+    """Archive dialogue file."""
+    from pf.consultation.dialogue_manager import archive_dialogue
+
+    dialogue_path = Path(".session") / f"{story_id}-dialogue.md"
+    archive_dir = Path(".session") / "archive"
+    result = archive_dialogue(dialogue_path, archive_dir, jira_key=jira_key, story_id=story_id)
+    if result.success:
+        click.echo(f"Archived to {result.data.get('archivePath', archive_dir)}" if result.data else "Archived")
+    else:
+        click.echo(f"Error: {result.error}", err=True)
+        raise SystemExit(1)

package/pennyfarthing-dist/pf/deadcode/__main__.py

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

package/pennyfarthing-dist/pf/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 pf.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
+    )