migrate-guard 0.1.0__py3-none-any.whl

migrate_guard/__init__.py

@@ -0,0 +1,3 @@
+"""Catch behavior changes when you rewrite a legacy service."""
+
+__version__ = "0.1.0"

migrate_guard/application/use_cases/run_corpus.py

@@ -0,0 +1,122 @@
+"""Use case: replay every case against the baseline and the candidate, and compare."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, replace
+
+from migrate_guard.domain.entities.case import Case, HttpResponse
+from migrate_guard.domain.entities.case_result import CaseResult, CaseStatus, RunResult
+from migrate_guard.domain.entities.state import StateSnapshot
+from migrate_guard.domain.ports.state import Seeder, StateError, StateProbe
+from migrate_guard.domain.ports.target_runner import TargetError, TargetRunner
+from migrate_guard.domain.services.case_compare import compare_case
+from migrate_guard.domain.services.state_diff import diff_states
+from migrate_guard.domain.value_objects.rules import Rule
+from migrate_guard.domain.value_objects.state_rules import StateRule
+
+
+class RunRefused(Exception):
+    """The run did not start: nothing was sent to any target. Maps to exit code 2."""
+
+
+@dataclass(frozen=True)
+class StateCheck:
+    """The database side of a run. Seeding is not optional: every case starts from a known state."""
+
+    baseline_seeder: Seeder
+    candidate_seeder: Seeder
+    baseline_probe: StateProbe
+    candidate_probe: StateProbe
+    rules: tuple[StateRule, ...] = ()
+
+
+class _CaseFailed(Exception):
+    """One step of a case failed: the case is an error and its remaining steps are skipped."""
+
+
+@dataclass(frozen=True)
+class RunCorpus:
+    baseline: TargetRunner
+    candidate: TargetRunner
+    rules: tuple[Rule, ...] = ()
+    allow_mutating: bool = False
+    state: StateCheck | None = None
+
+    def execute(self, cases: Sequence[Case]) -> RunResult:
+        # Every refusal happens before the first request, so a refused run touches nothing.
+        if not cases:
+            raise RunRefused("the corpus has no cases")
+        mutating = [c.name for c in cases if c.is_mutating]
+        if mutating and not self.allow_mutating:
+            raise RunRefused(
+                "mutating cases need `allow_mutating: true` in the config: " + ", ".join(mutating)
+            )
+        for side, target in (("baseline", self.baseline), ("candidate", self.candidate)):
+            try:
+                target.check_reachable()
+            except TargetError as e:
+                raise RunRefused(f"target unreachable: {side} ({e})") from e
+
+        results: list[CaseResult] = []
+        used: set[Rule | StateRule] = set()
+        compared_any = False
+        for case in cases:
+            try:
+                result, case_used = self._run_case(case)
+            except _CaseFailed as e:
+                results.append(CaseResult.failed(case.name, str(e)))
+                continue
+            results.append(result)
+            used.update(case_used)
+            compared_any = True
+
+        # With no case compared there is no evidence that a rule is stale: don't warn.
+        all_rules: tuple[Rule | StateRule, ...] = (
+            *self.rules,
+            *(self.state.rules if self.state else ()),
+        )
+        unused = tuple(r for r in all_rules if r not in used) if compared_any else ()
+        return RunResult(tuple(results), unused)
+
+    def _run_case(self, case: Case) -> tuple[CaseResult, set[Rule | StateRule]]:
+        # Order (SPEC §6): seed both -> baseline -> probe baseline -> candidate -> probe
+        # candidate -> compare. Seeding both first means a failed seed sends no request at all.
+        if self.state:
+            _step("seed failed: baseline", self.state.baseline_seeder.seed)
+            _step("seed failed: candidate", self.state.candidate_seeder.seed)
+        b_response = _request("baseline", self.baseline, case)
+        b_state = self._probe("baseline", self.state.baseline_probe if self.state else None)
+        c_response = _request("candidate", self.candidate, case)
+        c_state = self._probe("candidate", self.state.candidate_probe if self.state else None)
+
+        result, body = compare_case(case.name, b_response, c_response, self.rules)
+        used: set[Rule | StateRule] = {r for r in self.rules if r not in body.unused_rules}
+        if self.state and b_state is not None and c_state is not None:
+            state = diff_states(b_state, c_state, self.state.rules)
+            used.update(r for r in self.state.rules if r not in state.unused_rules)
+            if state.differences:
+                result = replace(
+                    result, status=CaseStatus.DIFFERENCE, state_differences=state.differences
+                )
+        return result, used
+
+    @staticmethod
+    def _probe(side: str, probe: StateProbe | None) -> StateSnapshot | None:
+        if probe is None:
+            return None
+        return _step(f"state probe failed: {side}", probe.snapshot)
+
+
+def _request(side: str, target: TargetRunner, case: Case) -> HttpResponse:
+    try:
+        return target.execute(case.request)
+    except TargetError as e:
+        raise _CaseFailed(f"{side}: {e}") from e
+
+
+def _step[T](label: str, action: Callable[[], T]) -> T:
+    try:
+        return action()
+    except StateError as e:
+        raise _CaseFailed(f"{label}: {e}") from e

migrate_guard/cli/app.py

@@ -0,0 +1,118 @@
+"""The `migrate-guard` command line."""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from migrate_guard.application.use_cases.run_corpus import RunRefused
+from migrate_guard.domain.entities.case_result import ExitCode
+from migrate_guard.domain.services.redaction import RedactionPolicy
+from migrate_guard.infrastructure.adapters.reporters.json_reporter import render_json_report
+from migrate_guard.infrastructure.adapters.reporters.junit_reporter import render_junit_report
+from migrate_guard.infrastructure.adapters.reporters.terminal_reporter import TerminalReporter
+from migrate_guard.infrastructure.adapters.targets.http_target import UnsafeTargetError
+from migrate_guard.infrastructure.config.loader import ConfigError, load_config
+from migrate_guard.infrastructure.config.state_config import StateConfigError
+from migrate_guard.infrastructure.wiring import select_cases, wire
+
+app = typer.Typer(
+    help="Catch behavior changes when you rewrite a legacy service.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+class ReportFormat(StrEnum):
+    TERMINAL = "terminal"
+    JSON = "json"
+    JUNIT = "junit"
+
+
+_RENDER = {ReportFormat.JSON: render_json_report, ReportFormat.JUNIT: render_junit_report}
+
+
+@app.callback()
+def _root() -> None:
+    """Keeps `run` as a subcommand even while it is the only one."""
+
+
+@app.command()
+def run(
+    config: Annotated[
+        Path, typer.Option("--config", "-c", help="Path to migrate-guard.yaml.")
+    ] = Path("migrate-guard.yaml"),
+    case: Annotated[
+        list[str] | None, typer.Option("--case", help="Run only this case (repeatable).")
+    ] = None,
+    allow_remote: Annotated[
+        bool, typer.Option("--allow-remote", help="Allow targets that are not loopback.")
+    ] = False,
+    report: Annotated[
+        ReportFormat,
+        typer.Option(
+            "--report",
+            help="json or junit go to --output (plus the terminal summary), or alone to stdout.",
+        ),
+    ] = ReportFormat.TERMINAL,
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="File for the json or junit report.")
+    ] = None,
+) -> None:
+    """Replay the corpus against the baseline and the candidate, and compare responses and state.
+
+    Exit codes: 0 all match, 1 differences or case errors, 2 refused (config, target, safety).
+    """
+    # Refusals go to stderr, so stdout stays a valid report when it is one.
+    errors = TerminalReporter(Console(stderr=True, highlight=False), RedactionPolicy())
+    try:
+        if output and report is ReportFormat.TERMINAL:
+            raise ConfigError("--output needs --report json or --report junit")
+        loaded = load_config(config)
+        cases = select_cases(loaded.cases, case or [])
+        wiring = wire(loaded, allow_remote=allow_remote)
+        try:
+            result = wiring.run_corpus.execute(cases)
+        finally:
+            wiring.close()
+    except (ConfigError, StateConfigError, UnsafeTargetError, RunRefused) as e:
+        errors.refused(str(e))
+        raise typer.Exit(ExitCode.REFUSED) from e
+
+    if report is ReportFormat.TERMINAL or output:
+        TerminalReporter(Console(highlight=False), loaded.redaction).report(result)
+    if report is not ReportFormat.TERMINAL:
+        text = _RENDER[report](result, loaded.redaction)
+        try:
+            _write(text, output)
+        except OSError as e:
+            errors.refused(f"can't write the report: {e.strerror or type(e).__name__}")
+            raise typer.Exit(ExitCode.REFUSED) from e
+    raise typer.Exit(result.exit_code)
+
+
+def _write(text: str, output: Path | None) -> None:
+    if output is None:
+        sys.stdout.write(text)
+        sys.stdout.flush()
+        return
+    # Write next to the target and rename: CI never picks up half a report.
+    fd, tmp = tempfile.mkstemp(dir=output.parent, prefix=f".{output.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(text)
+        os.replace(tmp, output)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def main() -> None:
+    app()

migrate_guard/domain/entities/case.py

@@ -0,0 +1,40 @@
+"""A case: one request replayed against both targets, and the response it gets back."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from migrate_guard.domain.value_objects.json_value import JsonValue
+
+# Methods that can change state on the target: they need `allow_mutating: true` (SPEC §7).
+MUTATING_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+type Headers = tuple[tuple[str, str], ...]
+
+
+@dataclass(frozen=True)
+class HttpRequest:
+    method: str
+    path: str
+    query: tuple[tuple[str, str], ...] = ()
+    headers: Headers = ()
+    json: JsonValue | None = None
+
+
+@dataclass(frozen=True)
+class Case:
+    name: str
+    request: HttpRequest
+    mutating: bool = False  # set it for a GET that writes; mutating methods count anyway
+
+    @property
+    def is_mutating(self) -> bool:
+        return self.mutating or self.request.method.upper() in MUTATING_METHODS
+
+
+@dataclass(frozen=True)
+class HttpResponse:
+    status: int
+    headers: Headers
+    # The parsed JSON body (numbers as Decimal), or the raw text when the body is not JSON.
+    body: JsonValue

migrate_guard/domain/entities/case_result.py

@@ -0,0 +1,59 @@
+"""The result of one case, and of a whole run."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from migrate_guard.domain.entities.difference import Difference
+from migrate_guard.domain.value_objects.rules import Rule
+from migrate_guard.domain.value_objects.state_rules import StateRule
+
+
+class CaseStatus(StrEnum):
+    MATCH = "match"
+    DIFFERENCE = "difference"
+    # The case could not be compared (timeout, connection error...). Never counted as a match.
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class StatusMismatch:
+    baseline: int
+    candidate: int
+
+
+@dataclass(frozen=True)
+class CaseResult:
+    name: str
+    status: CaseStatus
+    status_mismatch: StatusMismatch | None = None
+    differences: tuple[Difference, ...] = ()  # in the response body
+    state_differences: tuple[Difference, ...] = ()  # in the database, at /table/row/column
+    error: str = ""
+
+    @classmethod
+    def failed(cls, name: str, error: str) -> CaseResult:
+        return cls(name, CaseStatus.ERROR, error=error)
+
+
+class ExitCode:
+    OK = 0  # every case matched
+    DIFFERENCES = 1  # at least one difference or case error
+    REFUSED = 2  # invalid config, unreachable target or safety refusal
+
+
+@dataclass(frozen=True)
+class RunResult:
+    cases: tuple[CaseResult, ...]
+    # Rules that matched nothing in any case of the run: probably stale (SPEC R2).
+    unused_rules: tuple[Rule | StateRule, ...] = ()
+
+    @property
+    def exit_code(self) -> int:
+        if all(c.status is CaseStatus.MATCH for c in self.cases):
+            return ExitCode.OK
+        return ExitCode.DIFFERENCES
+
+    def count(self, status: CaseStatus) -> int:
+        return sum(1 for c in self.cases if c.status is status)

migrate_guard/domain/entities/difference.py

@@ -0,0 +1,42 @@
+"""One mismatch between the baseline and the candidate."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, StrEnum
+from typing import Literal
+
+from migrate_guard.domain.value_objects.json_pointer import JsonPointer
+from migrate_guard.domain.value_objects.json_value import JsonValue
+
+
+class _Missing(Enum):
+    MISSING = "missing"
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+
+# A key that does not exist, which is not the same as a key whose value is null.
+MISSING = _Missing.MISSING
+type Side = JsonValue | Literal[_Missing.MISSING]
+
+
+class DiffKind(StrEnum):
+    VALUE_CHANGED = "value_changed"  # same type, different value: 2.68 vs 2.67
+    TYPE_CHANGED = "type_changed"  # "10" vs 10, null vs 0
+    MISSING_IN_CANDIDATE = "missing_in_candidate"  # the rewrite dropped a field
+    ADDED_IN_CANDIDATE = "added_in_candidate"  # the rewrite added a field
+    DUPLICATE_KEY = "duplicate_key"  # an `unordered` array has two items with the same key
+    # A rule matched but can't read the value (bad datetime, no timezone, missing key...).
+    # Never a silent match: the rule's assumption is broken, so a human has to look.
+    RULE_NOT_APPLICABLE = "rule_not_applicable"
+
+
+@dataclass(frozen=True)
+class Difference:
+    kind: DiffKind
+    location: JsonPointer
+    baseline: Side
+    candidate: Side
+    detail: str = ""  # why, in words, when the kind alone doesn't say it

migrate_guard/domain/entities/state.py

@@ -0,0 +1,27 @@
+"""What a target's database looks like after a case: the watched tables, row by row."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from migrate_guard.domain.value_objects.json_value import JsonValue
+
+type Row = dict[str, JsonValue]  # logical column name -> normalized value
+
+
+@dataclass(frozen=True)
+class TableSnapshot:
+    # Row key text (e.g. "sku=A1") -> the row. The key comes from the configured key columns.
+    rows: dict[str, Row] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class StateSnapshot:
+    tables: dict[str, TableSnapshot] = field(default_factory=dict)  # by logical table name
+
+    def as_json(self) -> JsonValue:
+        """The snapshot as one JSON document, so the response diff engine can compare it."""
+        return {
+            name: {key: dict(row) for key, row in table.rows.items()}
+            for name, table in self.tables.items()
+        }

migrate_guard/domain/ports/state.py

@@ -0,0 +1,23 @@
+"""Ports for the database side: read a target's state, and reset it before each case."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from migrate_guard.domain.entities.state import StateSnapshot
+
+
+class StateError(Exception):
+    """Seeding or probing failed. The case becomes an error, never a match."""
+
+
+class StateProbe(ABC):
+    @abstractmethod
+    def snapshot(self) -> StateSnapshot:
+        """Read the watched tables. Read-only: it must never write."""
+
+
+class Seeder(ABC):
+    @abstractmethod
+    def seed(self) -> None:
+        """Reset the database to the known starting state, all or nothing."""

migrate_guard/domain/ports/target_runner.py

@@ -0,0 +1,21 @@
+"""Port: something that can execute a case (a running service, an in-process app...)."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from migrate_guard.domain.entities.case import HttpRequest, HttpResponse
+
+
+class TargetError(Exception):
+    """The target could not answer: connection refused, timeout, invalid response..."""
+
+
+class TargetRunner(ABC):
+    @abstractmethod
+    def check_reachable(self) -> None:
+        """Raise TargetError if the target can't be reached at all, before any case runs."""
+
+    @abstractmethod
+    def execute(self, request: HttpRequest) -> HttpResponse:
+        """Send the request and return the response; raise TargetError if there is none."""

migrate_guard/domain/services/case_compare.py

@@ -0,0 +1,23 @@
+"""Compare the two responses of one case: the status code, then the body with the rules."""
+
+from __future__ import annotations
+
+from migrate_guard.domain.entities.case import HttpResponse
+from migrate_guard.domain.entities.case_result import CaseResult, CaseStatus, StatusMismatch
+from migrate_guard.domain.services.response_diff import ResponseDiff, diff_responses
+from migrate_guard.domain.value_objects.rules import Rule
+
+
+def compare_case(
+    name: str, baseline: HttpResponse, candidate: HttpResponse, rules: tuple[Rule, ...]
+) -> tuple[CaseResult, ResponseDiff]:
+    """The result, plus the raw body diff so the caller can track which rules were used."""
+    mismatch = (
+        StatusMismatch(baseline.status, candidate.status)
+        if baseline.status != candidate.status
+        else None
+    )
+    # The body is compared even when the status differs: both facts help to find the cause.
+    body = diff_responses(baseline.body, candidate.body, rules)
+    status = CaseStatus.MATCH if mismatch is None and body.is_match else CaseStatus.DIFFERENCE
+    return CaseResult(name, status, mismatch, body.differences), body

migrate_guard/domain/services/redaction.py

@@ -0,0 +1,94 @@
+"""Hide secrets before anything reaches a report or a log (SPEC §7)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, replace
+
+from migrate_guard.domain.entities.case import Headers
+from migrate_guard.domain.entities.difference import MISSING, Difference, Side
+from migrate_guard.domain.value_objects.json_value import JsonValue
+
+REDACTED = "[REDACTED]"
+
+SENSITIVE_HEADERS = frozenset({"authorization", "cookie", "set-cookie", "x-api-key"})
+DEFAULT_FIELD_PATTERNS = ("password", "passwd", "token", "secret", "api_key", "apikey")
+
+# 13 to 19 digits, optionally grouped by spaces or dashes. Luhn-checked to limit false positives.
+_CARD_CANDIDATE = re.compile(r"(?<!\d)\d(?:[ -]?\d){12,18}(?!\d)")
+
+
+@dataclass(frozen=True)
+class RedactionPolicy:
+    """Field names are matched case-insensitively, as substrings: `token` hides `access_token`."""
+
+    field_patterns: tuple[str, ...] = DEFAULT_FIELD_PATTERNS
+
+    def is_sensitive_field(self, name: str) -> bool:
+        lowered = name.lower()
+        return any(p.lower() in lowered for p in self.field_patterns)
+
+
+def redact_headers(headers: Headers, policy: RedactionPolicy) -> Headers:
+    return tuple(
+        (name, REDACTED)
+        if name.lower() in SENSITIVE_HEADERS or policy.is_sensitive_field(name)
+        else (name, value)
+        for name, value in headers
+    )
+
+
+def redact_value(value: JsonValue, policy: RedactionPolicy) -> JsonValue:
+    if isinstance(value, dict):
+        return {
+            k: REDACTED if policy.is_sensitive_field(k) else redact_value(v, policy)
+            for k, v in value.items()
+        }
+    if isinstance(value, list):
+        return [redact_value(v, policy) for v in value]
+    if isinstance(value, str):
+        return redact_text(value)
+    if isinstance(value, int) and not isinstance(value, bool) and _is_card(str(value)):
+        return REDACTED
+    return value
+
+
+def redact_text(text: str) -> str:
+    return _CARD_CANDIDATE.sub(lambda m: REDACTED if _is_card(m.group()) else m.group(), text)
+
+
+def redact_difference(diff: Difference, policy: RedactionPolicy) -> Difference:
+    # Under a sensitive field everything goes, the detail too: it can quote the values.
+    if any(policy.is_sensitive_field(token) for token in diff.location.tokens):
+        return replace(
+            diff,
+            baseline=_hide(diff.baseline),
+            candidate=_hide(diff.candidate),
+            detail=REDACTED if diff.detail else "",
+        )
+    return replace(
+        diff,
+        baseline=_redact_side(diff.baseline, policy),
+        candidate=_redact_side(diff.candidate, policy),
+        detail=redact_text(diff.detail),
+    )
+
+
+def _hide(side: Side) -> Side:
+    return side if side is MISSING else REDACTED
+
+
+def _redact_side(side: Side, policy: RedactionPolicy) -> Side:
+    return side if side is MISSING else redact_value(side, policy)
+
+
+def _is_card(candidate: str) -> bool:
+    digits = [int(c) for c in candidate if c.isdigit()]
+    if not 13 <= len(digits) <= 19:
+        return False
+    total = 0
+    for i, d in enumerate(reversed(digits)):
+        if i % 2 == 1:
+            d = d * 2 - 9 if d > 4 else d * 2
+        total += d
+    return total % 10 == 0