mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/local_review.py

@@ -0,0 +1,375 @@
+"""Run local deterministic checks without creating a review decision.
+
+**It writes nothing.** No file, no folder, no permission, no recorded state. The tests prove that
+by digesting the entire tree before and after the call rather than by reading the code and
+believing it, and they do the same for a Workbench folder's control folder, because a recorded
+state file is what an accidental write would touch first.
+
+**It cannot say a decision.** :data:`LOCAL_REVIEW_STATUS` is a module constant and is not a
+parameter of anything, so no code path can produce another value;
+:attr:`LocalReview.human_review_pending` is a property returning the literal ``True`` rather than a
+field, so it cannot be constructed false. Releasing a dataset needs two independent reviewers and a
+signed decision, and :data:`PENDING_SENTENCE` says so on every run, passing or failing, in both
+output modes.
+
+**It cannot seal one.** This module does not import sealing or signing code.
+
+**A broken build is a result, not a crash.** The seal check runs through
+:func:`pipeline.inspect_candidate`, which replays the whole sealed tree before reporting a single
+fact. When it refuses, its refusal is captured as a failed check carrying its finding identifier:
+"this build does not verify" is exactly the answer a reviewer asked for. Only the refusal for a
+folder with no build in it is left to raise, because that is a typo rather than a review result.
+
+One reading, not two: every fact below comes from the single :func:`inspect_candidate` call. A
+second open of the same folder would be a second race window, and closing that window is the entire
+reason that reader exists.
+
+**Which route the rights check takes, and why.** ``pipeline._validate_rights`` takes a parsed
+``TablePlan`` -- not a sealed tree -- and raises on the first source it objects to. It can
+therefore neither be handed a verified reading nor report per source, which is what a review needs,
+so the rights facts are read from the ``evidence/sources.json`` member of that same verified
+reading and reported one source at a time. The values are the ones the build recorded and sealed;
+the gate that acted on them at build time is named ``rights_permission`` in the recorded checks
+fingerprint.
+
+Nothing here prints. Every function returns facts or text for terminal or browser rendering.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness.pipeline import (
+    GRAPH_MANIFEST_VERSION,
+    GRAPH_RECIPE_MANIFEST_VERSION,
+    BuildError,
+    inspect_candidate,
+)
+from mostlyright.data_harness.ux.readers import require_a_build
+from mostlyright.data_harness.ux.render import render_human
+
+# The only status this module can report. It cannot be constructed as a sealed decision.
+LOCAL_REVIEW_STATUS = "local_checks_completed"
+
+# Printed on every run, whether the checks passed or failed, in both output modes. This is the
+# honest line: the checks below are what one machine can decide alone, and that is not a release.
+PENDING_SENTENCE = (
+    "Human review is still pending. These checks are what this machine can decide on its own; "
+    "releasing a dataset needs two independent reviewers and a signed decision."
+)
+
+# The names of the checks this module contributes. The quality checks keep the names the build
+# recorded for them (MIN_ROWS, NOT_NULL_<column>, UNIQUE_GRAIN), so a check reads the same here as
+# it does in the receipt.
+SEAL_CHECK = "SEAL_REPLAY"
+JOIN_CHECK = "JOIN_ROW_MULTIPLIER"
+LINEAGE_CHECK = "LINEAGE_COMPLETE"
+RIGHTS_CHECK_PREFIX = "RIGHTS_"
+
+# Where the rendered check lines sit in the payload both renderings are built from, and where the
+# closing sentence sits. Both are keys a person reads; the check names inside are values, never
+# keys, because a name taken from the data would be relabelled into a name the data does not have.
+CHECKS_KEY = "checks"
+PENDING_KEY = "what happens next"
+
+# Where the one fact a script branches on sits in the payload.
+ALL_CHECKS_PASSED_KEY = "all_checks_passed"
+
+_PASSED = "[pass]"
+_FAILED = "[fail]"
+
+# What the build's own recorded checks fingerprint requires of a join: every left row matched, and
+# exactly one row out per row in. Read from ``pipeline.validation_policy_digest``'s mandatory gates
+# rather than restated here, so local review applies the Build's rule.
+_REQUIRED_ROW_MULTIPLIER = 1.0
+
+# Rights statuses the build refuses outright.
+_REFUSED_RIGHTS = frozenset({"unknown", "prohibited"})
+
+
+@dataclass(frozen=True)
+class LocalCheck:
+    """One check, its outcome, and the recorded value that decided it.
+
+    ``evidence`` is not a restatement of the outcome: it is the number, the name, or the identifier
+    a person would ask for next. A check that says only "failed" makes its reader open the folder,
+    which is the thing this command exists to save them.
+    """
+
+    name: str
+    passed: bool
+    evidence: str
+
+    @property
+    def line(self) -> str:
+        """This check as one plain line: outcome first, then what it was, then why."""
+
+        return f"{_PASSED if self.passed else _FAILED} {self.name}: {self.evidence}"
+
+
+@dataclass(frozen=True)
+class LocalReview:
+    """The result of running every deterministic check on one build.
+
+    ``status`` and ``human_review_pending`` are properties rather than fields on purpose. A field
+    is something a caller sets; these two are the whole safety argument of the module, so they are
+    not settable at all -- constructing this with either as a keyword is a ``TypeError``.
+    """
+
+    run_dir: Path
+    candidate_digest: str | None
+    table_sha256: str | None
+    checks: tuple[LocalCheck, ...]
+
+    @property
+    def status(self) -> str:
+        return LOCAL_REVIEW_STATUS
+
+    @property
+    def human_review_pending(self) -> bool:
+        return True
+
+    @property
+    def passed(self) -> bool:
+        """Whether every check passed. Never a verdict on the build -- only on the checks."""
+
+        return all(check.passed for check in self.checks)
+
+    def to_dict(self) -> dict[str, Any]:
+        """The one payload both renderings are built from."""
+
+        width = len(str(max(len(self.checks), 1)))
+        return {
+            "status": LOCAL_REVIEW_STATUS,
+            "run_dir": str(self.run_dir),
+            "candidate_digest": self.candidate_digest,
+            "table_sha256": self.table_sha256,
+            ALL_CHECKS_PASSED_KEY: self.passed,
+            "human_review_pending": self.human_review_pending,
+            CHECKS_KEY: {
+                f"check {index:0{width}d}": check.line
+                for index, check in enumerate(self.checks, start=1)
+            },
+            PENDING_KEY: PENDING_SENTENCE,
+        }
+
+    def lines(self) -> list[str]:
+        """Exactly the plain lines the command line prints, from exactly the same payload."""
+
+        return render_human(self.to_dict()).splitlines()
+
+
+def local_review_exit_code(payload: Mapping[str, Any]) -> int:
+    """1 when a check failed, so this reads as a gate in a script.
+
+    Derived from the emitted payload rather than a second Build read. The
+    number a script branches on and the line a person reads are the same fact.
+
+    A failed seal replay exits 1. Passing checks exit 0 and leave human review pending; this
+    command does not approve a build.
+    """
+
+    return 0 if payload.get(ALL_CHECKS_PASSED_KEY) is True else 1
+
+
+def run_local_review(run_dir: Path | str) -> LocalReview:
+    """Run every deterministic check on the build at ``run_dir`` and report, writing nothing.
+
+    A folder with no build in it is named as such before anything else runs, because the reader's
+    own refusal for a missing tree reads like a break-in rather than the typo it usually is. Every
+    other refusal from the sealed reading becomes a failed seal check, so a build that does not
+    verify comes back as a review rather than a traceback.
+    """
+
+    target = Path(run_dir)
+    require_a_build(target)
+    try:
+        inspection = inspect_candidate(target)
+    except BuildError as error:
+        return LocalReview(
+            run_dir=target,
+            candidate_digest=None,
+            table_sha256=None,
+            checks=(
+                LocalCheck(
+                    name=SEAL_CHECK,
+                    passed=False,
+                    evidence=f"this build does not replay as sealed ({error.finding_id})",
+                ),
+            ),
+        )
+    checks: list[LocalCheck] = [
+        LocalCheck(
+            name=SEAL_CHECK,
+            passed=True,
+            evidence=f"every file replays to the fingerprint {inspection.candidate_digest}",
+        ),
+        *_quality_checks(inspection.quality),
+        _join_check(
+            inspection.join,
+            graph=inspection.manifest_version
+            in {GRAPH_MANIFEST_VERSION, GRAPH_RECIPE_MANIFEST_VERSION},
+        ),
+        _lineage_check(
+            inspection.columns,
+            inspection.lineage,
+            graph=inspection.manifest_version
+            in {GRAPH_MANIFEST_VERSION, GRAPH_RECIPE_MANIFEST_VERSION},
+        ),
+        *_rights_checks(inspection.sources),
+    ]
+    return LocalReview(
+        run_dir=target,
+        candidate_digest=inspection.candidate_digest,
+        table_sha256=inspection.table_sha256,
+        checks=tuple(checks),
+    )
+
+
+def _quality_checks(quality: Mapping[str, Any]) -> list[LocalCheck]:
+    """Every check the build recorded, under the name the build recorded it."""
+
+    recorded = quality.get("checks") if isinstance(quality, Mapping) else None
+    if not isinstance(recorded, list):
+        return [
+            LocalCheck(
+                name="QUALITY_CHECKS",
+                passed=False,
+                evidence="this build recorded no list of checks",
+            )
+        ]
+    return [
+        LocalCheck(
+            name=str(check.get("check_id", "an unnamed check")),
+            passed=bool(check.get("passed")),
+            evidence=f"wanted {check.get('expected')}, found {check.get('observed')}",
+        )
+        for check in recorded
+        if isinstance(check, Mapping)
+    ]
+
+
+def _join_check(join: Mapping[str, Any], *, graph: bool = False) -> LocalCheck:
+    """The declared relationship against the rows that actually came out of it."""
+
+    if graph:
+        nodes = join.get("nodes") if isinstance(join, Mapping) else None
+        valid = isinstance(nodes, list) and all(isinstance(node, Mapping) for node in nodes)
+        joins = sum(
+            node.get("operation") == "join" for node in nodes or () if isinstance(node, Mapping)
+        )
+        return LocalCheck(
+            name=JOIN_CHECK,
+            passed=valid,
+            evidence=f"the verified graph records {joins} join operation(s)",
+        )
+    if not join:
+        return LocalCheck(
+            name=JOIN_CHECK,
+            passed=True,
+            evidence="this build joins nothing, so there is no relationship to hold to",
+        )
+    cardinality = join.get("cardinality")
+    multiplier = join.get("row_multiplier")
+    unmatched = join.get("unmatched_left_rows")
+    evidence = (
+        f"declared {cardinality}; {join.get('left_rows')} rows in, {join.get('output_rows')} out "
+        f"({multiplier} out per row in), {unmatched} did not match"
+    )
+    passed = multiplier == _REQUIRED_ROW_MULTIPLIER and unmatched == 0
+    return LocalCheck(name=JOIN_CHECK, passed=passed, evidence=evidence)
+
+
+def _lineage_check(
+    columns: Sequence[str], lineage: Mapping[str, Any], *, graph: bool = False
+) -> LocalCheck:
+    """Whether every column that shipped can be traced back to a column that arrived."""
+
+    entries = lineage.get("columns", {}) if graph and isinstance(lineage, Mapping) else lineage
+    untraced = [
+        str(column)
+        for column in columns
+        if not _traces_to_a_source(entries.get(column) if isinstance(entries, Mapping) else None)
+    ]
+    if untraced:
+        return LocalCheck(
+            name=LINEAGE_CHECK,
+            passed=False,
+            evidence=(
+                f"{len(columns) - len(untraced)} of {len(columns)} columns trace to a column of a "
+                f"source; no source recorded for: {', '.join(untraced)}"
+            ),
+        )
+    return LocalCheck(
+        name=LINEAGE_CHECK,
+        passed=True,
+        evidence=f"all {len(columns)} columns trace to a column of a source",
+    )
+
+
+def _traces_to_a_source(entry: Any) -> bool:
+    if isinstance(entry, Mapping) and isinstance(entry.get("inputs"), list):
+        return bool(entry["inputs"]) and all(
+            isinstance(item, Mapping)
+            and bool(item.get("source_id"))
+            and bool(item.get("source_column"))
+            for item in entry["inputs"]
+        )
+    return (
+        isinstance(entry, Mapping)
+        and bool(entry.get("source_id"))
+        and bool(entry.get("source_column"))
+    )
+
+
+def _rights_checks(sources: Sequence[Mapping[str, Any]]) -> list[LocalCheck]:
+    """What each source is recorded as allowing, one check per source.
+
+    One check per source rather than one for all of them: a reviewer who has to act on this needs
+    the name of the file that is the problem, not the sentence "the rights do not permit this".
+    """
+
+    if not sources:
+        return [
+            LocalCheck(
+                name=f"{RIGHTS_CHECK_PREFIX}NONE",
+                passed=False,
+                evidence="this build recorded no source to check the rights of",
+            )
+        ]
+    checks: list[LocalCheck] = []
+    for source in sources:
+        name = str(source.get("source_id", "an unnamed source"))
+        rights = source.get("rights")
+        rights = rights if isinstance(rights, Mapping) else {}
+        status = str(rights.get("status", "not recorded"))
+        permissions = [str(item) for item in rights.get("permissions", ()) or ()]
+        allowed = ", ".join(permissions) if permissions else "nothing"
+        checks.append(
+            LocalCheck(
+                name=f"{RIGHTS_CHECK_PREFIX}{name}",
+                passed=status not in _REFUSED_RIGHTS and bool(permissions),
+                evidence=f"recorded as {status}; may {allowed}",
+            )
+        )
+    return checks
+
+
+__all__ = [
+    "ALL_CHECKS_PASSED_KEY",
+    "CHECKS_KEY",
+    "JOIN_CHECK",
+    "LINEAGE_CHECK",
+    "LOCAL_REVIEW_STATUS",
+    "PENDING_KEY",
+    "PENDING_SENTENCE",
+    "RIGHTS_CHECK_PREFIX",
+    "SEAL_CHECK",
+    "LocalCheck",
+    "LocalReview",
+    "local_review_exit_code",
+    "run_local_review",
+]