shannon-codebase-insight 0.4.0__py3-none-any.whl

shannon_insight/cli.py

@@ -0,0 +1,333 @@
+"""Command-line interface for Shannon Insight"""
+
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from . import __version__
+from .core import CodebaseAnalyzer
+from .config import load_settings, AnalysisSettings
+from .logging_config import setup_logging
+from .exceptions import ShannonInsightError
+
+app = typer.Typer(
+    name="shannon-insight",
+    help="Shannon Insight - Multi-Signal Codebase Quality Analyzer",
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+console = Console()
+
+
+@app.callback(invoke_without_command=True, no_args_is_help=True)
+def main(
+    ctx: typer.Context,
+    path: Path = typer.Argument(
+        Path("."),
+        help="Path to the codebase directory to analyze",
+        exists=False,
+        file_okay=False,
+        dir_okay=True,
+        readable=True,
+    ),
+    language: str = typer.Option(
+        "auto",
+        "--language",
+        "-l",
+        help="Programming language (auto, go, typescript, react, javascript, python)",
+    ),
+    top: int = typer.Option(
+        15,
+        "--top",
+        "-t",
+        help="Number of top files to display",
+        min=1,
+        max=1000,
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output JSON file path",
+        dir_okay=False,
+    ),
+    fmt: str = typer.Option(
+        "rich",
+        "--format",
+        "-f",
+        help="Output format: rich (default), json, csv, quiet",
+    ),
+    explain: Optional[str] = typer.Option(
+        None,
+        "--explain",
+        "-e",
+        help="Deep-dive explanation for a specific file (substring match)",
+    ),
+    fail_above: Optional[float] = typer.Option(
+        None,
+        "--fail-above",
+        help="Exit 1 if any file's score exceeds this threshold (for CI gating)",
+        min=0.0,
+    ),
+    threshold: Optional[float] = typer.Option(
+        None,
+        "--threshold",
+        help="Z-score threshold for anomaly detection (0.0 - 10.0)",
+        min=0.0,
+        max=10.0,
+    ),
+    config: Optional[Path] = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Configuration file path (TOML format)",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Enable verbose (DEBUG) logging",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Suppress all but ERROR logging",
+    ),
+    no_cache: bool = typer.Option(
+        False,
+        "--no-cache",
+        help="Disable caching",
+    ),
+    clear_cache: bool = typer.Option(
+        False,
+        "--clear-cache",
+        help="Clear cache before running",
+    ),
+    workers: Optional[int] = typer.Option(
+        None,
+        "--workers",
+        "-w",
+        help="Number of parallel workers (default: auto-detect)",
+        min=1,
+        max=32,
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show version and exit",
+    ),
+):
+    """
+    Analyze codebase quality using mathematical primitives.
+
+    Named after Claude Shannon, father of information theory.
+
+    [bold cyan]Examples:[/bold cyan]
+
+      shannon-insight /path/to/codebase
+
+      shannon-insight /path/to/codebase --language go
+
+      shannon-insight /path/to/codebase --top 20 --output results.json
+
+      shannon-insight . --format json | jq .
+
+      shannon-insight . --fail-above 2.0 --format quiet
+
+      shannon-insight . --explain complex.go
+    """
+    # If subcommand is invoked, don't run main analysis
+    if ctx.invoked_subcommand is not None:
+        return
+
+    # Handle version
+    if version:
+        console.print(
+            f"[bold cyan]Shannon Insight[/bold cyan] version [green]{__version__}[/green]"
+        )
+        raise typer.Exit(0)
+
+    # Validate mutually exclusive options
+    if verbose and quiet:
+        console.print("[red]Error:[/red] --verbose and --quiet are mutually exclusive")
+        raise typer.Exit(1)
+
+    # Validate format
+    valid_formats = {"rich", "json", "csv", "quiet"}
+    if fmt not in valid_formats:
+        console.print(f"[red]Error:[/red] --format must be one of: {', '.join(sorted(valid_formats))}")
+        raise typer.Exit(1)
+
+    # Setup logging first
+    logger = setup_logging(verbose=verbose, quiet=quiet)
+
+    try:
+        # Load settings from config file and environment
+        overrides = {}
+
+        # CLI overrides (highest priority)
+        if threshold is not None:
+            overrides["z_score_threshold"] = threshold
+        if no_cache:
+            overrides["enable_cache"] = False
+        if workers is not None:
+            overrides["parallel_workers"] = workers
+        if verbose:
+            overrides["verbose"] = True
+        if quiet:
+            overrides["quiet"] = True
+
+        settings = load_settings(config_file=config, **overrides)
+
+        # Log configuration
+        logger.debug(f"Loaded settings: {settings.model_dump()}")
+
+        # Create analyzer
+        analyzer = CodebaseAnalyzer(root_dir=path, language=language, settings=settings)
+
+        # Clear cache if requested
+        if clear_cache:
+            if hasattr(analyzer, "cache") and analyzer.cache:
+                analyzer.cache.clear()
+                console.print("[yellow]Cache cleared[/yellow]")
+
+        # Run analysis
+        reports = analyzer.analyze()
+
+        # Handle results based on format
+        if reports:
+            if explain:
+                # --explain mode: deep-dive on matching file(s)
+                analyzer.print_explain(reports, explain)
+            elif fmt == "json":
+                # JSON to stdout
+                print(analyzer.format_json(reports))
+            elif fmt == "csv":
+                # CSV to stdout
+                print(analyzer.format_csv(reports), end="")
+            elif fmt == "quiet":
+                # Just file paths
+                print(analyzer.format_quiet(reports))
+            else:
+                # Default rich output: summary + detailed report
+                analyzer.print_summary(reports, top_n=top)
+                analyzer.print_report(reports, top_n=top)
+
+            # Export JSON report
+            if output is not None:
+                analyzer.export_json(reports, filename=str(output))
+            elif fmt == "rich":
+                # Auto-save with timestamp when using rich output
+                ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+                auto_path = f"analysis_report_{ts}.json"
+                analyzer.export_json(reports, filename=auto_path)
+
+            # --fail-above CI gating
+            if fail_above is not None:
+                max_score = max(r.overall_score for r in reports)
+                if max_score > fail_above:
+                    if fmt == "rich":
+                        console.print(
+                            f"\n[red]FAIL:[/red] Max score {max_score:.3f} "
+                            f"exceeds threshold {fail_above:.3f}"
+                        )
+                    raise typer.Exit(1)
+
+            if fmt == "rich":
+                console.print()
+                console.print("[bold green]ANALYSIS COMPLETE[/bold green]")
+                console.print()
+        else:
+            if fmt == "json":
+                print("[]")
+            elif fmt == "csv":
+                print("file,overall_score,confidence,structural_entropy,"
+                      "network_centrality,churn_volatility,semantic_coherence,"
+                      "cognitive_load,anomaly_flags")
+            elif fmt == "rich":
+                console.print(
+                    "[bold green]No anomalies detected - codebase looks clean![/bold green]"
+                )
+            raise typer.Exit(0)
+
+    except typer.Exit:
+        raise  # Re-raise typer exits (--fail-above, no anomalies, etc.)
+
+    except ShannonInsightError as e:
+        # Handle known errors
+        logger.error(f"{e.__class__.__name__}: {e}")
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    except KeyboardInterrupt:
+        logger.info("Analysis interrupted by user")
+        console.print("\n[yellow]Analysis interrupted[/yellow]")
+        raise typer.Exit(130)
+
+    except Exception as e:
+        # Handle unexpected errors
+        logger.exception("Unexpected error during analysis")
+        console.print(f"[red]Unexpected error:[/red] {e}")
+        if verbose:
+            console.print_exception()
+        raise typer.Exit(1)
+
+
+@app.command()
+def cache_info():
+    """Show cache information and statistics."""
+    from .config import default_settings
+    from .cache import AnalysisCache
+
+    cache = AnalysisCache(
+        cache_dir=default_settings.cache_dir,
+        ttl_hours=default_settings.cache_ttl_hours,
+        enabled=default_settings.enable_cache,
+    )
+
+    stats = cache.stats()
+
+    console.print("[bold cyan]Shannon Insight Cache Info[/bold cyan]")
+    console.print()
+
+    if stats.get("enabled"):
+        console.print(f"Status: [green]Enabled[/green]")
+        console.print(f"Directory: [blue]{stats.get('directory', 'N/A')}[/blue]")
+        console.print(f"Entries: [yellow]{stats.get('size', 0)}[/yellow]")
+        console.print(f"Size: [yellow]{stats.get('volume', 0)} bytes[/yellow]")
+    else:
+        console.print(f"Status: [red]Disabled[/red]")
+
+
+@app.command()
+def cache_clear():
+    """Clear the analysis cache."""
+    from .config import default_settings
+    from .cache import AnalysisCache
+
+    cache = AnalysisCache(
+        cache_dir=default_settings.cache_dir,
+        ttl_hours=default_settings.cache_ttl_hours,
+        enabled=default_settings.enable_cache,
+    )
+
+    if not default_settings.enable_cache:
+        console.print("[yellow]Cache is disabled[/yellow]")
+        raise typer.Exit(0)
+
+    cache.clear()
+    console.print("[green]Cache cleared successfully[/green]")
+
+
+if __name__ == "__main__":
+    app()

shannon_insight/config.py

@@ -0,0 +1,235 @@
+"""
+Configuration management for Shannon Insight.
+
+Uses pydantic-settings for type-safe configuration with automatic validation.
+"""
+
+from pathlib import Path
+from typing import List, Optional
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class AnalysisSettings(BaseSettings):
+    """
+    Type-safe configuration with automatic validation.
+
+    Configuration hierarchy (highest to lowest priority):
+    1. CLI arguments (merged manually in CLI)
+    2. Environment variables (SHANNON_*)
+    3. TOML file (./shannon-insight.toml or ~/.shannon-insight.toml)
+    4. Defaults defined in Field()
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="SHANNON_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # ==================== Anomaly Detection ====================
+
+    z_score_threshold: float = Field(
+        default=1.5,
+        gt=0.0,
+        lt=10.0,
+        description="Z-score threshold for anomaly detection",
+    )
+
+    # ==================== PageRank ====================
+
+    pagerank_damping: float = Field(
+        default=0.85, ge=0.0, le=1.0, description="PageRank damping factor"
+    )
+
+    pagerank_iterations: int = Field(
+        default=20, ge=1, le=100, description="Maximum PageRank iterations"
+    )
+
+    pagerank_tolerance: float = Field(
+        default=1e-6, gt=0.0, description="PageRank convergence tolerance"
+    )
+
+    # ==================== Signal Fusion ====================
+
+    fusion_weights: List[float] = Field(
+        default=[0.2, 0.25, 0.2, 0.15, 0.2],
+        description="Signal fusion weights [entropy, centrality, churn, coherence, cognitive]",
+    )
+
+    fusion_normalize: bool = Field(
+        default=True, description="Normalize weights to sum to 1.0"
+    )
+
+    # ==================== File Filtering ====================
+
+    exclude_patterns: List[str] = Field(
+        default=[
+            "*_test.go",
+            "*_test.ts",
+            "*.test.ts",
+            "*.spec.ts",
+            "vendor/*",
+            "node_modules/*",
+            "dist/*",
+            "build/*",
+            ".git/*",
+            "venv/*",
+            ".venv/*",
+            "__pycache__/*",
+            ".tox/*",
+            ".mypy_cache/*",
+        ],
+        description="File patterns to exclude from analysis",
+    )
+
+    max_file_size_mb: float = Field(
+        default=10.0, gt=0.0, le=100.0, description="Maximum file size in MB"
+    )
+
+    max_files: int = Field(
+        default=10000, gt=0, le=100000, description="Maximum number of files to analyze"
+    )
+
+    # ==================== Performance ====================
+
+    parallel_workers: Optional[int] = Field(
+        default=None,
+        ge=1,
+        le=32,
+        description="Number of parallel workers (None = auto-detect)",
+    )
+
+    timeout_seconds: int = Field(
+        default=10, ge=1, le=300, description="Timeout for file operations in seconds"
+    )
+
+    # ==================== Cache ====================
+
+    enable_cache: bool = Field(
+        default=True, description="Enable caching for faster repeated analysis"
+    )
+
+    cache_dir: str = Field(default=".shannon-cache", description="Cache directory path")
+
+    cache_ttl_hours: int = Field(
+        default=24,
+        ge=0,
+        le=720,  # 30 days max
+        description="Cache time-to-live in hours",
+    )
+
+    # ==================== Logging ====================
+
+    verbose: bool = Field(default=False, description="Enable verbose (DEBUG) logging")
+
+    quiet: bool = Field(default=False, description="Suppress all but ERROR logging")
+
+    log_file: Optional[str] = Field(
+        default=None, description="Log file path (optional)"
+    )
+
+    # ==================== Security ====================
+
+    allow_hidden_files: bool = Field(
+        default=False, description="Allow analysis of hidden files (starting with .)"
+    )
+
+    block_system_dirs: bool = Field(
+        default=True, description="Block access to system directories"
+    )
+
+    follow_symlinks: bool = Field(
+        default=False, description="Follow symbolic links during scanning"
+    )
+
+    # ==================== Validators ====================
+
+    @field_validator("fusion_weights")
+    @classmethod
+    def validate_fusion_weights(cls, v: List[float]) -> List[float]:
+        """Validate fusion weights."""
+        if len(v) != 5:
+            raise ValueError("fusion_weights must have exactly 5 values")
+
+        if any(w < 0 for w in v):
+            raise ValueError("fusion_weights must be non-negative")
+
+        weight_sum = sum(v)
+        if weight_sum == 0:
+            raise ValueError("fusion_weights cannot all be zero")
+
+        # Normalize to sum to 1.0
+        return [w / weight_sum for w in v]
+
+    @field_validator("cache_dir")
+    @classmethod
+    def validate_cache_dir(cls, v: str) -> str:
+        """Validate cache directory."""
+        # Convert to absolute path
+        cache_path = Path(v)
+        if not cache_path.is_absolute():
+            cache_path = Path.cwd() / cache_path
+        return str(cache_path)
+
+    @field_validator("parallel_workers")
+    @classmethod
+    def validate_parallel_workers(cls, v: Optional[int]) -> Optional[int]:
+        """Validate parallel workers count."""
+        if v is not None and v < 1:
+            raise ValueError("parallel_workers must be at least 1")
+        return v
+
+    # ==================== Computed Properties ====================
+
+    @property
+    def max_file_size_bytes(self) -> int:
+        """Get max file size in bytes."""
+        return int(self.max_file_size_mb * 1024 * 1024)
+
+    @property
+    def cache_ttl_seconds(self) -> int:
+        """Get cache TTL in seconds."""
+        return self.cache_ttl_hours * 3600
+
+
+def load_settings(config_file: Optional[Path] = None, **overrides) -> AnalysisSettings:
+    """
+    Load settings from config file and environment variables.
+
+    Args:
+        config_file: Optional TOML config file path
+        **overrides: Manual overrides (typically from CLI args)
+
+    Returns:
+        Loaded settings with all overrides applied
+    """
+    # Try to load from TOML file
+    if config_file and config_file.exists():
+        # pydantic-settings doesn't natively support TOML
+        # We'll load it manually and pass as overrides
+        try:
+            tomli = __import__("tomli")
+            with open(config_file, "rb") as f:
+                toml_data = tomli.load(f)
+            # Merge TOML data with overrides (overrides take precedence)
+            merged = {**toml_data, **overrides}
+            return AnalysisSettings(**merged)
+        except ImportError:
+            # tomli not available, fall back to env vars + overrides
+            pass
+        except Exception as e:
+            # TOML parsing failed, warn and continue
+            import warnings
+
+            warnings.warn(f"Failed to load config file {config_file}: {e}")
+
+    # Load from environment variables + overrides
+    return AnalysisSettings(**overrides)
+
+
+# Default settings instance
+default_settings = AnalysisSettings()