sqlassert-dbt 0.3.1__py3-none-any.whl

sqlassert_dbt/project.py

@@ -0,0 +1,340 @@
+"""Analyze a dbt project from its `target/manifest.json`, without dbt.
+
+Each model is analyzed in a Program of its own (`program.py`): its own tests
+are Assertions, the passing tests of what it reads are Property Declarations.
+An incremental model is analyzed once per `is_incremental()` branch, and a
+claim about it holds only when it holds in both.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from sqlassert_dbt.expectations import Expectation, PropertyKind, expectations
+from sqlassert_dbt.manifest import Manifest, Relation, load_manifest
+from sqlassert_dbt.program import QUERY_MATERIALIZATIONS, Body, BranchResult, Builder, branches, raw_line_of
+from sqlassert_dbt.report import DbtReport, Location, MarkerOutcome, Problem, Status, TestOutcome, Untested
+from sqlassert.dialects import MODELLED_DIALECTS
+from sqlassert.ir.model import LiteralValue
+from sqlassert.reporting import Outcome
+from sqlassert.sql_parse import _marker_shapes
+
+# The dialects sqlassert analyzes soundly: those `dialects.py` models. A dbt
+# adapter maps onto its SQLGlot dialect; one not modelled is analyzed only
+# under a dialect the user names explicitly.
+SUPPORTED_DIALECTS = MODELLED_DIALECTS
+_ADAPTER_DIALECTS = {
+    "duckdb": "duckdb", "postgres": "postgres", "redshift": "redshift", "snowflake": "snowflake", "bigquery": "bigquery",
+    "databricks": "databricks", "spark": "spark", "trino": "trino", "mysql": "mysql", "sqlserver": "tsql",
+    "fabric": "tsql", "athena": "athena", "clickhouse": "clickhouse", "oracle": "oracle",
+}
+
+# Incremental strategies whose table stays unique on `unique_key` when every
+# batch is: matching rows are replaced, never appended.
+_REPLACING_STRATEGIES = {"merge", "delete+insert"}
+
+UNSUPPORTED_DIALECT = "dbt-unsupported-dialect"
+UNANALYZED_MODEL = "dbt-unanalyzed-model"
+UNANALYZED_BRANCH = "dbt-unanalyzed-branch"
+UNKNOWN_COLUMNS = "dbt-unknown-columns"
+EPHEMERAL_NOT_LOCATED = "dbt-ephemeral-not-located"
+UNTRUSTED_UPSTREAM_TESTS = "dbt-untrusted-upstream-tests"
+
+
+class ProjectError(Exception):
+    """The project cannot be analyzed at all: no manifest, or an unreadable one."""
+
+
+def analyze_project(
+    project_dir: Path, *, manifest_path: Path | None = None, dialect: str | None = None, trust_upstream_tests: bool = False,
+) -> DbtReport:
+    """Every test and marker of the dbt project at `project_dir`.
+
+    `dialect` overrides the one the manifest's adapter names; without it, an
+    adapter sqlassert does not support leaves every model unanalyzed.
+    `trust_upstream_tests` makes the passing tests of what a model reads facts
+    about it, which holds when they run before it, as under `dbt build`.
+    """
+    from sqlassert_dbt.manifest import ManifestError
+
+    path = manifest_path or project_dir / "target" / "manifest.json"
+    try:
+        manifest = load_manifest(path)
+    except ManifestError as error:
+        raise ProjectError(f"{error}; run `dbt compile` (or `dbt build`) first") from error
+    return _Analysis(manifest, tuple(expectations(manifest)), trust_upstream_tests).run(dialect)
+
+
+@dataclass
+class _Analysis:
+    manifest: Manifest
+    expectations: tuple[Expectation, ...]
+    trust_upstream_tests: bool = False
+
+    def run(self, requested: str | None) -> DbtReport:
+        problems: list[Problem] = []
+        dialect = self._dialect(requested, problems)
+        tests: list[TestOutcome] = []
+        markers: list[MarkerOutcome] = []
+        untested: list[Untested] = []
+        undeclared: set[str] = set()
+        builder = (
+            Builder(self.manifest.relations, self.expectations, dialect, self.trust_upstream_tests)
+            if dialect is not None else None
+        )
+        for relation in sorted(self.manifest.relations.values(), key=lambda relation: relation.unique_id):
+            own = [e for e in self.expectations if e.node == relation.unique_id]
+            if builder is None:
+                tests.extend(self._outcome(e, relation, Status.NOT_PROVED, "the project's dialect is not supported") for e in own)
+                continue
+            outcome = self._model(builder, relation, own)
+            tests.extend(outcome.tests)
+            markers.extend(outcome.markers)
+            untested.extend(outcome.untested)
+            problems.extend(outcome.problems)
+            undeclared |= outcome.undeclared
+        if builder is not None and builder.untrusted:
+            problems.append(Problem(
+                UNTRUSTED_UPSTREAM_TESTS,
+                f"{len(builder.untrusted)} passing test(s) of the relations models read were not used as facts, since nothing "
+                "says they ran before those models were built: pass --trust-upstream-tests when they do (dbt build), "
+                "or run through `sqlassert-dbt build`",
+                "warning",
+            ))
+        for node in sorted(undeclared):
+            relation = self.manifest.relations[node]
+            supply = (
+                "an enforced model contract listing every column's data_type declares them"
+                if relation.resource_type == "model"
+                else "only the warehouse's catalog lists them"
+            )
+            problems.append(Problem(
+                UNKNOWN_COLUMNS,
+                f"the columns of {relation.resource_type} {relation.label} are not all known from the manifest, so its keys "
+                f"and nullability come from its passing tests only: {supply}",
+                "warning", Location(relation.patch_path or relation.original_file_path), relation.label,
+            ))
+        return DbtReport(dialect, tuple(tests), tuple(markers), tuple(untested), tuple(_unique(problems)))
+
+    def _dialect(self, requested: str | None, problems: list[Problem]) -> str | None:
+        if requested is not None:
+            return requested
+        adapter = self.manifest.adapter_type
+        dialect = _ADAPTER_DIALECTS.get(adapter or "")
+        if dialect in SUPPORTED_DIALECTS:
+            return dialect
+        problems.append(Problem(
+            UNSUPPORTED_DIALECT,
+            f"the {adapter or 'unknown'} adapter's SQL dialect is not supported (supported: {', '.join(sorted(SUPPORTED_DIALECTS))}), "
+            "so no model was analyzed; pass --dialect to analyze it under a dialect whose semantics you vouch for",
+            "error",
+        ))
+        return None
+
+    def _model(self, builder: Builder, relation: Relation, own: list[Expectation]) -> _ModelOutcome:
+        outcome = _ModelOutcome()
+        if relation.resource_type != "model":
+            outcome.tests.extend(
+                self._outcome(e, relation, Status.NOT_PROVED, f"a {relation.resource_type} is a table: only its own data shows this")
+                for e in own
+            )
+            return outcome
+        if relation.language != "sql" or relation.compiled_code is None:
+            why = f"it is a {relation.language} model" if relation.language != "sql" else "it has no compiled code; run `dbt compile`"
+            # Its own markers go unchecked: that fails the check, not a fact a connection could supply.
+            severity = "error" if relation.language == "sql" and _has_markers(relation.raw_code) else "warning"
+            outcome.problems.append(Problem(
+                UNANALYZED_MODEL, f"model {relation.name} was not analyzed: {why}", severity,
+                Location(relation.original_file_path), relation.name,
+            ))
+            outcome.tests.extend(self._outcome(e, relation, Status.NOT_PROVED, "its model was not analyzed") for e in own)
+            return outcome
+
+        found = branches(relation, self.manifest.relations)
+        for warning in found.warnings:
+            outcome.problems.append(Problem(EPHEMERAL_NOT_LOCATED, warning, "warning", Location(relation.original_file_path), relation.name))
+        if found.unrendered is not None:
+            outcome.problems.append(Problem(
+                UNANALYZED_BRANCH, f"model {relation.name}: {found.unrendered}", "warning", Location(relation.original_file_path), relation.name,
+            ))
+        analyzed = tuple(e for e in own if e.asserted is not None and e.unprovable is None)
+        results = [(body, builder.analyze(relation, body, analyzed)) for body in found.bodies]
+        complete = found.unrendered is None
+        for _, result in results:
+            outcome.undeclared |= result.undeclared
+
+        for expectation in own:
+            outcome.tests.append(self._test(expectation, relation, results, complete, found.unrendered))
+        outcome.markers.extend(self._markers(relation, results, found.unrendered))
+        outcome.problems.extend(self._problems(relation, results))
+        if complete and relation.materialized != "ephemeral":
+            outcome.untested.extend(self._untested(relation, own, results))
+        return outcome
+
+    def _outcome(self, e: Expectation, relation: Relation, status: Status, reason: str, explanation: str = "") -> TestOutcome:
+        return TestOutcome(e.unique_id, e.name, e.kind, relation.label, Location(e.path), status, reason, explanation)
+
+    def _test(
+        self, e: Expectation, relation: Relation, results: list[tuple[Body, BranchResult]], complete: bool, unrendered: str | None,
+    ) -> TestOutcome:
+        if e.asserted is None or e.unprovable is not None:
+            return self._outcome(e, relation, Status.NOT_PROVED, e.unprovable or "it states no Property")
+        found = [test for _, result in results if (test := result.tests.get(e.unique_id)) is not None]
+        failed = next((test for test in found if not test.proved), None)
+        if failed is not None or len(found) != len(results):
+            reason = "its Property is not proved from the SQL"
+            return self._outcome(e, relation, Status.NOT_PROVED, reason, failed.explanation if failed else "")
+        explanation = found[0].explanation
+        if not complete:
+            return self._outcome(e, relation, Status.NOT_PROVED, unrendered or "a branch was not analyzed", explanation)
+        reason = self._materialization_gap(e, relation)
+        if reason is not None:
+            return self._outcome(e, relation, Status.NOT_PROVED, reason, explanation)
+        return self._outcome(e, relation, Status.PROVED, "", explanation)
+
+    def _materialization_gap(self, e: Expectation, relation: Relation) -> str | None:
+        """Why a Property of the model's query is not one of its relation, or None."""
+        if relation.materialized in QUERY_MATERIALIZATIONS | {"ephemeral"}:
+            return None
+        if relation.materialized != "incremental":
+            return f"a {relation.materialized} materialization's rows are not known to be its query's"
+        match e.asserted:
+            case "not_null" | "enum":
+                return None  # Every row of the table came from one batch.
+            case "unique" | "key":
+                if relation.incremental_predicates:
+                    return (
+                        "its incremental_predicates can keep an earlier row out of the match on its unique_key, "
+                        "so a key of every batch is not one of the table"
+                    )
+                key = {column.lower() for column in relation.unique_key}
+                if relation.incremental_strategy in _REPLACING_STRATEGIES and key == {column.lower() for column in e.columns}:
+                    return None
+                return (
+                    "an incremental table keeps rows of earlier runs, so a key of every batch is a key of the table only "
+                    "under a merge or delete+insert strategy on that unique_key"
+                )
+            case _:
+                return "an incremental table keeps rows of earlier runs, whose references may since have gone"
+
+    def _markers(self, relation: Relation, results: list[tuple[Body, BranchResult]], unrendered: str | None) -> list[MarkerOutcome]:
+        grouped: dict[tuple, list] = {}
+        for index, (_, result) in enumerate(results):
+            for marker in result.markers:
+                key = (
+                    (marker.raw_line, marker.place, marker.marker) if marker.raw_line is not None
+                    else (None, index, marker.line, marker.place, marker.marker)
+                )
+                grouped.setdefault(key, []).append(marker)
+        found = []
+        for markers in grouped.values():
+            first = markers[0]
+            failed = next((marker for marker in markers if marker.outcome is Outcome.UNKNOWN), None)
+            outcome, explanation = (Outcome.UNKNOWN, failed.explanation) if failed else (Outcome.PROVED, first.explanation)
+            if outcome is Outcome.PROVED and unrendered is not None:
+                outcome, explanation = Outcome.UNKNOWN, f"{explanation}\nnot proved for every run: {unrendered}"
+            location = (
+                Location(relation.original_file_path, first.raw_line) if first.raw_line is not None
+                else Location(relation.compiled_path or relation.original_file_path, first.line)
+            )
+            found.append(MarkerOutcome(relation.name, location, first.marker, outcome, explanation))
+        return found
+
+    def _problems(self, relation: Relation, results: list[tuple[Body, BranchResult]]) -> list[Problem]:
+        found = []
+        for body, result in results:
+            for problem in result.problems:
+                diagnostic = problem.diagnostic
+                if problem.raw_line is not None:
+                    location = Location(relation.original_file_path, problem.raw_line)
+                elif problem.line is not None:
+                    location = Location(relation.compiled_path or relation.original_file_path, problem.line)
+                else:
+                    location = Location(relation.original_file_path)
+                message = _raw_lines_in(diagnostic.message, body) if problem.raw_line is not None else diagnostic.message
+                found.append(Problem(diagnostic.code, message, "warning" if problem.warning else "error", location, relation.name))
+        return found
+
+    def _untested(self, relation: Relation, own: list[Expectation], results: list[tuple[Body, BranchResult]]) -> list[Untested]:
+        incremental = relation.materialized == "incremental"
+        if relation.materialized not in QUERY_MATERIALIZATIONS and not incremental:
+            return []
+        additions = [
+            {(a.kind, a.columns, a.values): a for a in result.additions
+             if not incremental or a.kind in {"not_null", "enum"}}
+            for _, result in results
+        ]
+        common = [addition for key, addition in additions[0].items() if all(key in other for other in additions[1:])]
+        stated = [(e.asserted, {c.lower() for c in e.columns}) for e in own]
+        location = Location(relation.patch_path or relation.original_file_path)
+        found = []
+        for addition in common:
+            columns = {column.lower() for column in addition.columns}
+            entry = _schema_entry(addition.kind, addition.columns, addition.values, stated, columns)
+            if entry is not None:
+                column = addition.columns[0] if len(addition.columns) == 1 else None
+                found.append(Untested(relation.name, location, column, entry, addition.explanation))
+        return found
+
+
+@dataclass
+class _ModelOutcome:
+    tests: list[TestOutcome]
+    markers: list[MarkerOutcome]
+    untested: list[Untested]
+    problems: list[Problem]
+    undeclared: set[str]
+
+    def __init__(self) -> None:
+        self.tests, self.markers, self.untested, self.problems, self.undeclared = [], [], [], [], set()
+
+
+def _schema_entry(
+    kind: PropertyKind, columns: tuple[str, ...], values: tuple[LiteralValue, ...],
+    stated: list[tuple[PropertyKind | None, set[str]]], members: set[str],
+) -> str | None:
+    """The schema.yml test stating a proved Property, None when a test already
+    states it or no standard test does (a nullable composite Unique Set)."""
+    def tested(*kinds: str) -> bool:
+        return any(asserted in kinds and found == members for asserted, found in stated)
+
+    match kind:
+        case "not_null":
+            return None if tested("not_null") or any(a == "key" and members <= found for a, found in stated) else "not_null"
+        case "enum":
+            if tested("enum"):
+                return None
+            listed = ", ".join(value.sql() if value.type == "string" else value.text for value in values)
+            quote = "" if all(value.type == "string" for value in values) else ", quote: false"
+            return f"accepted_values: {{values: [{listed}]{quote}}}"
+        case "unique" | "key" if len(columns) == 1:
+            return None if tested("unique", "key") else "unique"
+        case "key":
+            if tested("unique", "key"):
+                return None
+            return f"dbt_utils.unique_combination_of_columns: {{combination_of_columns: [{', '.join(columns)}]}}"
+        case _:
+            return None
+
+
+def _raw_lines_in(message: str, body: Body) -> str:
+    """`message` with each body line it names replaced by the model file's line."""
+    def replaced(match: re.Match[str]) -> str:
+        line = raw_line_of(body, int(match.group(1)))
+        return f"line {line}" if line is not None else match.group(0)
+
+    return re.sub(r"\bline (\d+)\b", replaced, message)
+
+
+def _unique(problems: list[Problem]) -> list[Problem]:
+    return list(dict.fromkeys(problems))
+
+
+_PROPERTY_MARKER = re.compile(r"/\*\*\s*(ASSERT|DECLARE)\b", re.IGNORECASE)
+
+
+def _has_markers(sql: str) -> bool:
+    """Whether `sql` writes a Property Marker."""
+    return any(_PROPERTY_MARKER.match(match.group()) for match in _marker_shapes(sql))

sqlassert_dbt/report.py

@@ -0,0 +1,158 @@
+"""What analyzing a dbt project found, as plain values, and its text rendering.
+
+Every item has a `Location` (a project-relative path and a line when known),
+so each maps onto a `check` finding: a path, a line, a code, a message, and a
+severity.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+from sqlassert.check import EXIT_FINDINGS, EXIT_OK
+from sqlassert.reporting import Outcome
+
+
+@dataclass(frozen=True)
+class Location:
+    path: str
+    line: int | None = None
+
+    def __str__(self) -> str:
+        return self.path if self.line is None else f"{self.path}:{self.line}"
+
+
+class Status(Enum):
+    PROVED = "proved"
+    NOT_PROVED = "not proved"
+
+
+@dataclass(frozen=True)
+class TestOutcome:
+    """A dbt test or contract constraint, checked against its model's SQL.
+
+    A PROVED test can never fail, so dbt may skip it; a NOT_PROVED one still
+    carries coverage only the warehouse run gives. `reason` says why it was
+    not proved; `explanation` is the proof or the failed attempt.
+    """
+
+    unique_id: str
+    name: str
+    kind: Literal["test", "constraint"]
+    model: str
+    location: Location
+    status: Status
+    reason: str = ""
+    explanation: str = ""
+
+    @property
+    def skippable(self) -> bool:
+        return self.kind == "test" and self.status is Status.PROVED
+
+
+@dataclass(frozen=True)
+class MarkerOutcome:
+    """A Property Marker written in a model file. `location` is the model file
+    when its line is known, else the compiled file and its line."""
+
+    model: str
+    location: Location
+    marker: str
+    outcome: Outcome
+    explanation: str = ""
+
+
+@dataclass(frozen=True)
+class Untested:
+    """A Property proved of a model that none of its tests states: `test` is
+    the entry to add under the column (or, with no column, the model) in `location`."""
+
+    model: str
+    location: Location
+    column: str | None
+    test: str
+    explanation: str = ""
+
+
+@dataclass(frozen=True)
+class Problem:
+    """A Diagnostic: a part of the project analysis could not model. A warning
+    names a fact a connection or the project could supply; it never fails. An
+    error fails the check: a model whose own markers went unchecked."""
+
+    code: str
+    message: str
+    severity: Literal["error", "warning"]
+    location: Location | None = None
+    model: str | None = None
+
+
+@dataclass(frozen=True)
+class DbtReport:
+    dialect: str | None
+    tests: tuple[TestOutcome, ...] = ()
+    markers: tuple[MarkerOutcome, ...] = ()
+    untested: tuple[Untested, ...] = ()
+    problems: tuple[Problem, ...] = ()
+
+    @property
+    def failed(self) -> bool:
+        """A marker not proved, or an error. Tests not proved do not fail it:
+        the warehouse run still checks them."""
+        return any(marker.outcome is Outcome.UNKNOWN for marker in self.markers) or any(
+            problem.severity == "error" for problem in self.problems
+        )
+
+
+def exit_code(report: DbtReport, *, require_proved: bool = False) -> int:
+    """`EXIT_FINDINGS` when the report failed or, under `require_proved`, a
+    test is not proved: for a project whose every test the SQL must back."""
+    unproved = require_proved and any(test.kind == "test" and test.status is Status.NOT_PROVED for test in report.tests)
+    return EXIT_FINDINGS if report.failed or unproved else EXIT_OK
+
+
+def format_text(report: DbtReport, *, explain: bool = False) -> str:
+    lines: list[str] = []
+
+    def evidence(text: str) -> None:
+        if explain and text:
+            lines.extend("    " + line for line in text.splitlines())
+
+    for marker in report.markers:
+        lines.append(f"{marker.location}: {marker.outcome.value.upper()} {marker.marker} ({marker.model})")
+        if marker.outcome is Outcome.UNKNOWN or explain:
+            evidence(marker.explanation)
+    for problem in report.problems:
+        where = f"{problem.location}: " if problem.location is not None else ""
+        lines.append(f"{where}{problem.severity} {problem.code}: {problem.message}")
+    proved = [test for test in report.tests if test.status is Status.PROVED]
+    unproved = [test for test in report.tests if test.status is Status.NOT_PROVED]
+    if proved:
+        lines.append("")
+        lines.append("Proved statically (a test here can be skipped):")
+        for test in proved:
+            lines.append(f"  {test.location}  {test.name}  ({test.kind} on {test.model})")
+            evidence(test.explanation)
+    if unproved:
+        lines.append("")
+        lines.append("Not proved (the warehouse run still checks these):")
+        for test in unproved:
+            lines.append(f"  {test.location}  {test.name}  ({test.kind} on {test.model}): {test.reason}")
+            evidence(test.explanation)
+    if report.untested:
+        lines.append("")
+        lines.append("Proved but untested (schema.yml additions):")
+        for item in report.untested:
+            target = f"{item.model}.{item.column}" if item.column else item.model
+            lines.append(f"  {item.location}  {target}: {item.test}")
+            evidence(item.explanation)
+    markers_unknown = sum(marker.outcome is Outcome.UNKNOWN for marker in report.markers)
+    lines.append("")
+    lines.append(
+        f"{len(proved)} proved, {len(unproved)} not proved, {len(report.untested)} untested properties, "
+        f"{len(report.markers)} markers ({markers_unknown} unknown), "
+        f"{sum(p.severity == 'error' for p in report.problems)} errors, {sum(p.severity == 'warning' for p in report.problems)} warnings"
+    )
+    return "\n".join(lines) + "\n"

sqlassert_dbt-0.3.1.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: sqlassert-dbt
+Version: 0.3.1
+Summary: Check a dbt project's tests and sqlassert markers from its compiled manifest.
+Author: Fred Israel
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/polvoazul/sqlassert/tree/main/integrations/dbt
+Project-URL: Issues, https://github.com/polvoazul/sqlassert/issues
+Keywords: dbt,sql,static-analysis,data-quality,sqlassert
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlassert
+Requires-Dist: sqlglot<31,>=30.30
+Provides-Extra: test
+Requires-Dist: dbt-core>=1.12; extra == "test"
+Requires-Dist: dbt-duckdb>=1.11; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# sqlassert-dbt
+
+Prove your dbt tests from the SQL, and skip the ones that can't fail.
+
+A `unique` or `not_null` test scans a table in the warehouse on every run, and
+it only tells you about today's data. Many of those tests follow from the SQL
+itself: `customer_id` is unique because the model groups by it, `status` is
+never null because of a `coalesce`. [sqlassert](https://github.com/polvoazul/sqlassert)
+proves them from the compiled model before anything runs, so dbt can leave them
+out: faster CI, a smaller warehouse bill, and the same guarantee for *any*
+data, not just the rows there today.
+
+```bash
+pip install sqlassert-dbt
+```
+
+_Alpha: the markers and dbt test mappings are stable; the CLI output may
+change._
+
+## Skip the tests the SQL proves
+
+Run dbt through the plugin:
+
+```bash
+sqlassert-dbt build . -- --target prod    # or: sqlassert-dbt test
+```
+
+It runs `dbt compile`, checks every model, then runs `dbt build` (or
+`dbt test`) with each proved test passed as `--exclude`. Arguments after `--`
+go to dbt unchanged. The exit code is dbt's when dbt fails, otherwise the
+check's.
+
+The tests of the sources, seeds and models a model reads are trusted as
+facts, since `dbt build` runs them first in the same invocation. If the
+arguments after `--` select nodes (`--select`, `--exclude`, `--selector`, ...),
+an upstream test may not run, so none is trusted.
+
+## Check without dbt
+
+`check` reads only `target/manifest.json`, so dbt does not need to be installed
+where it runs (a CI step after `dbt compile`, say):
+
+```bash
+$ dbt compile
+$ sqlassert-dbt check . --trust-upstream-tests
+models/customers.sql:12: UNKNOWN /**ASSERT NOT NULL(first_name)**/ (customers)
+
+Proved statically (a test here can be skipped):
+  models/schema.yml  unique_stg_customers_customer_id  (test on stg_customers)
+
+Not proved (the warehouse run still checks these):
+  models/schema.yml  accepted_values_stg_orders_status__placed__shipped__returned  (test on stg_orders): its Property is not proved from the SQL
+
+Proved but untested (schema.yml additions):
+  models/schema.yml  customers.customer_id: not_null
+```
+
+Three lists come out:
+
+- **Proved statically:** tests the SQL already guarantees. Skip them.
+- **Not proved:** tests that still need the warehouse. Nothing is wrong; the
+  SQL alone can't show the property.
+- **Proved but untested:** properties sqlassert proved that no test states.
+  Free `schema.yml` additions, which cost nothing to keep.
+
+| Option | |
+|---|---|
+| `--trust-upstream-tests` | Treat passing tests of upstream nodes as facts (true under `dbt build`). Without it, a `dbt-untrusted-upstream-tests` warning lists them. |
+| `--require-proved` | Fail when any test is not proved, not only when a marker is `UNKNOWN`. |
+| `--explain` | Print each proof, and each failed proof. |
+| `--dialect NAME` | Analyze under this dialect instead of the adapter's. |
+| `--manifest PATH` | Read another manifest (default `PROJECT/target/manifest.json`). |
+
+Exit codes: `0` every marker proved; `1` a marker is `UNKNOWN` or an error was
+reported (unproved tests fail it only with `--require-proved`); `2` the
+manifest cannot be read.
+
+## What it understands
+
+| dbt | sqlassert Property |
+|---|---|
+| `unique` | Unique Set |
+| `not_null` | Not Null |
+| `accepted_values` | Enum |
+| `relationships` | Referential Coverage (Foreign Key) |
+| `dbt_utils.unique_combination_of_columns` | Non-Null Unique Set (it counts NULL equal to NULL) |
+| contract `primary_key`, `unique`, `not_null`, `foreign_key` | the same Properties |
+
+A model's own tests are what gets proved. Upstream tests are evidence, used
+only when they fail on any failing row: not a test with `severity: warn`, a
+`where:` config, or `error_if`/`fail_calc` thresholds. A constraint counts only
+on a contracted table whose adapter enforces it.
+
+## Markers in models
+
+You can also write sqlassert markers straight into a model, and they are checked
+and reported at their line in the model file:
+
+```sql
+-- models/customer_orders.sql
+select c.customer_id, c.first_name, o.order_id
+from {{ ref('stg_orders') }} o
+/**ASSERT MANY TO ONE**/ join {{ ref('stg_customers') }} c
+  on o.customer_id = c.customer_id
+```
+
+If someone later loads duplicate customers upstream, or drops the `unique`
+test that made this provable, the marker turns `UNKNOWN` and CI fails before
+the join fans out in production. See the
+[sqlassert README](https://github.com/polvoazul/sqlassert#readme) for every
+marker.
+
+## Details
+
+- **Manifest:** only the latest schema (v12, written by dbt 1.8 to 1.12).
+- **Ephemeral models** are analyzed where dbt inlined them.
+- **Incremental models** are analyzed in both `is_incremental()` branches. A
+  test holds only if it holds in both, and a key only under a `merge` or
+  `delete+insert` strategy on that `unique_key` with no
+  `incremental_predicates`. The other branch is rendered without dbt only when
+  the model uses `ref`, `source`, `this`, `config` and `is_incremental()`
+  alone; otherwise it is reported unanalyzed.
+- **Adapters:** analyzed when sqlassert models their dialect (DuckDB,
+  PostgreSQL, MySQL, Snowflake, BigQuery, Databricks / Spark, Redshift, Trino).
+- A model with markers but no compiled code is an error, not skipped.
+
+## License
+
+MIT

sqlassert_dbt-0.3.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+sqlassert_dbt/__init__.py,sha256=wNTLoPSO-V8sYtEVlxok9oGMDmGAJTUhZpdsl_ZB5qo,864
+sqlassert_dbt/__main__.py,sha256=et37YAtNV-b3k9bGl0UJrTELxH38MFS52SRIRaMxzm8,5374
+sqlassert_dbt/expectations.py,sha256=6mubjTwnwpPDBl1P5V2ImB7FwpFKK0grL6oHp7eOoWg,15480
+sqlassert_dbt/jinja.py,sha256=L5m_9Tf85HH-VJGOMQ0NUWS7BT782-eJOoL_ppCK-Vk,7029
+sqlassert_dbt/manifest.py,sha256=YFwXrxdpSKvNlimdqMWnDqRfINAWaUdgUB2YzuqVPWU,9472
+sqlassert_dbt/program.py,sha256=A6wv01ywKQTW_9LZK-GSA--TYxR3RwMUG33g0VJvpWo,32312
+sqlassert_dbt/project.py,sha256=S6JEXfxKtdOScouQoepEdj5tLhuvdPOzq1AwXg9nSro,17732
+sqlassert_dbt/report.py,sha256=mx4xy_XPXjo7QzViXUx5-3hJX5L-vE_7IpyFk6Wrok8,5600
+sqlassert_dbt-0.3.1.dist-info/licenses/LICENSE,sha256=KCR0_j-gr5ufUNxamIKNzeyyiI6g-S69oecRjZ07l_A,1068
+sqlassert_dbt-0.3.1.dist-info/METADATA,sha256=rmazLHsDpx6SRz36VVNWIOos1wyelKHTaWjntGhmlMU,6148
+sqlassert_dbt-0.3.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sqlassert_dbt-0.3.1.dist-info/entry_points.txt,sha256=4J9EK9q9ozlR8A8fJj7oPJmYtvl5HzM0oXX49HDB_vk,62
+sqlassert_dbt-0.3.1.dist-info/top_level.txt,sha256=w2-3Vq1UafNmPEBbCwdq4aZ-hsvRaBwKvouODJDNc1M,14
+sqlassert_dbt-0.3.1.dist-info/RECORD,,

sqlassert_dbt-0.3.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sqlassert_dbt-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sqlassert-dbt = sqlassert_dbt.__main__:main