ballpython 2.0.0__py3-none-any.whl → 2.0.2__py3-none-any.whl

pycleaner/cli.py

@@ -18,18 +18,29 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from pycleaner.baseline import BaselineFingerprint, BaselineManager
+from pycleaner.cache import ContentAddressableCache
 from pycleaner.complexity_analyzer import ComplexityAnalyzer
 from pycleaner.config import ConfigError, PyCleanerConfig, load_config
 from pycleaner.dead_code_detector import DeadCodeDetector
 from pycleaner.dependency_auditor import DependencyAuditor, DependencyAuditReport
+from pycleaner.discovery import (
+    DEFAULT_IGNORED_DIRS,
+    collect_project_python_files,
+    find_project_root,
+    is_protected_file,
+)
+from pycleaner.explanations import get_explanation, list_rules
 from pycleaner.pipeline import CleanPipeline, CleanResult
 from pycleaner.security_scanner import SecurityScanner
 from pycleaner.taint_engine import TaintEngine
 from pycleaner.test_generator import TestGenerator
 from pycleaner.type_checker import TypeChecker
+from pycleaner.verifier import CounterExample, ProofReceipt, VerificationTier
 
 try:
     from rich.console import Console
+    from rich.panel import Panel
     from rich.progress import (
         BarColumn,
         Progress,
@@ -48,6 +59,7 @@ except ImportError:
 SUBCOMMANDS = {
     "fix",
     "check",
+    "prove",
     "audit",
     "scan",
     "complexity",
@@ -59,9 +71,14 @@ SUBCOMMANDS = {
     "taint",
     "test-gen",
     "ultimate",
+    "baseline",
+    "explain",
+    "cache",
+    "help",
 }
 
 _OPTIONS_WITH_VALUE = {
+    "--config",
     "--workers",
     "--severity",
     "--max-cyclomatic",
@@ -70,6 +87,12 @@ _OPTIONS_WITH_VALUE = {
     "--max-args",
     "--interval",
     "--output-dir",
+    "--output-json",
+    "--proof-iterations",
+    "--proof-seed",
+    "--baseline",
+    "--cache-db",
+    "--output",
 }
 
 
@@ -118,6 +141,19 @@ def _register_fix_subparsers(subparsers: Any) -> None:
     _add_fix_args(ult_p)
     ult_p.add_argument("--diff", action="store_true", help="Show unified diffs")
 
+    prove_p = subparsers.add_parser(
+        "prove",
+        help="Verify transformations using differential execution fuzzing (Tier A/B/C)",
+    )
+    _add_common_args(prove_p)
+    _add_fix_args(prove_p)
+    prove_p.add_argument("--diff", action="store_true", help="Show unified diffs")
+    prove_p.add_argument(
+        "--apply",
+        action="store_true",
+        help="Apply proven (Tier A) changes to disk",
+    )
+
 
 def _register_analysis_subparsers(subparsers: Any) -> None:
     audit_p = subparsers.add_parser("audit", help="Audit project dependencies")
@@ -153,6 +189,11 @@ def _register_analysis_subparsers(subparsers: Any) -> None:
         "dead-code", help="Detect unused functions, classes, and unreachable code"
     )
     _add_common_args(dc_p)
+    dc_p.add_argument(
+        "--fix",
+        action="store_true",
+        help="Auto-prune unreachable code, redundant pass statements, and dead branches",
+    )
 
     types_p = subparsers.add_parser(
         "types",
@@ -195,6 +236,65 @@ def _register_tool_subparsers(subparsers: Any) -> None:
         help="Print generated tests to stdout without saving",
     )
 
+    baseline_p = subparsers.add_parser(
+        "baseline",
+        help="Generate or update technical debt baseline for ratchet enforcement",
+    )
+    _add_common_args(baseline_p)
+    baseline_p.add_argument(
+        "--output",
+        default=".pycleaner/baseline.json",
+        help="Path to save baseline JSON (default: .pycleaner/baseline.json)",
+    )
+
+    explain_p = subparsers.add_parser(
+        "explain",
+        help="Explain diagnostic codes, security rules, and verification tiers",
+    )
+    explain_p.add_argument(
+        "code",
+        nargs="?",
+        default=None,
+        help="Diagnostic rule code or topic to explain (e.g. DC001, SEC001, PROVE001, or omit to list all)",
+    )
+
+    help_p = subparsers.add_parser(
+        "help",
+        help="Show help for ballpython or a specific command",
+    )
+    help_p.add_argument(
+        "command_name",
+        nargs="?",
+        default=None,
+        metavar="COMMAND",
+        help="Subcommand to show help for (e.g. fix, prove, check)",
+    )
+
+    cache_p = subparsers.add_parser(
+        "cache",
+        help="Inspect, query statistics, or invalidate content-addressable cache",
+    )
+    cache_p.add_argument(
+        "--stats",
+        action="store_true",
+        help="Display cache utilization and database storage statistics",
+    )
+    cache_p.add_argument(
+        "--clear",
+        action="store_true",
+        help="Wipe all entries from the local cache database",
+    )
+    cache_p.add_argument(
+        "--db",
+        default=None,
+        help="Custom path to cache SQLite database file (default: .pycleaner/cache.db)",
+    )
+    cache_p.add_argument(
+        "--json",
+        action="store_true",
+        help="Output statistics in JSON format",
+    )
+
 
 def build_parser(prog: str = "ballpython") -> argparse.ArgumentParser:
     """Construct command-line argument parser with subcommands."""
@@ -294,6 +394,14 @@ def _add_fix_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--no-syntax-fix", action="store_true", help="Disable syntax healing"
     )
+    parser.add_argument(
+        "--no-modernize",
+        action="store_true",
+        help="Disable PEP 585/604 code modernization",
+    )
+    parser.add_argument(
+        "--no-dead-code", action="store_true", help="Disable dead code pruning"
+    )
     parser.add_argument(
         "--no-missing-imports", action="store_true", help="Disable import resolution"
     )
@@ -303,24 +411,47 @@ def _add_fix_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--no-format", action="store_true", help="Disable code formatting"
     )
+    parser.add_argument(
+        "--prove",
+        action="store_true",
+        help="Prove transformations preserve behavior using differential execution fuzzing",
+    )
+    parser.add_argument(
+        "--proof-iterations",
+        type=int,
+        default=50,
+        help="Number of differential fuzzing test cases per callable (default: 50)",
+    )
+    parser.add_argument(
+        "--proof-seed",
+        type=int,
+        default=None,
+        help="Deterministic random seed for differential proof engine",
+    )
+    parser.add_argument(
+        "--output-json",
+        default=".pycleaner/verification-report.json",
+        help="Path to save verification receipt JSON",
+    )
+    parser.add_argument(
+        "--cache",
+        action="store_true",
+        help="Enable content-addressable incremental caching (.pycleaner/cache.db)",
+    )
+    parser.add_argument(
+        "--cache-db",
+        default=".pycleaner/cache.db",
+        help="Path to SQLite cache database (default: .pycleaner/cache.db)",
+    )
+    parser.add_argument(
+        "--baseline",
+        default=None,
+        metavar="PATH",
+        help="Path to baseline JSON for ratchet enforcement (e.g. .pycleaner/baseline.json)",
+    )
 
 
-_DEFAULT_IGNORE_DIRS = frozenset(
-    {
-        ".git",
-        ".venv",
-        "venv",
-        "env",
-        "__pycache__",
-        "build",
-        "dist",
-        ".tox",
-        ".mypy_cache",
-        ".pytest_cache",
-        ".ruff_cache",
-        "site-packages",
-    }
-)
+_DEFAULT_IGNORE_DIRS = DEFAULT_IGNORED_DIRS
 
 
 def _collect_dir_python_files(
@@ -341,10 +472,11 @@ def _collect_target_files(
     files: list[Path] = []
     for target in targets:
         path = Path(target).resolve()
-        if path.is_file() and path.suffix == ".py":
-            files.append(path)
+        if path.is_file():
+            if path.suffix == ".py" and not is_protected_file(path):
+                files.append(path)
         elif path.is_dir():
-            files.extend(_collect_dir_python_files(path, ignore_dirs))
+            files.extend(collect_project_python_files(path))
     return files
 
 
@@ -387,12 +519,27 @@ def discover_python_files(
     resolved_root = (
         root if root is not None else _resolve_project_root(effective_targets)
     )
-    files = _collect_target_files(effective_targets)
 
-    if config and config.exclude:
-        files = [
-            f for f in files if not _is_file_excluded(f, resolved_root, config.exclude)
-        ]
+    explicit_files: list[Path] = []
+    dir_targets: list[str] = []
+    for target in effective_targets:
+        p = Path(target).resolve()
+        if p.is_file():
+            if p.suffix == ".py" and not is_protected_file(p):
+                explicit_files.append(p)
+        elif p.is_dir():
+            dir_targets.append(str(p))
+
+    files = list(explicit_files)
+    if dir_targets:
+        dir_files = _collect_target_files(dir_targets)
+        if config and config.exclude:
+            dir_files = [
+                f
+                for f in dir_files
+                if not _is_file_excluded(f, resolved_root, config.exclude)
+            ]
+        files.extend(dir_files)
 
     return sorted(set(files))
 
@@ -456,6 +603,7 @@ def _route_command(
     diff = getattr(args, "diff", False)
 
     dispatch_simple = {
+        "help": lambda: _cmd_help(args, print_msg),
         "hook": lambda: _cmd_hook(args, print_msg),
         "audit": lambda: _cmd_audit(args, config, print_msg),
         "scan": lambda: _cmd_scan(args, config, print_msg, console),
@@ -467,6 +615,10 @@ def _route_command(
         "watch": lambda: _cmd_watch(args, config, print_msg),
         "ultimate": lambda: _cmd_ultimate(args, config, print_msg, console),
         "all": lambda: _run_all_command(args, config, print_msg, console),
+        "prove": lambda: _cmd_prove(args, config, print_msg, console),
+        "baseline": lambda: _cmd_baseline(args, config, print_msg, console),
+        "explain": lambda: _cmd_explain(args, print_msg, console),
+        "cache": lambda: _cmd_cache(args, config, print_msg, console),
         "check": lambda: _cmd_fix(
             args,
             config,
@@ -505,10 +657,13 @@ def main(argv: Sequence[str] | None = None) -> int:
 
     targets = getattr(args, "paths", ["."])
     target_path = Path(targets[0]).resolve() if targets else Path.cwd()
-    root_dir = target_path if target_path.is_dir() else target_path.parent
+    root_dir = find_project_root(target_path)
 
     try:
-        config = load_config(project_root=root_dir)
+        config = load_config(
+            project_root=root_dir,
+            explicit_config_file=getattr(args, "config", None),
+        )
     except ConfigError as err:
         print_msg(f"[red]Configuration Error:[/red] {err}")
         return 2
@@ -527,6 +682,11 @@ class _FixBatchState:
     changed_count: int = 0
     error_count: int = 0
     diagnostics: list[dict[str, str]] = field(default_factory=list)
+    proven_count: int = 0
+    suggested_count: int = 0
+    refused_count: int = 0
+    proof_receipts: list[ProofReceipt] = field(default_factory=list)
+    counterexamples: list[CounterExample] = field(default_factory=list)
 
 
 @dataclass(slots=True)
@@ -555,6 +715,10 @@ def _report_file_modifications(
     print_msg(f"[green]{action}:[/green] {py_file.name}")
     for repair in result.syntax_repairs:
         print_msg(f"  • Syntax: {repair}", style="cyan")
+    for mod in result.modernize_transforms:
+        print_msg(f"  • Modernize: {mod}", style="green")
+    for dc in result.dead_code_pruned:
+        print_msg(f"  • Dead-code: {dc}", style="yellow")
     for imp in result.resolved_imports:
         print_msg(f"  • Import: {imp}", style="magenta")
     if result.lint_changed:
@@ -574,6 +738,28 @@ def _accumulate_result(
     if result.diagnostics:
         state.diagnostics.extend(result.diagnostics)
 
+    if result.proof_receipts:
+        state.proof_receipts.extend(result.proof_receipts)
+    if result.refused_changes:
+        state.counterexamples.extend(result.refused_changes)
+        state.refused_count += len(result.refused_changes)
+    if result.verification_tier == VerificationTier.TIER_A_PROVEN:
+        state.proven_count += 1
+    elif result.verification_tier == VerificationTier.TIER_B_SUGGESTED:
+        state.suggested_count += 1
+    elif result.verification_tier == VerificationTier.TIER_C_REFUSED:
+        if not is_json:
+            print_msg(
+                f"[bold red]Refused (Tier C):[/bold red] {py_file.name} — transformation falsified by differential fuzzing; rolled back!"
+            )
+            for ce in result.refused_changes:
+                print_msg(
+                    f"  • {ce.callable_name} diverged on args={ce.arguments} kwargs={ce.keyword_arguments}"
+                )
+                print_msg(
+                    f"    original={ce.original_result or ce.original_error} vs transformed={ce.transformed_result or ce.transformed_error} (seed {ce.seed})"
+                )
+
     if result.error:
         state.error_count += 1
         if not is_json:
@@ -591,20 +777,41 @@ def _accumulate_result(
 def _build_fix_pipeline(
     args: argparse.Namespace, config: PyCleanerConfig
 ) -> CleanPipeline:
+    verify_proofs = (
+        getattr(args, "prove", False) or getattr(args, "command", None) == "prove"
+    )
+    proof_iterations = getattr(args, "proof_iterations", 50)
+    proof_seed = getattr(args, "proof_seed", None)
+    enable_cache = getattr(args, "cache", False)
+    cache_db_path = getattr(args, "cache_db", ".pycleaner/cache.db")
     if getattr(args, "missing_imports_only", False):
         return CleanPipeline(
             enable_syntax_healing=False,
+            enable_modernizer=False,
+            enable_dead_code_pruning=False,
             enable_import_resolution=True,
             enable_lint_fixing=False,
             enable_formatting=False,
             config=config,
+            verify_proofs=verify_proofs,
+            proof_iterations=proof_iterations,
+            proof_seed=proof_seed,
+            enable_cache=enable_cache,
+            cache_db_path=cache_db_path,
         )
     return CleanPipeline(
         enable_syntax_healing=not getattr(args, "no_syntax_fix", False),
+        enable_modernizer=not getattr(args, "no_modernize", False),
+        enable_dead_code_pruning=not getattr(args, "no_dead_code", False),
         enable_import_resolution=not getattr(args, "no_missing_imports", False),
         enable_lint_fixing=not getattr(args, "no_lint_fix", False),
         enable_formatting=not getattr(args, "no_format", False),
         config=config,
+        verify_proofs=verify_proofs,
+        proof_iterations=proof_iterations,
+        proof_seed=proof_seed,
+        enable_cache=enable_cache,
+        cache_db_path=cache_db_path,
     )
 
 
@@ -707,13 +914,18 @@ def _run_fix_audit(
     apply_changes: bool,
     args: argparse.Namespace,
     print_msg: Any,
+    config: PyCleanerConfig | None = None,
+    target_files: Sequence[Path] | None = None,
 ) -> DependencyAuditReport:
-    auditor = DependencyAuditor(root_dir)
+    exclude_patterns = config.exclude if config else ()
+    auditor = DependencyAuditor(root_dir, exclude_patterns=exclude_patterns)
     fix_any = getattr(args, "fix_deps", False) or getattr(args, "fix_all", False)
     prune_any = getattr(args, "prune_deps", False) or getattr(args, "fix_all", False)
     should_fix = apply_changes and fix_any
     should_prune = apply_changes and prune_any
-    audit_report = auditor.audit(fix=should_fix, prune_unused=should_prune)
+    audit_report = auditor.audit(
+        fix=should_fix, prune_unused=should_prune, target_files=target_files
+    )
     _render_audit_terminal_output(audit_report, print_msg, should_fix)
     return audit_report
 
@@ -722,7 +934,12 @@ def _compute_fix_exit_code(
     state: _FixBatchState,
     audit_report: DependencyAuditReport,
     apply_changes: bool,
+    is_prove_cmd: bool = False,
 ) -> int:
+    if state.refused_count > 0:
+        return 1
+    if is_prove_cmd:
+        return 0 if state.error_count == 0 else 1
     if not apply_changes and (
         state.changed_count > 0
         or state.error_count > 0
@@ -746,7 +963,7 @@ def _is_parallel_enabled(
 
 def _resolve_root_dir(paths: Sequence[str] | None) -> Path:
     target = Path(paths[0]).resolve() if paths else Path.cwd()
-    return target if target.is_dir() else target.parent
+    return find_project_root(target)
 
 
 def _report_fix_start(count: int, apply_changes: bool, print_msg: Any) -> None:
@@ -785,11 +1002,380 @@ def _cmd_fix(
         print(json.dumps(state.diagnostics, indent=2))
         return 0 if state.error_count == 0 else 1
 
-    audit_report = _run_fix_audit(root_dir, opts.apply_changes, args, print_msg)
+    audit_report = _run_fix_audit(
+        root_dir,
+        opts.apply_changes,
+        args,
+        print_msg,
+        config=config,
+        target_files=py_files,
+    )
     print_msg(
         f"\n[bold]Summary: {len(py_files)} inspected, {state.changed_count} updated, {state.error_count} errors.[/bold]"
     )
-    return _compute_fix_exit_code(state, audit_report, opts.apply_changes)
+
+    if pipeline.verify_proofs:
+        total_proven_callables = sum(
+            1 for r in state.proof_receipts if r.tier == VerificationTier.TIER_A_PROVEN
+        )
+        total_refused_callables = len(state.counterexamples)
+        if not is_json:
+            print_msg("\n[bold cyan]Verification Receipts (Trust Ladder):[/bold cyan]")
+            print_msg(
+                f"  [bold green]• Proven (Tier A):[/bold green] {total_proven_callables} callable(s) invariant-preserving across {pipeline.proof_iterations} input(s)"
+            )
+            if state.suggested_count > 0:
+                print_msg(
+                    f"  [yellow]• Suggested (Tier B):[/yellow] {state.suggested_count} module(s) (not isolated for dynamic fuzzing)"
+                )
+            if total_refused_callables > 0:
+                print_msg(
+                    f"  [bold red]• Refused (Tier C):[/bold red] {total_refused_callables} transformation(s) diverged; rolled back"
+                )
+
+        output_report_path = getattr(
+            args, "output_json", ".pycleaner/verification-report.json"
+        )
+        try:
+            out_p = Path(output_report_path)
+            out_p.parent.mkdir(parents=True, exist_ok=True)
+            report_data = {
+                "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "total_inspected": len(py_files),
+                "proven_tier_a_callables": total_proven_callables,
+                "suggested_tier_b_files": state.suggested_count,
+                "refused_tier_c_callables": total_refused_callables,
+                "proof_receipts": [
+                    {
+                        "file": r.filepath,
+                        "callable": r.callable_name,
+                        "tier": r.tier.value,
+                        "iterations": r.iterations_run,
+                        "seed": r.seed,
+                        "duration_ms": r.duration_ms,
+                        "reason": r.reason,
+                    }
+                    for r in state.proof_receipts
+                ],
+                "counterexamples": [
+                    {
+                        "callable": ce.callable_name,
+                        "arguments": [repr(a) for a in ce.arguments],
+                        "kwargs": {k: repr(v) for k, v in ce.keyword_arguments.items()},
+                        "original_result": ce.original_result,
+                        "original_error": ce.original_error,
+                        "transformed_result": ce.transformed_result,
+                        "transformed_error": ce.transformed_error,
+                        "seed": ce.seed,
+                    }
+                    for ce in state.counterexamples
+                ],
+            }
+            out_p.write_text(json.dumps(report_data, indent=2), encoding="utf-8")
+            if not is_json:
+                print_msg(f"  [dim]Report saved to {output_report_path}[/dim]")
+        except OSError as e:
+            if not is_json:
+                print_msg(f"  [red]Failed to write verification report:[/red] {e}")
+
+    if getattr(args, "baseline", None):
+        baseline_mgr = BaselineManager(args.baseline)
+        current_issues: list[BaselineFingerprint] = []
+        for diag in state.diagnostics:
+            current_issues.append(
+                BaselineManager.create_fingerprint(
+                    rule=diag.get("rule", "LINT001"),
+                    file_path=diag.get("file", "<unknown>"),
+                    line=int(diag.get("line", 1)),
+                    symbol=diag.get("message", "diagnostic violation"),
+                    root_dir=root_dir,
+                )
+            )
+        tolerated, new_debt = baseline_mgr.filter_new_issues(current_issues)
+        if not is_json:
+            print_msg(
+                f"\n[bold cyan]Baseline Ratchet Enforcement ({args.baseline}):[/bold cyan]"
+            )
+            if tolerated:
+                print_msg(
+                    f"  • Baseline tolerated: [yellow]{len(tolerated)}[/yellow] existing issue(s)"
+                )
+            if new_debt:
+                print_msg(
+                    f"  • [bold red]Ratchet Violation:[/bold red] {len(new_debt)} new technical debt issue(s) detected!"
+                )
+                for nd in new_debt:
+                    print_msg(
+                        f"    [red]• [X] {nd.rule} at {nd.file}:{nd.line} ({nd.symbol})[/red]"
+                    )
+                return 1
+            else:
+                print_msg(
+                    "  • [bold green]Ratchet Passed:[/bold green] 0 new technical debt issues introduced."
+                )
+        elif new_debt:
+            return 1
+
+    is_prove = getattr(args, "command", None) == "prove"
+    return _compute_fix_exit_code(
+        state, audit_report, opts.apply_changes, is_prove_cmd=is_prove
+    )
+
+
+def _cmd_prove(
+    args: argparse.Namespace,
+    config: PyCleanerConfig,
+    print_msg: Any,
+    console: Any,
+) -> int:
+    """The Proof-Carrying Differential Equivalence Runner."""
+    args.prove = True
+    diff = getattr(args, "diff", False)
+    apply_changes = getattr(args, "apply", False)
+
+    print_msg(
+        "[bold cyan]=== PyCleaner Prove: Differential Equivalence Verification ===[/bold cyan]\n"
+    )
+
+    return _cmd_fix(
+        args,
+        config,
+        print_msg,
+        console,
+        _FixOptions(
+            apply_changes=apply_changes,
+            show_diff=diff,
+            backup=config.backup and not getattr(args, "no_backup", False),
+        ),
+    )
+
+
+def _cmd_baseline(
+    args: argparse.Namespace,
+    config: PyCleanerConfig,
+    print_msg: Any,
+    console: Any,
+) -> int:
+    """Generate or update technical debt baseline for ratchet enforcement."""
+    output_path = Path(getattr(args, "output", ".pycleaner/baseline.json"))
+    root_dir = _resolve_root_dir(getattr(args, "paths", None))
+    py_files = discover_python_files(args.paths, config=config, root=root_dir)
+
+    print_msg(
+        "[bold cyan]=== Generating PyCleaner Technical Debt Baseline ===[/bold cyan]"
+    )
+    print_msg(f"Inspecting {len(py_files)} file(s) across {root_dir.name}...")
+
+    fingerprints: list[BaselineFingerprint] = []
+
+    detector = DeadCodeDetector()
+    dead_code_report = detector.scan_project(root_dir)
+    for item in dead_code_report.items:
+        if item.kind == "unused-import":
+            rule = "DC002"
+        elif item.kind in ("function", "class"):
+            rule = "DC003"
+        else:
+            rule = "DC001"
+        fingerprints.append(
+            BaselineManager.create_fingerprint(
+                rule=rule,
+                file_path=item.filepath,
+                line=item.lineno,
+                symbol=item.name,
+                root_dir=root_dir,
+            )
+        )
+
+    scanner = SecurityScanner()
+    sec_report = scanner.scan_project(root_dir)
+    for finding in sec_report.findings:
+        fingerprints.append(
+            BaselineManager.create_fingerprint(
+                rule=finding.category,
+                file_path=finding.filepath,
+                line=finding.lineno,
+                symbol=finding.message,
+                root_dir=root_dir,
+            )
+        )
+
+    analyzer = ComplexityAnalyzer()
+    comp_report = analyzer.analyze_project(root_dir)
+    thresholds = (
+        getattr(args, "max_cyclomatic", config.max_cyclomatic_complexity),
+        getattr(args, "max_cognitive", config.max_cognitive_complexity),
+        getattr(args, "max_lines", config.max_function_length),
+        getattr(args, "max_args", config.max_arguments),
+    )
+    violations = comp_report.above_threshold(*thresholds)
+    for v in violations:
+        fingerprints.append(
+            BaselineManager.create_fingerprint(
+                rule="CMP001",
+                file_path=v.filepath,
+                line=v.lineno,
+                symbol=f"{v.qualified_name} (CC={v.cyclomatic})",
+                root_dir=root_dir,
+            )
+        )
+
+    manager = BaselineManager(output_path)
+    saved_file = manager.save_baseline(fingerprints, root_dir)
+
+    print_msg(f"\n[bold green]Baseline successfully recorded![/bold green]")
+    print_msg(f"  • Issues snapshotted: [bold yellow]{len(fingerprints)}[/bold yellow]")
+    print_msg(f"  • Output file: [bold]{saved_file}[/bold]")
+    print_msg(
+        "\n[dim]Ratchet Guarantee: Technical debt in this repository is now locked. Run CI with:[/dim]"
+    )
+    print_msg(f"  [cyan]pycleaner check --baseline {output_path}[/cyan]\n")
+
+    return 0
+
+
+def _cmd_explain(
+    args: argparse.Namespace,
+    print_msg: Any,
+    console: Any,
+) -> int:
+    """Explain diagnostic codes, security rules, and verification tiers."""
+    code = getattr(args, "code", None)
+
+    if not code:
+        rules = list_rules()
+        print_msg(
+            "[bold cyan]PyCleaner Diagnostic & Verification Rules Catalog[/bold cyan]\n"
+        )
+        if console and has_rich:
+            table = Table(show_header=True, header_style="bold magenta")
+            table.add_column("Code", style="cyan", width=10)
+            table.add_column("Category", style="yellow", width=25)
+            table.add_column("Severity", width=12)
+            table.add_column("Title", style="white")
+            for r in rules:
+                sev_color = (
+                    "red"
+                    if r.severity in ("Critical", "High")
+                    else ("yellow" if r.severity == "Medium" else "green")
+                )
+                table.add_row(
+                    r.code,
+                    r.category,
+                    f"[{sev_color}]{r.severity}[/{sev_color}]",
+                    r.title,
+                )
+            console.print(table)
+        else:
+            for r in rules:
+                print(f"{r.code:8} [{r.severity:8}] {r.title} ({r.category})")
+        print_msg(
+            "\n[dim]Run 'pycleaner explain <CODE>' for full details and remediation examples.[/dim]"
+        )
+        return 0
+
+    rule = get_explanation(code)
+    if rule is None:
+        print_msg(f"[bold red]Unknown rule code or topic:[/bold red] '{code}'")
+        print_msg(
+            "[dim]Run 'pycleaner explain' without arguments to list all available rules.[/dim]"
+        )
+        return 1
+
+    sev_color = (
+        "red"
+        if rule.severity in ("Critical", "High")
+        else ("yellow" if rule.severity == "Medium" else "green")
+    )
+    print_msg(
+        f"\n[bold cyan]PyCleaner Rule Guide: {rule.code} - {rule.title}[/bold cyan]"
+    )
+    print_msg(
+        f"  [bold]Category:[/bold] {rule.category} | [bold]Severity:[/bold] [{sev_color}]{rule.severity}[/{sev_color}]\n"
+    )
+    print_msg(f"[bold]Description:[/bold]\n{rule.description}\n")
+
+    if rule.vulnerable_example:
+        print_msg("[bold red][X] Flawed / Baseline Example:[/bold red]")
+        if console and has_rich:
+            console.print(
+                Syntax(
+                    rule.vulnerable_example,
+                    "python",
+                    theme="monokai",
+                    line_numbers=False,
+                )
+            )
+        else:
+            print(rule.vulnerable_example)
+
+    if rule.remediated_example:
+        print_msg("\n[bold green][+] Verified / Remediated Example:[/bold green]")
+        if console and has_rich:
+            console.print(
+                Syntax(
+                    rule.remediated_example,
+                    "python",
+                    theme="monokai",
+                    line_numbers=False,
+                )
+            )
+        else:
+            print(rule.remediated_example)
+
+    print_msg(
+        f"\n[bold]Remediation Details & Proof Invariants:[/bold]\n{rule.remediation_details}\n"
+    )
+    return 0
+
+
+def _cmd_help(args: argparse.Namespace, print_msg: Any) -> int:
+    cmd_name = getattr(args, "command_name", None)
+    parser = build_parser()
+    if not cmd_name:
+        parser.print_help()
+        return 0
+
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            if cmd_name in action.choices:
+                action.choices[cmd_name].print_help()
+                return 0
+    print_msg(
+        f"Unknown command: '{cmd_name}'. Run 'ballpython --help' to view available commands.",
+        style="yellow",
+    )
+    return 1
+
+
+def _cmd_cache(
+    args: argparse.Namespace,
+    config: PyCleanerConfig,
+    print_msg: Any,
+    console: Any,
+) -> int:
+    """Manage and inspect the content-addressable verification and AST cache."""
+    db_path = getattr(args, "db", None) or getattr(
+        config, "cache_db_path", ".pycleaner/cache.db"
+    )
+    cache = ContentAddressableCache(db_path=db_path)
+
+    if getattr(args, "clear", False):
+        cache.clear()
+        print_msg("[green]Content-addressable cache cleared successfully.[/green]")
+        return 0
+
+    stats = cache.get_stats()
+    if getattr(args, "json", False):
+        print(json.dumps(stats, indent=2))
+        return 0
+
+    print_msg("[bold cyan]=== Content-Addressable Cache Statistics ===[/bold cyan]")
+    print_msg(f"  Database Path:       {cache.db_path}")
+    print_msg(f"  Cached File Entries: {stats['file_cache_entries']}")
+    print_msg(f"  Provenance Records:  {stats['provenance_entries']}")
+    print_msg(f"  Database File Size:  {stats['db_size_bytes']:,} bytes")
+    return 0
 
 
 def _render_audit_json(audit_report: DependencyAuditReport) -> int:
@@ -839,12 +1425,10 @@ def _render_audit_cli_output(
 
 def _cmd_audit(args: argparse.Namespace, config: PyCleanerConfig, print_msg) -> int:
     """Dependency audit command."""
-    root_dir = Path(args.paths[0]).resolve() if args.paths else Path.cwd()
-    if not root_dir.is_dir():
-        root_dir = root_dir.parent
+    root_dir = find_project_root(args.paths[0] if args.paths else None)
 
     is_check = getattr(args, "check", False)
-    auditor = DependencyAuditor(root_dir)
+    auditor = DependencyAuditor(root_dir, exclude_patterns=config.exclude)
     audit_report = auditor.audit(
         fix=getattr(args, "fix_deps", False) and not is_check,
         prune_unused=getattr(args, "prune_deps", False) and not is_check,
@@ -936,7 +1520,7 @@ def _cmd_scan(
         severity_threshold=severity,
         ignore_rules=set(config.ignore_security_rules),
     )
-    report = scanner.scan_project(root_dir)
+    report = scanner.scan_project(root_dir, exclude_patterns=config.exclude)
 
     target_base = args.paths[0] if args.paths else "."
     if getattr(args, "json", False):
@@ -1035,7 +1619,7 @@ def _cmd_complexity(
         root_dir = root_dir.parent
 
     analyzer = ComplexityAnalyzer()
-    report = analyzer.analyze_project(root_dir)
+    report = analyzer.analyze_project(root_dir, exclude_patterns=config.exclude)
 
     thresholds = (
         getattr(args, "max_cyclomatic", config.max_cyclomatic_complexity),
@@ -1113,7 +1697,22 @@ def _cmd_dead_code(
         ignore_decorators=set(config.ignore_decorators),
         ignore_names=set(config.ignore_names),
     )
-    report = detector.scan_project(root_dir)
+    if getattr(args, "fix", False):
+        print_msg(f"[bold green]Pruning dead code across {root_dir}...[/bold green]")
+        fix_results = detector.fix_project(root_dir, exclude_patterns=config.exclude)
+        total_pruned = sum(len(res.pruned_items) for res in fix_results.values())
+        print_msg(
+            f"[green]Successfully fixed {len(fix_results)} file(s), pruned {total_pruned} dead code item(s).[/green]"
+        )
+        for p, res in fix_results.items():
+            try:
+                rel_p = p.relative_to(root_dir)
+            except ValueError:
+                rel_p = p
+            print_msg(f"  [cyan]{rel_p}[/cyan]: {len(res.pruned_items)} pruned")
+        return 0
+
+    report = detector.scan_project(root_dir, exclude_patterns=config.exclude)
 
     if getattr(args, "json", False):
         return _render_dead_code_json(report.items)
@@ -1198,7 +1797,7 @@ def _cmd_types(
         root_dir = root_dir.parent
 
     checker = TypeChecker(strict=config.strict_types)
-    report = checker.check_project(root_dir)
+    report = checker.check_project(root_dir, exclude_patterns=config.exclude)
 
     target_base = args.paths[0] if args.paths else "."
     if getattr(args, "json", False):
@@ -1292,7 +1891,7 @@ def _cmd_taint(
         root_dir = root_dir.parent
 
     engine = TaintEngine()
-    report = engine.scan_path(root_dir)
+    report = engine.scan_path(root_dir, exclude_patterns=config.exclude)
 
     target_base = args.paths[0] if args.paths else "."
     if getattr(args, "json", False):
@@ -1498,6 +2097,8 @@ def _cmd_watch(
 
 def _cmd_hook(args: argparse.Namespace, print_msg) -> int:
     """Output pre-commit hook configuration and setup instructions."""
+    from pycleaner import __version__
+
     hook_yaml = (
         "- id: pycleaner\n"
         "  name: pycleaner\n"
@@ -1523,12 +2124,12 @@ def _cmd_hook(args: argparse.Namespace, print_msg) -> int:
     print_msg(
         "To integrate pycleaner with pre-commit, add the following to [bold].pre-commit-hooks.yaml[/bold]:\n"
     )
-    print_msg(hook_yaml)
+    print_msg(hook_yaml.replace("[", "\\["))
     print_msg("Then in your repository's [bold].pre-commit-config.yaml[/bold], add:\n")
     print_msg(
         "  repos:\n"
-        "    - repo: https://github.com/your-org/pycleaner\n"
-        "      rev: v2.0.0\n"
+        "    - repo: https://github.com/moonrox420/ball-python\n"
+        f"      rev: v{__version__}\n"
         "      hooks:\n"
         "        - id: pycleaner\n"
         '          args: ["check"]  # Use check for non-mutating validation\n'