regscope 0.1.0__py3-none-any.whl

regscope/collectors/redis.py

@@ -0,0 +1,76 @@
+"""Optional count-only instrumentation for redis-py commands."""
+
+from __future__ import annotations
+
+from functools import wraps
+from threading import Lock
+from typing import Any, Callable, ClassVar, Optional
+
+
+class RedisCollector:
+    """Count redis-py commands without recording keys, values, or arguments.
+
+    The redis-py hook is process-global while attached. Do not attach multiple
+    Redis collectors concurrently; use one collector per tracked execution.
+    """
+
+    _active_owner: ClassVar[Optional["RedisCollector"]] = None
+    _ownership_lock: ClassVar[Lock] = Lock()
+
+    def __init__(self) -> None:
+        self._redis: Optional[Any] = None
+        self._original: Optional[Callable[..., Any]] = None
+        self._wrapped: Optional[Callable[..., Any]] = None
+        self._count = 0
+        self._lock = Lock()
+
+    def attach(self) -> None:
+        try:
+            import redis
+        except ImportError as error:
+            raise RuntimeError(
+                "Redis tracking requires the 'redis' extra: install regscope[redis]"
+            ) from error
+        with self._ownership_lock:
+            if self._original is not None:
+                raise RuntimeError("collector is already attached")
+            if type(self)._active_owner is not None:
+                raise RuntimeError("another Redis collector is already attached")
+
+            original = redis.Redis.execute_command
+
+            @wraps(original)
+            def counted_command(client: Any, *args: Any, **kwargs: Any) -> Any:
+                with self._lock:
+                    self._count += 1
+                return original(client, *args, **kwargs)
+
+            redis.Redis.execute_command = counted_command
+            self._redis = redis
+            self._original = original
+            self._wrapped = counted_command
+            type(self)._active_owner = self
+
+    def detach(self) -> None:
+        if (
+            self._redis is not None
+            and self._original is not None
+            and self._wrapped is not None
+            and self._redis.Redis.execute_command is self._wrapped
+        ):
+            self._redis.Redis.execute_command = self._original
+        with self._ownership_lock:
+            if type(self)._active_owner is self:
+                type(self)._active_owner = None
+        self._redis = None
+        self._original = None
+        self._wrapped = None
+
+    @property
+    def command_count(self) -> int:
+        with self._lock:
+            return self._count
+
+    def reset(self) -> None:
+        with self._lock:
+            self._count = 0

regscope/collectors/sqlalchemy.py

@@ -0,0 +1,57 @@
+"""Optional SQLAlchemy query-count collector.
+
+Only statement counts are recorded. SQL text, parameters, and result data are
+intentionally never retained.
+"""
+
+from __future__ import annotations
+
+from threading import Lock
+from typing import Any, Callable, Optional
+
+
+class SQLAlchemyCollector:
+    """Count SQLAlchemy cursor executions for one engine."""
+
+    def __init__(self) -> None:
+        self._event: Optional[Any] = None
+        self._engine: Optional[Any] = None
+        self._count = 0
+        self._lock = Lock()
+
+    def attach(self, engine: Any) -> None:
+        """Attach to an SQLAlchemy engine, importing SQLAlchemy lazily."""
+        try:
+            from sqlalchemy import event
+        except ImportError as error:
+            raise RuntimeError(
+                "SQLAlchemy query tracking requires the 'db' extra: "
+                "install regscope[db]"
+            ) from error
+        if self._engine is not None:
+            raise RuntimeError("collector is already attached")
+        event.listen(engine, "before_cursor_execute", self._before_cursor_execute)
+        self._event = event
+        self._engine = engine
+
+    def detach(self) -> None:
+        """Remove the event listener if this collector is attached."""
+        if self._engine is not None and self._event is not None:
+            self._event.remove(
+                self._engine, "before_cursor_execute", self._before_cursor_execute
+            )
+        self._engine = None
+        self._event = None
+
+    @property
+    def query_count(self) -> int:
+        with self._lock:
+            return self._count
+
+    def reset(self) -> None:
+        with self._lock:
+            self._count = 0
+
+    def _before_cursor_execute(self, *args: Any, **kwargs: Any) -> None:
+        with self._lock:
+            self._count += 1

regscope/core/__init__.py

@@ -0,0 +1 @@
+"""Core execution and comparison primitives."""

regscope/core/comparison.py

@@ -0,0 +1,99 @@
+"""Noise-aware comparison of observed behavior profiles."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from statistics import median
+from typing import Dict, Iterable, List, Mapping, Optional
+
+from ..models import Baseline, BehaviorProfile
+
+
+DEFAULT_THRESHOLD = 0.20
+
+
+@dataclass(frozen=True)
+class MetricComparison:
+    metric: str
+    current: float
+    baseline_median: float
+    delta: float
+    change_ratio: float
+    regression: bool
+    threshold: float
+
+
+@dataclass(frozen=True)
+class ComparisonResult:
+    function: str
+    metrics: List[MetricComparison]
+    status: str = "compared"
+
+    @property
+    def regression(self) -> bool:
+        return any(metric.regression for metric in self.metrics)
+
+    @property
+    def risk(self) -> str:
+        regressions = sum(metric.regression for metric in self.metrics)
+        if regressions == 0:
+            return "none"
+        if any(metric.metric == "exceptions" and metric.regression for metric in self.metrics):
+            return "high"
+        return "medium" if regressions > 1 else "low"
+
+
+def compare(
+    current: BehaviorProfile,
+    baseline: Baseline,
+    threshold: float = DEFAULT_THRESHOLD,
+    thresholds: Optional[Mapping[str, float]] = None,
+) -> ComparisonResult:
+    """Compare ``current`` with the baseline's observed metric distribution."""
+    if not 0 <= threshold < 1:
+        raise ValueError("threshold must be between 0 and 1")
+    if current.function != baseline.function:
+        raise ValueError("profile function does not match baseline function")
+    if not baseline.runs:
+        return ComparisonResult(function=current.function, metrics=[], status="baseline_missing")
+
+    metrics = []
+    for name in ("duration_ns", "call_count", "exceptions"):
+        current_value = float(getattr(current, name))
+        baseline_values = [float(getattr(run, name)) for run in baseline.runs]
+        baseline_median = float(median(baseline_values))
+        delta = current_value - baseline_median
+        change_ratio = _change_ratio(current_value, baseline_median)
+        metric_threshold = (thresholds or {}).get(name, threshold)
+        if not 0 <= metric_threshold < 1:
+            raise ValueError("metric thresholds must be between 0 and 1")
+        metrics.append(
+            MetricComparison(
+                metric=name,
+                current=current_value,
+                baseline_median=baseline_median,
+                delta=delta,
+                change_ratio=change_ratio,
+                regression=_is_regression(
+                    current_value, baseline_median, metric_threshold, name
+                ),
+                threshold=metric_threshold,
+            )
+        )
+    return ComparisonResult(function=current.function, metrics=metrics)
+
+
+def _change_ratio(current: float, baseline: float) -> float:
+    if baseline == 0:
+        return 0.0 if current == 0 else float("inf")
+    return (current - baseline) / baseline
+
+
+def _is_regression(
+    current: float, baseline: float, threshold: float, metric: str
+) -> bool:
+    if metric == "exceptions" and baseline == 0:
+        return current > 0
+    if baseline == 0:
+        return current > 0
+    return current > baseline * (1 + threshold)

regscope/core/runtime.py

@@ -0,0 +1,49 @@
+"""Low-level synchronous execution measurement."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Optional, Tuple, TypeVar
+
+from ..models import BehaviorProfile
+
+
+T = TypeVar("T")
+
+
+def measure_sync(
+    function: Callable[..., T],
+    *args: Any,
+    profile_sink: Optional[Callable[[BehaviorProfile], None]] = None,
+    **kwargs: Any,
+) -> Tuple[T, BehaviorProfile]:
+    """Call ``function`` and return its result together with an observation.
+
+    Exceptions are counted and re-raised unchanged. ``profile_sink`` receives
+    the profile for both successful and exceptional calls, allowing callers to
+    persist the observation without changing the function's semantics.
+    """
+    started = time.perf_counter_ns()
+    exception_count = 0
+    try:
+        result = function(*args, **kwargs)
+    except BaseException:
+        exception_count = 1
+        raise
+    finally:
+        duration_ns = time.perf_counter_ns() - started
+        observed = BehaviorProfile(
+            function=_function_name(function),
+            duration_ns=duration_ns,
+            exceptions=exception_count,
+        )
+        if profile_sink is not None:
+            profile_sink(observed)
+
+    return result, observed
+
+
+def _function_name(function: Callable[..., Any]) -> str:
+    module = getattr(function, "__module__", "__main__")
+    qualified_name = getattr(function, "__qualname__", getattr(function, "__name__", "<callable>"))
+    return f"{module}.{qualified_name}"

regscope/errors.py

@@ -0,0 +1,9 @@
+"""Public RegScope exception types."""
+
+
+class RegScopeError(Exception):
+    """Base class for expected RegScope errors."""
+
+
+class MalformedRecordError(RegScopeError, ValueError):
+    """A persisted baseline or history record cannot be decoded safely."""

regscope/models.py

@@ -0,0 +1,112 @@
+"""Structured records produced by RegScope collectors."""
+
+from __future__ import annotations
+
+import json
+import hashlib
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, List, Mapping
+
+
+SCHEMA_VERSION = 1
+
+
+def _validate_schema(version: int) -> None:
+    if version > SCHEMA_VERSION:
+        raise ValueError(
+            f"unsupported schema version {version}; maximum supported is {SCHEMA_VERSION}"
+        )
+
+
+def _canonical_json(value: Mapping[str, Any]) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"))
+
+
+@dataclass(frozen=True)
+class BehaviorProfile:
+    """One observed execution of a tracked function."""
+
+    function: str
+    duration_ns: int
+    call_count: int = 0
+    exceptions: int = 0
+    call_graph: Dict[str, int] = field(default_factory=dict)
+    metrics: Dict[str, int] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    schema_version: int = SCHEMA_VERSION
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a JSON-compatible structured representation."""
+        return asdict(self)
+
+    def to_json(self) -> str:
+        """Serialize this profile deterministically."""
+        return _canonical_json(self.to_dict())
+
+    def fingerprint(self) -> str:
+        """Return a derived SHA-256 checksum of the structured profile."""
+        return hashlib.sha256(self.to_json().encode("utf-8")).hexdigest()
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "BehaviorProfile":
+        """Build a profile from a decoded JSON object."""
+        schema_version = int(data.get("schema_version", SCHEMA_VERSION))
+        _validate_schema(schema_version)
+        return cls(
+            function=str(data["function"]),
+            duration_ns=int(data["duration_ns"]),
+            call_count=int(data.get("call_count", 0)),
+            exceptions=int(data.get("exceptions", 0)),
+            call_graph={str(k): int(v) for k, v in data.get("call_graph", {}).items()},
+            metrics={str(k): int(v) for k, v in data.get("metrics", {}).items()},
+            metadata=dict(data.get("metadata", {})),
+            schema_version=schema_version,
+        )
+
+    @classmethod
+    def from_json(cls, value: str) -> "BehaviorProfile":
+        return cls.from_dict(json.loads(value))
+
+
+@dataclass
+class Baseline:
+    """A bounded collection of observed profiles for one tracked function."""
+
+    function: str
+    runs: List[BehaviorProfile] = field(default_factory=list)
+    max_runs: int = 5
+    schema_version: int = SCHEMA_VERSION
+
+    def add(self, profile: BehaviorProfile) -> None:
+        if profile.function != self.function:
+            raise ValueError("profile function does not match baseline function")
+        if self.max_runs < 1:
+            raise ValueError("max_runs must be at least 1")
+        self.runs.append(profile)
+        del self.runs[:-self.max_runs]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "function": self.function,
+            "runs": [profile.to_dict() for profile in self.runs],
+            "max_runs": self.max_runs,
+            "schema_version": self.schema_version,
+        }
+
+    def to_json(self) -> str:
+        return _canonical_json(self.to_dict())
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Baseline":
+        schema_version = int(data.get("schema_version", SCHEMA_VERSION))
+        _validate_schema(schema_version)
+        return cls(
+            function=str(data["function"]),
+            runs=[BehaviorProfile.from_dict(item) for item in data.get("runs", [])],
+            max_runs=int(data.get("max_runs", 5)),
+            schema_version=schema_version,
+        )
+
+    @classmethod
+    def from_json(cls, value: str) -> "Baseline":
+        return cls.from_dict(json.loads(value))

regscope/pytest_plugin.py

@@ -0,0 +1,74 @@
+"""Optional pytest integration for baseline comparisons."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+import os
+
+import pytest
+
+from .core.comparison import DEFAULT_THRESHOLD, ComparisonResult, compare
+from .models import BehaviorProfile
+from .storage import BaselineStore
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("regscope")
+    group.addoption(
+        "--regscope-baseline-dir",
+        action="store",
+        default=".regscope",
+        help="directory containing RegScope JSON baselines",
+    )
+    group.addoption(
+        "--regscope-threshold",
+        action="store",
+        type=float,
+        default=DEFAULT_THRESHOLD,
+        help="allowed relative increase before a regression is reported",
+    )
+    group.addoption(
+        "--regscope-update-baseline",
+        action="store_true",
+        help="update baselines only when REGSCOPE_TRUSTED_BASELINE=1",
+    )
+
+
+@pytest.fixture
+def regscope_compare(request: pytest.FixtureRequest) -> Callable[[BehaviorProfile], ComparisonResult]:
+    """Return a helper that compares a profile and fails on regression."""
+    directory = Path(request.config.getoption("--regscope-baseline-dir"))
+    threshold = request.config.getoption("--regscope-threshold")
+
+    def compare_profile(profile: BehaviorProfile) -> ComparisonResult:
+        baseline = BaselineStore(directory).load(profile.function)
+        result = compare(profile, baseline, threshold=threshold)
+        if result.regression:
+            pytest.fail(f"RegScope behavioral regression detected for {profile.function}")
+        return result
+
+    return compare_profile
+
+
+@pytest.fixture
+def regscope_record(request: pytest.FixtureRequest) -> Callable[[BehaviorProfile], ComparisonResult]:
+    """Compare a profile and optionally record it in a trusted update run."""
+    directory = Path(request.config.getoption("--regscope-baseline-dir"))
+    threshold = request.config.getoption("--regscope-threshold")
+    update_requested = request.config.getoption("--regscope-update-baseline")
+    trusted = os.environ.get("REGSCOPE_TRUSTED_BASELINE") == "1"
+    store = BaselineStore(directory)
+
+    def record_profile(profile: BehaviorProfile) -> ComparisonResult:
+        baseline = store.load(profile.function)
+        result = compare(profile, baseline, threshold=threshold)
+        if result.status == "baseline_missing" and not (update_requested and trusted):
+            pytest.fail(f"RegScope baseline missing for {profile.function}")
+        if result.regression and not (update_requested and trusted):
+            pytest.fail(f"RegScope behavioral regression detected for {profile.function}")
+        if update_requested and trusted:
+            store.append(profile)
+        return result
+
+    return record_profile

regscope/storage/__init__.py

@@ -0,0 +1,5 @@
+"""Persistence adapters for RegScope behavior profiles."""
+
+from .json_store import BaselineStore
+
+__all__ = ["BaselineStore"]

regscope/storage/json_store.py

@@ -0,0 +1,121 @@
+"""Atomic JSON persistence for behavior baselines."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import ClassVar, Dict, Iterator, Optional
+
+from ..models import Baseline, BehaviorProfile
+from ..errors import MalformedRecordError
+
+
+class BaselineStore:
+    """Store one bounded baseline file per tracked function."""
+
+    _thread_locks: ClassVar[Dict[str, threading.RLock]] = {}
+    _thread_locks_guard: ClassVar[threading.Lock] = threading.Lock()
+
+    def __init__(self, directory: os.PathLike[str] | str, max_runs: int = 5) -> None:
+        if max_runs < 1:
+            raise ValueError("max_runs must be at least 1")
+        self.directory = Path(directory)
+        self.max_runs = max_runs
+
+    def path_for(self, function: str) -> Path:
+        digest = hashlib.sha256(function.encode("utf-8")).hexdigest()[:16]
+        return self.directory / f"{digest}.json"
+
+    def load(self, function: str) -> Baseline:
+        path = self.path_for(function)
+        if not path.exists():
+            return Baseline(function=function, max_runs=self.max_runs)
+        try:
+            return Baseline.from_json(path.read_text(encoding="utf-8"))
+        except (OSError, TypeError, ValueError, KeyError) as error:
+            raise MalformedRecordError(
+                f"invalid baseline record at {path}: {error}"
+            ) from error
+
+    def save(self, baseline: Baseline) -> Path:
+        self.directory.mkdir(parents=True, exist_ok=True)
+        destination = self.path_for(baseline.function)
+        temporary: Optional[str] = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w", encoding="utf-8", dir=self.directory, delete=False
+            ) as handle:
+                temporary = handle.name
+                handle.write(baseline.to_json())
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary, destination)
+        finally:
+            if temporary is not None and os.path.exists(temporary):
+                os.unlink(temporary)
+        return destination
+
+    def append(self, profile: BehaviorProfile) -> Baseline:
+        with self._append_lock(profile.function):
+            baseline = self.load(profile.function)
+            baseline.max_runs = self.max_runs
+            baseline.add(profile)
+            self.save(baseline)
+            return baseline
+
+    @contextmanager
+    def _append_lock(self, function: str) -> Iterator[None]:
+        path = self.path_for(function)
+        with self._thread_lock(path):
+            self.directory.mkdir(parents=True, exist_ok=True)
+            lock_path = path.with_suffix(".lock")
+            with lock_path.open("a+", encoding="utf-8") as lock_file:
+                lock_file.seek(0)
+                lock_file.write("0")
+                lock_file.flush()
+                lock_file.seek(0)
+                _lock_file(lock_file)
+                try:
+                    yield
+                finally:
+                    _unlock_file(lock_file)
+
+    @classmethod
+    @contextmanager
+    def _thread_lock(cls, path: Path) -> Iterator[None]:
+        key = str(path)
+        with cls._thread_locks_guard:
+            lock = cls._thread_locks.setdefault(key, threading.RLock())
+        with lock:
+            yield
+
+
+def _lock_file(handle: object) -> None:
+    if os.name == "nt":
+        import msvcrt
+
+        msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+        return
+    try:
+        import fcntl
+    except ImportError:
+        return
+    fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+
+
+def _unlock_file(handle: object) -> None:
+    if os.name == "nt":
+        import msvcrt
+
+        handle.seek(0)
+        msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+        return
+    try:
+        import fcntl
+    except ImportError:
+        return
+    fcntl.flock(handle.fileno(), fcntl.LOCK_UN)

regscope/trends/__init__.py

@@ -0,0 +1,5 @@
+"""Historical behavior trend storage and summaries."""
+
+from .history import HistoryStore, TrendPoint, TrendSummary
+
+__all__ = ["HistoryStore", "TrendPoint", "TrendSummary"]