repodoc 0.1.0__py3-none-any.whl

repodoc/__init__.py

@@ -0,0 +1,3 @@
+"""RepoDoctor: A Copilot-first CLI tool for repository health analysis."""
+
+__version__ = "0.1.0"

repodoc/cli.py

@@ -0,0 +1,98 @@
+"""CLI entry point for RepoDoctor."""
+
+import contextlib
+import locale
+import sys
+
+import typer
+from rich.console import Console
+
+from repodoc import __version__
+from repodoc.commands import deadcode, diet, docker, report, scan, tour
+
+# Force UTF-8 encoding for all output streams (Windows compatibility)
+if sys.platform == "win32":
+    # Set console code page to UTF-8 on Windows
+    with contextlib.suppress(Exception):
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        kernel32.SetConsoleCP(65001)
+        kernel32.SetConsoleOutputCP(65001)
+
+# Set default encoding for Python's text streams
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+
+# Set locale to UTF-8 if possible
+with contextlib.suppress(locale.Error):
+    locale.setlocale(locale.LC_ALL, "en_US.UTF-8")
+with contextlib.suppress(locale.Error):
+    locale.setlocale(locale.LC_ALL, "C.UTF-8")
+
+app = typer.Typer(
+    name="repodoc",
+    help="""
+    🏥 RepoDoctor - AI-Powered Repository Health Analysis
+
+    RepoDoctor uses GitHub Copilot CLI to analyze your codebase and provide
+    actionable insights on repository health, code quality, and best practices.
+
+    📋 Quick Start:
+
+      $ repodoc scan              # Full health check
+      $ repodoc diet              # Find bloat and missing files
+      $ repodoc tour              # Generate TOUR.md for onboarding
+      $ repodoc docker            # Analyze Dockerfiles
+      $ repodoc deadcode          # Detect unused code
+
+    ⚙️  Requirements:
+
+      • GitHub Copilot CLI must be installed and authenticated
+      • Run from within a code repository directory
+
+    📖 For detailed help on each command:
+
+      $ repodoc <command> --help
+    """,
+    add_completion=False,
+    no_args_is_help=True,
+)
+# Force UTF-8 for Rich console output
+console = Console(force_terminal=None, legacy_windows=False)
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        console.print(f"[bold]RepoDoctor[/bold] version {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show version and exit.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """RepoDoctor - Copilot-powered repository health analysis."""
+    pass
+
+
+# Register commands
+app.command(name="diet")(diet)
+app.command(name="tour")(tour)
+app.command(name="docker")(docker)
+app.command(name="deadcode")(deadcode)
+app.command(name="scan")(scan)
+app.command(name="report")(report)
+
+
+if __name__ == "__main__":
+    app()

repodoc/commands/__init__.py

@@ -0,0 +1,10 @@
+"""Command implementations for RepoDoctor CLI."""
+
+from repodoc.commands.deadcode import deadcode
+from repodoc.commands.diet import diet
+from repodoc.commands.docker import docker
+from repodoc.commands.report import report
+from repodoc.commands.scan import scan
+from repodoc.commands.tour import tour
+
+__all__ = ["diet", "tour", "docker", "deadcode", "scan", "report"]

repodoc/commands/base.py

@@ -0,0 +1,284 @@
+"""Base command infrastructure with common patterns and utilities."""
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from repodoc.core.exceptions import RepoDocError
+from repodoc.core.logger import get_logger
+
+# Force UTF-8 for Rich console output
+console = Console(force_terminal=None, legacy_windows=False)
+logger = get_logger()
+
+
+def get_repo_root() -> Path:
+    """
+    Get the repository root directory (current working directory).
+
+    Returns:
+        Path to repository root
+
+    Raises:
+        EmptyRepositoryError: If repository has no analyzable content
+    """
+    from repodoc.core.exceptions import EmptyRepositoryError
+
+    cwd = Path.cwd().resolve()
+    logger.debug(f"Working directory: {cwd}")
+
+    # Basic validation: check if directory has any code files
+    has_content = False
+    common_code_extensions = {
+        ".py",
+        ".js",
+        ".ts",
+        ".java",
+        ".go",
+        ".rs",
+        ".rb",
+        ".cpp",
+        ".c",
+        ".h",
+        ".css",
+        ".html",
+    }
+
+    try:
+        # Quick check: look for at least one code file in first few levels
+        for item in cwd.iterdir():
+            if item.is_file() and item.suffix in common_code_extensions:
+                has_content = True
+                break
+            elif item.is_dir() and not item.name.startswith("."):
+                # Check one level deep
+                for subitem in item.iterdir():
+                    if subitem.is_file() and subitem.suffix in common_code_extensions:
+                        has_content = True
+                        break
+            if has_content:
+                break
+    except (PermissionError, OSError):
+        # If we can't read, assume it's okay
+        logger.warning("Could not fully validate repository content")
+        return cwd
+
+    if not has_content:
+        logger.warning(f"No code files found in {cwd}")
+        raise EmptyRepositoryError()
+
+    return cwd
+
+
+def ensure_repodoc_dir(repo_root: Path) -> Path:
+    """Ensure .repodoc directory exists in repository root."""
+    repodoc_dir = repo_root / ".repodoc"
+    repodoc_dir.mkdir(exist_ok=True)
+    logger.debug(f"Ensured .repodoc directory: {repodoc_dir}")
+    return repodoc_dir
+
+
+def save_json_output(data: Any, output_path: Path) -> None:
+    """Save structured data as JSON to specified path."""
+    try:
+        with open(output_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+        console.print(f"[green]✓[/green] JSON output saved to: {output_path}")
+        logger.info(f"Saved JSON output to {output_path}")
+    except Exception as e:
+        error_msg = f"Failed to save JSON output to {output_path}: {e}"
+        logger.error(error_msg)
+        raise RepoDocError(error_msg) from e
+
+
+def save_text_output(
+    output_path: Path, render_func: Callable[..., None], *args: Any, **kwargs: Any
+) -> None:
+    """
+    Save formatted text output to file by capturing rendered content.
+
+    Args:
+        output_path: Path to save the output
+        render_func: Renderer function to call (e.g., renderer.render)
+        *args, **kwargs: Arguments to pass to the render function
+    """
+    try:
+        from rich.console import Console
+
+        # Create a file console that writes to the output file
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            file_console = Console(
+                file=f,
+                width=120,
+                force_terminal=False,  # Disable color codes for file
+                legacy_windows=False,
+            )
+
+            # Create a new terminal renderer with the file console
+            from repodoc.renderers.terminal_renderer import TerminalRenderer
+
+            file_terminal = TerminalRenderer(
+                verbose=kwargs.get("verbose", False), console=file_console
+            )
+
+            # Replace the console in the renderer temporarily
+            original_terminal = kwargs.get("terminal")
+            if original_terminal:
+                # Create new renderer with file terminal
+                # Type ignore needed because __self__ is not part of Callable type
+                renderer_class = render_func.__self__.__class__  # type: ignore[attr-defined]
+                file_renderer = renderer_class(file_terminal)
+                # Call render method with file renderer
+                getattr(file_renderer, render_func.__name__)(*args)  # type: ignore[attr-defined]
+
+        console.print(f"[green]✓[/green] Output saved to: {output_path}")
+        logger.info(f"Saved text output to {output_path}")
+    except Exception as e:
+        error_msg = f"Failed to save output to {output_path}: {e}"
+        logger.error(error_msg)
+        raise RepoDocError(error_msg) from e
+
+
+def handle_json_flag(data: dict[str, Any], json_flag: bool, out_path: str | None) -> None:
+    """Handle --json and --out flags for structured output."""
+    if json_flag and not out_path:
+        # Use print() for pure JSON output without Rich formatting
+        print(json.dumps(data, indent=2))
+    elif out_path:
+        output_file = Path(out_path)
+        save_json_output(data, output_file)
+
+
+def print_success_message(command: str, next_actions: list[str] | None = None) -> None:
+    """
+    Print a success message with optional next actions.
+
+    Args:
+        command: Name of the command that succeeded
+        next_actions: List of suggested next actions
+    """
+    console.print(f"\n[green bold]✓ {command} completed successfully![/green bold]")
+
+    if next_actions:
+        console.print("\n[cyan]💡 Next steps:[/cyan]")
+        for action in next_actions:
+            console.print(f"  • {action}")
+
+
+def print_progress(message: str, emoji: str = "⏳") -> None:
+    """Print a progress message with emoji."""
+    console.print(f"\n{emoji} {message}...")
+
+
+def render_health_score(score: float, label: str = "Health Score") -> None:
+    """Render a health score with color coding."""
+    if score >= 80:
+        color = "green"
+        emoji = "✓"
+    elif score >= 60:
+        color = "yellow"
+        emoji = "⚠"
+    else:
+        color = "red"
+        emoji = "✗"
+
+    console.print(
+        Panel(f"[{color} bold]{emoji} {label}: {score}/100[/{color} bold]", border_style=color)
+    )
+
+
+def render_issues_table(issues: list[dict[str, Any]], title: str = "Issues") -> None:
+    """Render a table of issues with severity indicators."""
+    if not issues:
+        console.print(f"[green]✓[/green] No {title.lower()} found")
+        return
+
+    table = Table(title=title, show_header=True, header_style="bold magenta")
+    table.add_column("Severity", style="dim", width=10)
+    table.add_column("Category", style="cyan", width=15)
+    table.add_column("Description")
+
+    for issue in issues:
+        severity = issue.get("severity", "unknown")
+        category = issue.get("category", "general")
+        description = issue.get("description", "")
+
+        severity_color = {
+            "critical": "red bold",
+            "high": "red",
+            "medium": "yellow",
+            "low": "blue",
+            "info": "dim",
+        }.get(severity, "white")
+
+        table.add_row(
+            f"[{severity_color}]{severity.upper()}[/{severity_color}]", category, description
+        )
+
+    console.print(table)
+
+
+def render_recommendations(recommendations: list[dict[str, Any]]) -> None:
+    """Render recommendations as a formatted list."""
+    if not recommendations:
+        return
+
+    console.print("\n[bold cyan]Recommendations:[/bold cyan]")
+    for i, rec in enumerate(recommendations, 1):
+        title = rec.get("title", "Recommendation")
+        description = rec.get("description", "")
+        console.print(f"  {i}. [yellow]{title}[/yellow]")
+        console.print(f"     {description}\n")
+
+
+def handle_command_error(error: Exception, verbose: bool = False) -> None:
+    """Handle command errors with appropriate logging and user messages."""
+    from repodoc.core.exceptions import (
+        CopilotExecutionError,
+        CopilotNotFoundError,
+        CopilotTimeoutError,
+        EmptyRepositoryError,
+        InvalidRepositoryError,
+        OutputParseError,
+        RepoDocError,
+        SchemaValidationError,
+    )
+
+    error_msg = str(error)
+    logger.error(f"Command failed: {error_msg}", exc_info=verbose)
+
+    # Handle specific error types with tailored messages
+    if isinstance(error, CopilotNotFoundError):
+        console.print("[red bold]✗ Copilot CLI Not Found[/red bold]")
+        console.print(error_msg)
+    elif isinstance(error, CopilotTimeoutError):
+        console.print("[red bold]✗ Operation Timed Out[/red bold]")
+        console.print(error_msg)
+    elif isinstance(error, CopilotExecutionError):
+        console.print("[red bold]✗ Copilot Execution Failed[/red bold]")
+        console.print(error_msg)
+    elif isinstance(error, (OutputParseError, SchemaValidationError)):
+        console.print("[red bold]✗ Output Parsing Failed[/red bold]")
+        console.print(error_msg)
+        if verbose:
+            console.print("\n[dim]Enable --verbose for more details[/dim]")
+    elif isinstance(error, (EmptyRepositoryError, InvalidRepositoryError)):
+        console.print("[red bold]✗ Repository Error[/red bold]")
+        console.print(error_msg)
+    elif isinstance(error, RepoDocError):
+        console.print(f"[red]✗ Error:[/red] {error_msg}")
+    else:
+        console.print(f"[red]✗ Unexpected error:[/red] {error_msg}")
+        if verbose:
+            console.print_exception()
+        else:
+            console.print("\n[dim]Run with --verbose for full error details[/dim]")
+
+    raise typer.Exit(code=1)

repodoc/commands/deadcode.py

@@ -0,0 +1,114 @@
+"""Deadcode command: Detect unused code with confidence levels."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+
+from repodoc.commands.base import (
+    console,
+    get_repo_root,
+    handle_command_error,
+    handle_json_flag,
+    save_text_output,
+)
+from repodoc.core.copilot import CopilotInvoker
+from repodoc.core.logger import get_logger
+from repodoc.core.parser import OutputParser
+from repodoc.prompts import get_prompt_loader
+from repodoc.renderers.command_renderers import DeadCodeRenderer
+from repodoc.renderers.terminal_renderer import TerminalRenderer
+from repodoc.schemas.deadcode import DeadCodeOutput
+
+logger = get_logger()
+
+
+def deadcode(
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Enable verbose output")] = False,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Output raw JSON instead of formatted text")
+    ] = False,
+    out: Annotated[
+        str | None, typer.Option("--out", "-o", help="Save output to specified file")
+    ] = None,
+    min_confidence: Annotated[
+        str,
+        typer.Option(
+            "--min-confidence", help="Minimum confidence level to report (low, medium, high)"
+        ),
+    ] = "medium",
+    timeout: Annotated[
+        int | None, typer.Option("--timeout", help="Timeout in seconds for Copilot CLI")
+    ] = None,
+) -> None:
+    """💀 Detect potentially dead code with confidence levels.
+
+    Identifies unused functions, classes, imports, and files based on
+    static analysis. Results include confidence levels for each finding.
+    """
+    try:
+        repo_root = get_repo_root()
+
+        # Validate confidence level
+        valid_levels = ["low", "medium", "high"]
+        if min_confidence not in valid_levels:
+            console.print(
+                f"[red]✗ Error:[/red] Invalid confidence level. "
+                f"Must be one of: {', '.join(valid_levels)}"
+            )
+            raise typer.Exit(code=1)
+
+        if verbose:
+            console.print(f"[dim]Detecting dead code in: {repo_root}[/dim]")
+
+        # Load prompt template
+        prompt_loader = get_prompt_loader()
+        prompt = prompt_loader.get_prompt("deadcode", repo_path=str(repo_root))
+
+        # Invoke Copilot CLI
+        copilot = CopilotInvoker(timeout=timeout)
+
+        if not json_output:
+            with console.status("[bold blue]Analyzing codebase for dead code...[/bold blue]"):
+                raw_output, _ = copilot.invoke_with_retry(prompt, cwd=repo_root)
+        else:
+            # Silent mode for JSON output
+            raw_output, _ = copilot.invoke_with_retry(prompt, cwd=repo_root)
+
+        # Parse and validate output
+        parser = OutputParser()
+        result = parser.parse_and_validate(raw_output, DeadCodeOutput)
+
+        # Handle JSON output (to stdout or file if --out specified)
+        if json_output:
+            handle_json_flag(result.model_dump(), json_output, out)
+            return
+
+        # Render human-readable output to terminal
+        terminal = TerminalRenderer(verbose=verbose, console=console)
+        renderer = DeadCodeRenderer(terminal)
+        renderer.render(result, min_confidence)
+
+        # If --out specified (without --json), save formatted text to file
+        if out:
+            save_text_output(
+                Path(out),
+                renderer.render,
+                result,
+                min_confidence,
+                terminal=terminal,
+                verbose=verbose,
+            )
+
+    except ValidationError as e:
+        logger.error(f"Failed to validate deadcode output: {e}")
+        console.print("[red]✗ Failed to parse Copilot output[/red]")
+        if verbose:
+            console.print_exception()
+        raise typer.Exit(code=1) from None
+    except typer.Exit:
+        # Let typer.Exit propagate without handling
+        raise
+    except Exception as e:
+        handle_command_error(e, verbose)

repodoc/commands/diet.py

@@ -0,0 +1,126 @@
+"""Diet command: Analyze repository bloat and hygiene."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+
+from repodoc.commands.base import (
+    console,
+    get_repo_root,
+    handle_command_error,
+    print_success_message,
+)
+from repodoc.core.copilot import CopilotInvoker
+from repodoc.core.logger import get_logger
+from repodoc.core.parser import OutputParser
+from repodoc.prompts import get_prompt_loader
+from repodoc.renderers.command_renderers import DietRenderer
+from repodoc.renderers.terminal_renderer import TerminalRenderer
+from repodoc.schemas.diet import DietOutput
+
+logger = get_logger()
+
+
+def diet(
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Enable verbose output")] = False,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Output JSON summary instead of generating DIET.md")
+    ] = False,
+    out: Annotated[
+        str | None,
+        typer.Option("--out", "-o", help="Custom output path for DIET.md (default: DIET.md)"),
+    ] = None,
+    timeout: Annotated[
+        int | None, typer.Option("--timeout", help="Timeout in seconds for Copilot CLI")
+    ] = None,
+) -> None:
+    """🍔 Analyze repository bloat and hygiene issues.
+
+    Generates a comprehensive diet analysis documenting repository size,
+    largest files/directories, suspected artifacts, and missing hygiene files.
+
+    By default, generates DIET.md in the repository root.
+
+    \b
+    Examples:
+      $ repodoc diet                        # Generate DIET.md (default)
+      $ repodoc diet --out docs/BLOAT.md   # Save to custom path
+      $ repodoc diet --json                 # Output JSON summary instead
+
+    \b
+    What it analyzes:
+      • Largest files in the repository
+      • Potentially unused dependencies
+      • Missing hygiene files (.gitignore, LICENSE, etc.)
+      • Overall repository size and health
+    """
+    try:
+        repo_root = get_repo_root()
+
+        if verbose and not json_output:
+            console.print(f"[dim]Running diet analysis on: {repo_root}[/dim]")
+
+        # Load prompt template
+        prompt_loader = get_prompt_loader()
+        prompt = prompt_loader.get_prompt("diet", repo_path=str(repo_root))
+
+        # Invoke Copilot CLI
+        copilot = CopilotInvoker(timeout=timeout)
+
+        if not json_output:
+            with console.status("[bold blue]🔍 Analyzing repository bloat...[/bold blue]"):
+                raw_output, _ = copilot.invoke_with_retry(prompt, cwd=repo_root)
+        else:
+            # Silent mode for JSON output
+            raw_output, _ = copilot.invoke_with_retry(prompt, cwd=repo_root)
+
+        # Parse and validate output
+        parser = OutputParser()
+        result = parser.parse_and_validate(raw_output, DietOutput)
+
+        # Handle JSON output
+        if json_output:
+            console.print_json(result.analysis.model_dump_json(indent=2))
+            return
+
+        # Generate DIET.md
+        diet_path = Path(out) if out else repo_root / "DIET.md"
+
+        # Write the DIET.md file
+        try:
+            with open(diet_path, "w", encoding="utf-8") as f:
+                f.write(result.diet_markdown)
+            if not json_output:
+                console.print(f"[green]✓[/green] Generated diet analysis: {diet_path}")
+        except Exception as e:
+            error_msg = f"Failed to write diet file: {e}"
+            logger.error(error_msg)
+            console.print(f"[red]✗ {error_msg}[/red]")
+            raise typer.Exit(code=1) from e
+
+        # Show terminal summary
+        terminal = TerminalRenderer(verbose=verbose, console=console)
+        renderer = DietRenderer(terminal)
+        renderer.render(result)
+
+        # Show success message with next actions
+        next_actions = [
+            "Review identified bloat and consider cleanup",
+            "Add missing hygiene files to improve repo health",
+            "Run 'repodoc scan' for a full health check",
+        ]
+        print_success_message("Diet analysis", next_actions)
+
+    except ValidationError as e:
+        logger.error(f"Failed to validate diet output: {e}")
+        console.print("[red]✗ Failed to parse Copilot output[/red]")
+        if verbose:
+            console.print_exception()
+        raise typer.Exit(code=1) from None
+    except typer.Exit:
+        # Let typer.Exit propagate without handling
+        raise
+    except Exception as e:
+        handle_command_error(e, verbose)