python-qv 0.1.1__tar.gz → 0.1.3__tar.gz

python_qv-0.1.3/.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build MkDocs Site in Strict Mode
+        run: uv run mkdocs build --strict
+
+      - name: Upload artifact for GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

python_qv-0.1.3/.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+# Build documentation using MkDocs
+mkdocs:
+  configuration: mkdocs.yml
+
+# Install docs dependencies
+python:
+  install:
+    - requirements: docs/requirements.txt

{python_qv-0.1.1 → python_qv-0.1.3}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: python-qv
-Version: 0.1.1
+Version: 0.1.3
 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://qv.readthedocs.io/
+Project-URL: Documentation, https://inzamol.github.io/qv/
 Project-URL: Issues, https://github.com/inzamol/qv/issues
 Author: Inzamul Hoque
 License-Expression: MIT
@@ -34,6 +34,7 @@ Requires-Dist: tox-uv>=1.7.0; extra == 'dev'
 Requires-Dist: tox>=4.15.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs<2.0.0,>=1.6.0; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.7.0; extra == 'docs'
 Description-Content-Type: text/markdown
 
@@ -198,8 +199,10 @@ Run `qv inspect` (or `qv ui`) for a full terminal dashboard:
 | | `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` |
+| **FastAPI Doctor** | `FAP-001`–`FAP-038` | Async blocking calls, CPU starvation in endpoints, insecure CORS, missing timeouts, lifecycle anti-patterns, Pydantic v2 migrations | `ERROR` / `WARNING` |
+| **SQL & Database** | `SQL-001`–`SQL-030` | N+1 queries in loops, session leaks, SQL injection, sync DB in async loop, missing eager loading, pool starvation, 2.0 syntax | `ERROR` / `WARNING` |
 
-👉 *See full explanations and remediation steps in the [Rules Catalog](docs/rules.md).*
+👉 *See all 80+ rules and remediation steps in the [Rules Catalog](docs/rules.md).*
 
 ---
 
@@ -330,6 +333,11 @@ qv environment
 
 # Check AST & imports only (circular import loops, unresolvable modules)
 qv architecture
+
+# Check framework-specific issues (FastAPI, SQLAlchemy, SQLModel)
+qv framework
+qv framework --name fastapi
+qv framework --name sqlalchemy
 ```
 
 ---

{python_qv-0.1.1 → python_qv-0.1.3}/README.md

@@ -159,8 +159,10 @@ Run `qv inspect` (or `qv ui`) for a full terminal dashboard:
 | | `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` |
+| **FastAPI Doctor** | `FAP-001`–`FAP-038` | Async blocking calls, CPU starvation in endpoints, insecure CORS, missing timeouts, lifecycle anti-patterns, Pydantic v2 migrations | `ERROR` / `WARNING` |
+| **SQL & Database** | `SQL-001`–`SQL-030` | N+1 queries in loops, session leaks, SQL injection, sync DB in async loop, missing eager loading, pool starvation, 2.0 syntax | `ERROR` / `WARNING` |
 
-👉 *See full explanations and remediation steps in the [Rules Catalog](docs/rules.md).*
+👉 *See all 80+ rules and remediation steps in the [Rules Catalog](docs/rules.md).*
 
 ---
 
@@ -291,6 +293,11 @@ qv environment
 
 # Check AST & imports only (circular import loops, unresolvable modules)
 qv architecture
+
+# Check framework-specific issues (FastAPI, SQLAlchemy, SQLModel)
+qv framework
+qv framework --name fastapi
+qv framework --name sqlalchemy
 ```
 
 ---

python_qv-0.1.3/docs/architecture.md

@@ -0,0 +1,211 @@
+# Architecture & Internal Design
+
+`qv` is built as an offline-first, modular diagnostic engine designed to analyze Python project ecosystems in sub-second execution time.
+
+---
+
+## 1. System Overview
+
+Traditional linters inspect only individual source files (AST), while package managers typically only inspect lockfiles. `qv` bridges this gap by unifying four distinct layers of the Python ecosystem into an immutable diagnostic model:
+
+1. **Manifests**: `pyproject.toml`, `requirements.txt`, `setup.cfg`, `Pipfile`.
+2. **Active Environment**: `sys.executable`, `site-packages`, `importlib.metadata` distributions, and installed version constraints.
+3. **Source Code AST**: Module import references, circular call loops, and orphan files.
+4. **Runtime & Infrastructure**: `Dockerfile`, `docker-compose.yml`, and `.github/workflows/` CI matrices.
+
+```text
+                             CLI / TUI (click + rich)
+                                        │
+                                Project Discovery
+                                        │
+                            ProjectContext (Immutable)
+                                        │
+         ┌───────────────┬──────────────┴───────────────┬────────────────┐
+   Dependencies    Environment                      Imports          Packaging
+     Analyzer        Analyzer                       Analyzer          Analyzer
+         └───────────────┼──────────────────────────────┴────────────────┘
+                                        │
+                                 AnalysisEngine
+                                        │
+                                Diagnostic Model
+                                        │
+                              Root Cause Correlator
+                                        │
+    ┌──────────────┬─────────────┼─────────────┬──────────────┬──────────────┐
+ Terminal         JSON         SARIF         HTML         GitHub Actions   Interactive
+ Reporter       Reporter     Reporter      Reporter         Annotator      TUI Dashboard
+```
+
+---
+
+## 2. End-to-End Diagnostic Pipeline
+
+The diagram below illustrates the complete lifecycle from project path discovery through multi-channel report generation:
+
+```mermaid
+flowchart TD
+    subgraph Discovery["1. Discovery & Context Ingestion"]
+        A["<b>File System Scanner</b><br/>Walks project root, excludes ignored paths"]
+        B["<b>Manifest Parser</b><br/>Parses PEP 621, Poetry, Flit, setuptools, requirements"]
+        C["<b>Environment Inspector</b><br/>Inspects active virtualenv & installed distributions"]
+        D["<b>AST Module Parser</b><br/>Extracts import statements & relative import trees"]
+        E["<b>Infrastructure Parser</b><br/>Extracts Docker base images & CI matrix versions"]
+    end
+
+    subgraph Context["2. Immutable Context"]
+        CTX["<b>ProjectContext</b><br/>Frozen snapshot of project metadata, AST, and environment"]
+    end
+
+    subgraph Analyzers["3. Subsystem Analyzers"]
+        F1["<b>Dependencies Analyzer</b><br/>Conflict resolution, undeclared/unused packages"]
+        F2["<b>Environment Analyzer</b><br/>Python interpreter, Docker, and CI drift"]
+        F3["<b>Imports Analyzer</b><br/>Tarjan's cycle algorithm & unresolvable modules"]
+        F4["<b>Packaging Analyzer</b><br/>PEP 621 compliance & schema validation"]
+    end
+
+    subgraph Correlation["4. Correlation & Scoring"]
+        G["<b>Analysis Engine & Correlator</b><br/>Aggregates findings, deduplicates evidence"]
+        H["<b>Health Score Calculator</b><br/>Applies severity penalties (0–100 score)"]
+    end
+
+    subgraph Reporters["5. Reporting & Remediation"]
+        R1["<b>Terminal Reporter</b><br/>Colorized Rich tables & boxes"]
+        R2["<b>Interactive TUI</b><br/>Live dashboard with keyboard navigation"]
+        R3["<b>Self-Contained HTML</b><br/>Single-file interactive report with SVG gauges"]
+        R4["<b>SARIF v2.1.0 & JSON</b><br/>GitHub Security & CI integration"]
+        R5["<b>Remediation Engine</b><br/>Safe diff generator & sync coordinator"]
+    end
+
+    Discovery --> CTX
+    CTX --> Analyzers
+    Analyzers --> Correlation
+    Correlation --> Reporters
+```
+
+---
+
+## 3. Subsystem Analyzers
+
+All diagnostic checks are implemented as independent analyzers under `src/qv/analyzers/`. Each analyzer accepts the immutable `ProjectContext` and yields structured `Diagnostic` instances.
+
+### 3.1 Dependencies Analyzer (`src/qv/analyzers/dependencies/`)
+- **Constraint Conflict Engine**: Validates installed package versions against declared PEP 508 version specifiers.
+- **Missing Dependency Detection**: Identifies third-party packages imported in source code that are missing from `pyproject.toml` or requirements files.
+- **Unused Dependency Detection**: Pinpoints direct declared dependencies that are never referenced across project source files.
+- **Standard Library Awareness**: Includes exhaustive Python 3.10–3.13 stdlib catalogs (accounting for PEP 594 removals).
+
+### 3.2 Environment & Drift Analyzer (`src/qv/analyzers/environment/`)
+- **Python Version Drift**: Compares the active virtualenv interpreter version against `requires-python` or target runtime.
+- **Container Drift**: Scans `Dockerfile` and `compose.yml` for base image Python version tags that diverge from project targets.
+- **CI Matrix Drift**: Verifies that GitHub Actions matrix definitions cover the Python versions declared in project manifests.
+
+### 3.3 Imports & AST Analyzer (`src/qv/analyzers/imports/`)
+- **Circular Import Cycle Detection**: Constructs a directed module dependency graph and uses **Tarjan's Strongly Connected Components (SCC)** algorithm to identify recursive import loops.
+- **Unresolved Local Imports**: Flags imports that reference non-existent local packages or missing `__init__.py` files.
+- **Orphan / Dead File Detection**: Identifies Python modules that are never imported by any other module, test file, or console script entry point.
+
+### 3.4 Packaging Analyzer (`src/qv/analyzers/packaging/`)
+- **PEP 621 Schema Validation**: Ensures required tables (`[project]`, `name`, `version`) are present and syntactically valid.
+- **Build Backend Consistency**: Verifies configuration compatibility with standard build tools (`setuptools`, `flit_core`, `hatchling`, `poetry.core`, `pdm.backend`).
+
+---
+
+## 4. Immutable Core Models
+
+All state within `qv` flows through immutable, strictly typed dataclasses defined in `src/qv/core/`:
+
+### 4.1 `ProjectContext`
+A frozen snapshot of discovered project assets:
+- `root_dir`: Absolute project path.
+- `manifest`: Parsed `pyproject.toml` or requirements metadata.
+- `environment`: Active Python interpreter version, virtualenv path, and installed distributions.
+- `source_files`: Parsed AST trees and imported module sets.
+- `config`: User configuration loaded from `[tool.qv]`.
+
+### 4.2 `Diagnostic`
+A structured diagnostic finding:
+- `rule_id`: Stable identifier (e.g. `DEP-001`, `IMP-001`).
+- `title`: Short human-readable summary.
+- `severity`: `ERROR`, `WARNING`, `INFO`.
+- `message`: Specific description of the root cause.
+- `location`: Optional file path and line number.
+- `evidence`: Bulleted list of facts discovered during analysis.
+- `suggestions`: Recommended CLI commands or code modifications.
+- `fix_action`: Optional automated remediation plan.
+
+---
+
+## 5. Root Cause Engine & Health Scoring
+
+`qv` scores project health on a scale from **0 to 100**:
+
+$$\text{Health Score} = \max\left(0, 100 - \sum \text{Severity Penalties}\right)$$
+
+### 5.1 Severity Penalties
+
+| Finding Severity | Base Penalty | Behavior in Strict / CI Mode |
+|---|---|---|
+| **`ERROR`** | **-15 points** | Fails scan immediately (exit code 1). |
+| **`WARNING`** | **-5 points** | Fails scan if `--strict` or `--ci` is enabled. |
+| **`INFO`** | **-1 point** | Non-blocking advisory finding. |
+
+### 5.2 Score Color Thresholds
+- **Green (Healthy)**: $80 \le \text{Score} \le 100$
+- **Yellow (Degraded)**: $50 \le \text{Score} \le 79$
+- **Red (Critical)**: $0 \le \text{Score} \le 49$
+
+---
+
+## 6. Safe Automated Remediation Engine
+
+The remediation engine (`src/qv/remediation/`) adheres to strict safety guarantees:
+
+1. **Non-Destructive AST/TOML Editing**: Modifications to `pyproject.toml` preserve existing formatting, comments, and unrelated tables.
+2. **Dry-Run Diff Generation**: All proposed fixes can be inspected in advance via `qv fix --dry-run`.
+3. **Reversible Fix Actions**: Fixes are scoped to specific files with atomic writes.
+4. **Package Manager Auto-Sync**: When `--sync` is passed, `qv` automatically invokes the project's native tool (`uv sync`, `poetry install`, `pip install`) to update the virtualenv.
+
+---
+
+## 7. Multi-Channel Reporting Pipeline
+
+Diagnostics can be formatted and routed to multiple consumers:
+
+- **Terminal Reporter**: Human-readable colorized output with evidence boxes and suggestion snippets.
+- **Interactive TUI Dashboard (`qv inspect`)**: Rich terminal interface with dual panes, scrolling, keyboard shortcuts, and live dependency tree toggling.
+- **Standalone HTML Report (`qv scan --html`)**: Single-file HTML dashboard with SVG health score meters, real-time client-side search, severity filters, and light/dark theme toggle.
+- **SARIF v2.1.0 Reporter**: Standard OASIS SARIF format for GitHub Advanced Security and Code Scanning alerts.
+- **JSON Reporter**: Machine-readable output for custom scripts and dashboard ingestion.
+
+---
+
+## 8. Codebase Directory Map
+
+```text
+src/qv/
+├── __init__.py                # Package version and public exports
+├── cli.py                     # Click CLI entry point and subcommands
+├── core/
+│   ├── config.py              # [tool.qv] configuration loader
+│   ├── context.py             # ProjectContext discovery & data ingestion
+│   ├── models.py              # Diagnostic, Severity, ScanResult dataclasses
+│   └── rules.py               # RuleCatalog registry
+├── analyzers/
+│   ├── dependencies/          # DEP-001 through DEP-006 analyzers
+│   ├── environment/           # ENV-001 through ENV-003 analyzers
+│   ├── imports/               # IMP-001 through IMP-004 analyzers
+│   └── packaging/             # PKG-001 and PKG-002 analyzers
+├── remediation/
+│   ├── engine.py              # Remediation planner and fix executor
+│   └── actions.py             # Atomic manifest & TOML fix handlers
+├── reporters/
+│   ├── terminal.py            # Rich console output formatting
+│   ├── html.py                # Standalone HTML report generator
+│   ├── sarif.py               # SARIF v2.1.0 generator
+│   ├── json.py                # JSON exporter
+│   └── github.py              # GitHub Actions PR annotation emitter
+├── tui/
+│   └── dashboard.py           # Interactive Rich terminal explorer
+└── visualizers/
+    └── tree.py                # Dependency & circular import visualizer
+```

python_qv-0.1.3/docs/assets/favicon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="#09090B" stroke="#27272A" stroke-width="1.5" />
+  
+  <!-- 'q' glyph -->
+  <circle cx="23" cy="29" r="9" fill="none" stroke="#FFFFFF" stroke-width="4.2" />
+  <path d="M32 20 L32 44" stroke="#FFFFFF" stroke-width="4.2" stroke-linecap="round" />
+
+  <!-- 'v' glyph -->
+  <path d="M37 23 L44 39 L51 23" fill="none" stroke="#E4E4E7" stroke-width="4.2" stroke-linecap="round" stroke-linejoin="round" />
+</svg>

python_qv-0.1.3/docs/assets/logo.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" width="100%" height="100%">
+  <!-- Background Badge / Squircle -->
+  <rect x="8" y="8" width="104" height="104" rx="26" fill="#09090B" stroke="#27272A" stroke-width="2" />
+
+  <!-- Subtle inner ambient frame -->
+  <rect x="14" y="14" width="92" height="92" rx="20" fill="none" stroke="#18181B" stroke-width="1" />
+
+  <!-- 'q' glyph -->
+  <circle cx="44" cy="54" r="16" fill="none" stroke="#FFFFFF" stroke-width="7" />
+  <path d="M60 38 L60 80" stroke="#FFFFFF" stroke-width="7" stroke-linecap="round" />
+
+  <!-- 'v' glyph -->
+  <path d="M68 42 L80 72 L92 42" fill="none" stroke="#E4E4E7" stroke-width="7" stroke-linecap="round" stroke-linejoin="round" />
+
+  <!-- Diagnostic focal dot -->
+  <circle cx="94" cy="34" r="3" fill="#A1A1AA" />
+</svg>

{python_qv-0.1.1 → python_qv-0.1.3}/docs/ci_integration.md

@@ -4,7 +4,7 @@
 
 ---
 
-## Official GitHub Action (`inzamol/qv`)
+## 1. Official GitHub Action (`inzamol/qv`)
 
 Use the official composite GitHub Action to run `qv` with automated PR annotations and step summaries:
 
@@ -28,9 +28,9 @@ jobs:
 
 ---
 
-## Custom CI Configuration
+## 2. Custom CI Configuration
 
-### Basic CI Check
+### 2.1 Basic CI Check
 
 Add a step to your `.github/workflows/ci.yml`:
 
@@ -52,7 +52,7 @@ jobs:
 
 ---
 
-### GitHub Code Scanning with SARIF
+### 2.2 GitHub Code Scanning with SARIF
 
 `qv` supports emitting findings in **SARIF v2.1.0** format for GitHub Advanced Security and Code Scanning:
 
@@ -84,7 +84,7 @@ jobs:
 
 ---
 
-## Pre-commit Integration
+## 3. Pre-commit Integration
 
 `qv` provides native pre-commit hooks via `.pre-commit-hooks.yaml`.
 
@@ -103,7 +103,7 @@ repos:
       # - id: qv-fix
 ```
 
-### Available Hooks
+### 3.1 Available Hooks
 
 | Hook ID | Description | Default Command |
 |---|---|---|
@@ -112,7 +112,7 @@ repos:
 
 ---
 
-## Exit Codes for CI Pipelines
+## 4. Exit Codes for CI Pipelines
 
 - `0`: Success — no blocking findings.
 - `1`: Failure — errors found (or warnings in `--strict` / `--ci` mode).

{python_qv-0.1.1 → python_qv-0.1.3}/docs/cli_reference.md

@@ -4,7 +4,7 @@
 
 ---
 
-## Global Options
+## 1. Global Options
 
 ```bash
 qv --help
@@ -13,7 +13,27 @@ qv --version
 
 ---
 
-## `qv scan`
+## 2. `qv init`
+
+Generates or updates the `[tool.qv]` configuration block in your `pyproject.toml` without overwriting existing settings.
+
+```bash
+qv init [PATH]
+```
+
+Example:
+
+```bash
+# Initialize [tool.qv] in current directory
+qv init
+
+# Initialize in a specific project path
+qv init ./services/backend
+```
+
+---
+
+## 3. `qv scan`
 
 Runs full diagnostic analysis on the specified directory.
 
@@ -21,13 +41,13 @@ Runs full diagnostic analysis on the specified directory.
 qv scan [PATH] [OPTIONS]
 ```
 
-### Arguments
+### 3.1 Arguments
 
 | Argument | Description | Default |
 |---|---|---|
 | `PATH` | Path to the project root directory | `.` (current directory) |
 
-### Options
+### 3.2 Options
 
 | Option | Description |
 |---|---|
@@ -40,7 +60,7 @@ qv scan [PATH] [OPTIONS]
 | `--offline` | Disables remote vulnerability/CVE queries (airgapped mode) |
 | `--output`, `-o <FILE>` | Writes output directly to a file |
 
-### Exit Codes
+### 3.3 Exit Codes
 
 | Exit Code | Meaning |
 |---|---|
@@ -51,7 +71,7 @@ qv scan [PATH] [OPTIONS]
 
 ---
 
-## `qv inspect` (alias: `qv ui`)
+## 4. `qv inspect` (alias: `qv ui`)
 
 Launches an interactive terminal dashboard (TUI) to navigate findings, expand evidence, view dependency trees, and apply fixes interactively with keyboard shortcuts.
 
@@ -60,7 +80,7 @@ qv inspect [PATH] [OPTIONS]
 qv ui [PATH] [OPTIONS]
 ```
 
-### Controls
+### 4.1 Controls
 
 | Key | Action |
 |---|---|
@@ -73,7 +93,7 @@ qv ui [PATH] [OPTIONS]
 
 ---
 
-## `qv fix`
+## 5. `qv fix`
 
 Safely and automatically fixes detectable diagnostic health issues (e.g., adding missing dependencies to `pyproject.toml`, removing unused dependencies, initializing packaging metadata).
 
@@ -81,7 +101,7 @@ Safely and automatically fixes detectable diagnostic health issues (e.g., adding
 qv fix [PATH] [OPTIONS]
 ```
 
-### Options
+### 5.1 Options
 
 | Option | Description |
 |---|---|
@@ -102,7 +122,7 @@ qv fix -y
 
 ---
 
-## `qv tree` / `qv graph`
+## 6. `qv tree` / `qv graph`
 
 Visualizes direct vs transitive package dependencies and internal source module import architecture (with circular import cycles highlighted).
 
@@ -110,7 +130,7 @@ Visualizes direct vs transitive package dependencies and internal source module
 qv tree [PATH] [OPTIONS]
 ```
 
-### Options
+### 6.1 Options
 
 | Option | Description |
 |---|---|
@@ -134,7 +154,7 @@ qv tree -d -L 2
 
 ---
 
-## `qv explain`
+## 7. `qv explain`
 
 Displays detailed explanations, evidence requirements, and remediation instructions for a rule.
 
@@ -150,37 +170,52 @@ qv explain DEP-002
 
 ---
 
-## `qv init`
-
-Generates or updates the `[tool.qv]` configuration block in your `pyproject.toml`.
-
-```bash
-qv init [PATH]
-```
-
----
-
-## Targeted Subsystem Commands
+## 8. Targeted Subsystem Commands
 
 Run focused checks on specific areas without executing the full scan:
 
-### `qv dependency`
+### 8.1 `qv dependency`
 Scans for dependency conflicts, missing imports, unused packages, and version mismatches.
 
 ```bash
 qv dependency [PATH]
 ```
 
-### `qv environment`
+### 8.2 `qv environment`
 Checks for Python runtime drift between local environment, Dockerfiles, and CI matrices.
 
 ```bash
 qv environment [PATH]
 ```
 
-### `qv architecture`
+### 8.3 `qv architecture`
 Scans source code for circular imports and unresolved internal modules.
 
 ```bash
 qv architecture [PATH]
 ```
+
+### 8.4 `qv framework` (alias: `qv frameworks`)
+Runs framework-specific diagnostic rules (e.g. FastAPI async blocking calls, SQLAlchemy N+1 queries, unclosed sessions, SQL injection, pool leaks).
+
+```bash
+qv framework [PATH] [OPTIONS]
+```
+
+Options:
+- `-n, --name [fastapi|sqlalchemy|sql|all]`: Filter analysis to a specific framework (default: all detected frameworks).
+- `--json`: Output framework scan results as structured JSON.
+- `--sarif`: Output framework scan results in SARIF v2.1.0 format.
+
+Example:
+```bash
+# Scan current project for all framework issues
+qv framework
+
+# Scan specifically for FastAPI issues
+qv framework --name fastapi
+
+# Scan specifically for SQLAlchemy / SQL database issues
+qv framework --name sqlalchemy
+```
+

{python_qv-0.1.1 → python_qv-0.1.3}/docs/configuration.md

@@ -4,7 +4,7 @@
 
 ---
 
-## Example `pyproject.toml`
+## 1. Example `pyproject.toml`
 
 ```toml
 [tool.qv]
@@ -38,7 +38,7 @@ python = "3.12"
 
 ---
 
-## Severity Overrides
+## 2. Severity Overrides
 
 You can adjust how strictly any rule is treated:
 
@@ -51,7 +51,7 @@ You can adjust how strictly any rule is treated:
 
 ---
 
-## Ignore Rules
+## 3. Ignore Rules
 
 To suppress rules that are not applicable to your workflow, list them under `[tool.qv.ignore]`:
 
@@ -62,7 +62,7 @@ rules = ["DEP-003", "ENV-002"]
 
 ---
 
-## Precedence Order
+## 4. Precedence Order
 
 When resolving configuration, `qv` follows this precedence: