mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/diffing.py

@@ -0,0 +1,444 @@
+"""Comparing two builds: what is different between the one on the left and the one on the right.
+
+``recipe-verify`` can already compare a new version against the version before it. This module
+answers the other question, the one a person actually has when a refresh looks wrong: here are two
+builds, what is different about them?
+
+Three rules shape everything below.
+
+**Both sides are verified before anything is compared.** Each side goes through
+:func:`recipe.version_summary`, which calls ``pipeline.verify_candidate`` and then reads the
+profile and lineage evidence off the verified snapshot. A comparison of unverified bytes would be
+worth nothing, because the bytes could say anything.
+
+**There is one drift vocabulary, not two.** Every change this module reports names the reviewed
+drift code that governs the same condition, in :data:`RELATED_DRIFT_CODES`: a column set that moved
+is ``RECIPE_SCHEMA_DRIFT``, a type that moved is ``RECIPE_TYPE_DRIFT``, a row count that moved is
+``RECIPE_ROW_COUNT_DRIFT``. Those codes are read from ``recipe._drift_report`` rather than invented
+here. Two conditions have no reviewed code, because a comparison of two arbitrary builds can meet
+cases a successor-against-predecessor check never does, and both are additions made here:
+
+* ``data_changed`` -- the shape is untouched and the bytes are not. The drift report has no such
+  code: it recomputes a version against its own predecessor under a recipe, where a change of data
+  with no change of shape is the ordinary case rather than a finding.
+* ``sources_changed`` -- even the data fingerprint matches, and only the recorded lineage differs.
+  The drift report folds lineage into ``EXACT_CANDIDATE_REPLAY`` for one build; it never compares
+  the lineage of two.
+
+Naming the reviewed code is a pointer, not a claim: it says which alert would look at this
+condition when a Recipe and its refresh bounds are in play. This module raises no alert.
+
+**A comparison describes; it never judges.** No severity, no eligibility, no opinion about whether
+a difference is acceptable -- ``recipe-verify`` owns that judgement and a read-only command that
+implied it would be putting a release opinion where nobody asked for one. That is also why the
+``DriftFinding`` shape is borrowed here without its ``severity`` field.
+
+The change list is the shortest true explanation rather than a restatement of every field: a
+removed column already explains the data fingerprint that moved with it, so ``data_changed`` is
+reported only when the shape is identical, and ``sources_changed`` only when even the data matches.
+Every fingerprint on both sides is carried in the payload regardless, so nothing is hidden.
+
+Nothing here prints. Every function returns facts or text, so the same comparison can be rendered
+into a browser page later without re-deriving it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.pipeline import verify_candidate
+from mostlyright.data_harness.recipe import VersionSummary, version_summary
+from mostlyright.data_harness.ux.readers import require_a_build
+
+# Every change this module can report, in the order a reader meets them: what the columns did,
+# then what the rows did, then what the bytes did.
+CHANGE_CODES: tuple[str, ...] = (
+    "column_added",
+    "column_removed",
+    "column_type_changed",
+    "row_count_changed",
+    "data_changed",
+    "sources_changed",
+)
+
+# The reviewed drift code that governs the same condition, or ``None`` where the drift review has
+# no equivalent. Both ``None`` entries are argued for in the module docstring above.
+RELATED_DRIFT_CODES: dict[str, str | None] = {
+    "column_added": "RECIPE_SCHEMA_DRIFT",
+    "column_removed": "RECIPE_SCHEMA_DRIFT",
+    "column_type_changed": "RECIPE_TYPE_DRIFT",
+    "row_count_changed": "RECIPE_ROW_COUNT_DRIFT",
+    "data_changed": None,
+    "sources_changed": None,
+}
+
+# The changes that are about the columns themselves, for `--columns-only`.
+COLUMN_CHANGE_CODES: frozenset[str] = frozenset(
+    {"column_added", "column_removed", "column_type_changed"}
+)
+
+_STATUS_BY_RESULT = {"identical": "builds_identical", "differs": "builds_differ"}
+
+
+@dataclass(frozen=True)
+class BuildChange:
+    """One difference between two builds, named at the granularity a person can act on.
+
+    A user chasing a broken refresh needs the column's name, not the sentence "the schema
+    changed", so every column-level difference is its own change carrying its own name.
+    """
+
+    code: str
+    summary: str
+    column: str | None = None
+    was: Any = None
+    now: Any = None
+    difference: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.code not in RELATED_DRIFT_CODES:
+            raise ValueError(f"unknown change code: {self.code!r}")
+
+    @property
+    def related_drift_code(self) -> str | None:
+        return RELATED_DRIFT_CODES[self.code]
+
+    @property
+    def is_column_change(self) -> bool:
+        return self.code in COLUMN_CHANGE_CODES
+
+    def to_dict(self) -> dict[str, Any]:
+        """The one record both renderings are built from.
+
+        The column name is a value and never a key (29-04's rule): a column called ``max_temp_c``
+        used as a key would be shown to a person as ``Max temp c``, a name its data does not have.
+        """
+
+        payload: dict[str, Any] = {"what": self.code}
+        if self.column is not None:
+            payload["column"] = self.column
+        if self.was is not None:
+            # `from` and `to` rather than the field names: read in order, a person meets them as
+            # "from this, to that", and that is also the order the plain rendering sorts them in.
+            payload["from"] = self.was
+        if self.now is not None:
+            payload["to"] = self.now
+        if self.difference is not None:
+            payload["difference"] = self.difference
+        payload["related drift alert"] = self.related_drift_code
+        return payload
+
+
+@dataclass(frozen=True)
+class ComparedBuild:
+    """One side of a comparison: what it is, who made it, and the verified shape of its data."""
+
+    run_dir: Path
+    manifest_version: str
+    candidate_digest: str
+    producer_principal: str
+    summary: VersionSummary
+
+    @property
+    def table_sha256(self) -> str:
+        return self.summary.table_sha256
+
+    @property
+    def row_count(self) -> int:
+        return self.summary.row_count
+
+    @property
+    def columns(self) -> tuple[str, ...]:
+        return self.summary.columns
+
+    @property
+    def column_types(self) -> dict[str, str]:
+        return dict(self.summary.column_types)
+
+    @property
+    def lineage_digest(self) -> str:
+        return self.summary.lineage_digest
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "run_dir": str(self.run_dir),
+            "manifest_version": self.manifest_version,
+            "candidate_digest": self.candidate_digest,
+            "table_sha256": self.table_sha256,
+            "lineage_digest": self.lineage_digest,
+            "built_by": self.producer_principal,
+            "row_count": self.row_count,
+            "columns": list(self.columns),
+        }
+
+
+@dataclass(frozen=True)
+class BuildComparison:
+    """Two verified builds and every difference between them."""
+
+    left: ComparedBuild
+    right: ComparedBuild
+    changes: tuple[BuildChange, ...]
+
+    @property
+    def status(self) -> str:
+        return "identical" if not self.changes else "differs"
+
+    @property
+    def same_build(self) -> bool:
+        """Whether both sides are the one build.
+
+        Kept apart from :attr:`status` on purpose. Two builds can hold the same data in the same
+        shape and still be two builds -- made by different people, under different Receipt
+        versions -- and answering "is the data the same?" with "these are the same build" would be
+        a different, false statement.
+        """
+
+        return self.left.candidate_digest == self.right.candidate_digest
+
+    @property
+    def column_changes(self) -> tuple[BuildChange, ...]:
+        return tuple(change for change in self.changes if change.is_column_change)
+
+    def to_dict(self, *, columns_only: bool = False) -> dict[str, Any]:
+        shown = self.column_changes if columns_only else self.changes
+        hidden = len(self.changes) - len(shown)
+        payload: dict[str, Any] = {
+            "status": _STATUS_BY_RESULT[self.status],
+            "summary": plain_comparison(self, columns_only=columns_only),
+            # The full count, always. A narrowed view narrows what is listed, never what is true.
+            "change count": len(self.changes),
+            "changes": _numbered(shown),
+            "first build": self.left.to_dict(),
+            "second build": self.right.to_dict(),
+        }
+        if hidden:
+            # A caller reading the record rather than the sentences still has to be able to tell
+            # that the list in front of it is not the whole list. The prose caveat is inside
+            # `summary`; this is the same fact in one field, so nobody has to parse prose for it.
+            payload["columns only"] = True
+        return payload
+
+
+def compare_builds(left: Path | str, right: Path | str) -> BuildComparison:
+    """Compare two sealed builds, verifying both before comparing either.
+
+    ``left`` is read as the earlier of the two and ``right`` as the later, so "added" means it is
+    in the second and not the first. Neither has to be the other's successor, and the two may
+    carry different Receipt versions.
+    """
+
+    first = _side(left)
+    second = _side(right)
+    return BuildComparison(
+        left=first, right=second, changes=_changes(first.summary, second.summary)
+    )
+
+
+def plain_comparison(comparison: BuildComparison, *, columns_only: bool = False) -> str:
+    """The plain-language answer, written from the same changes the record carries.
+
+    A comparison with nothing to report still says a sentence. An empty screen is not an answer.
+    """
+
+    if not comparison.changes:
+        return "\n".join(_nothing_changed_lines(comparison))
+    shown = comparison.column_changes if columns_only else comparison.changes
+    hidden = len(comparison.changes) - len(shown)
+    lines = [
+        f"Going from the first build to the second, {_things(len(comparison.changes))} changed:"
+    ]
+    if shown:
+        lines.extend(f"  {change.summary}" for change in shown)
+    else:
+        lines.append("  no column changed.")
+    if hidden:
+        lines.append(f"  {_left_out_sentence(hidden)}")
+    return "\n".join(lines)
+
+
+# ------------------------------------------------------------------------------------------------
+# Reading one side
+# ------------------------------------------------------------------------------------------------
+
+
+def _side(run_dir: Path | str) -> ComparedBuild:
+    """Verify one side and read back everything the comparison needs from it.
+
+    ``version_summary`` verifies the sealed tree and returns the shape of the data; it does not
+    carry the Receipt version or who made the build, and both belong in the answer, so
+    ``verify_candidate`` is called for those. A folder with no build in it is named as such first,
+    because the verified reader's refusal for a missing tree reads like a break-in rather than the
+    typo it usually is.
+    """
+
+    target = Path(run_dir)
+    require_a_build(target)
+    verified = verify_candidate(target)
+    return ComparedBuild(
+        run_dir=target,
+        manifest_version=verified.manifest_version,
+        candidate_digest=verified.candidate_digest,
+        producer_principal=verified.producer_principal,
+        summary=version_summary(target),
+    )
+
+
+# ------------------------------------------------------------------------------------------------
+# The comparison itself
+# ------------------------------------------------------------------------------------------------
+
+
+def _changes(before: VersionSummary, after: VersionSummary) -> tuple[BuildChange, ...]:
+    """Every difference between two verified summaries, most specific explanation first.
+
+    The shape is compared field by field over ``to_drift_dict``. Only when nothing about the shape
+    moved does the data fingerprint get its own change, and only when even that matches does the
+    recorded lineage get one: a removed column already accounts for the fingerprint that moved with
+    it, and saying so twice would read as two problems where there is one.
+    """
+
+    changes = [
+        *_column_changes(before, after),
+        *_type_changes(before, after),
+        *_row_count_changes(before, after),
+    ]
+    if changes:
+        return tuple(changes)
+    if before.table_sha256 != after.table_sha256:
+        return (
+            BuildChange(
+                code="data_changed",
+                summary=(
+                    "the data changed but its shape did not: the same columns, the same types "
+                    "and the same number of rows, over different data"
+                ),
+                was=before.table_sha256,
+                now=after.table_sha256,
+            ),
+        )
+    if before.lineage_digest != after.lineage_digest:
+        return (
+            BuildChange(
+                code="sources_changed",
+                summary=("the data is the same, but where it came from is recorded differently"),
+                was=before.lineage_digest,
+                now=after.lineage_digest,
+            ),
+        )
+    return ()
+
+
+def _column_changes(before: VersionSummary, after: VersionSummary) -> list[BuildChange]:
+    gone = sorted(set(before.columns) - set(after.columns))
+    arrived = sorted(set(after.columns) - set(before.columns))
+    return [
+        *(
+            BuildChange(
+                code="column_removed",
+                summary=f"the column {name} was removed",
+                column=name,
+                was=dict(before.column_types).get(name),
+            )
+            for name in gone
+        ),
+        *(
+            BuildChange(
+                code="column_added",
+                summary=f"the column {name} was added",
+                column=name,
+                now=dict(after.column_types).get(name),
+            )
+            for name in arrived
+        ),
+    ]
+
+
+def _type_changes(before: VersionSummary, after: VersionSummary) -> list[BuildChange]:
+    old = dict(before.column_types)
+    new = dict(after.column_types)
+    return [
+        BuildChange(
+            code="column_type_changed",
+            summary=f"the column {name} changed type from {old[name]} to {new[name]}",
+            column=name,
+            was=old[name],
+            now=new[name],
+        )
+        for name in sorted(set(old) & set(new))
+        if old[name] != new[name]
+    ]
+
+
+def _row_count_changes(before: VersionSummary, after: VersionSummary) -> list[BuildChange]:
+    if before.row_count == after.row_count:
+        return []
+    difference = _signed(after.row_count - before.row_count)
+    return [
+        BuildChange(
+            code="row_count_changed",
+            summary=(
+                f"the row count went from {before.row_count} to {after.row_count} ({difference})"
+            ),
+            was=before.row_count,
+            now=after.row_count,
+            difference=difference,
+        )
+    ]
+
+
+# ------------------------------------------------------------------------------------------------
+# Saying it plainly
+# ------------------------------------------------------------------------------------------------
+
+
+def _nothing_changed_lines(comparison: BuildComparison) -> list[str]:
+    lines = ["Nothing about the data or its shape is different."]
+    if comparison.same_build:
+        lines.append("Both sides are the same build: one build fingerprint, read twice.")
+        return lines
+    lines.append("These are still two builds, not one: their build fingerprints differ.")
+    if comparison.left.manifest_version != comparison.right.manifest_version:
+        lines.append(
+            f"They were written under different Receipt versions: "
+            f"{comparison.left.manifest_version} and {comparison.right.manifest_version}."
+        )
+    return lines
+
+
+def _left_out_sentence(hidden: int) -> str:
+    thing = "change is" if hidden == 1 else "changes are"
+    return (
+        f"only column changes were asked for, so {hidden} other {thing} not shown here; "
+        "run this again without --columns-only to see everything"
+    )
+
+
+def _things(count: int) -> str:
+    return "1 thing" if count == 1 else f"{count} things"
+
+
+def _signed(delta: int) -> str:
+    return f"+{delta}" if delta > 0 else str(delta)
+
+
+def _numbered(changes: tuple[BuildChange, ...]) -> dict[str, Any]:
+    width = len(str(max(len(changes), 1)))
+    return {
+        f"change {index:0{width}d}": change.to_dict()
+        for index, change in enumerate(changes, start=1)
+    }
+
+
+__all__ = [
+    "CHANGE_CODES",
+    "COLUMN_CHANGE_CODES",
+    "RELATED_DRIFT_CODES",
+    "BuildChange",
+    "BuildComparison",
+    "ComparedBuild",
+    "compare_builds",
+    "plain_comparison",
+]