python-qv 0.1.0__py3-none-any.whl

qv/analyzers/docker/__init__.py

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

qv/analyzers/environment/__init__.py

@@ -0,0 +1,5 @@
+"""Environment analyzers."""
+
+from qv.analyzers.environment.drift import EnvironmentAnalyzer
+
+__all__ = ["EnvironmentAnalyzer"]

qv/analyzers/environment/drift.py

@@ -0,0 +1,164 @@
+"""Environment analyzer implementing ENV-001, ENV-002, ENV-003."""
+
+from __future__ import annotations
+
+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
+
+
+class EnvironmentAnalyzer:
+    """Analyzes runtime environments, Dockerfiles, and CI matrices for drift."""
+
+    id = "environment"
+    name = "Environment Analyzer"
+    description = (
+        "Checks for Python runtime drift, Docker runtime drift, and CI test matrix mismatches."
+    )
+
+    def analyze(self, context: ProjectContext) -> list[Diagnostic]:
+        diagnostics: list[Diagnostic] = []
+
+        diagnostics.extend(self._check_python_version_drift(context))
+        diagnostics.extend(self._check_docker_drift(context))
+        diagnostics.extend(self._check_ci_drift(context))
+
+        return diagnostics
+
+    def _check_python_version_drift(self, context: ProjectContext) -> list[Diagnostic]:
+        """ENV-001: Check if running Python satisfies project requires-python or config."""
+        diagnostics: list[Diagnostic] = []
+        rule = get_rule_definition("ENV-001")
+        if not rule:
+            return diagnostics
+
+        target_python = context.config.get("target_python")
+        if target_python:
+            try:
+                spec = SpecifierSet(
+                    target_python
+                    if any(c in target_python for c in "<>=~!")
+                    else f"=={target_python}.*"
+                )
+                current_ver = Version(context.python_runtime.version_str)
+                if not spec.contains(current_ver):
+                    diagnostics.append(
+                        Diagnostic(
+                            id=rule.id,
+                            severity=rule.default_severity,
+                            category=rule.category,
+                            title=rule.title,
+                            message=f"Active Python {context.python_runtime.version_str} does not match target Python {target_python}.",
+                            evidence=[
+                                Evidence(
+                                    fact=f"Active Python version: {context.python_runtime.version_str}",
+                                    source=context.python_runtime.executable
+                                    or "Active Interpreter",
+                                ),
+                                Evidence(
+                                    fact=f"Configured Python target: {target_python}",
+                                    source="pyproject.toml",
+                                ),
+                            ],
+                            suggestions=[
+                                Suggestion(
+                                    description=f"Use Python {target_python} for your virtual environment.",
+                                    command=f"uv venv --python {target_python}"
+                                    if context.package_manager == "uv"
+                                    else None,
+                                )
+                            ],
+                            doc_url=rule.doc_url,
+                        )
+                    )
+            except Exception:
+                pass
+
+        return diagnostics
+
+    def _check_docker_drift(self, context: ProjectContext) -> list[Diagnostic]:
+        """ENV-002: Check Dockerfile Python version against target/active Python."""
+        diagnostics: list[Diagnostic] = []
+        rule = get_rule_definition("ENV-002")
+        if not rule or not context.docker.has_dockerfile or not context.docker.base_python_version:
+            return diagnostics
+
+        docker_py = context.docker.base_python_version
+        active_py = f"{context.python_runtime.major}.{context.python_runtime.minor}"
+
+        if docker_py != active_py:
+            rel_docker = (
+                context.docker.dockerfile_path.relative_to(context.project_root)
+                if context.docker.dockerfile_path
+                and context.docker.dockerfile_path.is_relative_to(context.project_root)
+                else "Dockerfile"
+            )
+            diagnostics.append(
+                Diagnostic(
+                    id=rule.id,
+                    severity=rule.default_severity,
+                    category=rule.category,
+                    title=rule.title,
+                    message=f"Dockerfile base image uses Python {docker_py}, while local runtime is {active_py}.",
+                    evidence=[
+                        Evidence(
+                            fact=f"Dockerfile base image: {context.docker.base_image}",
+                            source=str(rel_docker),
+                        ),
+                        Evidence(
+                            fact=f"Local Python version: {context.python_runtime.version_str}",
+                            source="Local environment",
+                        ),
+                    ],
+                    suggestions=[
+                        Suggestion(
+                            description=f"Update base image in {rel_docker} to use python:{active_py}-slim.",
+                            code_snippet=f"FROM python:{active_py}-slim",
+                        )
+                    ],
+                    file=str(rel_docker),
+                    doc_url=rule.doc_url,
+                )
+            )
+
+        return diagnostics
+
+    def _check_ci_drift(self, context: ProjectContext) -> list[Diagnostic]:
+        """ENV-003: Check CI workflow python versions against active/target python."""
+        diagnostics: list[Diagnostic] = []
+        rule = get_rule_definition("ENV-003")
+        if not rule or not context.ci.has_ci or not context.ci.matrix_python_versions:
+            return diagnostics
+
+        active_major_minor = f"{context.python_runtime.major}.{context.python_runtime.minor}"
+        if active_major_minor not in context.ci.matrix_python_versions:
+            diagnostics.append(
+                Diagnostic(
+                    id=rule.id,
+                    severity=rule.default_severity,
+                    category=rule.category,
+                    title=rule.title,
+                    message=f"Local Python {active_major_minor} is not tested in CI matrix ({', '.join(context.ci.matrix_python_versions)}).",
+                    evidence=[
+                        Evidence(
+                            fact=f"CI test matrix versions: {', '.join(context.ci.matrix_python_versions)}",
+                            source="CI workflows",
+                        ),
+                        Evidence(
+                            fact=f"Local Python version: {active_major_minor}",
+                            source="Local environment",
+                        ),
+                    ],
+                    suggestions=[
+                        Suggestion(
+                            description=f"Add '{active_major_minor}' to your CI matrix configuration.",
+                        )
+                    ],
+                    doc_url=rule.doc_url,
+                )
+            )
+
+        return diagnostics

qv/analyzers/imports/__init__.py

@@ -0,0 +1,5 @@
+"""Import analyzers."""
+
+from qv.analyzers.imports.analyzer import ImportAnalyzer
+
+__all__ = ["ImportAnalyzer"]

qv/analyzers/imports/analyzer.py

@@ -0,0 +1,160 @@
+"""Import and Architecture analyzer implementing IMP-001 and IMP-002."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from qv.core.context import ProjectContext
+from qv.core.models import Diagnostic, Evidence, Suggestion
+from qv.rules.registry import get_rule_definition
+
+
+class ImportAnalyzer:
+    """Analyzes import graphs for circular dependencies and unresolved local imports."""
+
+    id = "imports"
+    name = "Import & Architecture Analyzer"
+    description = "Detects circular imports and unresolved internal modules."
+
+    def analyze(self, context: ProjectContext) -> list[Diagnostic]:
+        diagnostics: list[Diagnostic] = []
+
+        diagnostics.extend(self._check_circular_imports(context))
+        diagnostics.extend(self._check_unresolved_local_imports(context))
+
+        return diagnostics
+
+    def _check_circular_imports(self, context: ProjectContext) -> list[Diagnostic]:
+        """IMP-001: Detect cycles in local import graph."""
+        diagnostics: list[Diagnostic] = []
+        rule = get_rule_definition("IMP-001")
+        if not rule or not context.source_files:
+            return diagnostics
+
+        # Build module mapping
+        module_to_file: dict[str, str] = {}
+        file_to_module: dict[str, str] = {}
+        for sf in context.source_files:
+            module_to_file[sf.module_name] = str(sf.relative_path)
+            file_to_module[str(sf.path)] = sf.module_name
+
+        # Build graph
+        graph: dict[str, set[str]] = defaultdict(set)
+        for imp in context.imports:
+            src_mod = file_to_module.get(str(imp.source_file))
+            if not src_mod:
+                continue
+
+            target_mod = imp.module_name
+            # If target module is in project
+            if target_mod in module_to_file and target_mod != src_mod:
+                graph[src_mod].add(target_mod)
+
+        # Detect cycles using DFS
+        visited: set[str] = set()
+        recursion_stack: list[str] = []
+        detected_cycles: list[list[str]] = []
+
+        def dfs(node: str) -> None:
+            visited.add(node)
+            recursion_stack.append(node)
+
+            for neighbor in graph.get(node, []):
+                if neighbor not in visited:
+                    dfs(neighbor)
+                elif neighbor in recursion_stack:
+                    # Cycle found
+                    idx = recursion_stack.index(neighbor)
+                    cycle = recursion_stack[idx:] + [neighbor]
+                    detected_cycles.append(cycle)
+
+            recursion_stack.pop()
+
+        for mod in list(graph.keys()):
+            if mod not in visited:
+                dfs(mod)
+
+        # Format diagnostics for cycles
+        seen_cycle_sets = set()
+        for cycle in detected_cycles:
+            cycle_key = tuple(sorted(set(cycle)))
+            if cycle_key in seen_cycle_sets:
+                continue
+            seen_cycle_sets.add(cycle_key)
+
+            cycle_str = " -> ".join(cycle)
+            primary_mod = cycle[0]
+            rel_file = module_to_file.get(primary_mod, primary_mod)
+
+            diagnostics.append(
+                Diagnostic(
+                    id=rule.id,
+                    severity=rule.default_severity,
+                    category=rule.category,
+                    title="Circular import detected",
+                    message=f"Circular import cycle detected: {cycle_str}",
+                    evidence=[
+                        Evidence(
+                            fact=f"Import chain: {cycle_str}",
+                            source=rel_file,
+                        )
+                    ],
+                    suggestions=[
+                        Suggestion(
+                            description=f"Break the cycle between {cycle[0]} and {cycle[1]} by refactoring shared logic into a separate module or using deferred imports inside functions.",
+                        )
+                    ],
+                    file=rel_file,
+                    doc_url=rule.doc_url,
+                )
+            )
+
+        return diagnostics
+
+    def _check_unresolved_local_imports(self, context: ProjectContext) -> list[Diagnostic]:
+        """IMP-002: Detect local imports that cannot be resolved to any project source file."""
+        diagnostics: list[Diagnostic] = []
+        rule = get_rule_definition("IMP-002")
+        if not rule or not context.source_files:
+            return diagnostics
+
+        known_modules = {sf.module_name for sf in context.source_files}
+
+        for imp in context.imports:
+            if not imp.module_name:
+                continue
+
+            # If it's a relative import or clearly aiming at a known root
+            if imp.is_relative:
+                rel_path = (
+                    imp.source_file.relative_to(context.project_root)
+                    if imp.source_file.is_relative_to(context.project_root)
+                    else imp.source_file
+                )
+                # If relative and target module is empty or not in known modules
+                if imp.module_name and imp.module_name not in known_modules:
+                    diagnostics.append(
+                        Diagnostic(
+                            id=rule.id,
+                            severity=rule.default_severity,
+                            category=rule.category,
+                            title=f"Unresolved relative import: {imp.module_name}",
+                            message=f"Module '{imp.module_name}' imported at {rel_path}:{imp.line_number} could not be resolved.",
+                            evidence=[
+                                Evidence(
+                                    fact=f"Relative import statement at {rel_path}:{imp.line_number}",
+                                    source=str(rel_path),
+                                )
+                            ],
+                            suggestions=[
+                                Suggestion(
+                                    description=f"Verify target file exists or correct relative import path in {rel_path}.",
+                                )
+                            ],
+                            file=str(rel_path),
+                            line=imp.line_number,
+                            doc_url=rule.doc_url,
+                        )
+                    )
+
+        return diagnostics

qv/analyzers/packaging/__init__.py

@@ -0,0 +1,5 @@
+"""Packaging analyzers."""
+
+from qv.analyzers.packaging.analyzer import PackagingAnalyzer
+
+__all__ = ["PackagingAnalyzer"]

qv/analyzers/packaging/analyzer.py

@@ -0,0 +1,117 @@
+"""Packaging analyzer implementing PKG-001 and PKG-002."""
+
+from __future__ import annotations
+
+import sys
+
+from qv.core.context import ProjectContext
+from qv.core.models import Diagnostic, Evidence, Suggestion
+from qv.rules.registry import get_rule_definition
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+class PackagingAnalyzer:
+    """Analyzes pyproject.toml and packaging metadata for validity and completeness."""
+
+    id = "packaging"
+    name = "Packaging Analyzer"
+    description = (
+        "Checks pyproject.toml and project metadata for PEP 621 compliance and completeness."
+    )
+
+    def analyze(self, context: ProjectContext) -> list[Diagnostic]:
+        diagnostics: list[Diagnostic] = []
+        pyproject_path = context.project_root / "pyproject.toml"
+
+        if not pyproject_path.exists():
+            return diagnostics
+
+        try:
+            with open(pyproject_path, "rb") as f:
+                data = tomllib.load(f)
+        except Exception as e:
+            rule_pkg002 = get_rule_definition("PKG-002")
+            if rule_pkg002:
+                diagnostics.append(
+                    Diagnostic(
+                        id=rule_pkg002.id,
+                        severity=rule_pkg002.default_severity,
+                        category=rule_pkg002.category,
+                        title=rule_pkg002.title,
+                        message=f"Failed to parse pyproject.toml: {e}",
+                        evidence=[
+                            Evidence(
+                                fact=str(e),
+                                source="pyproject.toml",
+                            )
+                        ],
+                        suggestions=[
+                            Suggestion(
+                                description="Check TOML syntax in pyproject.toml for missing quotes, brackets, or invalid keys.",
+                            )
+                        ],
+                        file="pyproject.toml",
+                        doc_url=rule_pkg002.doc_url,
+                    )
+                )
+            return diagnostics
+
+        # Check PKG-001: Missing metadata
+        rule_pkg001 = get_rule_definition("PKG-001")
+        if rule_pkg001:
+            project_table = data.get("project")
+            poetry_table = data.get("tool", {}).get("poetry")
+
+            if project_table is None and poetry_table is None:
+                diagnostics.append(
+                    Diagnostic(
+                        id=rule_pkg001.id,
+                        severity=rule_pkg001.default_severity,
+                        category=rule_pkg001.category,
+                        title="Missing [project] metadata in pyproject.toml",
+                        message="pyproject.toml does not contain a standard PEP 621 [project] table or tool metadata table.",
+                        evidence=[
+                            Evidence(
+                                fact="Neither [project] nor [tool.poetry] table found in pyproject.toml",
+                                source="pyproject.toml",
+                            )
+                        ],
+                        suggestions=[
+                            Suggestion(
+                                description="Add a [project] table with name, version, and dependencies.",
+                            )
+                        ],
+                        file="pyproject.toml",
+                        doc_url=rule_pkg001.doc_url,
+                    )
+                )
+            elif project_table is not None:
+                if not project_table.get("name"):
+                    diagnostics.append(
+                        Diagnostic(
+                            id=rule_pkg001.id,
+                            severity=rule_pkg001.default_severity,
+                            category=rule_pkg001.category,
+                            title="Missing project name in [project] table",
+                            message="[project] table in pyproject.toml is missing the required 'name' field.",
+                            evidence=[
+                                Evidence(
+                                    fact="'name' field is missing or empty in [project]",
+                                    source="pyproject.toml",
+                                )
+                            ],
+                            suggestions=[
+                                Suggestion(
+                                    description='Add name = "my-project" to [project].',
+                                )
+                            ],
+                            file="pyproject.toml",
+                            doc_url=rule_pkg001.doc_url,
+                        )
+                    )
+
+        return diagnostics

qv/analyzers/security/__init__.py

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

qv/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI package for qv."""
+
+from qv.cli.main import cli, main
+
+__all__ = ["cli", "main"]