pycode-doctor 0.1.0__py3-none-any.whl

pycode_doctor-0.1.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: pycode-doctor
+Version: 0.1.0
+Summary: Fast, local-first CLI that gives your Python codebase a 0-100 health score
+Project-URL: Homepage, https://github.com/nabroleonx/python-doctor
+Project-URL: Documentation, https://nabroleonx.github.io/python-doctor/
+Project-URL: Repository, https://github.com/nabroleonx/python-doctor.git
+Project-URL: Issues, https://github.com/nabroleonx/python-doctor/issues
+Author: Nabeel S. Qureshi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,code-quality,health-check,linting,mcp,python,static-analysis
+Classifier: Development Status :: 3 - Alpha
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: bandit>=1.8
+Requires-Dist: click>=8.1
+Requires-Dist: deptry>=0.14
+Requires-Dist: mypy>=1.13
+Requires-Dist: radon>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: ruff>=0.8.0
+Requires-Dist: vulture>=2.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: basedpyright>=1.38; extra == 'full'
+Requires-Dist: detect-secrets>=1.5; extra == 'full'
+Requires-Dist: httpx>=0.27; extra == 'full'
+Requires-Dist: mcp>=1.0; extra == 'full'
+Requires-Dist: typos>=1.44; extra == 'full'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: pyright
+Requires-Dist: basedpyright>=1.38; extra == 'pyright'
+Provides-Extra: quality-extra
+Requires-Dist: typos>=1.44; extra == 'quality-extra'
+Provides-Extra: secrets
+Requires-Dist: detect-secrets>=1.5; extra == 'secrets'
+Provides-Extra: vulns
+Requires-Dist: httpx>=0.27; extra == 'vulns'
+Description-Content-Type: text/markdown
+
+# python-doctor
+
+Fast, local-first Python code health checks with a single command.
+
+`python-doctor` combines Ruff, mypy, Bandit, Radon, Vulture, and deptry into a
+single 0-100 score with clear category breakdowns. It is designed to feel good
+with `uvx` first.
+
+## Quickstart
+
+Run it with no install step:
+
+```bash
+uvx python-doctor .
+```
+
+Use the latest published version explicitly:
+
+```bash
+uvx python-doctor@latest .
+```
+
+For deeper optional scans:
+
+```bash
+uvx --from 'python-doctor[full]' python-doctor .
+```
+
+Persistent install:
+
+```bash
+uv tool install python-doctor
+```
+
+## What The Default Scan Includes
+
+- Ruff for quality, security, complexity, and dead-code rule families
+- mypy for type checking
+- Bandit for security checks
+- Radon for complexity metrics
+- Vulture for dead code
+- deptry for dependency hygiene
+
+Optional extras add:
+
+- `dependency-vulns` for OSV-backed dependency vulnerability scanning
+- `detect-secrets` for secret scanning
+- `basedpyright` as an optional type backend
+- `typos` for spelling checks in source code
+- MCP support
+
+## Common Commands
+
+```bash
+# fast feedback
+python-doctor . --profile quick
+
+# full default scan
+python-doctor .
+
+# include optional analyzers if installed
+python-doctor . --profile full
+
+# only score output
+python-doctor . --score
+
+# machine-readable output
+python-doctor . --json
+
+# analyze only selected categories
+python-doctor . --only quality,types
+
+# skip categories
+python-doctor . --skip security,dead_code
+
+# safe Ruff autofix, then rescan
+python-doctor . --fix
+
+# show remediation text inline
+python-doctor . --show-fixes
+```
+
+## Why `src/python_doctor/`?
+
+The package is intentionally laid out as `src/python_doctor/`.
+
+- `python-doctor` is the distribution and CLI name
+- `python_doctor` is the Python import package name
+
+The `src/` layout prevents packaging and test mistakes where imports succeed
+from the checkout but fail from the built wheel.
+
+## Configuration
+
+Zero-config by default. Customize in `pyproject.toml`:
+
+```toml
+[tool.python-doctor]
+timeout = 60
+
+[tool.python-doctor.weights]
+quality = 25
+types = 20
+security = 20
+complexity = 15
+dead_code = 10
+dependencies = 10
+
+[tool.python-doctor.ignore]
+rules = ["S101"]
+files = ["tests/**", "migrations/**"]
+```
+
+See `docs/configuration.md` for the full reference.
+
+## MCP Server
+
+Expose health data to AI coding agents (Claude Code, Cursor, VS Code):
+
+```bash
+python-doctor install-mcp cursor
+```
+
+This registers python-doctor as an MCP server. Your AI agent can then call
+tools like `analyze_code`, `explain_rule`, `get_score`, `suggest_fixes`, and
+`check_diff`.
+
+See `docs/mcp-server.md` for details.
+
+## Plugins
+
+Extend python-doctor with custom analyzers via entry points:
+
+```toml
+[project.entry-points."python_doctor.analyzers"]
+my-analyzer = "my_package:MyAnalyzer"
+```
+
+See `docs/plugins.md` for the full guide.
+
+## Output Model
+
+The score covers six categories:
+
+- quality
+- type safety
+- security
+- complexity
+- dead code
+- dependencies
+
+V1 also reports coverage, so a score can tell you whether the scan was full,
+partial, or limited.
+
+## Docs
+
+Kept intentionally small:
+
+- `docs/configuration.md` -- weights, thresholds, ignore rules
+- `docs/scoring.md` -- scoring methodology
+- `docs/mcp-server.md` -- MCP server setup
+- `docs/plugins.md` -- custom analyzer development
+- `docs/development.md` -- contributing to python-doctor
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+```
+
+See `docs/development.md` for the full guide.
+
+## License
+
+MIT

pycode_doctor-0.1.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+python_doctor/__init__.py,sha256=GEmocznJ1GPmdotedvBkb8vb9tqWgtZZPIUArbQDPKw,233
+python_doctor/__main__.py,sha256=TheTVeqS5jM_yHTR8-UDoGF7LZpa-LN9lZhbSGTioEA,94
+python_doctor/analysis_request.py,sha256=hJ8zJL4-c0mFyBsTMHqwbQ6Wb2rAKW_J1XBl5QKNpsk,1078
+python_doctor/analyzer_catalog.py,sha256=KYMrHnvBLyjQb50XeaHmI3-Szc-6g3vkoJcNcFB2G3M,2909
+python_doctor/cache.py,sha256=8jKFX4UuufQLuzDJ4_aOikxA6V1v8JSGPeg8q0FijnQ,8599
+python_doctor/cli.py,sha256=m-AE14ZTQXOUSCyOvjhNlY2kbeTG1xmaK0LYwzoVZlI,15315
+python_doctor/config.py,sha256=nhDq7wEKgUDI6TWsZkTsRrLNBKaVaPr4uwXMDvbImiw,2716
+python_doctor/dedup.py,sha256=ZJOzSFT51Ii9haR_BpNpnhJqjsjQLfG9kJbgXFjCWgs,3141
+python_doctor/detection.py,sha256=ABjUd1kMwqn7bvqQOlGp1tIg7Z_qlLJqU-h_ukJCfKs,9143
+python_doctor/diff.py,sha256=5jLvukNG63kQkimcjNw1KXoIf-ttj_8e4oujN-xQ-Nk,3937
+python_doctor/discovery.py,sha256=Nw1GyM_H7X3U4QDcdAcSPaQdAn9IOsuw2M4YnGDrZlM,4938
+python_doctor/models.py,sha256=0NNrKABPiWU0mZqjhBqxiS7tTgofFgXpr9Yy_2i3hww,3539
+python_doctor/plan.py,sha256=Qlkl-tPooiQKqhX_vpn9pkkl5h7tukwMOTci8fCgNO0,3363
+python_doctor/progress.py,sha256=xMJYrThZEB-YOfBk6nJl5ymkFYGRUHnF4D3O6kIbpMk,2983
+python_doctor/rules.py,sha256=7ogCxVurBUN_dnyH2PvsV5vV8FluleVqJWG9Yq9rNHQ,13339
+python_doctor/runner.py,sha256=1Q50IFu5vC8uL2vOwD76pzLLs9HFxjCoW9tPRREyiMk,13090
+python_doctor/analyzers/__init__.py,sha256=MRpzQzzoQ1f2IjI805fM13iTXi547pjyLlgfMTssRNs,1592
+python_doctor/analyzers/bandit_scanner.py,sha256=2wWwI06GykLPVV0wVlfbavfRN6tYUDupVt_Q2ggZREs,4030
+python_doctor/analyzers/basedpyright_analyzer.py,sha256=nm6RNAWJIcT5VnkUBLkj1MCfkf5S4MN3LnPZzAjg8-k,3375
+python_doctor/analyzers/cached.py,sha256=cU2wrnKzbm7ZCA1ivhdOhwya6CvnKl2GQnqeKfKS8cY,3684
+python_doctor/analyzers/dependency_vulns.py,sha256=Ld_aRYQ-wlx9KnD31m9LC0gAQ-YI6pv2wFdCIYwOyUw,9585
+python_doctor/analyzers/deptry_analyzer.py,sha256=jiKmpkRsHshcWiRfH8IHXnLEj-7zmaQa-wNYpIbk56o,4800
+python_doctor/analyzers/detect_secrets_analyzer.py,sha256=IQPVIgAxz1Psg_pNldu6BMiKvvotTP2aDsySgAH3_Qc,3543
+python_doctor/analyzers/mypy_checker.py,sha256=Amdwi_ea0AoZ23YNmjr_lEKRVdnYEYCkwuWD9tNqx1E,6916
+python_doctor/analyzers/radon_analyzer.py,sha256=F9WZOI7ml9nulBNitXqlZ-G1xqJz357J2QHTA8-pcl8,5593
+python_doctor/analyzers/registry.py,sha256=uId0xunYpKgmpv8Yf3p_v1LsBBF468cZvX1wLmcboP0,2350
+python_doctor/analyzers/ruff.py,sha256=JP3OKcj3a7eqGdgr6fT5sXBnjHU9LfnRQKS9om5JSkY,7640
+python_doctor/analyzers/typos_analyzer.py,sha256=Mp6Edf0K97G-dasvSjJ5iDoNdq4ZG9Oz4BWEgT_k5HY,2506
+python_doctor/analyzers/vulture_analyzer.py,sha256=lyK4cbrVLm6Y1WOOzOd3nzAimE90GpA_k5jCxCFhi8Q,5102
+python_doctor/dependencies/discovery.py,sha256=8mr_SNpWLNQ_ALXIArcRIhJYMQm-PtvWpH8YPQgDd-s,6172
+python_doctor/formatters/__init__.py,sha256=2I9wUpnh-PwbhHCMGzN1UBkk8_h-VNymhWTU9_NeqX8,51
+python_doctor/formatters/badge.py,sha256=-OVW7DrqSztpm52aCdsWIUsCPOdCSes_LnzeLbA1U6k,1205
+python_doctor/formatters/human.py,sha256=YX3B5x3A3k-aueG93wuS3p4Mr20JtDXaGpTY3WPE-0I,12861
+python_doctor/formatters/json_fmt.py,sha256=dEQf8nQZNZycME3nBoItvpV_xc6dhXTldECS5G2mXxw,675
+python_doctor/mcp/__init__.py,sha256=C1lL_z6kdHTSFVkbA0a69r6iiPsUloO5_JnO3xQbxhc,311
+python_doctor/mcp/installer.py,sha256=EP-jfnuTlQzucTRDQbWnLY8MBYznFcuLRBW2kh_QXaU,4014
+python_doctor/mcp/server.py,sha256=WykSeuUytLWl5qGFRBZk7zxhQ4_BuiMJRgf_LmdJIUU,14092
+python_doctor/scoring/__init__.py,sha256=I1pfz5tLOXV3LQfd9-Wfmuky26XO8o0ZOJXQ6lS1Ohw,65
+python_doctor/scoring/engine.py,sha256=XBlezBowojgywQazjHawGl_QSIhMvL06Y4RNv9FAdxY,11708
+python_doctor/skills/SKILL.md,sha256=E82Sx67gXjYNaAdwxCH_YR4gcUH7kR2hQxa15izOiUM,10354
+python_doctor/skills/__init__.py,sha256=9jNK2waGK3m3sPSIxMwBuirFjd3CB87I9Vj3JgcXfG4,52
+python_doctor/skills/agents.py,sha256=pa664sFEidmgfywoMgHrshPzCOFf8pn4bsKvYI79tRA,3336
+python_doctor/skills/installer.py,sha256=lsunMZVLi0NakSDrGqA_rijnnbq-pvGMUo8K3EKl7T0,8543
+python_doctor/skills/rule_db.py,sha256=rmEPdZxeJKxkaB-zg7JCrhOwIBa2KytXoJN0L5ivdjs,30135
+pycode_doctor-0.1.0.dist-info/METADATA,sha256=gYQRiuGWzjRpQa2nWY4k-ft-mXYbKqOtsEk_fckFB5s,5849
+pycode_doctor-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pycode_doctor-0.1.0.dist-info/entry_points.txt,sha256=k00e5HBu9PXhbdm2uwFCjQ8VzyROfrlhQDxPAMXcL18,767
+pycode_doctor-0.1.0.dist-info/licenses/LICENSE,sha256=THxgl_tZ7hmDxzXmNERdQldpIlreAZGjnOYuc2_SsjQ,1074
+pycode_doctor-0.1.0.dist-info/RECORD,,

pycode_doctor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pycode_doctor-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,14 @@
+[console_scripts]
+python-doctor = python_doctor.cli:main
+
+[python_doctor.analyzers]
+bandit = python_doctor.analyzers.bandit_scanner:BanditAnalyzer
+basedpyright = python_doctor.analyzers.basedpyright_analyzer:BasedPyrightAnalyzer
+dependency-vulns = python_doctor.analyzers.dependency_vulns:DependencyVulnerabilityAnalyzer
+deptry = python_doctor.analyzers.deptry_analyzer:DeptryAnalyzer
+detect-secrets = python_doctor.analyzers.detect_secrets_analyzer:DetectSecretsAnalyzer
+mypy = python_doctor.analyzers.mypy_checker:MypyAnalyzer
+radon = python_doctor.analyzers.radon_analyzer:RadonAnalyzer
+ruff = python_doctor.analyzers.ruff:RuffAnalyzer
+typos = python_doctor.analyzers.typos_analyzer:TyposAnalyzer
+vulture = python_doctor.analyzers.vulture_analyzer:VultureAnalyzer

pycode_doctor-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nabeel S. Qureshi
+
+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/__init__.py

@@ -0,0 +1,8 @@
+"""python-doctor: Fast, local-first Python code health checker."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pycode-doctor")
+except PackageNotFoundError:
+    __version__ = "0.1.0"

python_doctor/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m python_doctor`."""
+
+from python_doctor.cli import main
+
+main()

python_doctor/analysis_request.py

@@ -0,0 +1,37 @@
+"""Structured analysis request passed to analyzers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from python_doctor.config import DoctorConfig
+from python_doctor.models import Category
+
+
+@dataclass
+class AnalysisRequest:
+    """Input contract shared by all analyzers."""
+
+    project_root: Path
+    files: list[Path]
+    config: DoctorConfig
+    categories: set[Category]
+    profile: str
+    framework: str | None = None
+    diff_base: str | None = None
+    quiet: bool = False
+    no_cache: bool = False
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def config_dict(self) -> dict[str, object]:
+        """Return a mutable dict representation for legacy integrations."""
+        data = self.config.__dict__.copy()
+        data["framework"] = self.framework
+        data["profile"] = self.profile
+        data["categories"] = [
+            category.value
+            for category in sorted(self.categories, key=lambda c: c.value)
+        ]
+        data.update(self.metadata)
+        return data

python_doctor/analyzer_catalog.py

@@ -0,0 +1,102 @@
+"""Analyzer metadata and category mapping."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from python_doctor.models import Category
+
+
+@dataclass(frozen=True)
+class AnalyzerInfo:
+    """Static metadata about a known analyzer."""
+
+    name: str
+    categories: frozenset[Category]
+    default_enabled: bool = True
+    optional: bool = False
+    requires_network: bool = False
+    project_wide: bool = False
+    profiles: frozenset[str] = field(
+        default_factory=lambda: frozenset({"quick", "default", "full"})
+    )
+
+
+ANALYZER_CATALOG: dict[str, AnalyzerInfo] = {
+    "ruff": AnalyzerInfo(
+        name="ruff",
+        categories=frozenset(
+            {
+                Category.QUALITY,
+                Category.SECURITY,
+                Category.COMPLEXITY,
+                Category.DEAD_CODE,
+            }
+        ),
+        profiles=frozenset({"quick", "default", "full"}),
+    ),
+    "mypy": AnalyzerInfo(
+        name="mypy",
+        categories=frozenset({Category.TYPE_SAFETY}),
+        profiles=frozenset({"default", "full"}),
+        project_wide=True,
+    ),
+    "bandit": AnalyzerInfo(
+        name="bandit",
+        categories=frozenset({Category.SECURITY}),
+        profiles=frozenset({"default", "full"}),
+    ),
+    "radon": AnalyzerInfo(
+        name="radon",
+        categories=frozenset({Category.COMPLEXITY}),
+        profiles=frozenset({"default", "full"}),
+    ),
+    "vulture": AnalyzerInfo(
+        name="vulture",
+        categories=frozenset({Category.DEAD_CODE}),
+        profiles=frozenset({"default", "full"}),
+        project_wide=True,
+    ),
+    "deptry": AnalyzerInfo(
+        name="deptry",
+        categories=frozenset({Category.DEPENDENCIES}),
+        profiles=frozenset({"quick", "default", "full"}),
+        project_wide=True,
+    ),
+    "dependency-vulns": AnalyzerInfo(
+        name="dependency-vulns",
+        categories=frozenset({Category.DEPENDENCIES}),
+        default_enabled=False,
+        optional=True,
+        requires_network=True,
+        project_wide=True,
+        profiles=frozenset({"full"}),
+    ),
+    "detect-secrets": AnalyzerInfo(
+        name="detect-secrets",
+        categories=frozenset({Category.SECURITY}),
+        default_enabled=False,
+        optional=True,
+        profiles=frozenset({"full"}),
+    ),
+    "basedpyright": AnalyzerInfo(
+        name="basedpyright",
+        categories=frozenset({Category.TYPE_SAFETY}),
+        default_enabled=False,
+        optional=True,
+        project_wide=True,
+        profiles=frozenset({"full"}),
+    ),
+    "typos": AnalyzerInfo(
+        name="typos",
+        categories=frozenset({Category.QUALITY}),
+        default_enabled=False,
+        optional=True,
+        profiles=frozenset({"full"}),
+    ),
+}
+
+
+def get_analyzer_info(name: str) -> AnalyzerInfo | None:
+    """Return catalog metadata for an analyzer name."""
+    return ANALYZER_CATALOG.get(name)

python_doctor/analyzers/__init__.py

@@ -0,0 +1,56 @@
+"""Analyzer protocol -- the interface every analyzer must implement."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from python_doctor.analysis_request import AnalysisRequest
+from python_doctor.models import Category, Diagnostic
+
+
+@runtime_checkable
+class Analyzer(Protocol):
+    """Protocol that all analyzers must satisfy.
+
+    Analyzers can be built-in or loaded via entry points.
+    Each analyzer:
+    - Has a unique name and primary category
+    - Can check if its underlying tool is available
+    - Runs analysis and returns a list of Diagnostics
+    """
+
+    @property
+    def name(self) -> str:
+        """Unique identifier, e.g. 'ruff', 'mypy', 'bandit'."""
+        ...
+
+    @property
+    def category(self) -> Category:
+        """Primary category this analyzer contributes to."""
+        ...
+
+    async def is_available(self) -> bool:
+        """Check if the underlying tool is installed and runnable.
+
+        Returns True if the tool is available, False otherwise.
+        This should be fast (check PATH, try import, etc).
+        """
+        ...
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        """Run analysis on the given files.
+
+        Args:
+            request: Structured request describing project context, enabled
+                categories, profile, files, and configuration.
+
+        Returns:
+            List of diagnostics found. Empty list means no issues.
+
+        Raises:
+            TimeoutError: If analysis exceeds configured timeout.
+        """
+        ...

python_doctor/analyzers/bandit_scanner.py

@@ -0,0 +1,143 @@
+"""Bandit security scanner integration.
+
+Bandit is invoked as a subprocess with -f json.
+Results are deduplicated against Ruff's S-prefix findings in the dedup engine.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import shutil
+from pathlib import Path
+
+from python_doctor.analysis_request import AnalysisRequest
+from python_doctor.models import Category, Diagnostic, Severity
+
+logger = logging.getLogger("python_doctor")
+
+# Bandit severity -> python-doctor Severity
+BANDIT_SEVERITY_MAP: dict[str, Severity] = {
+    "HIGH": Severity.ERROR,
+    "MEDIUM": Severity.WARNING,
+    "LOW": Severity.INFO,
+}
+
+
+class BanditAnalyzer:
+    """Security scanning via Bandit."""
+
+    @property
+    def name(self) -> str:
+        return "bandit"
+
+    @property
+    def category(self) -> Category:
+        return Category.SECURITY
+
+    async def is_available(self) -> bool:
+        """Check if bandit is on PATH."""
+        return shutil.which("bandit") is not None
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        """Run bandit with JSON output and parse results."""
+        files = request.files
+        config = request.config_dict()
+        if not files:
+            return []
+
+        cmd = ["bandit", "-f", "json", "--quiet"]
+
+        str_paths = [str(f) for f in files]
+        cmd.extend(str_paths)
+
+        timeout: int = 60
+        if "timeout" in config and isinstance(config["timeout"], (int, float)):
+            timeout = int(config["timeout"])
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(),
+                timeout=timeout,
+            )
+        except asyncio.TimeoutError:
+            logger.warning("Bandit timed out")
+            return []
+        except FileNotFoundError:
+            logger.warning("Bandit binary not found")
+            return []
+
+        # Exit codes: 0 = clean, 1 = issues found, 2 = error
+        if proc.returncode == 2:
+            logger.error("Bandit error: %s", stderr.decode())
+            return []
+
+        output = stdout.decode()
+        if not output.strip():
+            return []
+
+        try:
+            data = json.loads(output)
+        except json.JSONDecodeError:
+            logger.error("Failed to parse Bandit JSON output")
+            return []
+
+        results = data.get("results", [])
+        if not isinstance(results, list):
+            return []
+        return [_map_bandit_result(r) for r in results]
+
+
+def _safe_int(val: object, default: int = 0) -> int:
+    """Safely convert a value from JSON to int."""
+    if val is None:
+        return default
+    if isinstance(val, int):
+        return val
+    try:
+        return int(str(val))
+    except (TypeError, ValueError):
+        return default
+
+
+def _map_bandit_result(raw: dict[str, object]) -> Diagnostic:
+    """Map a single Bandit JSON result to our Diagnostic model."""
+    severity = BANDIT_SEVERITY_MAP.get(
+        str(raw.get("issue_severity", "LOW")),
+        Severity.INFO,
+    )
+
+    test_id = str(raw.get("test_id", "B000"))
+
+    # Build fix suggestion from CWE
+    cwe = raw.get("issue_cwe")
+    fix_text: str | None = None
+    if isinstance(cwe, dict) and cwe.get("id"):
+        fix_text = f"CWE-{cwe['id']}"
+
+    help_url = raw.get("more_info")
+
+    end_col = raw.get("end_col_offset")
+
+    return Diagnostic(
+        file_path=Path(str(raw.get("filename", "unknown"))),
+        line=_safe_int(raw.get("line_number")),
+        column=_safe_int(raw.get("col_offset")),
+        severity=severity,
+        rule_id=test_id,
+        tool="bandit",
+        category=Category.SECURITY,
+        message=str(raw.get("issue_text", "")),
+        fix=fix_text,
+        help_url=str(help_url) if help_url else None,
+        end_column=_safe_int(end_col) if end_col else None,
+    )