ghostbuster-cli 0.1.0__py3-none-any.whl

ghostbuster/__init__.py

@@ -0,0 +1,3 @@
+"""Ghostbuster — Find and bust the ghosts haunting your codebase."""
+
+__version__ = "0.1.0"

ghostbuster/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running ghostbuster as a module: python -m ghostbuster."""
+
+from ghostbuster.cli.app import app
+
+app()

ghostbuster/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI sub-package for ghostbuster terminal interface."""

ghostbuster/cli/app.py

@@ -0,0 +1,76 @@
+"""Main Typer application — entry point for the ghostbuster CLI.
+
+This module ties together all sub-commands and global options.
+"""
+
+from __future__ import annotations
+
+import typer
+
+import ghostbuster
+from ghostbuster.cli.bust import bust
+from ghostbuster.cli.scan import scan
+
+app = typer.Typer(
+    name="ghostbuster",
+    help="Find and bust the ghosts haunting your codebase.",
+    no_args_is_help=False,
+    add_completion=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=True,
+    pretty_exceptions_show_locals=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        typer.echo(f"ghostbuster {ghostbuster.__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        "-V",
+        help="Show version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+    debug: bool = typer.Option(
+        False,
+        "--debug",
+        help="Show full stack traces on error.",
+        envvar="GHOSTBUSTER_DEBUG",
+    ),
+) -> None:
+    """Ghostbuster - Find and bust the ghosts haunting your codebase.
+
+    Run [bold cyan]ghostbuster scan[/bold cyan] to detect issues, or
+    [bold cyan]ghostbuster bust[/bold cyan] to auto-fix them.
+
+    [dim]Examples:[/dim]
+        ghostbuster scan                    # Scan current directory
+        ghostbuster scan ./my-project -v    # Verbose scan
+        ghostbuster scan --format json      # JSON output for CI
+        ghostbuster bust --confirm          # Auto-fix issues
+    """
+    # Store debug flag in context for sub-commands
+    ctx.ensure_object(dict)
+    ctx.obj["debug"] = debug
+
+    # If no sub-command is given, run scan with defaults
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(scan)
+
+
+# Register sub-commands
+app.command(name="scan")(scan)
+app.command(name="bust")(bust)
+
+
+if __name__ == "__main__":
+    app()

ghostbuster/cli/bust.py

@@ -0,0 +1,116 @@
+"""Bust command — auto-fix ghost findings.
+
+Usage:
+    ghostbuster bust [PATH] [OPTIONS]
+    ghostbuster bust .                    # dry-run by default (safe)
+    ghostbuster bust . --confirm          # actually apply fixes
+    ghostbuster bust --category dead-import --confirm
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from ghostbuster.cli.display import (
+    console,
+    print_banner,
+    print_bust_applied,
+    print_bust_preview,
+    print_error,
+)
+from ghostbuster.core.models import GhostCategory
+from ghostbuster.core.scanner import create_default_orchestrator
+from ghostbuster.fixers.import_fixer import ImportFixer
+
+
+def bust(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Path to the project directory to fix.",
+        exists=True,
+        file_okay=False,
+        resolve_path=True,
+    ),
+    confirm: bool = typer.Option(
+        False,
+        "--confirm",
+        help="Actually apply fixes. Without this flag, only shows what would be changed (dry-run).",
+    ),
+    category: list[str] | None = typer.Option(
+        None,
+        "--category",
+        "-c",
+        help="Only fix specific categories.",
+    ),
+    no_color: bool = typer.Option(
+        False,
+        "--no-color",
+        help="Disable colored output.",
+    ),
+) -> None:
+    """Bust the ghosts - auto-fix findings in your codebase.
+
+    By default, runs in dry-run mode (shows what would be fixed).
+    Use --confirm to actually apply the fixes.
+
+    Examples:
+        ghostbuster bust                      # preview changes (safe)
+        ghostbuster bust --confirm            # apply fixes
+        ghostbuster bust -c dead-import --confirm
+    """
+    if no_color:
+        console.no_color = True
+
+    # Validate categories
+    valid_categories = {c.value for c in GhostCategory}
+    if category:
+        for cat in category:
+            if cat not in valid_categories:
+                print_error(
+                    f"Unknown category: '{cat}'",
+                    f"Valid categories: {', '.join(sorted(valid_categories))}",
+                )
+                raise typer.Exit(1)
+
+    print_banner()
+
+    if confirm:
+        console.print("  [bold yellow]LIVE MODE[/bold yellow] - changes will be applied!\n")
+    else:
+        console.print("  [bold cyan]DRY-RUN MODE[/bold cyan] - no changes will be made.\n")
+
+    # First, scan to find ghosts
+    try:
+        orchestrator = create_default_orchestrator()
+
+        with console.status("[cyan]Scanning for fixable ghosts...[/cyan]", spinner="dots"):
+            result = orchestrator.run(path, categories=category)
+
+    except Exception as exc:
+        print_error(f"Scan failed: {exc}")
+        raise typer.Exit(1) from exc
+
+    # Filter to only fixable ghosts
+    fixable_ghosts = [g for g in result.ghosts if g.fixable]
+
+    if not fixable_ghosts:
+        console.print("  [green]No fixable ghosts found. Your codebase is clean![/green]\n")
+        return
+
+    console.print(f"  Found [bold]{len(fixable_ghosts)}[/bold] fixable ghosts.\n")
+
+    # Apply fixes per category
+    fixer = ImportFixer()
+
+    if confirm:
+        changes = fixer.fix(fixable_ghosts, path)
+        print_bust_applied(changes)
+        console.print(
+            "\n  [bold green]Ghostbusting complete![/bold green] "
+            "Don't forget to review the changes and run your tests.\n"
+        )
+    else:
+        changes = fixer.preview(fixable_ghosts, path)
+        print_bust_preview(changes)

ghostbuster/cli/display.py

@@ -0,0 +1,276 @@
+"""Rich console display helpers for ghostbuster output.
+
+All terminal formatting lives here — the core logic never imports Rich.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from ghostbuster.core.models import ScanResult
+
+console = Console()
+error_console = Console(stderr=True)
+
+
+def print_banner() -> None:
+    """Print the ghostbuster ASCII banner."""
+    banner = Text()
+    banner.append("G H O S T B U S T E R", style="bold cyan")
+    banner.append("\n")
+    banner.append("Find and bust the ghosts haunting your codebase", style="dim")
+
+    console.print(
+        Panel(
+            banner,
+            border_style="cyan",
+            padding=(1, 2),
+        )
+    )
+    console.print()
+
+
+def print_scanning_start(path: str, scanner_names: list[str]) -> None:
+    """Print the scan start message."""
+    console.print(f"  Scanning [bold cyan]{path}[/bold cyan]")
+    console.print(f"  Scanners: [dim]{', '.join(scanner_names)}[/dim]")
+    console.print()
+
+
+def print_scan_result(result: ScanResult, verbose: bool = False) -> None:
+    """Print the full scan result with ghost table and score card."""
+    if not result.ghosts:
+        _print_clean_result(result)
+        return
+
+    _print_ghost_table(result, verbose)
+    console.print()
+    _print_category_summary(result)
+    console.print()
+    _print_score_card(result)
+    _print_footer(result)
+
+
+def print_scan_result_json(result: ScanResult) -> None:
+    """Print scan result as JSON (for scripting/CI)."""
+    console.print_json(json.dumps(result.to_dict(), indent=2))
+
+
+def print_scan_result_markdown(result: ScanResult) -> None:
+    """Print scan result as markdown (for pasting into issues/PRs)."""
+    if result.score:
+        console.print(f"# Ghost Score: {result.score.value}/100")
+        console.print(f"_{result.score.label}_")
+        console.print()
+
+    if not result.ghosts:
+        console.print("No ghosts found!")
+        return
+
+    console.print(f"**{result.ghost_count} ghosts found** ({result.fixable_count} auto-fixable)")
+    console.print()
+
+    by_category = result.ghosts_by_category()
+    for category, ghosts in by_category.items():
+        console.print(f"## {category.label} ({len(ghosts)})")
+        console.print()
+        for ghost in ghosts:
+            location = ""
+            if ghost.file_path:
+                location = f" - `{ghost.file_path.name}"
+                if ghost.line_number:
+                    location += f":{ghost.line_number}"
+                location += "`"
+            console.print(f"- **{ghost.name}**: {ghost.message}{location}")
+        console.print()
+
+
+def print_bust_preview(changes: list[str]) -> None:
+    """Print a preview of changes that would be made in bust mode."""
+    if not changes:
+        console.print("  [green]Nothing to fix - your codebase is clean![/green]")
+        return
+
+    console.print(f"  [bold yellow]{len(changes)} fixes available (dry-run):[/bold yellow]")
+    console.print()
+    for change in changes:
+        console.print(f"  [dim]{change}[/dim]")
+    console.print()
+    console.print("  [dim]Run with [bold]--confirm[/bold] to apply these fixes.[/dim]")
+
+
+def print_bust_applied(changes: list[str]) -> None:
+    """Print the results of applied fixes."""
+    if not changes:
+        console.print("  [green]Nothing to fix![/green]")
+        return
+
+    console.print(f"  [bold green]Applied {len(changes)} fixes:[/bold green]")
+    console.print()
+    for change in changes:
+        console.print(f"  [green]{change}[/green]")
+
+
+def print_error(message: str, hint: str = "") -> None:
+    """Print a user-friendly error message."""
+    error_console.print(f"  [bold red]Error:[/bold red] {message}")
+    if hint:
+        error_console.print(f"  [dim]Hint: {hint}[/dim]")
+
+
+def _print_clean_result(result: ScanResult) -> None:
+    """Print the all-clear message when no ghosts are found."""
+    msg = Text()
+    msg.append("No ghosts detected!\n", style="bold green")
+    msg.append("Your codebase is squeaky clean.", style="green")
+
+    console.print(
+        Panel(
+            msg,
+            border_style="green",
+            title="[bold green]Ghost Report[/bold green]",
+            padding=(1, 2),
+        )
+    )
+    if result.duration_ms > 0:
+        console.print(f"  [dim]Completed in {result.duration_ms:.0f}ms[/dim]")
+
+
+def _print_ghost_table(result: ScanResult, verbose: bool) -> None:
+    """Print the table of found ghosts."""
+    table = Table(
+        title="Ghosts Found",
+        title_style="bold red",
+        border_style="red",
+        show_lines=verbose,
+        padding=(0, 1),
+    )
+
+    table.add_column("#", style="dim", width=4, justify="right")
+    table.add_column("Category", style="cyan", width=14)
+    table.add_column("Severity", width=8, justify="center")
+    table.add_column("Name", style="bold", max_width=30)
+    table.add_column("Message", max_width=60)
+    if verbose:
+        table.add_column("Location", style="dim", max_width=30)
+        table.add_column("Fix", style="green dim", max_width=30)
+
+    for i, ghost in enumerate(result.ghosts, 1):
+        row = [
+            str(i),
+            ghost.category.label,
+            ghost.severity.value.upper(),
+            ghost.name,
+            ghost.message,
+        ]
+        if verbose:
+            location = ""
+            if ghost.file_path:
+                location = ghost.file_path.name
+                if ghost.line_number:
+                    location += f":{ghost.line_number}"
+            row.append(location)
+            row.append(ghost.suggestion if ghost.fixable else "-")
+
+        table.add_row(*row)
+
+    console.print(table)
+
+
+def _print_category_summary(result: ScanResult) -> None:
+    """Print a summary breakdown by category."""
+    by_category = result.ghosts_by_category()
+
+    table = Table(
+        title="Breakdown by Category",
+        title_style="bold",
+        border_style="dim",
+        show_header=True,
+        padding=(0, 1),
+    )
+
+    table.add_column("Category", style="cyan")
+    table.add_column("Count", justify="right", style="bold")
+    table.add_column("Fixable", justify="right", style="green")
+    table.add_column("Description", style="dim")
+
+    for category in sorted(by_category.keys(), key=lambda c: len(by_category[c]), reverse=True):
+        ghosts = by_category[category]
+        fixable = sum(1 for g in ghosts if g.fixable)
+        table.add_row(
+            category.label,
+            str(len(ghosts)),
+            str(fixable) if fixable > 0 else "-",
+            category.description,
+        )
+
+    console.print(table)
+
+
+def _print_score_card(result: ScanResult) -> None:
+    """Print the Ghost Score card."""
+    if not result.score:
+        return
+
+    score = result.score
+    score_val = score.value
+
+    # Color based on score severity
+    if score_val == 0 or score_val <= 20:
+        color = "green"
+        bar_char = "#"
+    elif score_val <= 50:
+        color = "yellow"
+        bar_char = "#"
+    elif score_val <= 80:
+        color = "red"
+        bar_char = "#"
+    else:
+        color = "bold red"
+        bar_char = "#"
+
+    # Build the score bar (50 chars wide)
+    bar_width = 50
+    filled = int(score_val / 100 * bar_width)
+    empty = bar_width - filled
+    bar = f"[{color}]{bar_char * filled}[/{color}][dim]{'-' * empty}[/dim]"
+
+    content = f"  [bold {color}]{score_val}[/bold {color}] / 100\n\n  {bar}\n\n  {score.label}"
+
+    console.print(
+        Panel(
+            content,
+            title=f"[bold {color}]Ghost Score[/bold {color}]",
+            border_style=color,
+            padding=(1, 2),
+            width=62,
+        )
+    )
+
+
+def _print_footer(result: ScanResult) -> None:
+    """Print the scan footer with stats."""
+    console.print()
+    parts = []
+    if result.ghost_count > 0:
+        parts.append(f"[bold]{result.ghost_count}[/bold] ghosts found")
+    if result.fixable_count > 0:
+        parts.append(f"[green]{result.fixable_count}[/green] auto-fixable")
+    if result.duration_ms > 0:
+        parts.append(f"Completed in {result.duration_ms:.0f}ms")
+
+    if parts:
+        console.print("  " + " | ".join(parts))
+
+    if result.fixable_count > 0:
+        console.print(
+            "\n  [dim]Run [bold]ghostbuster bust --confirm[/bold] to auto-fix what we can.[/dim]"
+        )
+    console.print()

ghostbuster/cli/scan.py

@@ -0,0 +1,141 @@
+"""Scan command — the primary ghostbuster command.
+
+Usage:
+    ghostbuster scan [PATH] [OPTIONS]
+    ghostbuster scan .
+    ghostbuster scan --format json
+    ghostbuster scan --category dead-import --verbose
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+
+import typer
+
+from ghostbuster.cli.display import (
+    console,
+    print_banner,
+    print_error,
+    print_scan_result,
+    print_scan_result_json,
+    print_scan_result_markdown,
+    print_scanning_start,
+)
+from ghostbuster.core.models import GhostCategory
+from ghostbuster.core.scanner import create_default_orchestrator
+
+
+class OutputFormat(str, Enum):
+    """Output format for scan results."""
+
+    rich = "rich"
+    json = "json"
+    markdown = "markdown"
+
+
+def scan(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Path to the project directory to scan.",
+        exists=True,
+        file_okay=False,
+        resolve_path=True,
+    ),
+    format: OutputFormat = typer.Option(
+        OutputFormat.rich,
+        "--format",
+        "-f",
+        help="Output format: rich (colorful), json (machine-readable), markdown (for issues/PRs).",
+    ),
+    category: list[str] | None = typer.Option(
+        None,
+        "--category",
+        "-c",
+        help="Only scan specific categories (dead-import, orphan-file, zombie-code, phantom-env).",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show detailed findings with locations and fix suggestions.",
+    ),
+    no_color: bool = typer.Option(
+        False,
+        "--no-color",
+        help="Disable colored output.",
+    ),
+) -> None:
+    """Scan your codebase for ghosts.
+
+    Searches for dead imports, orphan files, zombie code, and phantom
+    environment variables in your project.
+
+    Examples:
+        ghostbuster scan
+        ghostbuster scan ./my-project --verbose
+        ghostbuster scan --format json --category dead-import
+    """
+    if no_color:
+        console.no_color = True
+
+    # Validate categories if provided
+    valid_categories = {c.value for c in GhostCategory}
+    if category:
+        for cat in category:
+            if cat not in valid_categories:
+                print_error(
+                    f"Unknown category: '{cat}'",
+                    f"Valid categories: {', '.join(sorted(valid_categories))}",
+                )
+                raise typer.Exit(1)
+
+    # Show banner for rich format
+    if format == OutputFormat.rich:
+        print_banner()
+        print_scanning_start(str(path), _get_scanner_names(category))
+
+    # Run the scan
+    try:
+        orchestrator = create_default_orchestrator()
+
+        with (
+            console.status("[cyan]Hunting for ghosts...[/cyan]", spinner="dots")
+            if format == OutputFormat.rich
+            else _nullcontext()
+        ):
+            result = orchestrator.run(path, categories=category)
+
+    except Exception as exc:
+        print_error(f"Scan failed: {exc}", "Run with --debug flag for full traceback.")
+        raise typer.Exit(1) from exc
+
+    # Display results
+    if format == OutputFormat.json:
+        print_scan_result_json(result)
+    elif format == OutputFormat.markdown:
+        print_scan_result_markdown(result)
+    else:
+        print_scan_result(result, verbose=verbose)
+
+    # Exit with non-zero code if ghosts were found (useful for CI)
+    if result.ghost_count > 0:
+        raise typer.Exit(1)
+
+
+def _get_scanner_names(categories: list[str] | None) -> list[str]:
+    """Get human-readable scanner names."""
+    if categories:
+        return categories
+    return ["dead-import", "orphan-file", "zombie-code", "phantom-env"]
+
+
+class _nullcontext:
+    """Simple null context manager for Python 3.10 compatibility."""
+
+    def __enter__(self) -> None:
+        return None
+
+    def __exit__(self, *args: object) -> None:
+        pass