debtscanner 0.2.0__tar.gz

debtscanner-0.2.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: debtscanner
+Version: 0.2.0
+Summary: AI-powered technical debt scanner for codebases
+Requires-Dist: click
+Requires-Dist: openai
+Requires-Dist: tqdm
+Requires-Dist: colorama
+Requires-Dist: rich
+Requires-Dist: python-dotenv
+Provides-Extra: watch
+Requires-Dist: watchdog; extra == "watch"
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary

debtscanner-0.2.0/README.md

@@ -0,0 +1,44 @@
+# debtscanner
+
+`debtscanner` is a Python CLI that scans codebases for technical debt using AI and produces prioritized results in terminal and HTML.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Configure
+
+Create a `.env` file in the project root:
+
+```env
+GITHUB_TOKEN=ghp_your_token_here
+```
+
+Or export `GITHUB_TOKEN` in your shell.
+
+## Commands
+
+```bash
+debtscanner scan .
+debtscanner scan src/ --output report.html
+debtscanner report
+debtscanner fix auth.py
+```
+
+## Options
+
+- `--ignore`: skip specific folders (repeatable or comma-separated)
+- `--severity`: minimum level to include (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
+
+## Supported languages
+
+- `.py`, `.js`, `.ts`, `.jsx`, `.tsx`, `.java`, `.go`, `.rb`
+
+## Behavior
+
+- Skips: `node_modules`, `.git`, `__pycache__`, `dist`, `build`, `.env`
+- Skips files larger than 100KB with warning
+- Skips binary files automatically
+- Retries once on API rate limits with a 2-second pause

debtscanner-0.2.0/debtscanner/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.2.0"

debtscanner-0.2.0/debtscanner/ai.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+from .prompts import FIX_PROMPT, SCAN_PROMPT
+
+PROVIDERS: dict[str, dict[str, Any]] = {
+    "github": {
+        "label": "GitHub Models (free with GitHub token)",
+        "base_url": "https://models.inference.ai.azure.com",
+        "default_model": "gpt-4o-mini",
+        "env_key": "GITHUB_TOKEN",
+        "env_hint": "ghp_xxxxxxxxxxxxxxxxxxxx",
+    },
+    "openai": {
+        "label": "OpenAI (requires API key)",
+        "base_url": "https://api.openai.com/v1",
+        "default_model": "gpt-4o-mini",
+        "env_key": "OPENAI_API_KEY",
+        "env_hint": "sk-xxxxxxxxxxxxxxxxxxxx",
+    },
+    "anthropic": {
+        "label": "Anthropic Claude (via OpenAI-compat proxy)",
+        "base_url": "https://api.anthropic.com/v1",
+        "default_model": "claude-sonnet-4-20250514",
+        "env_key": "ANTHROPIC_API_KEY",
+        "env_hint": "sk-ant-xxxxxxxxxxxxxxxxxxxx",
+    },
+    "ollama": {
+        "label": "Ollama (local, no key needed)",
+        "base_url": "http://localhost:11434/v1",
+        "default_model": "llama3",
+        "env_key": "",
+        "env_hint": "",
+    },
+}
+
+
+def _resolve_provider() -> tuple[str, str, str]:
+    load_dotenv()
+
+    provider_name = os.getenv("DEBTSCANNER_PROVIDER", "github").lower()
+    info = PROVIDERS.get(provider_name)
+
+    if info is None:
+        raise RuntimeError(
+            f"Unknown provider '{provider_name}'. "
+            f"Valid choices: {', '.join(PROVIDERS)}"
+        )
+
+    model = os.getenv("DEBTSCANNER_MODEL", info["default_model"])
+    base_url = os.getenv("DEBTSCANNER_BASE_URL", info["base_url"])
+
+    if provider_name == "ollama":
+        return base_url, "ollama", model
+
+    env_key = info["env_key"]
+    token = os.getenv(env_key, "")
+    if not token:
+        raise RuntimeError(
+            f"Missing {env_key} for provider '{provider_name}'. "
+            f"Run `debtscanner init` or add it to your .env file."
+        )
+
+    return base_url, token, model
+
+
+class AIClient:
+    def __init__(self) -> None:
+        base_url, api_key, model = _resolve_provider()
+        self.model = model
+        self.client = OpenAI(base_url=base_url, api_key=api_key)
+
+    def _create_completion(self, user_content: str) -> str:
+        for attempt in range(2):
+            try:
+                response = self.client.chat.completions.create(
+                    model=self.model,
+                    messages=[
+                        {
+                            "role": "user",
+                            "content": user_content,
+                        }
+                    ],
+                    temperature=0.2,
+                )
+                return (response.choices[0].message.content or "").strip()
+            except Exception as exc:
+                error_text = str(exc).lower()
+                should_retry = "429" in error_text or "rate limit" in error_text
+                if should_retry and attempt == 0:
+                    time.sleep(2)
+                    continue
+                raise
+
+        return ""
+
+    def analyze_code(self, filename: str, content: str) -> str:
+        prompt = f"{SCAN_PROMPT}\n\nFILE UNDER REVIEW: {filename}\n\nCODE:\n{content}"
+        return self._create_completion(prompt)
+
+    def suggest_fixes(self, filename: str, content: str) -> str:
+        prompt = f"{FIX_PROMPT}\n\nFILE UNDER REVIEW: {filename}\n\nCODE:\n{content}"
+        return self._create_completion(prompt)

debtscanner-0.2.0/debtscanner/cli.py

@@ -0,0 +1,516 @@
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Sequence
+
+import click
+from colorama import Fore, Style
+from colorama import init as colorama_init
+from rich.console import Console
+from tqdm import tqdm
+
+from .ai import AIClient, PROVIDERS
+from .reporter import (
+    render_file_scores_table,
+    render_json,
+    render_markdown,
+    render_terminal_table,
+    summarize,
+    summary_line,
+    write_html_report,
+)
+from .scanner import (
+    MAX_FILE_SIZE_BYTES,
+    filter_min_severity,
+    parse_ai_scan_response,
+    scan_files,
+    sort_debt_items,
+    top_critical_files,
+)
+
+colorama_init(autoreset=True)
+console = Console()
+
+SEVERITY_CHOICES = ["LOW", "MEDIUM", "HIGH", "CRITICAL"]
+FORMAT_CHOICES = ["table", "json", "markdown"]
+
+
+def _read_file_for_fix(file_path: str) -> str:
+    if os.path.getsize(file_path) > MAX_FILE_SIZE_BYTES:
+        raise click.ClickException("File too large (>100KB). Please scan a smaller file.")
+
+    with open(file_path, "rb") as binary_file:
+        chunk = binary_file.read(2048)
+        if b"\x00" in chunk:
+            raise click.ClickException("Binary files are not supported for fix suggestions.")
+
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="ignore") as source_file:
+            return source_file.read()
+    except OSError as exc:
+        raise click.ClickException(f"Unable to read file: {exc}") from exc
+
+
+def _run_scan(
+    target: str,
+    ignore: Sequence[str],
+    min_severity: str,
+    output: str | None = None,
+    fmt: str = "table",
+) -> int:
+    target_path = Path(target).resolve()
+    if not target_path.exists() or not target_path.is_dir():
+        raise click.ClickException(f"Directory not found: {target}")
+
+    files, warnings = scan_files(str(target_path), ignore_dirs=ignore)
+
+    for warning in warnings:
+        click.echo(f"{Fore.YELLOW}Warning:{Style.RESET_ALL} {warning}")
+
+    if not files:
+        raise click.ClickException(
+            "No supported source files were found. Try a different path or adjust --ignore."
+        )
+
+    try:
+        ai_client = AIClient()
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    all_items = []
+    for source_file in tqdm(files, desc="Scanning files", unit="file"):
+        relative_name = os.path.relpath(source_file.path, str(target_path))
+        response = ai_client.analyze_code(relative_name, source_file.content)
+        all_items.extend(parse_ai_scan_response(response, relative_name))
+
+    filtered = sort_debt_items(filter_min_severity(all_items, min_severity))
+
+    if fmt == "json":
+        click.echo(render_json(filtered, total_files=len(files)))
+    elif fmt == "markdown":
+        click.echo(render_markdown(filtered, total_files=len(files)))
+    else:
+        top5 = top_critical_files(filtered)
+        if top5:
+            render_file_scores_table(top5)
+            console.print()
+
+        if filtered:
+            render_terminal_table(filtered)
+        else:
+            console.print(
+                "[yellow]No debt items found for the selected severity threshold.[/yellow]"
+            )
+
+        console.print(summary_line(len(files), filtered))
+        console.print(summarize(filtered))
+
+    if output:
+        report_path = write_html_report(filtered, output, total_files=len(files))
+        click.echo(f"Saved HTML report to {report_path}")
+
+    return len(filtered)
+
+
+@click.group()
+def main() -> None:
+    pass
+
+
+@main.command()
+def init() -> None:
+    click.echo(f"\n{Fore.CYAN}Welcome to debtscanner setup!{Style.RESET_ALL}\n")
+
+    click.echo("Choose an AI provider:\n")
+    provider_keys = list(PROVIDERS.keys())
+    for idx, key in enumerate(provider_keys, 1):
+        info = PROVIDERS[key]
+        click.echo(f"  {Fore.GREEN}{idx}{Style.RESET_ALL}) {info['label']}")
+
+    click.echo()
+    choice = click.prompt(
+        "Enter provider number",
+        type=click.IntRange(1, len(provider_keys)),
+        default=1,
+    )
+    provider_name = provider_keys[choice - 1]
+    provider_info = PROVIDERS[provider_name]
+
+    env_key = provider_info["env_key"]
+    token = ""
+    if env_key:
+        from dotenv import dotenv_values
+
+        env_path = Path.cwd() / ".env"
+        env_example_path = Path.cwd() / ".env.example"
+
+        existing_env: dict[str, str | None] = {}
+        if env_path.exists():
+            existing_env = dotenv_values(env_path)
+        elif env_example_path.exists():
+            existing_env = dotenv_values(env_example_path)
+
+        existing_token = (
+            os.getenv(env_key, "")
+            or (existing_env.get(env_key) or "")
+        )
+
+        hint = provider_info["env_hint"]
+        is_placeholder = (
+            not existing_token
+            or existing_token == hint
+            or existing_token.startswith("ghp_your_")
+            or "xxxx" in existing_token
+        )
+
+        if existing_token and not is_placeholder:
+            masked = existing_token[:6] + "..." + existing_token[-4:]
+            click.echo(
+                f"\n{Fore.GREEN}Found existing {env_key}{Style.RESET_ALL} ({masked})"
+            )
+            keep = click.confirm("Keep this token?", default=True)
+            if keep:
+                token = existing_token
+            else:
+                click.echo(f"\nPaste your new {env_key} (input is visible):")
+                token = click.prompt(
+                    f"{env_key}",
+                    default="",
+                    show_default=False,
+                ).strip()
+                if not token:
+                    click.echo(
+                        f"{Fore.YELLOW}No token provided - keeping the existing one.{Style.RESET_ALL}"
+                    )
+                    token = existing_token
+        else:
+            click.echo(
+                f"\n{provider_info['label']} requires the environment variable "
+                f"{Fore.YELLOW}{env_key}{Style.RESET_ALL}."
+            )
+            click.echo("Paste your token below (input is visible):")
+            token = click.prompt(
+                f"{env_key}",
+                default="",
+                show_default=False,
+            ).strip()
+            if not token:
+                click.echo(
+                    f"{Fore.YELLOW}No token provided - you can add it later "
+                    f"by editing .env{Style.RESET_ALL}"
+                )
+                token = hint
+    else:
+        click.echo(f"\n{provider_info['label']} - no API key needed.")
+
+    default_model = provider_info["default_model"]
+    click.echo(f"\nDefault model: {Fore.CYAN}{default_model}{Style.RESET_ALL}")
+    change_model = click.confirm("Use a different model?", default=False)
+    if change_model:
+        model = click.prompt("Enter model name").strip()
+        if not model:
+            model = default_model
+    else:
+        model = default_model
+
+    env_lines = [
+        f"# debtscanner configuration (generated by `debtscanner init`)",
+        f"DEBTSCANNER_PROVIDER={provider_name}",
+    ]
+    if env_key and token:
+        env_lines.append(f"{env_key}={token}")
+    if model != default_model:
+        env_lines.append(f"DEBTSCANNER_MODEL={model}")
+
+    env_path = Path.cwd() / ".env"
+    if env_path.exists():
+        overwrite = click.confirm(
+            f"\n{Fore.YELLOW}.env already exists. Overwrite?{Style.RESET_ALL}",
+            default=False,
+        )
+        if not overwrite:
+            click.echo("Aborted - .env was not modified.")
+            return
+
+    env_path.write_text("\n".join(env_lines) + "\n", encoding="utf-8")
+    click.echo(f"\n{Fore.GREEN}Created .env{Style.RESET_ALL} with provider={provider_name}")
+    click.echo("Run `debtscanner scan .` to start scanning!\n")
+
+
+@main.command()
+@click.argument("target", default=".")
+@click.option("--output", type=click.Path(dir_okay=False), default=None, help="Write HTML report")
+@click.option(
+    "--ignore",
+    multiple=True,
+    help="Folder(s) to ignore. Can be repeated or comma-separated.",
+)
+@click.option(
+    "--severity",
+    "min_severity",
+    type=click.Choice(SEVERITY_CHOICES, case_sensitive=False),
+    default="LOW",
+    show_default=True,
+    help="Minimum severity level to include.",
+)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(FORMAT_CHOICES, case_sensitive=False),
+    default="table",
+    show_default=True,
+    help="Output format: table, json, or markdown.",
+)
+@click.option(
+    "--watch",
+    is_flag=True,
+    default=False,
+    help="Re-scan automatically when source files change.",
+)
+def scan(
+    target: str,
+    output: str | None,
+    ignore: Sequence[str],
+    min_severity: str,
+    fmt: str,
+    watch: bool,
+) -> None:
+    if watch:
+        _watch_loop(target=target, ignore=ignore, min_severity=min_severity, output=output, fmt=fmt)
+    else:
+        _run_scan(
+            target=target,
+            ignore=ignore,
+            min_severity=min_severity.upper(),
+            output=output,
+            fmt=fmt,
+        )
+
+
+@main.command()
+@click.argument("target", default=".")
+@click.option(
+    "--output",
+    type=click.Path(dir_okay=False),
+    default="report.html",
+    show_default=True,
+    help="Output path for the HTML report.",
+)
+@click.option(
+    "--ignore",
+    multiple=True,
+    help="Folder(s) to ignore. Can be repeated or comma-separated.",
+)
+@click.option(
+    "--severity",
+    "min_severity",
+    type=click.Choice(SEVERITY_CHOICES, case_sensitive=False),
+    default="LOW",
+    show_default=True,
+    help="Minimum severity level to include.",
+)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(FORMAT_CHOICES, case_sensitive=False),
+    default="table",
+    show_default=True,
+    help="Output format: table, json, or markdown.",
+)
+@click.option(
+    "--watch",
+    is_flag=True,
+    default=False,
+    help="Re-scan automatically when source files change.",
+)
+def report(
+    target: str,
+    output: str,
+    ignore: Sequence[str],
+    min_severity: str,
+    fmt: str,
+    watch: bool,
+) -> None:
+    if watch:
+        _watch_loop(target=target, ignore=ignore, min_severity=min_severity, output=output, fmt=fmt)
+    else:
+        _run_scan(
+            target=target,
+            ignore=ignore,
+            min_severity=min_severity.upper(),
+            output=output,
+            fmt=fmt,
+        )
+
+
+@main.command()
+@click.argument("filepath", type=click.Path(exists=True, dir_okay=False))
+def fix(filepath: str) -> None:
+    try:
+        code = _read_file_for_fix(filepath)
+    except click.ClickException:
+        raise
+    except OSError as exc:
+        raise click.ClickException(f"Unable to access file: {exc}") from exc
+
+    try:
+        ai_client = AIClient()
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    filename = os.path.basename(filepath)
+    response = ai_client.suggest_fixes(filename, code)
+
+    if not response.strip():
+        console.print("[yellow]AI returned no fix suggestions.[/yellow]")
+        return
+
+    console.rule(f"Fix Suggestions: {filename}")
+    console.print(response)
+
+
+def _watch_loop(
+    *,
+    target: str,
+    ignore: Sequence[str],
+    min_severity: str,
+    output: str | None,
+    fmt: str,
+) -> None:
+    target_path = Path(target).resolve()
+    if not target_path.exists() or not target_path.is_dir():
+        raise click.ClickException(f"Directory not found: {target}")
+
+    click.echo(
+        f"{Fore.CYAN}Watching {target_path} for changes "
+        f"(Ctrl+C to stop)...{Style.RESET_ALL}\n"
+    )
+
+    _run_scan(
+        target=target,
+        ignore=ignore,
+        min_severity=min_severity.upper(),
+        output=output,
+        fmt=fmt,
+    )
+
+    try:
+        _watch_with_watchdog(target_path, ignore, min_severity, output, fmt)
+    except ImportError:
+        _watch_with_polling(target_path, ignore, min_severity, output, fmt)
+
+
+def _watch_with_watchdog(
+    target_path: Path,
+    ignore: Sequence[str],
+    min_severity: str,
+    output: str | None,
+    fmt: str,
+) -> None:
+    from watchdog.observers import Observer
+    from watchdog.events import FileSystemEventHandler
+    import threading
+
+    from .scanner import SUPPORTED_EXTENSIONS
+
+    debounce_timer: threading.Timer | None = None
+    lock = threading.Lock()
+
+    def _do_rescan() -> None:
+        click.echo(f"\n{Fore.CYAN}Change detected - rescanning...{Style.RESET_ALL}\n")
+        try:
+            _run_scan(
+                target=str(target_path),
+                ignore=ignore,
+                min_severity=min_severity.upper(),
+                output=output,
+                fmt=fmt,
+            )
+        except click.ClickException as exc:
+            click.echo(f"{Fore.RED}Error: {exc.message}{Style.RESET_ALL}")
+
+    class _Handler(FileSystemEventHandler):
+        def on_any_event(self, event) -> None:
+            if event.is_directory:
+                return
+            src = getattr(event, "src_path", "")
+            ext = os.path.splitext(src)[1].lower()
+            if ext not in SUPPORTED_EXTENSIONS:
+                return
+
+            nonlocal debounce_timer
+            with lock:
+                if debounce_timer is not None:
+                    debounce_timer.cancel()
+                debounce_timer = threading.Timer(1.5, _do_rescan)
+                debounce_timer.daemon = True
+                debounce_timer.start()
+
+    observer = Observer()
+    observer.schedule(_Handler(), str(target_path), recursive=True)
+    observer.start()
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        click.echo(f"\n{Fore.YELLOW}Stopped watching.{Style.RESET_ALL}")
+    finally:
+        observer.stop()
+        observer.join()
+
+
+def _watch_with_polling(
+    target_path: Path,
+    ignore: Sequence[str],
+    min_severity: str,
+    output: str | None,
+    fmt: str,
+) -> None:
+    from .scanner import iter_source_files
+
+    click.echo(
+        f"{Fore.YELLOW}(watchdog not installed - using polling, "
+        f"install watchdog for better performance){Style.RESET_ALL}\n"
+    )
+
+    def _snapshot() -> dict[str, float]:
+        result: dict[str, float] = {}
+        for fp in iter_source_files(str(target_path), ignore_dirs=ignore):
+            try:
+                result[fp] = os.path.getmtime(fp)
+            except OSError:
+                pass
+        return result
+
+    prev = _snapshot()
+
+    try:
+        while True:
+            time.sleep(3)
+            current = _snapshot()
+            if current != prev:
+                prev = current
+                click.echo(
+                    f"\n{Fore.CYAN}Change detected - rescanning...{Style.RESET_ALL}\n"
+                )
+                try:
+                    _run_scan(
+                        target=str(target_path),
+                        ignore=ignore,
+                        min_severity=min_severity.upper(),
+                        output=output,
+                        fmt=fmt,
+                    )
+                except click.ClickException as exc:
+                    click.echo(f"{Fore.RED}Error: {exc.message}{Style.RESET_ALL}")
+    except KeyboardInterrupt:
+        click.echo(f"\n{Fore.YELLOW}Stopped watching.{Style.RESET_ALL}")
+
+
+if __name__ == "__main__":
+    main()

debtscanner-0.2.0/debtscanner/prompts.py

@@ -0,0 +1,17 @@
+SCAN_PROMPT = """You are a senior code reviewer. Analyze this code for technical 
+debt. For each issue found, output EXACTLY in this format:
+SEVERITY: [CRITICAL/HIGH/MEDIUM/LOW]
+FILE: [filename]
+LINE: [line number]
+ISSUE: [one line description]
+FIX: [one line suggested fix]
+---
+Be specific. Only report real issues. Maximum 10 issues per file."""
+
+FIX_PROMPT = """You are a senior developer. Given this code, show me exactly 
+how to fix the most critical technical debt issues.
+For each fix show:
+BEFORE: [the problematic code]
+AFTER: [the fixed code]
+WHY: [one line explanation]
+Maximum 3 fixes. Be specific and actionable."""