debtpilot 0.1.0__tar.gz

debtpilot-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,113 @@
+#  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/debtpilot.egg-info/PKG-INFO

@@ -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/debtpilot.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+README.md
+pyproject.toml
+debtpilot.egg-info/PKG-INFO
+debtpilot.egg-info/SOURCES.txt
+debtpilot.egg-info/dependency_links.txt
+debtpilot.egg-info/entry_points.txt
+debtpilot.egg-info/requires.txt
+debtpilot.egg-info/top_level.txt
+debtpilot_core/__init__.py
+debtpilot_core/ai_advisor.py
+debtpilot_core/autostart.py
+debtpilot_core/cli.py
+debtpilot_core/daemon.py
+debtpilot_core/dashboard.py
+debtpilot_core/database.py
+debtpilot_core/digest.py
+debtpilot_core/hooks.py
+debtpilot_core/linter.py
+debtpilot_core/notifier.py
+debtpilot_core/predictor.py
+debtpilot_core/reporter.py
+debtpilot_core/scanner.py
+debtpilot_core/scorer.py

debtpilot-0.1.0/debtpilot.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

debtpilot-0.1.0/debtpilot.egg-info/entry_points.txt

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

debtpilot-0.1.0/debtpilot.egg-info/requires.txt

@@ -0,0 +1,14 @@
+rich>=13.0
+
+[daemon]
+websockets>=12.0
+watchdog>=4.0
+
+[full]
+debtpilot[daemon,notify]
+
+[notify]
+plyer>=2.1
+
+[notify:platform_system == "Windows"]
+win10toast>=0.9

debtpilot-0.1.0/debtpilot.egg-info/top_level.txt

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

debtpilot-0.1.0/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-0.1.0/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}"