sober-audit 2.0.0__py3-none-any.whl

sober/__init__.py

@@ -0,0 +1,7 @@
+"""
+sober - The Vibe Coding Hangover Cure.
+Audit, sanitize, and proofread AI-generated code before pushing to production.
+"""
+
+__version__ = "2.0.0"
+__author__ = "shenald-dev"

sober/cli.py

@@ -0,0 +1,491 @@
+"""
+CLI Entrypoint for SOBER - The Vibe Coding Hangover Cure.
+"""
+
+import json
+import time
+from pathlib import Path
+
+import typer
+
+from sober import __version__
+from sober.core.ci import init_github_actions_workflow
+from sober.core.config import load_config
+from sober.core.git_helper import (
+    get_git_diff_range_files,
+    get_git_hook_status,
+    get_git_hooks_dir,
+    install_git_hook,
+    uninstall_git_hook,
+)
+from sober.core.manifest import ManifestInspector
+from sober.core.remediation import generate_agent_remediation_prompt
+from sober.core.sanitizer import apply_cure
+from sober.core.scanner import FileToAudit, get_all_code_files, get_git_modified_files
+from sober.core.scorer import SoberAuditReport
+from sober.core.watcher import LiveSoberWatcher
+from sober.detectors.antipatterns import audit_antipatterns
+from sober.detectors.chatter import audit_chatter
+from sober.detectors.duplicates import audit_duplicates
+from sober.detectors.ghost_code import audit_ghost_code
+from sober.detectors.hallucinations import audit_hallucinations
+from sober.detectors.security import audit_security
+from sober.ui.console import (
+    console,
+    print_banner,
+    render_cure_results,
+    render_hook_status,
+    render_report,
+)
+
+app = typer.Typer(
+    help="🍸 The Vibe Coding Hangover Cure. Audit, sanitize, and proofread AI-generated code before pushing to production.",
+    add_completion=False,
+    no_args_is_help=False,
+)
+
+hook_app = typer.Typer(help="Manage Git pre-commit hooks for automated sobriety checks.", add_completion=False)
+app.add_typer(hook_app, name="hook")
+
+ci_app = typer.Typer(help="Manage CI/CD workflows and automated GitHub Actions gates.", add_completion=False)
+app.add_typer(ci_app, name="ci")
+
+
+def version_callback(value: bool):
+    if value:
+        console.print(f"[bold cyan]sober[/] version [bold green]{__version__}[/]")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def _main_callback(
+    ctx: typer.Context,
+    _version: bool | None = typer.Option(
+        None, "--version", "-v", help="Show version and exit.", callback=version_callback, is_eager=True
+    ),
+):
+    if ctx.invoked_subcommand is None:
+        scan(Path("."))
+
+
+def _execute_audit(
+    files: list[FileToAudit],
+    path: Path,
+    json_output: bool = False,
+    sarif_output: bool = False,
+    markdown_output: bool = False,
+    cure: bool = False,
+    strict: bool = False,
+    min_score_override: float | None = None,
+    offline: bool = False,
+) -> SoberAuditReport:
+    """Core audit runner for scan, diff, and explain commands."""
+    start_time = time.time()
+    config = load_config(path)
+    if offline:
+        config.offline_mode = True
+    manifest = ManifestInspector(path)
+
+    # Filter out files ignored by config
+    filtered_files = []
+    for f in files:
+        rel = str(f.path.relative_to(path) if f.path.is_relative_to(path) else f.path)
+        if not config.is_path_ignored(rel):
+            filtered_files.append(f)
+    files = filtered_files
+
+    if not files:
+        empty_report = SoberAuditReport([], files_scanned=0, duration_seconds=0.0)
+        if json_output:
+            print(json.dumps({"error": "No supported source files found to audit."}))
+        elif sarif_output:
+            print(json.dumps(empty_report.to_sarif(), indent=2))
+        elif markdown_output:
+            print(empty_report.to_markdown())
+        else:
+            console.print("[bold yellow]No supported source files (.py, .ts, .tsx, .js, .jsx) found to audit.[/]")
+        return empty_report
+
+    # Run detectors
+    all_issues = []
+    for f in files:
+        if config.is_detector_enabled("hallucinations"):
+            all_issues.extend(audit_hallucinations(f, path, manifest_inspector=manifest, config=config))
+        if config.is_detector_enabled("antipatterns"):
+            all_issues.extend(audit_antipatterns(f, path))
+        if config.is_detector_enabled("ghost_code"):
+            all_issues.extend(audit_ghost_code(f, path))
+        if config.is_detector_enabled("security"):
+            all_issues.extend(audit_security(f, path, custom_secret_patterns=config.custom_secret_patterns))
+        if config.is_detector_enabled("chatter"):
+            all_issues.extend(audit_chatter(f, path))
+
+    if config.is_detector_enabled("duplicates"):
+        all_issues.extend(audit_duplicates(files, path))
+
+    duration = time.time() - start_time
+    report = SoberAuditReport(all_issues, files_scanned=len(files), duration_seconds=duration)
+
+    # Render outputs
+    if json_output:
+        print(json.dumps(report.to_dict(), indent=2))
+    elif sarif_output:
+        print(json.dumps(report.to_sarif(), indent=2))
+    elif markdown_output:
+        print(report.to_markdown())
+    else:
+        render_report(report)
+
+    # Optional auto-cure
+    if cure:
+        cured = apply_cure(report.issues, path)
+        if not (json_output or sarif_output or markdown_output):
+            render_cure_results(cured)
+
+    # Strict mode validation
+    effective_min_score = min_score_override if min_score_override is not None else config.min_score
+    should_fail = False
+
+    if strict:
+        if report.score < effective_min_score:
+            should_fail = True
+        if config.fail_on_critical and report.critical_count > 0:
+            should_fail = True
+
+    if should_fail:
+        if not (json_output or sarif_output or markdown_output):
+            console.print(
+                f"\n[bold red]❌ STRICT CHECK FAILED: Sober Score is {report.score}% (<{effective_min_score}%) or critical issues detected.[/]\n"
+            )
+        raise typer.Exit(1)
+
+    return report
+
+
+@app.command(name="scan")
+def scan(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Target repository or folder path to audit (defaults to current directory).",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    all_files: bool = typer.Option(
+        False,
+        "--all",
+        "-a",
+        help="Audit all codebase files instead of only uncommitted / modified git changes.",
+    ),
+    cure: bool = typer.Option(
+        False,
+        "--cure",
+        "-c",
+        help="Automatically sanitize and strip leftover debug statements, markdown fences, & AI debris.",
+    ),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        "-s",
+        help="Fail with exit code 1 if the Sober Score is below threshold or has critical issues.",
+    ),
+    min_score: float | None = typer.Option(
+        None,
+        "--min-score",
+        help="Override minimum score threshold for strict mode (default: 95.0).",
+    ),
+    offline: bool = typer.Option(
+        False,
+        "--offline",
+        help="Disable external network queries (PyPI/npm) and perform air-gapped manifest-only audits.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Output raw JSON results for CI/CD integrations.",
+    ),
+    sarif_output: bool = typer.Option(
+        False,
+        "--sarif",
+        help="Output SARIF 2.1.0 format for GitHub Code Scanning Alerts.",
+    ),
+    markdown_output: bool = typer.Option(
+        False,
+        "--markdown",
+        "-m",
+        help="Output GitHub Flavored Markdown summary suitable for PR comments.",
+    ),
+):
+    """Scan code for AI hallucinations, slopsquatting, ghost code, security leaks, and hangover slop."""
+    if not (json_output or sarif_output or markdown_output):
+        print_banner()
+
+    files = []
+    if not all_files:
+        files = get_git_modified_files(path)
+        if not files and not (json_output or sarif_output or markdown_output):
+            console.print("[dim]No uncommitted git changes detected. Auditing all repository files...[/]\n")
+            files = get_all_code_files(path)
+    else:
+        files = get_all_code_files(path)
+
+    _execute_audit(
+        files=files,
+        path=path,
+        json_output=json_output,
+        sarif_output=sarif_output,
+        markdown_output=markdown_output,
+        cure=cure,
+        strict=strict,
+        min_score_override=min_score,
+        offline=offline,
+    )
+
+
+@app.command(name="diff")
+def _diff_command(
+    revision: str = typer.Argument(
+        ...,
+        help="Git revision or commit range to audit (e.g. 'HEAD~1', 'main..HEAD', 'origin/main').",
+    ),
+    path: Path = typer.Option(
+        Path("."),
+        "--path",
+        "-p",
+        help="Target repository root directory.",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    cure: bool = typer.Option(False, "--cure", "-c", help="Auto-sanitize detected debug statements."),
+    strict: bool = typer.Option(False, "--strict", "-s", help="Fail if sobriety threshold not met."),
+    min_score: float | None = typer.Option(None, "--min-score", help="Override minimum score threshold."),
+    offline: bool = typer.Option(False, "--offline", help="Perform offline manifest audit without external network calls."),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output raw JSON."),
+    sarif_output: bool = typer.Option(False, "--sarif", help="Output SARIF 2.1.0."),
+    markdown_output: bool = typer.Option(False, "--markdown", "-m", help="Output Markdown report."),
+):
+    """Audit code changes introduced across a specific git commit range or branch."""
+    if not (json_output or sarif_output or markdown_output):
+        print_banner()
+        console.print(f"[bold cyan]Auditing changes in git range:[/] [yellow]{revision}[/]\n")
+
+    files = get_git_diff_range_files(path, revision)
+    _execute_audit(
+        files=files,
+        path=path,
+        json_output=json_output,
+        sarif_output=sarif_output,
+        markdown_output=markdown_output,
+        cure=cure,
+        strict=strict,
+        min_score_override=min_score,
+        offline=offline,
+    )
+
+
+@app.command(name="watch")
+def _watch_command(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Target repository to monitor in real-time.",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    interval: float = typer.Option(0.5, "--interval", "-i", help="Polling interval in seconds."),
+    cure: bool = typer.Option(False, "--cure", "-c", help="Auto-cure detected debug statements and chatter on save."),
+):
+    """Live continuous watcher daemon for real-time AI vibe-coding feedback."""
+    print_banner()
+    console.print(f"[bold cyan]👀 SOBER Live Watcher active on {path.resolve()}[/] [dim](Ctrl+C to exit)[/]\n")
+
+    def _on_change():
+        console.clear()
+        print_banner()
+        console.print("[bold yellow]⚡ Change detected! Re-auditing sobriety...[/]\n")
+        files = get_git_modified_files(path)
+        if not files:
+            files = get_all_code_files(path)
+        _execute_audit(files=files, path=path, cure=cure)
+
+    watcher = LiveSoberWatcher(path, poll_interval=interval)
+    try:
+        watcher.watch(_on_change)
+    except KeyboardInterrupt:
+        console.print("\n[bold cyan]SOBER Live Watcher stopped.[/]")
+
+
+@app.command(name="explain")
+def _explain_command(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Target repository or folder path to audit.",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    all_files: bool = typer.Option(False, "--all", "-a", help="Audit all files instead of only uncommitted changes."),
+):
+    """Generate high-density prompt context for autonomous coding agents (Claude, Cursor, Aider) to self-heal."""
+    files = get_all_code_files(path) if all_files else get_git_modified_files(path)
+    if not files and not all_files:
+        files = get_all_code_files(path)
+
+    config = load_config(path)
+    manifest = ManifestInspector(path)
+
+    all_issues = []
+    for f in files:
+        if config.is_detector_enabled("hallucinations"):
+            all_issues.extend(audit_hallucinations(f, path, manifest_inspector=manifest, config=config))
+        if config.is_detector_enabled("antipatterns"):
+            all_issues.extend(audit_antipatterns(f, path))
+        if config.is_detector_enabled("ghost_code"):
+            all_issues.extend(audit_ghost_code(f, path))
+        if config.is_detector_enabled("security"):
+            all_issues.extend(audit_security(f, path, custom_secret_patterns=config.custom_secret_patterns))
+        if config.is_detector_enabled("chatter"):
+            all_issues.extend(audit_chatter(f, path))
+
+    if config.is_detector_enabled("duplicates"):
+        all_issues.extend(audit_duplicates(files, path))
+
+    report = SoberAuditReport(all_issues, files_scanned=len(files), duration_seconds=0.0)
+    prompt = generate_agent_remediation_prompt(
+        issues=report.issues,
+        score=report.score,
+        grade=report.grade,
+        status_label=report.status_label,
+        files_scanned=len(files),
+    )
+    print(prompt)
+
+
+@app.command(name="cure")
+def _cure_command(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Target folder to sanitize debug debris and AI chatter.",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    all_files: bool = typer.Option(False, "--all", "-a", help="Cure all files instead of only uncommitted changes."),
+):
+    """Standalone sanitization tool: auto-strip leftover debug statements, debuggers, and AI chatter."""
+    print_banner()
+    files = get_all_code_files(path) if all_files else get_git_modified_files(path)
+    if not files and not all_files:
+        files = get_all_code_files(path)
+
+    all_issues = []
+    for f in files:
+        all_issues.extend(audit_ghost_code(f, path))
+        all_issues.extend(audit_chatter(f, path))
+
+    cured = apply_cure(all_issues, path)
+    render_cure_results(cured)
+
+
+@hook_app.command(name="install")
+def _hook_install(
+    path: Path = typer.Argument(Path("."), help="Target Git repository root path."),
+):
+    """Install a native Git pre-commit hook that runs sober scan before every commit."""
+    success, msg = install_git_hook(path)
+    if success:
+        console.print(f"[bold green]✔ Successfully installed sober pre-commit hook at {msg}[/]\n")
+    else:
+        console.print(f"[bold red]❌ {msg}[/]\n")
+        raise typer.Exit(1)
+
+
+@hook_app.command(name="uninstall")
+def _hook_uninstall(
+    path: Path = typer.Argument(Path("."), help="Target Git repository root path."),
+):
+    """Remove the sober Git pre-commit hook."""
+    success, msg = uninstall_git_hook(path)
+    if success:
+        console.print(f"[bold green]✔ {msg}[/]\n")
+    else:
+        console.print(f"[bold yellow]{msg}[/]\n")
+
+
+@hook_app.command(name="status")
+def _hook_status(
+    path: Path = typer.Argument(Path("."), help="Target Git repository root path."),
+):
+    """Check the status of the Git pre-commit hook."""
+    installed = get_git_hook_status(path)
+    hooks_dir = get_git_hooks_dir(path)
+    hook_path = str(hooks_dir / "pre-commit") if hooks_dir else ""
+    render_hook_status(installed, hook_path)
+
+
+@ci_app.command(name="init")
+def _ci_init(
+    path: Path = typer.Argument(Path("."), help="Target repository root path."),
+):
+    """Initialize a GitHub Actions workflow for automated PR sobriety checks."""
+    wf_path = init_github_actions_workflow(path)
+    console.print(f"[bold green]✔ Generated GitHub Actions workflow at {wf_path}[/]\n")
+
+
+@app.command(name="init")
+def _init_command(
+    path: Path = typer.Argument(Path("."), help="Target directory to create sober.toml."),
+):
+    """Initialize a starter sober.toml configuration file."""
+    target_file = path / "sober.toml"
+    if target_file.exists():
+        console.print(f"[bold yellow]Configuration file {target_file} already exists.[/]")
+        raise typer.Exit(0)
+
+    starter_config = """# SOBER Configuration File (v2.0)
+# Documentation: https://github.com/shenald-dev/sober
+
+[sober]
+min_score = 95.0
+fail_on_critical = true
+max_workers = 10
+offline_mode = false
+
+# Paths to ignore during audits
+ignore_paths = [
+    "tests/*",
+    "docs/*",
+    "migrations/*",
+]
+
+# Allowed internal or proprietary packages that should never trigger hallucination alerts
+allowed_packages = [
+    "@my-org/*",
+    # "internal_company_sdk",
+]
+
+# Disable specific detectors if needed
+# disabled_detectors = ["duplicates"]
+
+# Custom proprietary secret regex patterns
+# [[sober.custom_secret_patterns]]
+# name = "Company Internal API Token"
+# pattern = "comp_[A-Za-z0-9]{32}"
+"""
+    target_file.write_text(starter_config, encoding="utf-8")
+    console.print(f"[bold green]✔ Initialized starter configuration at {target_file}[/]")
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

sober/core/__init__.py

@@ -0,0 +1 @@
+"""Core audit, scanning, scoring, and sanitizing engines."""

sober/core/ci.py

@@ -0,0 +1,61 @@
+"""
+CI / GitHub Actions Workflow Generator for SOBER.
+Bootstraps ready-to-run GitHub Actions workflows for automated PR sobriety checks.
+"""
+
+from pathlib import Path
+
+GITHUB_ACTIONS_WORKFLOW = """name: SOBER Code Sobriety Radar
+
+on:
+  pull_request:
+    branches: [main, master]
+  push:
+    branches: [main, master]
+
+jobs:
+  sober-audit:
+    name: AI Hangover & Security Audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install SOBER
+        run: |
+          pip install git+https://github.com/shenald-dev/sober.git
+
+      - name: Run SOBER Audit (SARIF & Markdown)
+        run: |
+          sober scan --all --sarif > sober.sarif
+          sober scan --all --markdown > sober-summary.md
+          cat sober-summary.md >> $GITHUB_STEP_SUMMARY
+        continue-on-error: true
+
+      - name: Upload SARIF to GitHub Code Scanning
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: sober.sarif
+          category: sober-hangover-guard
+
+      - name: Strict Sobriety Gate
+        run: |
+          sober scan --all --strict --min-score 90
+"""
+
+
+def init_github_actions_workflow(repo_root: Path) -> Path:
+    """Create .github/workflows/sober-guard.yml."""
+    workflows_dir = repo_root / ".github" / "workflows"
+    workflows_dir.mkdir(parents=True, exist_ok=True)
+    workflow_file = workflows_dir / "sober-guard.yml"
+    workflow_file.write_text(GITHUB_ACTIONS_WORKFLOW, encoding="utf-8")
+    return workflow_file

sober/core/config.py

@@ -0,0 +1,89 @@
+"""
+Configuration loader for SOBER - supports sober.toml and pyproject.toml [tool.sober].
+"""
+
+import fnmatch
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib  # type: ignore
+
+
+@dataclass
+class SoberConfig:
+    min_score: float = 95.0
+    fail_on_critical: bool = True
+    ignore_paths: list[str] = field(default_factory=list)
+    allowed_packages: list[str] = field(default_factory=list)
+    disabled_detectors: list[str] = field(default_factory=list)
+    custom_secret_patterns: list[dict[str, str]] = field(default_factory=list)
+    max_workers: int = 10
+    offline_mode: bool = False
+
+    def is_path_ignored(self, rel_path: str) -> bool:
+        """Check if relative file path matches any ignore glob patterns."""
+        normalized = rel_path.replace("\\", "/")
+        for pattern in self.ignore_paths:
+            norm_pattern = pattern.replace("\\", "/")
+            if fnmatch.fnmatch(normalized, norm_pattern) or fnmatch.fnmatch(Path(normalized).name, norm_pattern):
+                return True
+        return False
+
+    def is_package_whitelisted(self, package_name: str) -> bool:
+        """Check if package name matches any allowed package names or wildcard scopes."""
+        clean_name = package_name.lower().strip()
+        for allowed in self.allowed_packages:
+            norm_allowed = allowed.lower().strip()
+            if norm_allowed == clean_name or fnmatch.fnmatch(clean_name, norm_allowed):
+                return True
+        return False
+
+    def is_detector_enabled(self, detector_name: str) -> bool:
+        """Check if detector is enabled."""
+        return detector_name.lower() not in [d.lower() for d in self.disabled_detectors]
+
+
+def load_config(root_path: Path) -> SoberConfig:
+    """Load configuration from sober.toml, .sober.toml, or pyproject.toml."""
+    candidates = [
+        root_path / "sober.toml",
+        root_path / ".sober.toml",
+        root_path / "pyproject.toml",
+    ]
+
+    for candidate in candidates:
+        if candidate.is_file():
+            try:
+                content = candidate.read_bytes()
+                data = tomllib.loads(content.decode("utf-8", errors="replace"))
+
+                section: dict[str, Any] = {}
+                if candidate.name == "pyproject.toml":
+                    section = data.get("tool", {}).get("sober", {})
+                else:
+                    section = data.get("sober", data)
+
+                if not section and candidate.name == "pyproject.toml":
+                    continue
+
+                return SoberConfig(
+                    min_score=float(section.get("min_score", 95.0)),
+                    fail_on_critical=bool(section.get("fail_on_critical", True)),
+                    ignore_paths=list(section.get("ignore_paths", [])),
+                    allowed_packages=list(section.get("allowed_packages", [])),
+                    disabled_detectors=list(section.get("disabled_detectors", [])),
+                    custom_secret_patterns=list(section.get("custom_secret_patterns", [])),
+                    max_workers=int(section.get("max_workers", 10)),
+                    offline_mode=bool(section.get("offline_mode", False)),
+                )
+            except Exception:
+                logging.debug(f"Failed to parse config candidate {candidate}", exc_info=True)
+                # If TOML has errors, skip to next candidate
+                continue
+
+    return SoberConfig()