debtpilot 0.1.0__py3-none-any.whl

debtpilot-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: debtpilot
+Version: 0.1.0
+Summary: Track technical debt before it blows up in production
+License: MIT
+Project-URL: Homepage, https://github.com/YOUR_GITHUB_USERNAME/debtpilot
+Project-URL: Issues, https://github.com/YOUR_GITHUB_USERNAME/debtpilot/issues
+Keywords: technical-debt,code-quality,developer-tools,cli,linting
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: rich>=13.0
+Provides-Extra: daemon
+Requires-Dist: websockets>=12.0; extra == "daemon"
+Requires-Dist: watchdog>=4.0; extra == "daemon"
+Provides-Extra: notify
+Requires-Dist: win10toast>=0.9; platform_system == "Windows" and extra == "notify"
+Requires-Dist: plyer>=2.1; extra == "notify"
+Provides-Extra: full
+Requires-Dist: debtpilot[daemon,notify]; extra == "full"
+
+#  DebtPilot
+
+> Track technical debt before it blows up in production.
+
+Every IDE catches syntax errors. DebtPilot does something no IDE can —
+it knows that `payments/stripe.js` has been edited 30 times by 4 different
+developers, has a TODO from 8 months ago, and a complexity score of 24.
+That combination is your next production incident.
+
+---
+
+## Install
+
+pip install debtpilot
+
+Full install (file watcher + live notifications):
+
+pip install "debtpilot[full]"
+
+---
+
+## Quickstart — 4 commands, done
+
+1. Scan your project
+debtpilot scan .
+
+2. See the report
+debtpilot report
+
+3. Block bad commits automatically
+debtpilot hook --install
+
+4. Start live background watching
+debtpilot start --dir .
+
+---
+
+## What it does
+
+| Command | What happens |
+|---|---|
+| `debtpilot scan .` | Scores every file 0-100 for technical debt |
+| `debtpilot report` | Shows top debt files in a ranked table |
+| `debtpilot file <path>` | Deep breakdown of one file |
+| `debtpilot ai <path>` | AI explains exactly what to fix (needs Gemini key) |
+| `debtpilot predict` | Predicts which file will cause your next bug |
+| `debtpilot dashboard` | Generates an HTML dashboard — open in browser |
+| `debtpilot report-pdf` | Generates a print-ready PDF report |
+| `debtpilot alerts` | Shows active danger alerts |
+| `debtpilot todos` | Lists stale TODOs by age |
+| `debtpilot hook --install` | Blocks commits above the debt threshold |
+| `debtpilot start` | Starts live file watcher + WebSocket server |
+| `debtpilot status` | Full health check of your DebtPilot setup |
+| `debtpilot digest --send` | Sends weekly email summary to your team |
+
+---
+
+## Debt Score (0-100)
+
+| Grade | Score | Meaning |
+|-------|-------|---------|
+| A | 0-25 | Healthy |
+| B | 26-45 | Watch |
+| C | 46-65 | Concerning |
+| D | 66-80 | Dangerous |
+| F | 81-100 | Critical — fix before next deploy |
+
+Score = weighted combination of: git churn (30%) + complexity (25%) +
+lint issues (20%) + stale TODOs (15%) + staleness (10%).
+
+---
+
+## AI Fix Suggestions (optional)
+
+Get a free Gemini API key at aistudio.google.com then:
+
+debtpilot config --gemini-key YOUR_KEY
+debtpilot ai src/payments.py
+
+DebtPilot sends the file context to Gemini and gets back exact fix
+suggestions with code examples and effort estimates.
+
+---
+
+## Weekly Email Digest
+
+debtpilot config --gmail you@gmail.com --gmail-password YOUR_APP_PASS --recipients team@company.com
+debtpilot digest --send
+
+Use a Gmail App Password from: myaccount.google.com/apppasswords
+
+---
+
+## Auto-start on Windows login
+
+debtpilot autostart --install --dir .
+
+DebtPilot will start silently in the background every time Windows starts.
+No manual debtpilot start needed.
+
+---
+
+## Requirements
+
+- Python 3.10 or higher
+- git in PATH
+- pylint / mypy / eslint — optional, for richer lint scores
+
+---
+
+## License
+
+MIT

debtpilot-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+debtpilot_core/__init__.py,sha256=7MH_x0z0JSLcdSAxEfT2-UMCNUfGl5Hm3jFbmtTTcpw,129
+debtpilot_core/ai_advisor.py,sha256=MBrmwIXDY4iclAXQyK-tSu2YL3ygUa0KT3qL6GRzO5E,6813
+debtpilot_core/autostart.py,sha256=06X-waesS_7GM1HoHkW_7XGHJ_M3ic1sF0K0M--D-18,8934
+debtpilot_core/cli.py,sha256=4UjYThoFz1PH1-Y2hR2zgh5Sji88LRzfWRXR2pTIpyU,26874
+debtpilot_core/daemon.py,sha256=T40hRan2ONQKQKEYslDoNGFyK010wO8gPXNt-2deIDM,9300
+debtpilot_core/dashboard.py,sha256=j9m2fGWRSF6bPhe4KGVZSQR9KQh99AiPkIp6rhoQu5o,11944
+debtpilot_core/database.py,sha256=jWAH9p2TtkcYGphK24ra2J72hiZaQT0RO0fcNnpAl6Q,9322
+debtpilot_core/digest.py,sha256=B_CIQf-CyOgBhKV_RDg4nt8pJgwBfe8KJzRFTt4FDo8,9865
+debtpilot_core/hooks.py,sha256=2Fcro5AopZWMKFno11MJfgrWHyWRJ6Gs1YX9E2vY-I8,5169
+debtpilot_core/linter.py,sha256=SntpTxopFEmnXNGU4Ktkdcrr8n7Ey5XbXA2Jf421EwI,4871
+debtpilot_core/notifier.py,sha256=CgmeKxa3ZVW9H0rD22wGn_e_4--j7vVLG0vdhv7_qKs,7979
+debtpilot_core/predictor.py,sha256=Eo5bEmQgi0sKVj4rKPC4XcRGYLAfNlsgM2Ql6aB2mr4,7828
+debtpilot_core/reporter.py,sha256=_nFYq6jdYdKeDpnzyHxbndcXjjXjfQwoRgQGuPf5fEE,8590
+debtpilot_core/scanner.py,sha256=qoXYw9xrk8NDDAWDi2xPJebjFEUu1Zt1AO3MMNwQIko,6541
+debtpilot_core/scorer.py,sha256=7heZFLW-u-P4S00obpPjy9zw_erDY2ZjnBIS9ZExoXo,4321
+debtpilot-0.1.0.dist-info/METADATA,sha256=lrjRqwz1iVsFmhu4MYlo7Y5cXk_6Wbvabi0OSIlSDhM,4240
+debtpilot-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+debtpilot-0.1.0.dist-info/entry_points.txt,sha256=aVse1t0vJT44p9SxUH8IlTqTi66qQQvvT-jVtld1d1M,54
+debtpilot-0.1.0.dist-info/top_level.txt,sha256=sJNOnUKGzPh8dq_N45_RGTlrPafldV3W1Aw8IMInsgU,15
+debtpilot-0.1.0.dist-info/RECORD,,

debtpilot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

debtpilot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+debtpilot = debtpilot_core.cli:main

debtpilot-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+debtpilot_core

debtpilot_core/__init__.py

@@ -0,0 +1,6 @@
+"""
+DebtPilot — Track technical debt before it blows up in production.
+"""
+
+__version__ = "0.1.0"
+__author__ = "DebtPilot"

debtpilot_core/ai_advisor.py

@@ -0,0 +1,206 @@
+"""
+DebtPilot - AI Fix Suggestions using Google Gemini (free API).
+Sends risky code to Gemini and gets back exact fix suggestions.
+"""
+
+import os
+import json
+import urllib.request
+import urllib.error
+from pathlib import Path
+from typing import Dict, List, Optional
+
+GEMINI_API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent"
+
+
+def get_api_key() -> Optional[str]:
+    # First check environment variable
+    key = os.environ.get("DEBTPILOT_GEMINI_KEY")
+    if key:
+        return key
+    # Then check config file
+    config_path = Path.home() / ".debtpilot" / "config.json"
+    if config_path.exists():
+        try:
+            data = json.loads(config_path.read_text())
+            return data.get("gemini_api_key")
+        except Exception:
+            pass
+    return None
+
+
+def save_api_key(api_key: str) -> None:
+    config_dir = Path.home() / ".debtpilot"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    config_path = config_dir / "config.json"
+    data = {}
+    if config_path.exists():
+        try:
+            data = json.loads(config_path.read_text())
+        except Exception:
+            pass
+    data["gemini_api_key"] = api_key
+    config_path.write_text(json.dumps(data, indent=2))
+
+
+def _call_gemini(prompt: str, api_key: str) -> str:
+    payload = json.dumps({
+        "contents": [{"parts": [{"text": prompt}]}],
+        "generationConfig": {"temperature": 0.3, "maxOutputTokens": 1500}
+    }).encode()
+
+    req = urllib.request.Request(
+        f"{GEMINI_API_URL}?key={api_key}",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            result = json.loads(r.read())
+            return result["candidates"][0]["content"]["parts"][0]["text"]
+    except urllib.error.HTTPError as e:
+        body = e.read().decode()
+        raise RuntimeError(f"Gemini API error {e.code}: {body}")
+    except Exception as e:
+        raise RuntimeError(f"Failed to call Gemini: {e}")
+
+
+def analyze_file(
+    filepath: str,
+    score_data: Dict,
+    lint_issues: List[Dict],
+    todos: List[Dict],
+    complexity: Dict,
+) -> Dict:
+    """
+    Send file context to Gemini and get back structured fix suggestions.
+    Returns dict with summary, fixes, and priority actions.
+    """
+    api_key = get_api_key()
+    if not api_key:
+        return {
+            "error": "No Gemini API key configured. Run: debtpilot config --gemini-key YOUR_KEY",
+            "summary": "AI advisor not configured. The rest of DebtPilot works without it.",
+            "fixes": [],
+            "priority_actions": ["Run: debtpilot config --gemini-key YOUR_KEY to enable AI suggestions"],
+            "risk_level": "UNKNOWN",
+            "estimated_fix_time": "N/A",
+            "ai_available": False,
+        }
+
+    # Read file content (first 150 lines to stay within token limits)
+    try:
+        lines = Path(filepath).read_text(encoding="utf-8", errors="ignore").splitlines()
+        code_preview = "\n".join(lines[:150])
+        total_lines = len(lines)
+    except OSError:
+        code_preview = "(could not read file)"
+        total_lines = 0
+
+    # Build lint summary
+    errors = [i for i in lint_issues if i.get("severity") == "error"][:5]
+    warnings = [i for i in lint_issues if i.get("severity") == "warning"][:5]
+    lint_summary = "\n".join(
+        [f"  ERROR L{i['line']}: {i['message']}" for i in errors] +
+        [f"  WARNING L{i['line']}: {i['message']}" for i in warnings]
+    ) or "  None detected"
+
+    # Build TODO summary
+    todo_summary = "\n".join(
+        [f"  L{t['line']} ({t.get('age_days', 0)} days old): {t.get('text', '')}" for t in todos[:5]]
+    ) or "  None"
+
+    # Build complexity summary
+    funcs = complexity.get("functions", [])[:5]
+    complexity_summary = "\n".join(
+        [f"  {f['name']}() at L{f['line']}: complexity {f['complexity']}" for f in funcs]
+    ) or f"  avg={complexity.get('avg_complexity', 0)}"
+
+    prompt = f"""You are a senior software engineer doing a technical debt review.
+
+FILE: {filepath}
+TOTAL LINES: {total_lines}
+DEBT SCORE: {score_data.get('total', 0)}/100 (Grade {score_data.get('grade', '?')} — {score_data.get('label', '')})
+
+SUB-SCORES:
+  Churn (how often edited by many people): {score_data.get('churn_score', 0)}/100
+  Complexity (how hard to understand): {score_data.get('complexity_score', 0)}/100
+  Lint issues: {score_data.get('lint_score', 0)}/100
+  Stale TODOs: {score_data.get('todo_score', 0)}/100
+  Staleness: {score_data.get('staleness_score', 0)}/100
+
+LINT ISSUES:
+{lint_summary}
+
+STALE TODOs:
+{todo_summary}
+
+COMPLEX FUNCTIONS:
+{complexity_summary}
+
+CODE PREVIEW (first 150 lines):
+{code_preview}
+
+Respond ONLY with a valid JSON object in this exact format, no markdown, no explanation outside the JSON:
+{{
+  "summary": "2-3 sentence plain English summary of the main problems",
+  "risk_level": "LOW or MEDIUM or HIGH or CRITICAL",
+  "fixes": [
+    {{
+      "title": "short title of the fix",
+      "problem": "what is wrong and why it matters",
+      "solution": "exactly what to do",
+      "code_example": "short before/after code snippet if relevant, else empty string",
+      "effort": "15min or 1hr or half-day or 1day"
+    }}
+  ],
+  "priority_actions": [
+    "action 1 — most important thing to do first",
+    "action 2",
+    "action 3"
+  ],
+  "estimated_fix_time": "total estimated time to resolve all issues"
+}}"""
+
+    raw = _call_gemini(prompt, api_key)
+
+    # Strip markdown code fences if present
+    raw = raw.strip()
+    if raw.startswith("```"):
+        raw = raw.split("```")[1]
+        if raw.startswith("json"):
+            raw = raw[4:]
+    raw = raw.strip()
+
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return {
+            "summary": raw[:500],
+            "risk_level": "UNKNOWN",
+            "fixes": [],
+            "priority_actions": [],
+            "estimated_fix_time": "unknown",
+            "parse_error": True,
+        }
+
+
+def quick_explain(code_snippet: str, question: str) -> str:
+    """Ask Gemini a quick question about a code snippet."""
+    api_key = get_api_key()
+    if not api_key:
+        return "No Gemini API key configured. Run: debtpilot config --gemini-key YOUR_KEY"
+
+    prompt = f"""You are a helpful senior developer. Answer concisely.
+
+Question: {question}
+
+Code:{code_snippet[:1000]}
+
+Give a direct, practical answer in 3-5 sentences maximum."""
+
+    try:
+        return _call_gemini(prompt, api_key)
+    except RuntimeError as e:
+        return f"AI error: {e}"

debtpilot_core/autostart.py

@@ -0,0 +1,255 @@
+"""
+DebtPilot - Windows Auto-startup Manager.
+Registers DebtPilot daemon with Windows Task Scheduler so it starts
+automatically on login — no manual 'debtpilot start' ever needed again.
+"""
+
+import os
+import sys
+import json
+import subprocess
+from pathlib import Path
+from typing import Dict, Optional
+
+
+TASK_NAME = "DebtPilotDaemon"
+CONFIG_PATH = Path.home() / ".debtpilot" / "config.json"
+
+
+def _get_config() -> Dict:
+    if CONFIG_PATH.exists():
+        try:
+            return json.loads(CONFIG_PATH.read_text())
+        except Exception:
+            pass
+    return {}
+
+
+def _save_config(data: Dict) -> None:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    existing = _get_config()
+    existing.update(data)
+    CONFIG_PATH.write_text(json.dumps(existing, indent=2))
+
+
+def _get_python_path() -> str:
+    return sys.executable
+
+
+def _get_debtpilot_path() -> Optional[str]:
+    """Find the debtpilot CLI script path."""
+    import shutil
+    path = shutil.which("debtpilot")
+    if path:
+        return path
+    # Fallback: construct from Python path
+    scripts = Path(sys.executable).parent / "Scripts" / "debtpilot.exe"
+    if scripts.exists():
+        return str(scripts)
+    return None
+
+
+def _get_project_dir() -> str:
+    config = _get_config()
+    return config.get("watched_project", str(Path.home()))
+
+
+# ── Windows Task Scheduler ───────────────────────────────────────────────────
+
+def _create_task_xml(python_path: str, project_dir: str, port: int) -> str:
+    """Generate the XML for Windows Task Scheduler."""
+    debtpilot = _get_debtpilot_path() or f"{Path(python_path).parent}\\Scripts\\debtpilot.exe"
+
+    return f"""<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>DebtPilot — Live technical debt monitoring daemon</Description>
+    <Author>DebtPilot</Author>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>{debtpilot}</Command>
+      <Arguments>start --dir "{project_dir}" --port {port}</Arguments>
+      <WorkingDirectory>{project_dir}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>"""
+
+
+def install_autostart(project_dir: Optional[str] = None, port: int = 57017) -> Dict:
+    """
+    Register DebtPilot with Windows Task Scheduler.
+    Runs automatically on every login.
+    """
+    if sys.platform != "win32":
+        return {
+            "success": False,
+            "error": "Autostart is currently Windows-only. On Mac/Linux, add 'debtpilot start' to your shell profile."
+        }
+
+    project_dir = project_dir or str(Path.cwd())
+    python_path = _get_python_path()
+
+    # Save project dir to config
+    _save_config({"watched_project": project_dir, "daemon_port": port})
+
+    # Write the task XML to a temp file
+    xml_content = _create_task_xml(python_path, project_dir, port)
+    xml_path = Path.home() / ".debtpilot" / "task.xml"
+    xml_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        xml_path.write_text(xml_content, encoding="utf-16")
+    except Exception as e:
+        return {"success": False, "error": f"Could not write task file: {e}"}
+
+    # Register with schtasks
+    try:
+        result = subprocess.run(
+            ["schtasks", "/Create", "/TN", TASK_NAME,
+             "/XML", str(xml_path), "/F"],
+            capture_output=True, text=True, timeout=30
+        )
+        if result.returncode == 0:
+            _save_config({"autostart": True})
+            return {
+                "success": True,
+                "message": (
+                    f"✅ DebtPilot will now start automatically on every login.\n"
+                    f"   Watching: {project_dir}\n"
+                    f"   Port: {port}\n"
+                    f"   Task name: {TASK_NAME}"
+                ),
+                "project_dir": project_dir,
+                "port": port,
+            }
+        else:
+            # Try running as admin via PowerShell elevation
+            return _install_with_elevation(xml_path, project_dir, port)
+    except FileNotFoundError:
+        return {"success": False, "error": "schtasks not found. Are you on Windows?"}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def _install_with_elevation(xml_path: Path, project_dir: str, port: int) -> Dict:
+    """Try to install task with admin elevation via PowerShell."""
+    try:
+        ps_command = (
+            f'Start-Process schtasks -ArgumentList '
+            f'"/Create /TN {TASK_NAME} /XML `"{xml_path}`" /F" '
+            f'-Verb RunAs -Wait'
+        )
+        result = subprocess.run(
+            ["powershell", "-Command", ps_command],
+            capture_output=True, text=True, timeout=30
+        )
+        if result.returncode == 0:
+            _save_config({"autostart": True})
+            return {
+                "success": True,
+                "message": (
+                    f"✅ Autostart installed with admin rights.\n"
+                    f"   Watching: {project_dir}"
+                ),
+            }
+        else:
+            return {
+                "success": False,
+                "error": (
+                    "Could not register with Task Scheduler.\n"
+                    "Try running your terminal as Administrator and retry:\n"
+                    "  debtpilot autostart --install"
+                )
+            }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def uninstall_autostart() -> Dict:
+    """Remove DebtPilot from Windows Task Scheduler."""
+    if sys.platform != "win32":
+        return {"success": False, "error": "Not on Windows"}
+
+    try:
+        result = subprocess.run(
+            ["schtasks", "/Delete", "/TN", TASK_NAME, "/F"],
+            capture_output=True, text=True, timeout=15
+        )
+        if result.returncode == 0:
+            _save_config({"autostart": False})
+            return {"success": True, "message": "✅ DebtPilot autostart removed."}
+        else:
+            return {"success": False, "error": "Task not found or could not be removed."}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def autostart_status() -> Dict:
+    """Check if autostart is registered."""
+    if sys.platform != "win32":
+        return {"installed": False, "platform": sys.platform}
+
+    try:
+        result = subprocess.run(
+            ["schtasks", "/Query", "/TN", TASK_NAME, "/FO", "LIST"],
+            capture_output=True, text=True, timeout=10
+        )
+        if result.returncode == 0:
+            config = _get_config()
+            # Parse next run time from output
+            next_run = ""
+            for line in result.stdout.splitlines():
+                if "Next Run Time" in line:
+                    next_run = line.split(":", 1)[-1].strip()
+            return {
+                "installed": True,
+                "task_name": TASK_NAME,
+                "project_dir": config.get("watched_project", "unknown"),
+                "port": config.get("daemon_port", 57017),
+                "next_run": next_run,
+            }
+        else:
+            return {"installed": False}
+    except Exception as e:
+        return {"installed": False, "error": str(e)}
+
+
+def run_now(project_dir: Optional[str] = None, port: int = 57017) -> Dict:
+    """Start the task immediately via Task Scheduler."""
+    if sys.platform != "win32":
+        return {"success": False, "error": "Not on Windows"}
+    try:
+        result = subprocess.run(
+            ["schtasks", "/Run", "/TN", TASK_NAME],
+            capture_output=True, text=True, timeout=10
+        )
+        return {
+            "success": result.returncode == 0,
+            "message": "Daemon started." if result.returncode == 0 else result.stderr
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def set_watched_project(project_dir: str) -> None:
+    """Update which project directory the daemon watches."""
+    _save_config({"watched_project": str(Path(project_dir).resolve())})