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

python_qv-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,73 @@
+name: 🐛 Bug Report
+description: Report unexpected behavior, inaccurate diagnostics, or crashes in qv.
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report an issue! Please search existing issues before filing a duplicate.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe the problem...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Provide the command and minimal project layout to reproduce the issue.
+      placeholder: |
+        1. Run `qv scan` on a project with ...
+        2. Expected output: ...
+        3. Actual output: ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: command_output
+    attributes:
+      label: Command Output / Error Trace
+      description: Paste the output of `qv scan` or stack trace here.
+      render: text
+    validations:
+      required: false
+
+  - type: dropdown
+    id: package_manager
+    attributes:
+      label: Package Manager
+      description: Which package manager was used in the scanned project?
+      options:
+        - uv
+        - poetry
+        - pip / requirements.txt
+        - pdm
+        - pipenv
+        - Other / None
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: Environment & Versions
+      description: Output of `qv version`, Python version, and OS.
+      placeholder: qv v0.1.0, Python 3.12.7, Ubuntu 24.04 / Windows 11 / macOS 14
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checkboxes
+    attributes:
+      label: Checklist
+      options:
+        - label: I have verified this is not a duplicate of an existing issue.
+          required: true
+        - label: I can reproduce this on the latest version of `qv`.
+          required: true

python_qv-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 📖 Documentation
+    url: https://qv.readthedocs.io/
+    about: Read the official documentation and guides.
+  - name: 💬 Discussions & Questions
+    url: https://github.com/inzamol/qv/discussions
+    about: Ask questions, share ideas, and discuss with the community.

python_qv-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,43 @@
+name: 💡 Feature Request
+description: Suggest a new capability, visualizer, reporter, or CLI option for qv.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea to make `qv` better? Tell us about your proposal!
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: Is your feature request related to a specific pain point or workflow limitation?
+      placeholder: I'm always frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed_solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution or new command/flag you'd like to see.
+      placeholder: Add a `--watch` flag to `qv scan` that...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Considered Alternatives
+      description: Describe any alternative solutions or workarounds you've evaluated.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: willingness
+    attributes:
+      label: Contribution
+      options:
+        - label: I would be interested in submitting a Pull Request to implement this.
+          required: false

python_qv-0.1.1/.github/ISSUE_TEMPLATE/rule_proposal.yml

@@ -0,0 +1,56 @@
+name: 📋 New Diagnostic Rule Proposal
+description: Propose a new diagnostic check, code smell detection, or ecosystem drift rule.
+title: "[Rule Proposal]: "
+labels: ["rules", "enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Diagnostic rules in `qv` detect real ecosystem friction, configuration bugs, or runtime hazards.
+
+  - type: input
+    id: suggested_rule_id
+    attributes:
+      label: Proposed Rule Category & ID
+      description: e.g. `DEP-xxx` (Dependencies), `ENV-xxx` (Environment), `IMP-xxx` (Imports), `PKG-xxx` (Packaging)
+      placeholder: DEP-007
+    validations:
+      required: true
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Rule Summary & Objective
+      description: What specific condition or bug does this rule identify?
+      placeholder: Detect when a requirement in pyproject.toml has an unpinned upper bound...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Default Severity
+      options:
+        - ERROR (Blocking hazard or broken project)
+        - WARNING (Sub-optimal or risky configuration)
+        - INFO (Advisory metric)
+    validations:
+      required: true
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Deterministic Evidence Sources
+      description: Where does the evidence come from without making external network calls?
+      placeholder: AST import nodes, pyproject.toml table parsing, etc.
+    validations:
+      required: true
+
+  - type: textarea
+    id: remediation
+    attributes:
+      label: Remediation Strategy & Fix
+      description: What actionable command or edit will resolve the issue?
+      placeholder: Run `uv add ...` or update the manifest table.
+    validations:
+      required: true

python_qv-0.1.1/.github/pull_request_template.md

@@ -0,0 +1,32 @@
+## 📝 Description
+
+Briefly describe the changes introduced in this Pull Request, including the problem solved or feature added.
+
+---
+
+## 🔗 Related Issues
+
+- Fixes #(issue)
+- Closes #(issue)
+
+---
+
+## 🧪 Type of Change
+
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature / rule (non-breaking change which adds new diagnostic or visualizer)
+- [ ] ⚡ Performance improvement
+- [ ] 📖 Documentation update
+- [ ] 🧹 Refactoring or code quality cleanup
+
+---
+
+## ✅ Quality Checklist
+
+- [ ] I have read the [Contributing Guidelines](https://github.com/inzamol/qv/blob/main/docs/contributing.md).
+- [ ] My code adheres to strict type annotations and passes `uv run pyright`.
+- [ ] My code passes linting and formatting via `uv run ruff check .` and `uv run ruff format --check .`.
+- [ ] I have added comprehensive unit tests covering positive and negative cases under `tests/`.
+- [ ] All tests pass locally with `uv run pytest`.
+- [ ] Multi-environment matrix passes locally with `uv run tox`.
+- [ ] If adding a new rule or CLI option, I have updated the relevant documentation in `docs/` and `README.md`.

python_qv-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test Matrix (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install all dependencies
+        run: uv sync --all-extras
+
+      - name: Lint with Ruff
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Static Type Checking with Pyright
+        run: uv run pyright
+
+      - name: Run Test Suite
+        run: uv run pytest --cov=src/qv --cov-report=term-missing
+
+      - name: Self Health Scan (Dogfooding qv)
+        run: uv run qv scan --strict --ci --github-annotations
+
+  docs:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build Docs in Strict Mode
+        run: uv run mkdocs build --strict

{python_qv-0.1.0 → python_qv-0.1.1}/.github/workflows/publish.yml

@@ -1,12 +1,12 @@
-name: Publish to PyPI
+name: Publish to PyPI & GitHub Release
 
 on:
-  release:
-    types: [published]
   push:
     tags:
       - "v[0-9]+.[0-9]+.[0-9]+"
       - "v[0-9]+.[0-9]+.[0-9]+-*"
+  release:
+    types: [published]
   workflow_dispatch:
     inputs:
       target:
@@ -24,7 +24,7 @@ concurrency:
 
 jobs:
   validate:
-    name: Run Test Suite (Pre-flight)
+    name: Validate Tag, Lint & Test Suite
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -42,23 +42,59 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
-      - name: Install dependencies
-        run: uv sync --all-extras --dev
+      - name: Install all dependencies
+        run: uv sync --all-extras
 
-      - name: Lint and type check
+      - name: Validate Git Tag vs Package Version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          uv run python -c "
+          import os, sys
+          from pathlib import Path
+          try:
+              import tomllib
+          except ImportError:
+              import tomli as tomllib
+
+          tag = os.environ.get('GITHUB_REF_NAME', '')
+          if not tag.startswith('v'):
+              sys.exit(0)
+          tag_ver = tag.lstrip('v')
+          pyproject = tomllib.loads(Path('pyproject.toml').read_text(encoding='utf-8'))
+          toml_ver = pyproject.get('project', {}).get('version', '')
+
+          from qv import __version__ as code_ver
+
+          errors = []
+          if tag_ver != toml_ver:
+              errors.append(f'Git tag version ({tag_ver}) != pyproject.toml version ({toml_ver})')
+          if tag_ver != code_ver:
+              errors.append(f'Git tag version ({tag_ver}) != qv.__version__ ({code_ver})')
+
+          if errors:
+              for err in errors:
+                  print(f'::error::{err}')
+              sys.exit(1)
+          print(f'✓ Tag {tag} strictly matches pyproject.toml and qv.__version__ ({tag_ver})')
+          "
+
+      - name: Lint and formatting checks
         run: |
           uv run ruff check .
           uv run ruff format --check .
 
-      - name: Run test suite
-        run: uv run pytest --cov=qv --cov-report=term-missing
+      - name: Static type checking
+        run: uv run pyright
+
+      - name: Run test suite with coverage
+        run: uv run pytest --cov=src/qv --cov-report=term-missing
 
   build:
-    name: Build & Verify Distributions
+    name: Build, Attest & Release Assets
     needs: [validate]
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write
       id-token: write
       attestations: write
 
@@ -88,10 +124,19 @@ jobs:
           path: dist/
           if-no-files-found: error
 
+      - name: Create or Update GitHub Release with Notes
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: contains(github.ref, '-')
+
   publish-to-pypi:
     name: Publish to PyPI
     needs: [build]
-    if: (github.event_name == 'release' && github.event.action == 'published') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) || (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi')
+    if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'release' && github.event.action == 'published') || (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi')
     runs-on: ubuntu-latest
     environment:
       name: pypi

{python_qv-0.1.0 → python_qv-0.1.1}/.gitignore

@@ -56,6 +56,9 @@ htmlcov/
 .DS_Store
 Thumbs.db
 
+# Documentation builds
+site/
+
 # Internal developer design docs
 dev_docs/
 

python_qv-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,43 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check & fix
+        entry: uv run ruff check --fix .
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format .
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]
+
+      - id: qv-scan
+        name: qv health scan
+        entry: uv run qv scan
+        language: system
+        args: [--strict, --offline]
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]
+
+      - id: pytest-check
+        name: pytest test suite
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit, pre-push]
+
+      - id: pyright-check
+        name: pyright typecheck
+        entry: uv run pyright
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit, pre-push]

python_qv-0.1.1/.pre-commit-hooks.yaml

@@ -0,0 +1,17 @@
+- id: qv-scan
+  name: qv scan
+  description: Diagnose Python project health, dependencies, and environment consistency
+  entry: qv scan
+  language: python
+  types_or: [python, toml, yaml, dockerfile]
+  pass_filenames: false
+  always_run: true
+
+- id: qv-fix
+  name: qv fix
+  description: Automatically remediate safe Python project health issues
+  entry: qv fix -y
+  language: python
+  types_or: [python, toml]
+  pass_filenames: false
+  always_run: true

python_qv-0.1.1/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_create_environment:
+      # Install uv for fast dependency resolution
+      - pip install uv
+    post_install:
+      # Install docs dependencies using uv
+      - uv pip install --system -e ".[docs]"
+
+mkdocs:
+  configuration: mkdocs.yml

python_qv-0.1.1/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2026-10-01
+
+Initial public release of `qv` — the proactive health diagnostics and remediation platform for Python projects.
+
+### Added
+- **Diagnostic Engine & Analyzers**:
+  - `DEP-001`: Dependency version constraint conflict detection.
+  - `DEP-002`: Missing undeclared package imports.
+  - `DEP-003`: Unused declared dependencies.
+  - `DEP-004`: Python target runtime incompatibility.
+  - `DEP-005`: Virtualenv vs declared pin drift.
+  - `DEP-006`: Known vulnerability/CVE reporting.
+  - `ENV-001`: Python interpreter version drift.
+  - `ENV-002`: Dockerfile base image Python version drift.
+  - `ENV-003`: CI matrix coverage drift.
+  - `IMP-001`: Circular import cycle detection with Tarjan's SCC algorithm.
+  - `IMP-002`: Unresolvable internal module imports.
+  - `IMP-003`: Orphan / dead internal modules.
+  - `IMP-004`: Deprecated / removed standard library modules (PEP 594).
+  - `PKG-001`: Missing PEP 621 packaging metadata.
+  - `PKG-002`: Invalid `pyproject.toml` syntax.
+- **Reporting & Visualizers**:
+  - Interactive Terminal Explorer (TUI) with keyboard navigation (`qv inspect`, `qv ui`).
+  - Self-contained, single-file interactive HTML report generator (`qv scan --html`).
+  - Standard SARIF v2.1.0 report exporter (`qv scan --sarif`).
+  - Machine-readable JSON reporter (`qv scan --json`).
+  - Color-coded Rich terminal reporter with circular health score gauge.
+  - Dependency and import architecture visualizers (`qv tree`, `qv graph`).
+- **Remediation**:
+  - Safe automated fix engine (`qv fix`) with dry-run previews, interactive confirmations, and package manager sync.
+- **Ecosystem & CI/CD**:
+  - Native pre-commit hooks (`qv-scan`, `qv-fix`).
+  - Official GitHub Action (`action.yml`) with automated PR annotations and Step Summary markdown.
+  - Automated PyPI publishing workflow with SLSA build provenance attestations.
+  - Comprehensive documentation site built with MkDocs Material and configured for ReadTheDocs.