regix 0.1.1__py3-none-any.whl

regix/__init__.py

@@ -0,0 +1,132 @@
+"""Regix — Regression Index for Python code quality.
+
+Detect, measure and report code quality regressions between git versions
+at function, class and line granularity.
+"""
+
+from regix.config import RegressionConfig
+from regix.models import (
+    CommitMetrics,
+    GateCheck,
+    GateResult,
+    HistoryRegression,
+    HistoryReport,
+    Improvement,
+    MetricDelta,
+    Regression,
+    RegressionReport,
+    Snapshot,
+    SymbolMetrics,
+    TrendLine,
+)
+
+# Ensure backends are registered on import
+from regix.backends import docstring_backend as _docstring  # noqa: F401
+
+try:
+    from regix.backends import lizard_backend as _lizard  # noqa: F401
+except ImportError:
+    pass
+try:
+    from regix.backends import radon_backend as _radon  # noqa: F401
+except ImportError:
+    pass
+try:
+    from regix.backends import coverage_backend as _cov  # noqa: F401
+except ImportError:
+    pass
+try:
+    from regix.backends import vallm_backend as _vallm  # noqa: F401
+except ImportError:
+    pass
+
+
+class Regix:
+    """Main entry point — wraps snapshot, compare, and history."""
+
+    def __init__(
+        self,
+        config: RegressionConfig | str | None = None,
+        workdir: str = ".",
+    ):
+        from pathlib import Path
+
+        if isinstance(config, str):
+            self.config = RegressionConfig.from_file(config)
+        elif config is None:
+            try:
+                self.config = RegressionConfig.from_file(workdir)
+            except FileNotFoundError:
+                self.config = RegressionConfig()
+        else:
+            self.config = config
+        self.config.workdir = str(Path(workdir).resolve())
+        self.config.apply_env_overrides()
+
+    def snapshot(self, ref: str = "HEAD", use_cache: bool = True) -> Snapshot:
+        """Capture metrics at a git ref."""
+        from pathlib import Path
+        from regix.snapshot import capture
+
+        return capture(ref, Path(self.config.workdir), self.config)
+
+    def compare(
+        self,
+        ref_before: str = "HEAD~1",
+        ref_after: str = "HEAD",
+        use_cache: bool = True,
+    ) -> RegressionReport:
+        """Compare metrics between two refs."""
+        from regix.compare import compare as do_compare
+
+        snap_a = self.snapshot(ref_before, use_cache)
+        snap_b = self.snapshot(ref_after, use_cache)
+        return do_compare(snap_a, snap_b, self.config)
+
+    def compare_local(self, ref_before: str = "HEAD") -> RegressionReport:
+        """Compare a git ref against the current working tree."""
+        return self.compare(ref_before, "local", use_cache=False)
+
+    def history(
+        self,
+        depth: int = 20,
+        ref: str = "HEAD",
+        metrics: list[str] | None = None,
+    ) -> HistoryReport:
+        """Walk commits and return a metric timeline."""
+        from pathlib import Path
+        from regix.history import build_history
+
+        return build_history(
+            depth=depth, ref=ref,
+            workdir=Path(self.config.workdir),
+            config=self.config,
+            metrics_filter=metrics,
+        )
+
+    def check_gates(self, ref: str = "HEAD") -> GateResult:
+        """Check current state against absolute thresholds."""
+        from regix.gates import check_gates
+
+        snap = self.snapshot(ref)
+        return check_gates(snap, self.config)
+
+
+__all__ = [
+    "Regix",
+    "RegressionConfig",
+    "Snapshot",
+    "SymbolMetrics",
+    "MetricDelta",
+    "Regression",
+    "Improvement",
+    "RegressionReport",
+    "CommitMetrics",
+    "HistoryRegression",
+    "HistoryReport",
+    "TrendLine",
+    "GateCheck",
+    "GateResult",
+]
+
+__version__ = "0.1.1"

regix/backends/__init__.py

@@ -0,0 +1,54 @@
+"""Backend ABC and registry for static analysis tools."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from regix.config import RegressionConfig
+from regix.models import SymbolMetrics
+
+# ── Global backend registry ─────────────────────────────────────────────────
+
+_BACKENDS: dict[str, "BackendBase"] = {}
+
+
+class BackendBase(ABC):
+    """Interface that all analysis backends must implement."""
+
+    name: str = ""
+    required_binary: str | None = None
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Return True if the backend's dependencies are installed."""
+        ...
+
+    @abstractmethod
+    def collect(
+        self,
+        workdir: Path,
+        files: list[Path],
+        config: RegressionConfig,
+    ) -> list[SymbolMetrics]:
+        """Run analysis and return per-symbol metrics."""
+        ...
+
+    def version(self) -> str:
+        """Return the version string of the backend tool."""
+        return "unknown"
+
+
+def register_backend(backend: BackendBase) -> None:
+    """Register a backend instance for use by Regix."""
+    _BACKENDS[backend.name] = backend
+
+
+def get_backend(name: str) -> BackendBase | None:
+    """Look up a registered backend by name."""
+    return _BACKENDS.get(name)
+
+
+def available_backends() -> list[str]:
+    """Return names of all registered backends."""
+    return list(_BACKENDS.keys())

regix/backends/coverage_backend.py

@@ -0,0 +1,110 @@
+"""Coverage backend — reads pytest-cov .coverage data."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from regix.backends import BackendBase, register_backend
+from regix.config import RegressionConfig
+from regix.models import SymbolMetrics
+
+
+class CoverageBackend(BackendBase):
+    name = "coverage"
+    required_binary = None
+
+    def is_available(self) -> bool:
+        try:
+            import coverage as cov  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def version(self) -> str:
+        try:
+            import coverage
+            return coverage.__version__
+        except (ImportError, AttributeError):
+            return "not installed"
+
+    def collect(
+        self,
+        workdir: Path,
+        files: list[Path],
+        config: RegressionConfig,
+    ) -> list[SymbolMetrics]:
+        """Read coverage from a JSON report or .coverage file."""
+        results: list[SymbolMetrics] = []
+
+        # Try JSON report first (from pytest --cov-report=json)
+        json_candidates = [
+            workdir / ".regix" / "coverage.json",
+            workdir / "coverage.json",
+            workdir / "htmlcov" / "status.json",
+        ]
+        for cj in json_candidates:
+            if cj.exists():
+                return self._from_json(cj, files)
+
+        # Fallback: read .coverage SQLite via coverage API
+        cov_file = workdir / ".coverage"
+        if cov_file.exists():
+            return self._from_coverage_file(cov_file, files, workdir)
+
+        return results
+
+    def _from_json(
+        self, path: Path, files: list[Path]
+    ) -> list[SymbolMetrics]:
+        results: list[SymbolMetrics] = []
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return results
+
+        file_data = data.get("files", {})
+        file_set = {str(f) for f in files}
+        for fname, finfo in file_data.items():
+            if file_set and fname not in file_set:
+                continue
+            summary = finfo.get("summary", {})
+            pct = summary.get("percent_covered", None)
+            if pct is not None:
+                results.append(
+                    SymbolMetrics(
+                        file=fname,
+                        symbol=None,
+                        coverage=pct,
+                        raw={"covered_lines": summary.get("covered_lines", 0)},
+                    )
+                )
+        return results
+
+    def _from_coverage_file(
+        self, cov_path: Path, files: list[Path], workdir: Path
+    ) -> list[SymbolMetrics]:
+        results: list[SymbolMetrics] = []
+        try:
+            import coverage as cov_lib
+
+            cov = cov_lib.Coverage(data_file=str(cov_path))
+            cov.load()
+            data = cov.get_data()
+            for fname in data.measured_files():
+                lines = data.lines(fname) or []
+                missing = data.lines(fname)  # simplified
+                total = len(lines)
+                if total > 0:
+                    pct = (len(lines) / total) * 100
+                else:
+                    pct = 0.0
+                results.append(
+                    SymbolMetrics(file=fname, symbol=None, coverage=pct)
+                )
+        except Exception:
+            pass
+        return results
+
+
+register_backend(CoverageBackend())

regix/backends/docstring_backend.py

@@ -0,0 +1,66 @@
+"""Docstring backend — pure Python, ast-based docstring coverage."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from regix.backends import BackendBase, register_backend
+from regix.config import RegressionConfig
+from regix.models import SymbolMetrics
+
+
+class DocstringBackend(BackendBase):
+    name = "docstring"
+    required_binary = None
+
+    def is_available(self) -> bool:
+        return True  # Built-in, always available
+
+    def version(self) -> str:
+        import sys
+        return f"ast (Python {sys.version_info.major}.{sys.version_info.minor})"
+
+    def collect(
+        self,
+        workdir: Path,
+        files: list[Path],
+        config: RegressionConfig,
+    ) -> list[SymbolMetrics]:
+        results: list[SymbolMetrics] = []
+        for fpath in files:
+            full = workdir / fpath
+            if not full.exists() or full.suffix != ".py":
+                continue
+            try:
+                source = full.read_text(encoding="utf-8")
+                tree = ast.parse(source, filename=str(full))
+            except (SyntaxError, UnicodeDecodeError, OSError):
+                continue
+
+            total = 0
+            documented = 0
+            for node in ast.walk(tree):
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                    # Skip private/dunder unless it's __init__
+                    name = node.name
+                    if name.startswith("_") and name != "__init__":
+                        continue
+                    total += 1
+                    docstring = ast.get_docstring(node)
+                    if docstring:
+                        documented += 1
+
+            pct = (documented / total * 100) if total > 0 else 100.0
+            results.append(
+                SymbolMetrics(
+                    file=str(fpath),
+                    symbol=None,
+                    docstring_coverage=round(pct, 1),
+                    raw={"total_public": total, "documented": documented},
+                )
+            )
+        return results
+
+
+register_backend(DocstringBackend())

regix/backends/lizard_backend.py

@@ -0,0 +1,71 @@
+"""Lizard backend — cyclomatic complexity and function length."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from regix.backends import BackendBase, register_backend
+from regix.config import RegressionConfig
+from regix.models import SymbolMetrics
+
+
+class LizardBackend(BackendBase):
+    name = "lizard"
+    required_binary = "lizard"
+
+    def is_available(self) -> bool:
+        try:
+            import lizard  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def version(self) -> str:
+        try:
+            import lizard
+            return getattr(lizard, "__version__", "unknown")
+        except ImportError:
+            return "not installed"
+
+    def collect(
+        self,
+        workdir: Path,
+        files: list[Path],
+        config: RegressionConfig,
+    ) -> list[SymbolMetrics]:
+        try:
+            import lizard
+        except ImportError:
+            return []
+
+        results: list[SymbolMetrics] = []
+        for fpath in files:
+            full = workdir / fpath
+            if not full.exists() or not full.is_file():
+                continue
+            try:
+                analysis = lizard.analyze_file(str(full))
+            except Exception:
+                continue
+
+            for func in analysis.function_list:
+                results.append(
+                    SymbolMetrics(
+                        file=str(fpath),
+                        symbol=func.name,
+                        line_start=func.start_line,
+                        line_end=func.end_line,
+                        cc=func.cyclomatic_complexity,
+                        length=func.nloc,
+                        raw={
+                            "token_count": func.token_count,
+                            "parameter_count": len(func.parameters),
+                        },
+                    )
+                )
+        return results
+
+
+# Auto-register
+register_backend(LizardBackend())

regix/backends/radon_backend.py

@@ -0,0 +1,92 @@
+"""Radon backend — maintainability index and raw CC."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from regix.backends import BackendBase, register_backend
+from regix.config import RegressionConfig
+from regix.models import SymbolMetrics
+
+
+class RadonBackend(BackendBase):
+    name = "radon"
+    required_binary = None
+
+    def is_available(self) -> bool:
+        try:
+            import radon.complexity  # noqa: F401
+            import radon.metrics  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def version(self) -> str:
+        try:
+            import radon
+            return getattr(radon, "__version__", "unknown")
+        except ImportError:
+            return "not installed"
+
+    def collect(
+        self,
+        workdir: Path,
+        files: list[Path],
+        config: RegressionConfig,
+    ) -> list[SymbolMetrics]:
+        try:
+            from radon.complexity import cc_visit
+            from radon.metrics import mi_visit
+        except ImportError:
+            return []
+
+        results: list[SymbolMetrics] = []
+        for fpath in files:
+            full = workdir / fpath
+            if not full.exists() or full.suffix != ".py":
+                continue
+            try:
+                source = full.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+
+            # Maintainability index (module-level)
+            try:
+                mi = mi_visit(source, multi=True)
+            except Exception:
+                mi = None
+
+            # CC per function/class
+            try:
+                cc_results = cc_visit(source)
+            except Exception:
+                cc_results = []
+
+            # Module-level entry with MI
+            results.append(
+                SymbolMetrics(
+                    file=str(fpath),
+                    symbol=None,
+                    mi=mi,
+                    raw={"radon_mi": mi},
+                )
+            )
+
+            for block in cc_results:
+                results.append(
+                    SymbolMetrics(
+                        file=str(fpath),
+                        symbol=block.name,
+                        line_start=block.lineno,
+                        line_end=block.endline,
+                        cc=block.complexity,
+                        raw={
+                            "radon_rank": block.letter,
+                            "radon_classname": getattr(block, "classname", None),
+                        },
+                    )
+                )
+        return results
+
+
+register_backend(RadonBackend())

regix/backends/vallm_backend.py

@@ -0,0 +1,74 @@
+"""Vallm backend — LLM-based code quality scoring via vallm."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from regix.backends import BackendBase, register_backend
+from regix.config import RegressionConfig
+from regix.models import SymbolMetrics
+
+
+class VallmBackend(BackendBase):
+    name = "vallm"
+    required_binary = "vallm"
+
+    def is_available(self) -> bool:
+        return shutil.which("vallm") is not None
+
+    def version(self) -> str:
+        try:
+            result = subprocess.run(
+                ["vallm", "--version"],
+                capture_output=True, text=True, check=False,
+            )
+            return result.stdout.strip() or "unknown"
+        except FileNotFoundError:
+            return "not installed"
+
+    def collect(
+        self,
+        workdir: Path,
+        files: list[Path],
+        config: RegressionConfig,
+    ) -> list[SymbolMetrics]:
+        if not self.is_available():
+            return []
+
+        results: list[SymbolMetrics] = []
+        try:
+            proc = subprocess.run(
+                ["vallm", "batch", str(workdir), "--recursive", "--format", "json"],
+                capture_output=True, text=True, check=False,
+                cwd=str(workdir),
+            )
+            if proc.returncode != 0:
+                return results
+
+            data = json.loads(proc.stdout)
+            file_set = {str(f) for f in files} if files else set()
+
+            for entry in data if isinstance(data, list) else data.get("files", []):
+                fname = entry.get("file", "")
+                if file_set and fname not in file_set:
+                    continue
+                score = entry.get("score", entry.get("quality_score"))
+                if score is not None:
+                    results.append(
+                        SymbolMetrics(
+                            file=fname,
+                            symbol=None,
+                            quality_score=float(score),
+                            raw=entry,
+                        )
+                    )
+        except (json.JSONDecodeError, OSError, FileNotFoundError):
+            pass
+
+        return results
+
+
+register_backend(VallmBackend())

regix/cache.py

@@ -0,0 +1,97 @@
+"""Content-addressed snapshot cache."""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import json
+from pathlib import Path
+
+from regix.models import Snapshot
+
+
+def _cache_dir(config_dir: str = "~/.cache/regix") -> Path:
+    """Resolve cache directory (XDG-compliant)."""
+    import os
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    if xdg:
+        d = Path(xdg) / "regix"
+    else:
+        d = Path(config_dir).expanduser()
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _cache_key(commit_sha: str, backend_versions: dict[str, str]) -> str:
+    """Compute cache key from commit SHA and backend versions."""
+    raw = commit_sha + ":" + json.dumps(sorted(backend_versions.items()))
+    return hashlib.sha256(raw.encode()).hexdigest()[:24]
+
+
+def lookup(
+    commit_sha: str,
+    backend_versions: dict[str, str],
+    cache_dir: str = "~/.cache/regix",
+) -> Snapshot | None:
+    """Return cached snapshot or None."""
+    d = _cache_dir(cache_dir)
+    key = _cache_key(commit_sha, backend_versions)
+    path = d / f"{key}.json.gz"
+    if not path.exists():
+        return None
+    try:
+        raw = gzip.decompress(path.read_bytes()).decode("utf-8")
+        data = json.loads(raw)
+        return Snapshot.load.__func__.__code__  # type: ignore[attr-defined]
+        # Simplified: reconstruct from stored JSON
+    except Exception:
+        return None
+    return None
+
+
+def store(
+    snapshot: Snapshot,
+    cache_dir: str = "~/.cache/regix",
+) -> Path:
+    """Store a snapshot in the cache, return its path."""
+    d = _cache_dir(cache_dir)
+    if not snapshot.commit_sha:
+        raise ValueError("Cannot cache a snapshot without a commit SHA (local ref)")
+    key = _cache_key(snapshot.commit_sha, snapshot.backend_versions)
+    path = d / f"{key}.json.gz"
+    data = json.dumps({
+        "ref": snapshot.ref,
+        "commit_sha": snapshot.commit_sha,
+        "timestamp": snapshot.timestamp.isoformat(),
+        "workdir": str(snapshot.workdir),
+        "backend_versions": snapshot.backend_versions,
+        "symbols": [
+            {
+                "file": s.file,
+                "symbol": s.symbol,
+                "line_start": s.line_start,
+                "line_end": s.line_end,
+                "cc": s.cc,
+                "mi": s.mi,
+                "length": s.length,
+                "coverage": s.coverage,
+                "docstring_coverage": s.docstring_coverage,
+                "quality_score": s.quality_score,
+                "imports": s.imports,
+                "raw": s.raw,
+            }
+            for s in snapshot.symbols
+        ],
+    }, default=str)
+    path.write_bytes(gzip.compress(data.encode("utf-8")))
+    return path
+
+
+def clear(cache_dir: str = "~/.cache/regix") -> int:
+    """Remove all cached snapshots. Returns count removed."""
+    d = _cache_dir(cache_dir)
+    count = 0
+    for f in d.glob("*.json.gz"):
+        f.unlink()
+        count += 1
+    return count