python-qv 0.1.0__py3-none-any.whl

python_qv-0.1.0.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.5
+Name: python-qv
+Version: 0.1.0
+Summary: Diagnose why a Python project is unhealthy — explain root cause and suggest safe fixes.
+Project-URL: Homepage, https://github.com/inzamol/qv
+Project-URL: Repository, https://github.com/inzamol/qv
+Project-URL: Documentation, https://github.com/inzamol/qv#readme
+Project-URL: Issues, https://github.com/inzamol/qv/issues
+Author: Inzamul Hoque
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+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 :: Bug Tracking
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: packaging>=23.2
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.350; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🔍 qv
+
+<div align="center">
+
+**Diagnose why your Python project is unhealthy — understand the root cause and get safe, actionable fixes.**
+
+[![PyPI Version](https://img.shields.io/pypi/v/python-qv.svg?color=blue)](https://pypi.org/project/python-qv/)
+[![Python Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://pypi.org/project/python-qv/)
+[![CI Status](https://github.com/inzamol/qv/actions/workflows/ci.yml/badge.svg)](https://github.com/inzamol/qv/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+[Installation](#-installation) • [Quick Start](#-quick-start) • [Features](#-what-it-detects) • [CLI Commands](#-cli-commands) • [CI/CD Integration](#-cicd-integration) • [Documentation](docs/getting_started.md)
+
+</div>
+
+---
+
+## 💡 Why qv?
+
+Python projects rarely fail because of Python syntax. They fail because of **ecosystem friction**:
+- Incompatible transitive dependency constraints that break your resolver.
+- Missing dependencies you forgot to add to `pyproject.toml`.
+- Docker containers running Python 3.10 while your team develops on 3.12.
+- Silent circular imports that only crash at runtime when certain modules load.
+
+Instead of parsing hundreds of lines of cryptic resolver logs, **`qv`** scans your project in milliseconds, pinpoints the root cause, shows the exact evidence, and gives you a copy-paste command to fix it.
+
+```text
+🔍 qv
+Project: payment-service
+Python:  3.12.7
+Package Manager: uv
+
+🔴 1 Errors   🟡 1 Warnings   🟢 48 Checks Passed
+
+┌────────────────── 🔴 DEP-001 Dependency constraint conflict ─────────────────┐
+│ celery 5.4.0 requires kombu<5.4.0,>=5.3.0, but installed is kombu 5.5.2.     │
+│                                                                              │
+│ Evidence:                                                                    │
+│   • celery declared requirement: kombu<5.4.0,>=5.3.0                         │
+│   • Installed kombu version: 5.5.2 in active environment                     │
+│                                                                              │
+│ Suggested fix:                                                               │
+│   Upgrade celery or pin kombu to <5.4.0,>=5.3.0.                             │
+│   $ uv add 'kombu<5.4.0,>=5.3.0'                                             │
+└──────────────────────────────────────────────────────────────────────────────┘
+
+Health Score: 85/100
+```
+
+---
+
+## 📦 Installation
+
+Install `python-qv` into your virtual environment (provides the `qv` CLI):
+
+```bash
+# Using pip
+pip install python-qv
+
+# Using uv
+uv add python-qv --dev
+
+# Run directly without installing (via uvx or pipx)
+uvx python-qv scan
+# or
+pipx run python-qv scan
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Run a Health Scan
+
+Run `qv scan` inside any Python repository:
+
+```bash
+qv scan
+```
+
+### 2. Understand Any Flagged Issue
+
+Need more context on why a rule triggered? Run `explain`:
+
+```bash
+qv explain DEP-001
+```
+
+### 3. Add Project Configuration
+
+To add default configuration to your `pyproject.toml`:
+
+```bash
+qv init
+```
+
+---
+
+## 🔍 What It Detects
+
+| Category | Rule ID | Description | Default Severity |
+|---|---|---|---|
+| **Dependencies** | `DEP-001` | Incompatible package version constraints across dependency tree | `ERROR` |
+| | `DEP-002` | Third-party packages imported in code but missing from `pyproject.toml` | `ERROR` |
+| | `DEP-003` | Declared dependencies that are never imported anywhere in project | `WARNING` |
+| | `DEP-004` | Package requires a Python version incompatible with target runtime | `WARNING` |
+| | `DEP-005` | Installed virtualenv version does not match declared manifest pin | `WARNING` |
+| **Environment** | `ENV-001` | Active interpreter version differs from project `requires-python` | `WARNING` |
+| | `ENV-002` | Dockerfile base image Python version differs from project runtime | `WARNING` |
+| | `ENV-003` | CI matrix does not cover the Python versions declared in project | `WARNING` |
+| **Architecture** | `IMP-001` | Circular import cycles across local modules | `ERROR` |
+| | `IMP-002` | Unresolved relative or internal module imports | `ERROR` |
+| **Packaging** | `PKG-001` | Missing PEP 621 metadata (name, version, etc.) | `WARNING` |
+| | `PKG-002` | Invalid syntax or malformed keys in `pyproject.toml` | `ERROR` |
+
+👉 *See full explanations and remediation steps in the [Rules Catalog](docs/rules.md).*
+
+---
+
+## 🛠️ CLI Commands
+
+```bash
+# Full project diagnostic scan
+qv scan
+
+# Scan another folder
+qv scan ./services/billing
+
+# Strict mode: fail CI on warnings as well as errors
+qv scan --strict
+
+# Output machine-readable formats
+qv scan --json
+qv scan --sarif -o results.sarif
+
+# Run focused subsystem scans
+qv dependency       # Check package constraints & imports
+qv environment      # Check Python, Docker & CI version drift
+qv architecture     # Check for circular imports & dead paths
+
+# Explain a rule
+qv explain DEP-002
+
+# Check installed version
+qv version
+```
+
+👉 *See detailed options in the [CLI Reference](docs/cli_reference.md).*
+
+---
+
+## ⚙️ Configuration
+
+Configure `qv` in your `pyproject.toml`:
+
+```toml
+[tool.qv]
+
+# Override severity for any rule (error, warning, info, off)
+[tool.qv.rules]
+DEP-001 = "error"
+DEP-003 = "warning"
+ENV-002 = "info"
+
+# Ignore specific rules
+[tool.qv.ignore]
+rules = ["DEP-004"]
+
+# Exclude directories from scanning
+[tool.qv.paths]
+exclude = [
+    ".venv",
+    "build",
+    "dist",
+    "legacy_scripts",
+]
+
+# Set expected target Python version
+[tool.qv.runtime]
+python = "3.12"
+```
+
+👉 *Learn more in the [Configuration Guide](docs/configuration.md).*
+
+---
+
+## 🤖 CI/CD Integration
+
+### GitHub Actions (with SARIF code scanning)
+
+Add this step to your GitHub Actions workflow (`.github/workflows/ci.yml`):
+
+```yaml
+name: Health & Dependency Scan
+
+on: [push, pull_request]
+
+jobs:
+  qv:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+
+      # Run scan in CI mode
+      - name: Run qv
+        run: uv run qv scan --ci
+
+      # Optional: Generate SARIF report for GitHub Code Scanning
+      - name: Generate SARIF report
+        run: uv run qv scan --sarif -o qv.sarif
+        if: always()
+
+      - name: Upload SARIF to GitHub Security
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: qv.sarif
+        if: always()
+```
+
+👉 *See full details in [CI/CD Integration](docs/ci_integration.md).*
+
+---
+
+## 🎯 Design Principles
+
+- **Diagnose first. Explain second. Fix safely.**
+- **No destructive auto-mutations**: Remediations provide the exact commands/diffs for you to review and apply.
+- **Local-first & Blazing fast**: Zero network calls required; scans complete in under a second.
+- **Package-manager agnostic**: Works out of the box with `uv`, Poetry, `pip`, PDM, and Pipenv.
+
+---
+
+## 📚 Complete Documentation
+
+- 🚀 [Getting Started Guide](docs/getting_started.md)
+- 📖 [CLI Reference](docs/cli_reference.md)
+- 📋 [Diagnostic Rules Catalog](docs/rules.md)
+- ⚙️ [Configuration Guide](docs/configuration.md)
+- 🤖 [CI/CD & SARIF Integration](docs/ci_integration.md)
+- 🤝 [Contributing Guidelines](docs/contributing.md)
+
+---
+
+## 📄 License
+
+Distributed under the [MIT License](LICENSE).

python_qv-0.1.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+qv/__init__.py,sha256=v4AKHyYLemGctPfnaZ7qLHlpL1dgam5uAkTk1qzXUQw,100
+qv/analyzers/__init__.py,sha256=_d-1_NpNFMDu1cT-SqTKRBBeipboWZlRt5zZ0tsVPk0,25
+qv/analyzers/ci/__init__.py,sha256=W0Kr4IJBwjysEJPY-D3wNeDMWVFOFQzZt71LIzRDGfY,20
+qv/analyzers/dependencies/__init__.py,sha256=AfzPubOgDrmbfPVe8I5egJ6tswolYzWsDwXjW-Maqhg,129
+qv/analyzers/dependencies/analyzer.py,sha256=gtQeMuhUXs29cEn3RcRkWCXQzVHTs1PbE4_tVzSHhUQ,14075
+qv/analyzers/docker/__init__.py,sha256=zQsRHV9IiRbjpb9AKmKzaMPtlXp1iSQCBSvyKDo-2q8,24
+qv/analyzers/environment/__init__.py,sha256=5EtSq3sQIJJxKAfpwWiCul3VHWMA94y3-QBi5pjHVb8,128
+qv/analyzers/environment/drift.py,sha256=tsu3Oi5Bng8e69Cvd6SBWsdyuK3Ut72saFvRpEjY-2I,7193
+qv/analyzers/imports/__init__.py,sha256=bShRWSwJunl5mbkHI738-jTut0RGStVQhtdzCae-fuo,112
+qv/analyzers/imports/analyzer.py,sha256=Vw0VKulyHcwONg9hkXEI2LfbMUxF4MZrNZVnaJnzSKw,6335
+qv/analyzers/packaging/__init__.py,sha256=owgIeiZUNwhn-gPLbho1jCqA72cg1f8u_6wsqDqsgdk,123
+qv/analyzers/packaging/analyzer.py,sha256=-57OYQPsS6uIN8u_1LR2CQRT8sOcDmYYCtGkgFo4jo0,4776
+qv/analyzers/security/__init__.py,sha256=LsUd6Rerxa9qt3U0bP1uiNyEbs0doVtN8zvrXkjZOJY,26
+qv/cli/__init__.py,sha256=EUnPKm0L_oVbU1jAO_Icle4TXMCVGpd_aFTQ4iaueik,88
+qv/cli/main.py,sha256=eewmxZF9dpcUTITY2qwVpAFa8NRF2JW7LhmBJzW4ppo,8112
+qv/core/analyzer.py,sha256=FPiEjghPbi-RVCOxODE_BRlkvtMsnrgbakhq7-YORuc,503
+qv/core/config.py,sha256=LW8zjnuNlosQdqumbvycBu8fGe_Neg2fWpB_vdhNHVA,3629
+qv/core/context.py,sha256=kAI_QENd6c9kRiIE5Ejt2Um4MZsQ3TL9ubkl3w5AJF0,2575
+qv/core/engine.py,sha256=p4Lg8teRj8EgoVqc26TaK1SrijOKRHtBKrDnsE8BZ7w,4400
+qv/core/models.py,sha256=9TDMASdnS_vaayjZSAu2kLUk-KPOKU6ikZlQr6KFSM0,3728
+qv/core/project.py,sha256=1aSdCrlp1EbygAHhW3ptGx3_GwJKL-FwJrhQhO5mozc,12906
+qv/frameworks/__init__.py,sha256=5XnOOPd2Kyb9uG3Z7MjqZO1emDZs5F1sCAmI4yjWMPI,25
+qv/integrations/__init__.py,sha256=xBWG_BBOAn4l43MnjXmhbu4qjiMdYq32pVjmDO0Q8iM,37
+qv/reporters/__init__.py,sha256=bTNB9uOshW9cgKv2Oja2uy4UrY5HJufUa0TzcLwO2fY,309
+qv/reporters/base.py,sha256=LvtGAy5xocwB8gqYuAvFEIO73ov7BwXa06Azj_Pnuu4,329
+qv/reporters/json_reporter.py,sha256=RRzEZAMpOw8HGEVbYV8n_PCJ0PrIvFlOgAGptUxvtvY,446
+qv/reporters/sarif.py,sha256=CZEtjmqB7sNCc4qZJBLtm_7cT_gYa8frI1jl9JHzuyU,3062
+qv/reporters/terminal.py,sha256=H5c5-HMKSZ2PIHx-ZE4XA5bhMH826JHzBav0EKFqU44,4549
+qv/rules/registry.py,sha256=EkH_1CcmGwUWkldU2D9ZZATEZx6vxaWqs9Sf9LzVDKA,7410
+python_qv-0.1.0.dist-info/METADATA,sha256=RmVlo5zNtDYwxBkpoZBY46m9uAfoJ3iPP64KfwepbAE,9046
+python_qv-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+python_qv-0.1.0.dist-info/entry_points.txt,sha256=y0aZqfDPndkJ2yXxBM2RLL1qriH72zWEKSj4nJtc2q4,94
+python_qv-0.1.0.dist-info/RECORD,,

python_qv-0.1.0.dist-info/WHEEL

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

python_qv-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+pydoctor = qv.cli.main:cli
+python-qv = qv.cli.main:cli
+qv = qv.cli.main:cli

qv/__init__.py

@@ -0,0 +1,3 @@
+"""qv - Package-manager-agnostic diagnostic platform for Python projects."""
+
+__version__ = "0.1.0"

qv/analyzers/__init__.py

@@ -0,0 +1 @@
+"""Analyzers package."""

qv/analyzers/ci/__init__.py

@@ -0,0 +1 @@
+"""CI analyzers."""

qv/analyzers/dependencies/__init__.py

@@ -0,0 +1,5 @@
+"""Dependency analyzers."""
+
+from qv.analyzers.dependencies.analyzer import DependencyAnalyzer
+
+__all__ = ["DependencyAnalyzer"]

qv/analyzers/dependencies/analyzer.py

@@ -0,0 +1,347 @@
+"""Dependency analyzer implementing DEP-001, DEP-002, DEP-003, DEP-004, DEP-005."""
+
+from __future__ import annotations
+
+import sys
+
+from packaging.requirements import Requirement
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
+
+from qv.core.context import ProjectContext
+from qv.core.models import Diagnostic, Evidence, Suggestion
+from qv.rules.registry import get_rule_definition
+
+# Known Python standard library modules (Python 3.10+)
+STDLIB_MODULES = (
+    set(sys.stdlib_module_names)
+    if hasattr(sys, "stdlib_module_names")
+    else {
+        "abc",
+        "argparse",
+        "ast",
+        "asyncio",
+        "base64",
+        "collections",
+        "contextlib",
+        "csv",
+        "dataclasses",
+        "datetime",
+        "decimal",
+        "difflib",
+        "dis",
+        "enum",
+        "functools",
+        "glob",
+        "hashlib",
+        "http",
+        "importlib",
+        "inspect",
+        "io",
+        "itertools",
+        "json",
+        "logging",
+        "math",
+        "multiprocessing",
+        "os",
+        "pathlib",
+        "pickle",
+        "pprint",
+        "random",
+        "re",
+        "shutil",
+        "socket",
+        "sqlite3",
+        "ssl",
+        "string",
+        "subprocess",
+        "sys",
+        "tempfile",
+        "threading",
+        "time",
+        "traceback",
+        "typing",
+        "unittest",
+        "urllib",
+        "uuid",
+        "warnings",
+        "weakref",
+        "xml",
+        "zipfile",
+        "__future__",
+    }
+)
+
+# Known tools/packages that may not be imported directly in application code
+IGNORED_UNUSED = {
+    "pytest",
+    "pytest-cov",
+    "ruff",
+    "black",
+    "mypy",
+    "pyright",
+    "flake8",
+    "isort",
+    "hatchling",
+    "flit",
+    "setuptools",
+    "wheel",
+    "gunicorn",
+    "uvicorn",
+}
+
+
+class DependencyAnalyzer:
+    """Analyzes declared and installed dependencies for conflicts and anomalies."""
+
+    id = "dependencies"
+    name = "Dependency Analyzer"
+    description = (
+        "Checks for dependency conflicts, missing imports, unused packages, and version mismatches."
+    )
+
+    def analyze(self, context: ProjectContext) -> list[Diagnostic]:
+        diagnostics: list[Diagnostic] = []
+
+        # Run individual sub-checks
+        diagnostics.extend(self._check_installed_conflicts(context))
+        diagnostics.extend(self._check_missing_dependencies(context))
+        diagnostics.extend(self._check_unused_dependencies(context))
+        diagnostics.extend(self._check_declaration_mismatch(context))
+
+        return diagnostics
+
+    def _check_installed_conflicts(self, context: ProjectContext) -> list[Diagnostic]:
+        """DEP-001: Check if any installed package's dependencies conflict with other installed packages."""
+        diagnostics: list[Diagnostic] = []
+        rule = get_rule_definition("DEP-001")
+        if not rule:
+            return diagnostics
+
+        for dist in context.installed_packages.values():
+            for req_str in dist.requires:
+                try:
+                    req = Requirement(req_str)
+                    # Ignore marker evaluation failure or unfulfilled markers for other OS/Python
+                    if req.marker and not req.marker.evaluate():
+                        continue
+
+                    dep_name = req.name.lower()
+                    if dep_name in context.installed_packages:
+                        installed_dep = context.installed_packages[dep_name]
+                        try:
+                            dep_ver = Version(installed_dep.version)
+                            if req.specifier and not req.specifier.contains(
+                                dep_ver, prereleases=True
+                            ):
+                                diag = Diagnostic(
+                                    id=rule.id,
+                                    severity=rule.default_severity,
+                                    category=rule.category,
+                                    title=rule.title,
+                                    message=f"{dist.name} requires {req.name}{req.specifier}, but installed is {installed_dep.name} {installed_dep.version}.",
+                                    evidence=[
+                                        Evidence(
+                                            fact=f"{dist.name} declared requirement: {req_str}",
+                                            source=f"{dist.name} metadata",
+                                        ),
+                                        Evidence(
+                                            fact=f"Installed {installed_dep.name} version: {installed_dep.version}",
+                                            source="Active environment",
+                                        ),
+                                    ],
+                                    suggestions=[
+                                        Suggestion(
+                                            description=f"Upgrade {dist.name} or pin {installed_dep.name} to {req.specifier}.",
+                                            command=f"{context.package_manager} add '{installed_dep.name}{req.specifier}'"
+                                            if context.package_manager in ("uv", "poetry")
+                                            else f"pip install '{installed_dep.name}{req.specifier}'",
+                                        )
+                                    ],
+                                    affected_packages=[dist.name, installed_dep.name],
+                                    doc_url=rule.doc_url,
+                                )
+                                diagnostics.append(diag)
+                        except Exception:
+                            pass
+                except Exception:
+                    pass
+
+        return diagnostics
+
+    def _check_missing_dependencies(self, context: ProjectContext) -> list[Diagnostic]:
+        """DEP-002: Check for imported packages not declared in dependencies."""
+        diagnostics: list[Diagnostic] = []
+        rule = get_rule_definition("DEP-002")
+        if not rule:
+            return diagnostics
+
+        declared_names = {d.name.lower().replace("-", "_"): d for d in context.dependencies}
+        declared_raw_names = {d.name.lower(): d for d in context.dependencies}
+
+        # Collect local top-level module names
+        local_modules = {
+            context.project_name.lower().replace("-", "_"),
+            context.project_name.lower(),
+        }
+        for sf in context.source_files:
+            parts = sf.relative_path.parts
+            if parts:
+                if parts[0] in ("src", "lib") and len(parts) > 1:
+                    local_modules.add(parts[1].replace(".py", "").lower().replace("-", "_"))
+                local_modules.add(parts[0].replace(".py", "").lower().replace("-", "_"))
+
+        seen_missing: set[str] = set()
+
+        for imp in context.imports:
+            if imp.is_relative or not imp.module_name:
+                continue
+
+            top_level = imp.module_name.split(".")[0]
+            top_level_norm = top_level.lower().replace("-", "_")
+
+            if (
+                top_level in STDLIB_MODULES
+                or top_level in local_modules
+                or top_level_norm in local_modules
+                or top_level_norm in declared_names
+                or top_level.lower() in declared_raw_names
+            ):
+                continue
+
+            # If it's missing from declared dependencies
+            if top_level_norm not in seen_missing:
+                seen_missing.add(top_level_norm)
+                rel_path = (
+                    imp.source_file.relative_to(context.project_root)
+                    if imp.source_file.is_relative_to(context.project_root)
+                    else imp.source_file
+                )
+                diag = Diagnostic(
+                    id=rule.id,
+                    severity=rule.default_severity,
+                    category=rule.category,
+                    title=f"Missing dependency: {top_level}",
+                    message=f"Module '{top_level}' is imported in {rel_path}:{imp.line_number} but is not declared in project dependencies.",
+                    evidence=[
+                        Evidence(
+                            fact=f"Import statement: `import {imp.module_name}` in {rel_path}:{imp.line_number}",
+                            source=str(rel_path),
+                        )
+                    ],
+                    suggestions=[
+                        Suggestion(
+                            description=f"Add '{top_level}' to project dependencies in pyproject.toml.",
+                            command=f"{context.package_manager} add {top_level}"
+                            if context.package_manager in ("uv", "poetry")
+                            else f"pip install {top_level}",
+                        )
+                    ],
+                    affected_packages=[top_level],
+                    file=str(rel_path),
+                    line=imp.line_number,
+                    doc_url=rule.doc_url,
+                )
+                diagnostics.append(diag)
+
+        return diagnostics
+
+    def _check_unused_dependencies(self, context: ProjectContext) -> list[Diagnostic]:
+        """DEP-003: Check for declared direct dependencies that have no detected imports."""
+        diagnostics: list[Diagnostic] = []
+        rule = get_rule_definition("DEP-003")
+        if not rule or not context.source_files:
+            return diagnostics
+
+        imported_top_levels = {
+            imp.module_name.split(".")[0].lower().replace("-", "_")
+            for imp in context.imports
+            if imp.module_name
+        }
+
+        for dep in context.dependencies:
+            if dep.is_dev:
+                continue
+
+            dep_norm = dep.name.lower().replace("-", "_")
+            if dep.name.lower() in IGNORED_UNUSED or dep_norm in IGNORED_UNUSED:
+                continue
+
+            if dep_norm not in imported_top_levels and dep.name.lower() not in imported_top_levels:
+                diag = Diagnostic(
+                    id=rule.id,
+                    severity=rule.default_severity,
+                    category=rule.category,
+                    title=f"Unused declared dependency: {dep.name}",
+                    message=f"Package '{dep.name}' is declared in {dep.source_file.name} but no imports were detected in project source files.",
+                    evidence=[
+                        Evidence(
+                            fact=f"Declared requirement: {dep.name}{dep.specifier} in {dep.source_file.name}",
+                            source=str(dep.source_file),
+                        )
+                    ],
+                    suggestions=[
+                        Suggestion(
+                            description=f"Remove '{dep.name}' from dependencies if not needed at runtime.",
+                            command=f"{context.package_manager} remove {dep.name}"
+                            if context.package_manager in ("uv", "poetry")
+                            else None,
+                        )
+                    ],
+                    affected_packages=[dep.name],
+                    file=str(dep.source_file),
+                    line=dep.line_number,
+                    confidence=0.85,
+                    doc_url=rule.doc_url,
+                )
+                diagnostics.append(diag)
+
+        return diagnostics
+
+    def _check_declaration_mismatch(self, context: ProjectContext) -> list[Diagnostic]:
+        """DEP-005: Check for declared versions that do not match installed versions in active environment."""
+        diagnostics: list[Diagnostic] = []
+        rule = get_rule_definition("DEP-005")
+        if not rule or not context.installed_packages:
+            return diagnostics
+
+        for dep in context.dependencies:
+            dep_name_lower = dep.name.lower()
+            if dep_name_lower in context.installed_packages and dep.specifier:
+                installed = context.installed_packages[dep_name_lower]
+                try:
+                    spec = SpecifierSet(dep.specifier)
+                    installed_ver = Version(installed.version)
+                    if not spec.contains(installed_ver, prereleases=True):
+                        diag = Diagnostic(
+                            id=rule.id,
+                            severity=rule.default_severity,
+                            category=rule.category,
+                            title=f"Installed/declaration mismatch for {dep.name}",
+                            message=f"Declared requirement is '{dep.name}{dep.specifier}', but environment has '{installed.name} {installed.version}'.",
+                            evidence=[
+                                Evidence(
+                                    fact=f"Declared specifier: {dep.specifier} in {dep.source_file.name}",
+                                    source=str(dep.source_file),
+                                ),
+                                Evidence(
+                                    fact=f"Installed version in environment: {installed.version}",
+                                    source="Active environment",
+                                ),
+                            ],
+                            suggestions=[
+                                Suggestion(
+                                    description="Synchronize the virtual environment with project manifest.",
+                                    command=f"{context.package_manager} sync"
+                                    if context.package_manager in ("uv", "poetry")
+                                    else f"pip install -r {dep.source_file.name}",
+                                )
+                            ],
+                            affected_packages=[dep.name],
+                            doc_url=rule.doc_url,
+                        )
+                        diagnostics.append(diag)
+                except Exception:
+                    pass
+
+        return diagnostics