python-doctor 0.1.0__tar.gz

python_doctor-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

python_doctor-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v

python_doctor-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/

python_doctor-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.2.0 (2026-02-18)
+
+### Added
+- 4 new analyzers: dependencies, docstrings, imports, exceptions
+- Enhanced structure checks: test-to-source ratio, README, LICENSE, .gitignore, linter config, type checker config, py.typed
+- Bandit B101 (assert) auto-filtered in test files
+- Tests (22 tests via pytest)
+- CI: health check on every push, tests across Python 3.10-3.13
+- PyPI publishing via Trusted Publishers
+
+### Changed
+- Score is now `max(0, 100 - total_deductions)` — categories keep their own maxes
+- All high-complexity functions refactored (CC 27 → <10)
+- Docstrings added to all public functions/classes
+
+## 0.1.0 (2026-02-18)
+
+### Added
+- Initial release with 5 analyzers: security (Bandit), lint (Ruff), dead code (Vulture), complexity (Radon), structure
+- CLI with `--verbose`, `--score`, `--json`, `--fix` flags
+- Exit code 1 if score < 50

python_doctor-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Thanks for your interest in python-doctor!
+
+## Quick Start
+
+```bash
+git clone https://github.com/saikatkumardey/python-doctor.git
+cd python-doctor
+uv sync --extra dev
+uv run pytest tests/ -v
+uv run python-doctor .
+```
+
+## Adding a New Analyzer
+
+1. Create `python_doctor/analyzers/your_analyzer.py`
+2. Implement `analyze(path: str, **kw) -> AnalyzerResult`
+3. Add the category to `rules.py` `CATEGORIES` dict
+4. Register it in `cli.py` `ANALYZERS` list
+5. Add tests in `tests/test_your_analyzer.py`
+6. Run `python-doctor .` — the score should still be 80+
+
+Every analyzer follows the same pattern: scan the codebase, produce `Finding` objects, cap the deduction at the category max.
+
+## Running Tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+## Code Quality
+
+We dogfood python-doctor on itself. The CI runs it on every push and fails if the score drops below 50.
+
+```bash
+uv run python-doctor . --verbose
+```
+
+## Releases
+
+Tags trigger PyPI + ClawHub publishing via CI. Don't publish manually.
+
+```bash
+# Bump version in pyproject.toml and __init__.py
+git tag v0.3.0
+git push origin v0.3.0
+```

python_doctor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saikat Kumar Dey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_doctor-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: python-doctor
+Version: 0.1.0
+Summary: One command. One score. Built for AI agents. Scans Python codebases and returns a 0-100 health score.
+Project-URL: Homepage, https://github.com/saikatkumardey/python-doctor
+Project-URL: Repository, https://github.com/saikatkumardey/python-doctor
+Project-URL: Issues, https://github.com/saikatkumardey/python-doctor/issues
+Project-URL: Changelog, https://github.com/saikatkumardey/python-doctor/blob/main/CHANGELOG.md
+Author-email: Saikat Kumar Dey <deysaikatkumar@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,code-quality,developer-tools,linting,python,static-analysis
+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
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: bandit>=1.7.0
+Requires-Dist: radon>=6.0.0
+Requires-Dist: ruff>=0.4.0
+Requires-Dist: vulture>=2.11
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Python Doctor 🐍
+
+[![Tests](https://github.com/saikatkumardey/python-doctor/actions/workflows/test.yml/badge.svg)](https://github.com/saikatkumardey/python-doctor/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/python-doctor)](https://pypi.org/project/python-doctor/)
+[![Python](https://img.shields.io/pypi/pyversions/python-doctor)](https://pypi.org/project/python-doctor/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**One command. One score. Built for AI agents.**
+
+Python Doctor scans a Python codebase and returns a 0-100 health score with structured, actionable output. It's designed so an AI agent can run it, read the results, fix the issues, and verify the fix — in a loop, without human intervention.
+
+```bash
+python-doctor .
+# 📊 Score: 98/100 (Excellent)
+```
+
+## Why?
+
+Setting up linting, security scanning, dead code detection, and complexity analysis means configuring 5+ tools, reading 5 different output formats, and deciding what matters. Python Doctor wraps them all into a single command with a single score.
+
+An agent doesn't need to know what Bandit is. It just needs to know the score dropped and which lines to fix.
+
+## Install the CLI
+
+```bash
+# Using uv (recommended)
+uv tool install git+https://github.com/saikatkumardey/python-doctor
+
+# Using pip
+pip install git+https://github.com/saikatkumardey/python-doctor
+
+# Or clone and run directly
+git clone https://github.com/saikatkumardey/python-doctor.git
+cd python-doctor
+uv run python-doctor /path/to/project
+```
+
+## Add to Your Coding Agent
+
+Python Doctor works with any agent that can run shell commands. Install the CLI (above), then add the rule to your agent:
+
+### Claude Code
+
+Add to your `CLAUDE.md`:
+
+```markdown
+## Python Health Check
+
+Before finishing work on Python files, run:
+  python-doctor . --json
+
+Fix any findings with severity "error". Target score: 80+.
+If score drops below 50, do not commit — fix the issues first.
+```
+
+### Cursor
+
+Add to `.cursor/rules/python-doctor.mdc`:
+
+```markdown
+---
+description: Python codebase health check
+globs: "**/*.py"
+alwaysApply: false
+---
+
+Run `python-doctor . --json` after modifying Python files.
+Fix findings. Target score: 80+. Do not commit below 50.
+```
+
+### OpenAI Codex
+
+Add to `AGENTS.md`:
+
+```markdown
+## Python Health Check
+
+After modifying Python files, run `python-doctor . --json` to check codebase health.
+Fix any findings. Target score: 80+. Exit code 1 means score < 50 — fix before committing.
+```
+
+### Windsurf / Cline / Aider
+
+Add to your project rules or system prompt:
+
+```
+After modifying Python files, run: python-doctor . --json
+Read the output. Fix findings with severity "error" first, then warnings.
+Re-run to verify the score improved. Target: 80+.
+```
+
+### OpenClaw
+
+```bash
+clawhub install python-doctor
+```
+
+### GitHub Actions (CI)
+
+```yaml
+- name: Health Check
+  run: |
+    uv tool install git+https://github.com/saikatkumardey/python-doctor
+    python-doctor . --verbose
+```
+
+Exits with code 1 if score < 50.
+
+## Usage
+
+```bash
+# Scan current directory
+python-doctor .
+
+# Verbose — show all findings with line numbers
+python-doctor . --verbose
+
+# Just the score (for CI or quick checks)
+python-doctor . --score
+
+# Structured JSON for agents
+python-doctor . --json
+
+# Auto-fix what Ruff can handle, then report the rest
+python-doctor . --fix
+```
+
+## What It Checks
+
+9 categories, 5 external tools + 4 custom AST analyzers:
+
+| Category | Max | What |
+|----------|-----|------|
+| 🔒 Security | -30 | Bandit (SQLi, hardcoded secrets, unsafe calls). Auto-skips `assert` in test files. |
+| 🧹 Lint | -25 | Ruff (unused imports, undefined names, style) |
+| 💀 Dead Code | -15 | Vulture (unused functions, variables, imports) |
+| 🔄 Complexity | -15 | Radon (cyclomatic complexity > 10) |
+| 🏗 Structure | -15 | File sizes, test ratio, type hints, README, LICENSE, linter/type-checker config |
+| 📦 Dependencies | -15 | Build file exists, no mixed systems, pip-audit vulnerabilities |
+| 📝 Docstrings | -10 | Public function/class docstring coverage |
+| 🔗 Imports | -10 | Star imports, circular import detection |
+| ⚡ Exceptions | -10 | Bare `except:`, silently swallowed exceptions |
+
+Score = `max(0, 100 - total_deductions)`. Each category is capped at its max.
+
+## The Loop
+
+This is how an agent uses it:
+
+1. `python-doctor . --json` → read the report
+2. Fix the findings (auto-fix with `--fix`, manual fixes for the rest)
+3. `python-doctor . --score` → verify improvement
+4. Repeat until score target met
+
+We built Python Doctor, then ran it on itself. Score: 47. Fixed everything it flagged. Score: 98. The tool eats its own dogfood.
+
+## License
+
+MIT — Saikat Kumar Dey, 2026

python_doctor-0.1.0/README.md

@@ -0,0 +1,159 @@
+# Python Doctor 🐍
+
+[![Tests](https://github.com/saikatkumardey/python-doctor/actions/workflows/test.yml/badge.svg)](https://github.com/saikatkumardey/python-doctor/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/python-doctor)](https://pypi.org/project/python-doctor/)
+[![Python](https://img.shields.io/pypi/pyversions/python-doctor)](https://pypi.org/project/python-doctor/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**One command. One score. Built for AI agents.**
+
+Python Doctor scans a Python codebase and returns a 0-100 health score with structured, actionable output. It's designed so an AI agent can run it, read the results, fix the issues, and verify the fix — in a loop, without human intervention.
+
+```bash
+python-doctor .
+# 📊 Score: 98/100 (Excellent)
+```
+
+## Why?
+
+Setting up linting, security scanning, dead code detection, and complexity analysis means configuring 5+ tools, reading 5 different output formats, and deciding what matters. Python Doctor wraps them all into a single command with a single score.
+
+An agent doesn't need to know what Bandit is. It just needs to know the score dropped and which lines to fix.
+
+## Install the CLI
+
+```bash
+# Using uv (recommended)
+uv tool install git+https://github.com/saikatkumardey/python-doctor
+
+# Using pip
+pip install git+https://github.com/saikatkumardey/python-doctor
+
+# Or clone and run directly
+git clone https://github.com/saikatkumardey/python-doctor.git
+cd python-doctor
+uv run python-doctor /path/to/project
+```
+
+## Add to Your Coding Agent
+
+Python Doctor works with any agent that can run shell commands. Install the CLI (above), then add the rule to your agent:
+
+### Claude Code
+
+Add to your `CLAUDE.md`:
+
+```markdown
+## Python Health Check
+
+Before finishing work on Python files, run:
+  python-doctor . --json
+
+Fix any findings with severity "error". Target score: 80+.
+If score drops below 50, do not commit — fix the issues first.
+```
+
+### Cursor
+
+Add to `.cursor/rules/python-doctor.mdc`:
+
+```markdown
+---
+description: Python codebase health check
+globs: "**/*.py"
+alwaysApply: false
+---
+
+Run `python-doctor . --json` after modifying Python files.
+Fix findings. Target score: 80+. Do not commit below 50.
+```
+
+### OpenAI Codex
+
+Add to `AGENTS.md`:
+
+```markdown
+## Python Health Check
+
+After modifying Python files, run `python-doctor . --json` to check codebase health.
+Fix any findings. Target score: 80+. Exit code 1 means score < 50 — fix before committing.
+```
+
+### Windsurf / Cline / Aider
+
+Add to your project rules or system prompt:
+
+```
+After modifying Python files, run: python-doctor . --json
+Read the output. Fix findings with severity "error" first, then warnings.
+Re-run to verify the score improved. Target: 80+.
+```
+
+### OpenClaw
+
+```bash
+clawhub install python-doctor
+```
+
+### GitHub Actions (CI)
+
+```yaml
+- name: Health Check
+  run: |
+    uv tool install git+https://github.com/saikatkumardey/python-doctor
+    python-doctor . --verbose
+```
+
+Exits with code 1 if score < 50.
+
+## Usage
+
+```bash
+# Scan current directory
+python-doctor .
+
+# Verbose — show all findings with line numbers
+python-doctor . --verbose
+
+# Just the score (for CI or quick checks)
+python-doctor . --score
+
+# Structured JSON for agents
+python-doctor . --json
+
+# Auto-fix what Ruff can handle, then report the rest
+python-doctor . --fix
+```
+
+## What It Checks
+
+9 categories, 5 external tools + 4 custom AST analyzers:
+
+| Category | Max | What |
+|----------|-----|------|
+| 🔒 Security | -30 | Bandit (SQLi, hardcoded secrets, unsafe calls). Auto-skips `assert` in test files. |
+| 🧹 Lint | -25 | Ruff (unused imports, undefined names, style) |
+| 💀 Dead Code | -15 | Vulture (unused functions, variables, imports) |
+| 🔄 Complexity | -15 | Radon (cyclomatic complexity > 10) |
+| 🏗 Structure | -15 | File sizes, test ratio, type hints, README, LICENSE, linter/type-checker config |
+| 📦 Dependencies | -15 | Build file exists, no mixed systems, pip-audit vulnerabilities |
+| 📝 Docstrings | -10 | Public function/class docstring coverage |
+| 🔗 Imports | -10 | Star imports, circular import detection |
+| ⚡ Exceptions | -10 | Bare `except:`, silently swallowed exceptions |
+
+Score = `max(0, 100 - total_deductions)`. Each category is capped at its max.
+
+## The Loop
+
+This is how an agent uses it:
+
+1. `python-doctor . --json` → read the report
+2. Fix the findings (auto-fix with `--fix`, manual fixes for the rest)
+3. `python-doctor . --score` → verify improvement
+4. Repeat until score target met
+
+We built Python Doctor, then ran it on itself. Score: 47. Fixed everything it flagged. Score: 98. The tool eats its own dogfood.
+
+## License
+
+MIT — Saikat Kumar Dey, 2026

python_doctor-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "python-doctor"
+version = "0.1.0"
+description = "One command. One score. Built for AI agents. Scans Python codebases and returns a 0-100 health score."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Saikat Kumar Dey", email = "deysaikatkumar@gmail.com"},
+]
+keywords = ["python", "linting", "code-quality", "ai-agents", "static-analysis", "developer-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "ruff>=0.4.0",
+    "bandit>=1.7.0",
+    "vulture>=2.11",
+    "radon>=6.0.0",
+]
+
+[project.scripts]
+python-doctor = "python_doctor.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/saikatkumardey/python-doctor"
+Repository = "https://github.com/saikatkumardey/python-doctor"
+Issues = "https://github.com/saikatkumardey/python-doctor/issues"
+Changelog = "https://github.com/saikatkumardey/python-doctor/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+exclude = [".venv", "venv", "node_modules", "__pycache__", ".git", ".tox"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true

python_doctor-0.1.0/python_doctor/__init__.py

@@ -0,0 +1,3 @@
+"""Python Doctor — health scoring for Python codebases."""
+
+__version__ = "0.2.0"

python_doctor-0.1.0/python_doctor/analyzers/__init__.py

@@ -0,0 +1 @@
+"""Analyzers for Python Doctor."""

python_doctor-0.1.0/python_doctor/analyzers/bandit_analyzer.py

@@ -0,0 +1,62 @@
+"""Bandit security analyzer."""
+
+import json
+import os
+import subprocess  # nosec B404 — required for running CLI tools
+
+from ..rules import BANDIT_SEVERITY_COST, CATEGORIES, AnalyzerResult, Finding
+
+_EXCLUDE_DIRS = [".venv", "venv", "node_modules", "__pycache__", ".git", ".tox", ".mypy_cache", ".ruff_cache"]
+
+
+def _is_test_file(filepath: str) -> bool:
+    """Check if a file is a test file (in test dir or test-named)."""
+    parts = os.path.normpath(filepath).split(os.sep)
+    if any(p in ("tests", "test") for p in parts):
+        return True
+    basename = os.path.basename(filepath)
+    return basename.startswith("test_") or basename.endswith("_test.py")
+
+
+def analyze(path: str, **_kw) -> AnalyzerResult:
+    """Run bandit security analysis on the project."""
+    result = AnalyzerResult(category="security")
+    max_ded = CATEGORIES["security"]["max_deduction"]
+    abs_path = os.path.abspath(path)
+    excludes = ",".join(os.path.join(abs_path, d) for d in _EXCLUDE_DIRS)
+
+    try:
+        proc = subprocess.run(  # nosec B603 B607 — intentional subprocess call to bandit CLI tool
+            ["bandit", "-r", "-f", "json", "-q",
+             "--exclude", excludes,
+             abs_path],
+            capture_output=True, text=True, timeout=120
+        )
+        data = json.loads(proc.stdout) if proc.stdout.strip() else {}
+        items = data.get("results", [])
+    except FileNotFoundError:
+        result.error = "bandit not found (skipped)"
+        return result
+    except Exception as e:
+        result.error = str(e)
+        return result
+
+    for item in items:
+        sev = item.get("issue_severity", "LOW").upper()
+        cost = BANDIT_SEVERITY_COST.get(sev, 1)
+        test_id = item.get("test_id", "?")
+        msg = item.get("issue_text", "")
+        filename = item.get("filename", "")
+        line = item.get("line_number", 0)
+
+        # Skip B101 (assert) in test files
+        if test_id == "B101" and _is_test_file(filename):
+            continue
+
+        result.findings.append(Finding(
+            category="security", rule=f"bandit/{test_id}", message=msg,
+            file=filename, line=line, severity=sev.lower(), cost=cost,
+        ))
+
+    result.deduction = min(sum(f.cost for f in result.findings), max_ded)
+    return result