python-qv 0.1.0__py3-none-any.whl

qv/core/models.py

@@ -0,0 +1,132 @@
+"""Core diagnostic and scan result models."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Severity(str, Enum):
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+    @property
+    def rank(self) -> int:
+        return {"info": 1, "warning": 2, "error": 3}[self.value]
+
+
+class Evidence(BaseModel):
+    """Fact supporting a diagnostic finding."""
+
+    fact: str
+    source: str | None = None
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class Suggestion(BaseModel):
+    """Safe, actionable remediation recommendation."""
+
+    description: str
+    command: str | None = None
+    code_snippet: str | None = None
+    is_safe: bool = True
+
+
+class Diagnostic(BaseModel):
+    """Standardized diagnostic finding emitted by all analyzers."""
+
+    id: str
+    severity: Severity
+    category: str
+    title: str
+    message: str
+    evidence: list[Evidence] = Field(default_factory=list)
+    suggestions: list[Suggestion] = Field(default_factory=list)
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+    affected_packages: list[str] = Field(default_factory=list)
+    file: str | None = None
+    line: int | None = None
+    column: int | None = None
+    dependency_chain: list[str] = Field(default_factory=list)
+    doc_url: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RootCause(BaseModel):
+    """Group of related symptoms belonging to one underlying root cause."""
+
+    id: str
+    title: str
+    summary: str
+    primary_diagnostic: Diagnostic
+    related_diagnostics: list[Diagnostic] = Field(default_factory=list)
+    recommendation: Suggestion
+
+
+class ScanSummary(BaseModel):
+    """High-level summary of a scan run."""
+
+    errors_count: int = 0
+    warnings_count: int = 0
+    info_count: int = 0
+    checks_passed: int = 0
+    health_score: int = 100
+
+
+class ScanResult(BaseModel):
+    """Complete output of a qv scan."""
+
+    project_name: str
+    project_path: str
+    python_version: str
+    package_manager: str
+    summary: ScanSummary
+    diagnostics: list[Diagnostic] = Field(default_factory=list)
+    root_causes: list[RootCause] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def has_blocking_errors(self) -> bool:
+        return self.summary.errors_count > 0
+
+    @classmethod
+    def create(
+        cls,
+        project_name: str,
+        project_path: str,
+        python_version: str,
+        package_manager: str,
+        diagnostics: list[Diagnostic],
+        checks_passed: int = 0,
+        root_causes: list[RootCause] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> ScanResult:
+        errors = sum(1 for d in diagnostics if d.severity == Severity.ERROR)
+        warnings = sum(1 for d in diagnostics if d.severity == Severity.WARNING)
+        infos = sum(1 for d in diagnostics if d.severity == Severity.INFO)
+
+        # Health score calculation (100 base, deductions for errors and warnings)
+        penalty = (errors * 15) + (warnings * 5)
+        health_score = max(0, min(100, 100 - penalty))
+
+        summary = ScanSummary(
+            errors_count=errors,
+            warnings_count=warnings,
+            info_count=infos,
+            checks_passed=checks_passed,
+            health_score=health_score,
+        )
+
+        return cls(
+            project_name=project_name,
+            project_path=project_path,
+            python_version=python_version,
+            package_manager=package_manager,
+            summary=summary,
+            diagnostics=diagnostics,
+            root_causes=root_causes or [],
+            metadata=metadata or {},
+        )

qv/core/project.py

@@ -0,0 +1,330 @@
+"""Project discovery and context builder."""
+
+from __future__ import annotations
+
+import ast
+import importlib.metadata
+import re
+import sys
+from pathlib import Path
+
+from packaging.requirements import Requirement
+
+from qv.core.config import QvConfig
+from qv.core.context import (
+    CIConfig,
+    DependencyDeclaration,
+    DockerConfig,
+    ImportRecord,
+    InstalledDistribution,
+    ProjectContext,
+    PythonRuntime,
+    SourceFile,
+)
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+class ProjectDiscovery:
+    """Discovers project files, manifests, environment, and source files."""
+
+    def __init__(self, root: Path, config: QvConfig | None = None) -> None:
+        self.root = root.resolve()
+        self.config = config or QvConfig.from_pyproject(self.root / "pyproject.toml")
+
+    def discover_context(self) -> ProjectContext:
+        """Build and return an immutable ProjectContext."""
+        pyproject_path = self.root / "pyproject.toml"
+        project_name = self.root.name
+        manifest_files: list[Path] = []
+        lock_files: list[Path] = []
+        dependencies: list[DependencyDeclaration] = []
+
+        # 1. Package manager detection & manifest parsing
+        package_manager = "pip"
+
+        if (self.root / "uv.lock").exists():
+            package_manager = "uv"
+            lock_files.append(self.root / "uv.lock")
+        elif (self.root / "poetry.lock").exists():
+            package_manager = "poetry"
+            lock_files.append(self.root / "poetry.lock")
+        elif (self.root / "pdm.lock").exists():
+            package_manager = "pdm"
+            lock_files.append(self.root / "pdm.lock")
+        elif (self.root / "Pipfile.lock").exists():
+            package_manager = "pipenv"
+            lock_files.append(self.root / "Pipfile.lock")
+
+        # Check pyproject.toml
+        if pyproject_path.exists():
+            manifest_files.append(pyproject_path)
+            try:
+                with open(pyproject_path, "rb") as f:
+                    pyproject_data = tomllib.load(f)
+
+                # Name
+                if "project" in pyproject_data and "name" in pyproject_data["project"]:
+                    project_name = pyproject_data["project"]["name"]
+
+                # Dependencies from [project.dependencies]
+                for dep_str in pyproject_data.get("project", {}).get("dependencies", []):
+                    try:
+                        req = Requirement(dep_str)
+                        dependencies.append(
+                            DependencyDeclaration(
+                                name=req.name,
+                                specifier=str(req.specifier),
+                                source_file=pyproject_path,
+                                extras=tuple(req.extras),
+                            )
+                        )
+                    except Exception:
+                        pass
+
+                # Optional/dev dependencies
+                for group, deps in (
+                    pyproject_data.get("project", {}).get("optional-dependencies", {}).items()
+                ):
+                    is_dev = group in ("dev", "test", "lint")
+                    for dep_str in deps:
+                        try:
+                            req = Requirement(dep_str)
+                            dependencies.append(
+                                DependencyDeclaration(
+                                    name=req.name,
+                                    specifier=str(req.specifier),
+                                    source_file=pyproject_path,
+                                    is_dev=is_dev,
+                                    extras=tuple(req.extras),
+                                )
+                            )
+                        except Exception:
+                            pass
+
+                # Poetry style [tool.poetry.dependencies]
+                poetry_deps = (
+                    pyproject_data.get("tool", {}).get("poetry", {}).get("dependencies", {})
+                )
+                for dep_name, dep_val in poetry_deps.items():
+                    if dep_name.lower() == "python":
+                        continue
+                    spec = dep_val if isinstance(dep_val, str) else str(dep_val.get("version", ""))
+                    dependencies.append(
+                        DependencyDeclaration(
+                            name=dep_name,
+                            specifier=spec,
+                            source_file=pyproject_path,
+                        )
+                    )
+            except Exception:
+                pass
+
+        # Check requirements files
+        req_candidates = [
+            self.root / "requirements.txt",
+            self.root / "requirements-dev.txt",
+            self.root / "requirements" / "base.txt",
+            self.root / "requirements" / "dev.txt",
+            self.root / "requirements" / "prod.txt",
+        ]
+        for req_path in req_candidates:
+            if req_path.exists():
+                manifest_files.append(req_path)
+                is_dev = "dev" in req_path.name.lower()
+                try:
+                    with open(req_path, encoding="utf-8") as f:
+                        for line_idx, line in enumerate(f, 1):
+                            line = line.strip()
+                            if not line or line.startswith("#") or line.startswith("-"):
+                                continue
+                            try:
+                                req = Requirement(line)
+                                dependencies.append(
+                                    DependencyDeclaration(
+                                        name=req.name,
+                                        specifier=str(req.specifier),
+                                        source_file=req_path,
+                                        line_number=line_idx,
+                                        is_dev=is_dev,
+                                        extras=tuple(req.extras),
+                                    )
+                                )
+                            except Exception:
+                                pass
+                except Exception:
+                    pass
+
+        # 2. Python runtime detection
+        is_venv = hasattr(sys, "real_prefix") or (
+            hasattr(sys, "base_prefix") and sys.base_prefix != sys.prefix
+        )
+        runtime = PythonRuntime(
+            version_str=f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+            major=sys.version_info.major,
+            minor=sys.version_info.minor,
+            micro=sys.version_info.micro,
+            executable=sys.executable,
+            is_virtualenv=is_venv,
+            virtualenv_path=Path(sys.prefix) if is_venv else None,
+        )
+
+        # 3. Installed packages collection
+        installed_packages: dict[str, InstalledDistribution] = {}
+        try:
+            for dist in importlib.metadata.distributions():
+                name = dist.metadata["Name"]
+                if not name:
+                    continue
+                requires = dist.requires or []
+                installed_packages[name.lower()] = InstalledDistribution(
+                    name=name,
+                    version=dist.version,
+                    location=str(dist.locate_file("")),
+                    requires=tuple(requires),
+                )
+        except Exception:
+            pass
+
+        # 4. Source file discovery & AST import extraction
+        source_files: list[SourceFile] = []
+        imports: list[ImportRecord] = []
+
+        exclude_patterns = set(self.config.paths.exclude)
+        for py_path in self.root.rglob("*.py"):
+            rel_path = py_path.relative_to(self.root)
+            # Check exclusions
+            parts = rel_path.parts
+            if any(part in exclude_patterns or part.startswith(".") for part in parts):
+                continue
+
+            try:
+                content = py_path.read_text(encoding="utf-8")
+                is_init = py_path.name == "__init__.py"
+                # Compute logical module name
+                mod_parts = list(rel_path.with_suffix("").parts)
+                if is_init:
+                    mod_parts = mod_parts[:-1]
+                module_name = ".".join(mod_parts)
+
+                source_file = SourceFile(
+                    path=py_path,
+                    relative_path=rel_path,
+                    content=content,
+                    is_init=is_init,
+                    module_name=module_name,
+                )
+                source_files.append(source_file)
+
+                # Parse AST
+                try:
+                    tree = ast.parse(content, filename=str(py_path))
+                    for node in ast.walk(tree):
+                        if isinstance(node, ast.Import):
+                            for alias in node.names:
+                                imports.append(
+                                    ImportRecord(
+                                        module_name=alias.name,
+                                        source_file=py_path,
+                                        line_number=node.lineno,
+                                        is_relative=False,
+                                    )
+                                )
+                        elif isinstance(node, ast.ImportFrom):
+                            mod = node.module or ""
+                            is_rel = node.level > 0
+                            symbols = tuple(alias.name for alias in node.names)
+                            imports.append(
+                                ImportRecord(
+                                    module_name=mod,
+                                    source_file=py_path,
+                                    line_number=node.lineno,
+                                    is_relative=is_rel,
+                                    imported_symbols=symbols,
+                                )
+                            )
+                except SyntaxError:
+                    pass
+            except Exception:
+                pass
+
+        # 5. Docker discovery
+        docker_config = self._discover_docker()
+
+        # 6. CI discovery
+        ci_config = self._discover_ci()
+
+        return ProjectContext(
+            project_root=self.root,
+            project_name=project_name,
+            python_runtime=runtime,
+            package_manager=package_manager,
+            manifest_files=tuple(manifest_files),
+            lock_files=tuple(lock_files),
+            dependencies=tuple(dependencies),
+            installed_packages=installed_packages,
+            source_files=tuple(source_files),
+            imports=tuple(imports),
+            docker=docker_config,
+            ci=ci_config,
+        )
+
+    def _discover_docker(self) -> DockerConfig:
+        dockerfile = self.root / "Dockerfile"
+        if not dockerfile.exists():
+            return DockerConfig(has_dockerfile=False)
+
+        base_image = None
+        base_python = None
+        try:
+            content = dockerfile.read_text(encoding="utf-8")
+            from_match = re.search(r"^FROM\s+([^\s]+)", content, re.MULTILINE | re.IGNORECASE)
+            if from_match:
+                base_image = from_match.group(1)
+                py_match = re.search(r"python:?([0-9]+\.[0-9]+)", base_image, re.IGNORECASE)
+                if py_match:
+                    base_python = py_match.group(1)
+        except Exception:
+            pass
+
+        return DockerConfig(
+            has_dockerfile=True,
+            dockerfile_path=dockerfile,
+            base_image=base_image,
+            base_python_version=base_python,
+        )
+
+    def _discover_ci(self) -> CIConfig:
+        gh_workflows = self.root / ".github" / "workflows"
+        workflow_files: list[Path] = []
+        matrix_versions: list[str] = []
+
+        if gh_workflows.exists() and gh_workflows.is_dir():
+            for f in gh_workflows.glob("*.yml"):
+                workflow_files.append(f)
+            for f in gh_workflows.glob("*.yaml"):
+                workflow_files.append(f)
+
+            # Look for python-version in workflow files
+            for wf in workflow_files:
+                try:
+                    text = wf.read_text(encoding="utf-8")
+                    found_versions = re.findall(r'["\']?3\.\d+["\']?', text)
+                    for v in found_versions:
+                        clean_v = v.strip("\"'")
+                        if clean_v not in matrix_versions:
+                            matrix_versions.append(clean_v)
+                except Exception:
+                    pass
+
+            return CIConfig(
+                has_ci=True,
+                provider="github_actions",
+                workflow_files=tuple(workflow_files),
+                matrix_python_versions=tuple(matrix_versions),
+            )
+
+        return CIConfig(has_ci=False)

qv/frameworks/__init__.py

@@ -0,0 +1 @@
+"""Framework plugins."""

qv/integrations/__init__.py

@@ -0,0 +1 @@
+"""Third-party tool integrations."""

qv/reporters/__init__.py

@@ -0,0 +1,13 @@
+"""Reporters package."""
+
+from qv.reporters.base import Reporter
+from qv.reporters.json_reporter import JsonReporter
+from qv.reporters.sarif import SarifReporter
+from qv.reporters.terminal import TerminalReporter
+
+__all__ = [
+    "Reporter",
+    "TerminalReporter",
+    "JsonReporter",
+    "SarifReporter",
+]

qv/reporters/base.py

@@ -0,0 +1,15 @@
+"""Base reporter interface."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from qv.core.models import ScanResult
+
+
+class Reporter(Protocol):
+    """Protocol for diagnostic output formatters."""
+
+    def render(self, result: ScanResult) -> str:
+        """Render scan result to string output."""
+        ...

qv/reporters/json_reporter.py

@@ -0,0 +1,16 @@
+"""JSON reporter for machine-readable diagnostic outputs."""
+
+from __future__ import annotations
+
+from qv.core.models import ScanResult
+
+
+class JsonReporter:
+    """Serializes scan result to formatted JSON string."""
+
+    def __init__(self, indent: int = 2) -> None:
+        self.indent = indent
+
+    def render(self, result: ScanResult) -> str:
+        """Render scan result as JSON."""
+        return result.model_dump_json(indent=self.indent)

qv/reporters/sarif.py

@@ -0,0 +1,85 @@
+"""SARIF (Static Analysis Results Interchange Format) reporter conforming to v2.1.0."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from qv.core.models import ScanResult, Severity
+from qv.rules.registry import RULES_CATALOG
+
+
+class SarifReporter:
+    """Generates standard SARIF v2.1.0 output for CI / Code Scanning integration."""
+
+    def render(self, result: ScanResult) -> str:
+        """Render scan result to SARIF v2.1.0 JSON format."""
+        sarif_data = self.to_sarif_dict(result)
+        return json.dumps(sarif_data, indent=2)
+
+    def to_sarif_dict(self, result: ScanResult) -> dict[str, Any]:
+        rules_dict: list[dict[str, Any]] = []
+        seen_rules = set()
+
+        for diag in result.diagnostics:
+            if diag.id not in seen_rules:
+                seen_rules.add(diag.id)
+                rule_def = RULES_CATALOG.get(diag.id)
+                rule_entry: dict[str, Any] = {
+                    "id": diag.id,
+                    "name": diag.id.replace("-", "_"),
+                    "shortDescription": {"text": diag.title},
+                    "fullDescription": {"text": rule_def.description if rule_def else diag.title},
+                }
+                if diag.doc_url:
+                    rule_entry["helpUri"] = diag.doc_url
+                rules_dict.append(rule_entry)
+
+        sarif_results: list[dict[str, Any]] = []
+        for diag in result.diagnostics:
+            level = (
+                "error"
+                if diag.severity == Severity.ERROR
+                else "warning"
+                if diag.severity == Severity.WARNING
+                else "note"
+            )
+            res_entry: dict[str, Any] = {
+                "ruleId": diag.id,
+                "level": level,
+                "message": {"text": diag.message},
+            }
+
+            if diag.file:
+                res_entry["locations"] = [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {
+                                "uri": diag.file.replace("\\", "/"),
+                            },
+                            "region": {
+                                "startLine": diag.line or 1,
+                                "startColumn": diag.column or 1,
+                            },
+                        }
+                    }
+                ]
+            sarif_results.append(res_entry)
+
+        return {
+            "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+            "version": "2.1.0",
+            "runs": [
+                {
+                    "tool": {
+                        "driver": {
+                            "name": "qv",
+                            "semanticVersion": "0.1.0",
+                            "informationUri": "https://github.com/inzamol/qv",
+                            "rules": rules_dict,
+                        }
+                    },
+                    "results": sarif_results,
+                }
+            ],
+        }