bricksentry 0.1.0__py3-none-any.whl

bricksentry/cli.py

@@ -0,0 +1,260 @@
+"""bricksentry CLI.
+
+Exit codes: 0 = verdict below --fail-on, 1 = verdict at or above --fail-on,
+2 = usage / configuration error.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+
+from bricksentry import __version__
+from bricksentry.config import Config
+from bricksentry.models import Verdict
+
+
+def _sentry(config_path):
+    from bricksentry.assess import Sentry
+
+    return Sentry(Config.load(config_path))
+
+
+def _emit(obj, fmt: str, markdown_fn=None):
+    if fmt == "json":
+        click.echo(json.dumps(obj if isinstance(obj, (dict, list)) else obj.to_dict(), indent=2, default=str))
+    elif fmt == "markdown" and markdown_fn:
+        click.echo(markdown_fn())
+    else:
+        click.echo(obj if isinstance(obj, str) else json.dumps(obj, indent=2, default=str))
+
+
+def _exit_for(verdict: Verdict, fail_on: str) -> None:
+    if verdict.rank >= Verdict(fail_on).rank:
+        sys.exit(1)
+
+
+config_opt = click.option("--config", "-c", "config_path", type=click.Path(), default=None,
+                          help="Path to bricksentry.yml (default: ./bricksentry.yml or $BRICKSENTRY_CONFIG)")
+fail_opt = click.option("--fail-on", type=click.Choice([v.value for v in Verdict]), default="block",
+                        show_default=True, help="Exit 1 when the verdict is at least this severe")
+
+
+@click.group()
+@click.version_option(__version__, prog_name="bricksentry")
+def main():
+    """Change-safety for Databricks pipelines and the AI agents that edit them."""
+
+
+@main.command()
+@click.argument("base")
+@click.argument("candidate")
+@click.option("--key", "-k", "keys", multiple=True, help="Key column (repeatable). Defaults to config.")
+@click.option("--sample-pct", type=float, default=None, help="Diff a deterministic hash sample (0-100).")
+@click.option("--format", "fmt", type=click.Choice(["text", "json"]), default="text")
+@config_opt
+def diff(base, candidate, keys, sample_pct, fmt, config_path):
+    """Diff BASE (production) against CANDIDATE (your change)."""
+    from bricksentry.explain import explain_diff
+
+    s = _sentry(config_path)
+    d = s.diff(base, candidate, keys=list(keys) or None, table=base, sample_pct=sample_pct)
+    _emit(d.to_dict() if fmt == "json" else explain_diff(d), fmt)
+
+
+@main.command()
+@click.argument("table")
+@click.option("--depth", type=int, default=None)
+@click.option("--format", "fmt", type=click.Choice(["text", "json"]), default="text")
+@config_opt
+def impact(table, depth, fmt, config_path):
+    """Show the downstream blast radius of TABLE."""
+    from bricksentry.explain import explain_impact
+
+    s = _sentry(config_path)
+    nodes = s.downstream(table, depth)
+    if fmt == "json":
+        _emit({"table": table, "downstream": [n.to_dict() for n in nodes]}, fmt)
+        return
+    click.echo(explain_impact(table, nodes))
+    for n in sorted(nodes, key=lambda n: (n.depth, n.kind, n.name)):
+        tags = ",".join(n.tags) if n.tags else ""
+        click.echo(f"  {'  ' * (n.depth - 1)}└ [{n.kind}] {n.name}  {n.owner or ''} {tags}".rstrip())
+
+
+@main.command()
+@click.option("--table", "-t", "tables", multiple=True, help="Table to assess (repeatable).")
+@click.option("--from-git", "git_base", default=None, help="Detect changed tables from `git diff BASE...HEAD`.")
+@click.option("--candidate", "cand_pairs", multiple=True, help="Override: TABLE=CANDIDATE_TABLE")
+@click.option("--pr", default=None, help="PR number for candidate_pattern {pr}.")
+@click.option("--format", "fmt", type=click.Choice(["text", "json", "markdown"]), default="text")
+@click.option("--output", "-o", type=click.Path(), default=None, help="Also write the markdown report here.")
+@click.option("--comment", is_flag=True, help="Post/update the report as a GitHub PR comment.")
+@fail_opt
+@config_opt
+def assess(tables, git_base, cand_pairs, pr, fmt, output, comment, fail_on, config_path):
+    """Assess a change: data diff + blast radius + policy verdict + rollback plan."""
+    from bricksentry.changes import changed_files, tables_for_files
+    from bricksentry.report import to_markdown
+
+    s = _sentry(config_path)
+    tables = list(tables)
+    if git_base:
+        files = changed_files(git_base)
+        found = tables_for_files(s.config, files)
+        click.echo(f"{len(files)} changed file(s) -> {len(found)} table(s): {', '.join(found) or 'none'}", err=True)
+        tables += [t for t in found if t not in tables]
+    if not tables:
+        click.echo("Nothing to assess: no tables given or matched.", err=True)
+        sys.exit(0)
+    candidates = dict(p.split("=", 1) for p in cand_pairs)
+    pr = pr or os.environ.get("BRICKSENTRY_PR")
+    a = s.assess(tables, candidates=candidates, pr=pr)
+    md = to_markdown(a)
+    if output:
+        Path(output).write_text(md)
+    if comment:
+        from bricksentry.github import upsert_pr_comment
+
+        url = upsert_pr_comment(md, pr=pr)
+        click.echo(f"PR comment: {url}", err=True)
+    if fmt == "text":
+        click.echo(f"{a.verdict.value.upper()} (risk {a.verdict.risk_tier})")
+        for t in a.tables:
+            click.echo(f"- {t.summary}")
+            for h in t.hits:
+                click.echo(f"    [{h.verdict.value}] {h.rule}: {h.reason}")
+        if a.notify:
+            click.echo(f"Notify: {', '.join(a.notify)}")
+    else:
+        _emit(a, fmt, lambda: md)
+    _exit_for(a.verdict, fail_on)
+
+
+@main.command()
+@click.argument("target")
+@click.option("--sql", "sql_text", default=None, help="The write statement. Use {{target}} or the table name.")
+@click.option("--file", "sql_file", type=click.Path(exists=True), default=None)
+@click.option("--key", "-k", "keys", multiple=True)
+@click.option("--format", "fmt", type=click.Choice(["text", "json"]), default="text")
+@fail_opt
+@config_opt
+def preview(target, sql_text, sql_file, keys, fmt, fail_on, config_path):
+    """Run a write against a sandbox clone of TARGET and show what it would change."""
+    if not (sql_text or sql_file):
+        raise click.UsageError("pass --sql or --file")
+    sql = sql_text or Path(sql_file).read_text()
+    s = _sentry(config_path)
+    out = s.preview_write(sql, target, keys=list(keys) or None)
+    if fmt == "json":
+        _emit(out, fmt)
+    else:
+        click.echo(f"{out['verdict'].upper()} (risk {out['risk_tier']})")
+        for t in out["tables"]:
+            click.echo(f"- {t['summary']}")
+            for h in t["rule_hits"]:
+                click.echo(f"    [{h['verdict']}] {h['rule']}: {h['reason']}")
+    _exit_for(Verdict(out["verdict"]), fail_on)
+
+
+@main.command()
+@click.argument("table")
+@config_opt
+def rollback(table, config_path):
+    """Print the SQL that restores TABLE to its current version."""
+    click.echo(_sentry(config_path).rollback_plan(table))
+
+
+@main.command()
+@click.option("--transport", type=click.Choice(["stdio", "sse", "streamable-http"]), default="stdio")
+@config_opt
+def mcp(transport, config_path):
+    """Start the MCP server for AI agents."""
+    if config_path:
+        os.environ["BRICKSENTRY_CONFIG"] = str(Path(config_path).resolve())
+    from bricksentry.mcp_server import serve
+
+    serve(transport)
+
+
+_INIT_CONFIG = """# bricksentry configuration
+backend:
+  type: databricks          # or duckdb for local work
+  # warehouse_id: <sql-warehouse-id>   # or env DATABRICKS_WAREHOUSE_ID
+  # profile: DEFAULT                   # ~/.databrickscfg profile (optional)
+
+sandbox_schema: main.bricksentry_sandbox   # where preview_write puts disposable clones
+
+# Where your CI build writes the candidate (changed) version of each table.
+candidate_pattern: "{catalog}.{schema}_pr_{pr}.{table}"
+
+# sample_pct: 10           # diff a deterministic 10% key sample on big tables
+
+lineage:
+  depth: 3
+  lookback_days: 90
+
+tables:
+  main.sales.orders:
+    keys: [order_id]
+    segment_by: [region]
+    paths: ["src/pipelines/orders/**", "resources/orders_job.yml"]
+
+policy: policy.yml
+"""
+
+_INIT_POLICY = """default: pass
+notify_owners_on: needs_human
+rules:
+  - {name: diff-failed,          when: {diff_error: true},              then: needs_human}
+  - {name: duplicate-keys,       when: {duplicate_keys: true},          then: block}
+  - {name: dropped-column,       when: {column_removed: true},          then: needs_human}
+  - {name: type-change,          when: {column_type_changed: true},     then: warn}
+  - {name: certified-downstream, when: {downstream_tag: certified},     then: needs_human}
+  - {name: pii-table,            when: {tag: pii},                      then: needs_human}
+  - {name: row-loss,             when: {removed_pct_gt: 1},             then: needs_human}
+  - {name: many-rows-changed,    when: {changed_pct_gt: 10},            then: warn}
+  - {name: numeric-total-moved,  when: {sum_change_pct_gt: 5},          then: warn}
+  - {name: wide-blast-radius,    when: {downstream_count_gt: 25},       then: warn}
+"""
+
+
+@main.command()
+@click.option("--force", is_flag=True)
+def init(force):
+    """Write a starter bricksentry.yml and policy.yml."""
+    for name, body in (("bricksentry.yml", _INIT_CONFIG), ("policy.yml", _INIT_POLICY)):
+        p = Path(name)
+        if p.exists() and not force:
+            click.echo(f"skip {name} (exists; use --force)")
+            continue
+        p.write_text(body)
+        click.echo(f"wrote {name}")
+
+
+
+
+def entry() -> None:
+    """Console entry point: turn unexpected errors into a clean message and exit code 2."""
+    try:
+        main(standalone_mode=False)
+    except click.exceptions.Exit as e:
+        sys.exit(e.exit_code)
+    except click.ClickException as e:
+        e.show()
+        sys.exit(2)
+    except click.exceptions.Abort:
+        sys.exit(2)
+    except SystemExit:
+        raise
+    except Exception as e:
+        click.echo(f"bricksentry: error: {e}", err=True)
+        sys.exit(2)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    entry()

bricksentry/config.py

@@ -0,0 +1,123 @@
+"""Project configuration, loaded from ``bricksentry.yml``.
+
+Example::
+
+    backend:
+      type: databricks            # or duckdb
+      warehouse_id: abc123        # env DATABRICKS_WAREHOUSE_ID also works
+    sandbox_schema: main.bricksentry_sandbox
+    candidate_pattern: "{catalog}.{schema}_pr_{pr}.{table}"
+    sample_pct: 10                # diff a deterministic 10% hash sample (omit for full diff)
+    lineage:
+      depth: 3
+      lookback_days: 90
+    tables:
+      main.sales.orders:
+        keys: [order_id]
+        segment_by: [region]
+        paths: ["pipelines/orders/**", "resources/orders_job.yml"]
+    policy: policy.yml            # or inline mapping
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+DEFAULT_CONFIG_NAMES = ("bricksentry.yml", "bricksentry.yaml", ".bricksentry.yml")
+
+
+@dataclass
+class TableSpec:
+    name: str
+    keys: list[str]
+    segment_by: list[str] = field(default_factory=list)
+    paths: list[str] = field(default_factory=list)
+    candidate: str | None = None  # explicit candidate table, overrides candidate_pattern
+
+
+@dataclass
+class Config:
+    backend: dict[str, Any] = field(default_factory=lambda: {"type": "duckdb"})
+    sandbox_schema: str = "bricksentry_sandbox"
+    candidate_pattern: str = "{catalog}.{schema}_ci.{table}"
+    sample_pct: float | None = None
+    max_samples: int = 5
+    lineage: dict[str, Any] = field(default_factory=dict)
+    tables: dict[str, TableSpec] = field(default_factory=dict)
+    policy: dict[str, Any] | None = None
+    root: Path = field(default_factory=Path.cwd)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], root: Path | None = None) -> "Config":
+        root = root or Path.cwd()
+        tables = {}
+        for name, spec in (data.get("tables") or {}).items():
+            spec = spec or {}
+            keys = spec.get("keys") or spec.get("key") or []
+            if isinstance(keys, str):
+                keys = [keys]
+            seg = spec.get("segment_by") or []
+            if isinstance(seg, str):
+                seg = [seg]
+            tables[name] = TableSpec(
+                name=name,
+                keys=list(keys),
+                segment_by=list(seg),
+                paths=list(spec.get("paths") or []),
+                candidate=spec.get("candidate"),
+            )
+        policy = data.get("policy")
+        if isinstance(policy, str):
+            policy = yaml.safe_load((root / policy).read_text()) or {}
+        return cls(
+            backend=data.get("backend") or {"type": "duckdb"},
+            sandbox_schema=data.get("sandbox_schema", "bricksentry_sandbox"),
+            candidate_pattern=data.get("candidate_pattern", "{catalog}.{schema}_ci.{table}"),
+            sample_pct=data.get("sample_pct"),
+            max_samples=int(data.get("max_samples", 5)),
+            lineage=data.get("lineage") or {},
+            tables=tables,
+            policy=policy,
+            root=root,
+        )
+
+    @classmethod
+    def load(cls, path: str | os.PathLike | None = None) -> "Config":
+        if path is None:
+            path = os.environ.get("BRICKSENTRY_CONFIG")
+        if path is None:
+            for name in DEFAULT_CONFIG_NAMES:
+                if Path(name).exists():
+                    path = name
+                    break
+        if path is None:
+            return cls()
+        p = Path(path)
+        data = yaml.safe_load(p.read_text()) or {}
+        return cls.from_dict(data, root=p.resolve().parent)
+
+    def spec(self, table: str) -> TableSpec:
+        if table in self.tables:
+            return self.tables[table]
+        return TableSpec(name=table, keys=[])
+
+    def candidate_for(self, table: str, pr: str | None = None) -> str:
+        spec = self.spec(table)
+        if spec.candidate:
+            return spec.candidate.format(pr=pr or os.environ.get("BRICKSENTRY_PR", "local"))
+        parts = table.split(".")
+        while len(parts) < 3:
+            parts.insert(0, "")
+        catalog, schema, name = parts[-3], parts[-2], parts[-1]
+        out = self.candidate_pattern.format(
+            catalog=catalog,
+            schema=schema,
+            table=name,
+            pr=pr or os.environ.get("BRICKSENTRY_PR", "local"),
+        )
+        return out.lstrip(".")

bricksentry/diff.py

@@ -0,0 +1,194 @@
+"""Key-based data diff, pushed down to the engine as SQL.
+
+Compares a *base* table (what production has now) with a *candidate* table
+(what the change produces) on primary-key columns and reports:
+
+* schema changes (added / removed / type-changed columns)
+* row counts, added / removed / changed / unchanged rows
+* per-column change counts, null counts and numeric sums
+* duplicate keys on either side
+* sample changed values per column
+* segment attribution ("most changes are in region = APAC")
+
+Sampling uses a deterministic hash on the keys, so both sides sample the same keys.
+"""
+
+from __future__ import annotations
+
+from bricksentry.backends.base import Backend
+from bricksentry.models import ColumnChange, SchemaChange, Segment, TableDiff
+
+MAX_SAMPLE_COLUMNS = 10
+
+
+class DiffError(ValueError):
+    pass
+
+
+def diff_tables(
+    backend: Backend,
+    base: str,
+    candidate: str,
+    keys: list[str],
+    *,
+    table: str | None = None,
+    sample_pct: float | None = None,
+    segment_by: list[str] | None = None,
+    max_samples: int = 5,
+    columns: list[str] | None = None,
+) -> TableDiff:
+    if not keys:
+        raise DiffError(
+            f"No key columns for {table or base}. Add `keys:` for it in bricksentry.yml "
+            "(or pass --key) so rows can be matched."
+        )
+    q = backend.quote
+    b_cols = backend.columns(base)
+    c_cols = backend.columns(candidate)
+
+    missing = [k for k in keys if k not in b_cols or k not in c_cols]
+    if missing:
+        raise DiffError(f"Key column(s) {missing} not present in both {base} and {candidate}")
+
+    schema = SchemaChange(
+        added={k: v for k, v in c_cols.items() if k not in b_cols},
+        removed={k: v for k, v in b_cols.items() if k not in c_cols},
+        type_changed={
+            k: (b_cols[k], c_cols[k]) for k in b_cols if k in c_cols and b_cols[k] != c_cols[k]
+        },
+    )
+    common = [c for c in b_cols if c in c_cols and c not in keys]
+    if columns:
+        common = [c for c in common if c in columns]
+
+    def side(tbl: str, alias: str) -> str:
+        where = f" WHERE {backend.sample_predicate(keys, sample_pct)}" if sample_pct else ""
+        return f"{alias} AS (SELECT * FROM {backend.qualified(tbl)}{where})"
+
+    ctes = f"WITH {side(base, 'b_src')}, {side(candidate, 'c_src')}"
+    join_on = " AND ".join(f"b.{q(k)} = c.{q(k)}" for k in keys)
+    k0 = q(keys[0])
+
+    def cmp(col: str) -> str:
+        bc, cc = f"b.{q(col)}", f"c.{q(col)}"
+        if col in schema.type_changed:
+            st = backend.string_type
+            bc, cc = f"CAST({bc} AS {st})", f"CAST({cc} AS {st})"
+        return f"{bc} IS DISTINCT FROM {cc}"
+
+    both = f"b.{k0} IS NOT NULL AND c.{k0} IS NOT NULL"
+    any_diff = " OR ".join(f"({cmp(c)})" for c in common) or "FALSE"
+
+    selects = [
+        f"SUM(CASE WHEN b.{k0} IS NULL THEN 1 ELSE 0 END) AS added_rows",
+        f"SUM(CASE WHEN c.{k0} IS NULL THEN 1 ELSE 0 END) AS removed_rows",
+        f"SUM(CASE WHEN {both} AND ({any_diff}) THEN 1 ELSE 0 END) AS changed_rows",
+        f"SUM(CASE WHEN {both} AND NOT ({any_diff}) THEN 1 ELSE 0 END) AS unchanged_rows",
+    ]
+    for i, col in enumerate(common):
+        selects.append(f"SUM(CASE WHEN {both} AND ({cmp(col)}) THEN 1 ELSE 0 END) AS chg_{i}")
+
+    join_sql = (
+        f"{ctes} SELECT {', '.join(selects)} "
+        f"FROM b_src b FULL OUTER JOIN c_src c ON {join_on}"
+    )
+    j = backend.query(join_sql)[0]
+
+    # Row counts, nulls, numeric sums per side.
+    def profile(tbl_cte: str, cols: dict[str, str]) -> dict:
+        parts = ["COUNT(*) AS n_rows"]
+        for i, col in enumerate(common):
+            parts.append(f"SUM(CASE WHEN {q(col)} IS NULL THEN 1 ELSE 0 END) AS nul_{i}")
+            if backend.is_numeric(cols[col]):
+                parts.append(f"SUM(CAST({q(col)} AS DOUBLE)) AS sum_{i}")
+        return backend.query(f"{ctes} SELECT {', '.join(parts)} FROM {tbl_cte}")[0]
+
+    pb = profile("b_src", b_cols)
+    pc = profile("c_src", c_cols)
+
+    def dupes(tbl_cte: str) -> int:
+        kc = ", ".join(q(k) for k in keys)
+        sql = (
+            f"{ctes} SELECT COUNT(*) AS n FROM "
+            f"(SELECT {kc} FROM {tbl_cte} GROUP BY {kc} HAVING COUNT(*) > 1) d"
+        )
+        return int(backend.scalar(sql) or 0)
+
+    col_changes: list[ColumnChange] = []
+    for i, col in enumerate(common):
+        changed = int(j.get(f"chg_{i}") or 0)
+        cc = ColumnChange(
+            column=col,
+            changed_rows=changed,
+            base_nulls=_int(pb.get(f"nul_{i}")),
+            candidate_nulls=_int(pc.get(f"nul_{i}")),
+            base_sum=_float(pb.get(f"sum_{i}")),
+            candidate_sum=_float(pc.get(f"sum_{i}")),
+        )
+        col_changes.append(cc)
+
+    # Samples for the most-changed columns.
+    key_sel = ", ".join(f"COALESCE(b.{q(k)}, c.{q(k)}) AS {q(k)}" for k in keys)
+    for cc in sorted(col_changes, key=lambda c: -c.changed_rows)[:MAX_SAMPLE_COLUMNS]:
+        if cc.changed_rows == 0 or max_samples <= 0:
+            continue
+        col = cc.column
+        sql = (
+            f"{ctes} SELECT {key_sel}, b.{q(col)} AS base_value, c.{q(col)} AS candidate_value "
+            f"FROM b_src b JOIN c_src c ON {join_on} WHERE {cmp(col)} "
+            f"ORDER BY {', '.join(f'b.{q(k)}' for k in keys)} LIMIT {int(max_samples)}"
+        )
+        cc.samples = [_jsonable(r) for r in backend.query(sql)]
+
+    # Segment attribution over added + removed + changed rows.
+    segments: list[Segment] = []
+    for seg in segment_by or []:
+        if seg not in b_cols and seg not in c_cols:
+            continue
+        b_seg = f"b.{q(seg)}" if seg in b_cols else "NULL"
+        c_seg = f"c.{q(seg)}" if seg in c_cols else "NULL"
+        affected = f"(b.{k0} IS NULL OR c.{k0} IS NULL OR ({any_diff}))"
+        sql = (
+            f"{ctes} SELECT COALESCE({c_seg}, {b_seg}) AS seg_value, COUNT(*) AS n "
+            f"FROM b_src b FULL OUTER JOIN c_src c ON {join_on} WHERE {affected} "
+            f"GROUP BY 1 ORDER BY n DESC LIMIT 5"
+        )
+        for r in backend.query(sql):
+            segments.append(Segment(column=seg, value=_jsonable_value(r["seg_value"]), affected_rows=int(r["n"])))
+
+    return TableDiff(
+        table=table or base,
+        base=base,
+        candidate=candidate,
+        keys=list(keys),
+        base_rows=int(pb.get("n_rows") or 0),
+        candidate_rows=int(pc.get("n_rows") or 0),
+        added_rows=int(j.get("added_rows") or 0),
+        removed_rows=int(j.get("removed_rows") or 0),
+        changed_rows=int(j.get("changed_rows") or 0),
+        unchanged_rows=int(j.get("unchanged_rows") or 0),
+        schema=schema,
+        columns=col_changes,
+        duplicate_keys_base=dupes("b_src"),
+        duplicate_keys_candidate=dupes("c_src"),
+        segments=segments,
+        sampled_pct=sample_pct,
+    )
+
+
+def _int(v):
+    return None if v is None else int(v)
+
+
+def _float(v):
+    return None if v is None else float(v)
+
+
+def _jsonable_value(v):
+    if v is None or isinstance(v, (str, int, float, bool)):
+        return v
+    return str(v)
+
+
+def _jsonable(row: dict) -> dict:
+    return {k: _jsonable_value(v) for k, v in row.items()}

bricksentry/explain.py

@@ -0,0 +1,91 @@
+"""Plain-English summaries, built from templates (deterministic, no LLM needed).
+
+An agent framework can pass this text to its own LLM if it wants richer prose,
+but the verdict never depends on it.
+"""
+
+from __future__ import annotations
+
+from bricksentry.models import ImpactNode, TableDiff
+
+
+def _n(x: int) -> str:
+    return f"{x:,}"
+
+
+def explain_diff(d: TableDiff) -> str:
+    if d.error:
+        return f"{d.table}: the diff could not run ({d.error})."
+    if d.is_identical:
+        scope = f" in a {d.sampled_pct:g}% sample" if d.sampled_pct else ""
+        return f"{d.table}: no data or schema changes{scope}."
+
+    parts: list[str] = []
+    rc = d.candidate_rows - d.base_rows
+    if rc:
+        parts.append(f"row count {'+' if rc > 0 else ''}{_n(rc)} ({d.row_count_change_pct:+.2f}%)")
+    if d.added_rows:
+        parts.append(f"{_n(d.added_rows)} rows added")
+    if d.removed_rows:
+        parts.append(f"{_n(d.removed_rows)} rows removed ({d.removed_pct:.2f}%)")
+    if d.changed_rows:
+        parts.append(f"{_n(d.changed_rows)} rows changed ({d.changed_pct:.2f}%)")
+    s = f"{d.table}: " + ", ".join(parts) if parts else f"{d.table}: schema-only change"
+
+    sch = []
+    if d.schema.removed:
+        sch.append("dropped " + ", ".join(d.schema.removed))
+    if d.schema.added:
+        sch.append("added " + ", ".join(d.schema.added))
+    if d.schema.type_changed:
+        sch.append("retyped " + ", ".join(f"{k} ({a} -> {b})" for k, (a, b) in d.schema.type_changed.items()))
+    if sch:
+        s += ". Schema: " + "; ".join(sch)
+
+    top = [c for c in sorted(d.columns, key=lambda c: -c.changed_rows) if c.changed_rows][:3]
+    if top:
+        s += ". Most changed: " + ", ".join(f"{c.column} ({_n(c.changed_rows)})" for c in top)
+
+    moved = [c for c in d.columns if c.sum_change_pct is not None and abs(c.sum_change_pct) >= 0.01]
+    moved.sort(key=lambda c: -abs(c.sum_change_pct or 0))
+    if moved:
+        s += ". Totals: " + ", ".join(f"sum({c.column}) {c.sum_change_pct:+.2f}%" for c in moved[:3])
+
+    nulls = [
+        c for c in d.columns
+        if c.base_nulls is not None and c.candidate_nulls is not None and c.candidate_nulls > c.base_nulls
+    ]
+    if nulls:
+        s += ". New nulls: " + ", ".join(f"{c.column} +{_n(c.candidate_nulls - c.base_nulls)}" for c in nulls[:3])
+
+    if d.segments:
+        by_col: dict[str, list] = {}
+        for seg in d.segments:
+            by_col.setdefault(seg.column, []).append(seg)
+        total = max(d.added_rows + d.removed_rows + d.changed_rows, 1)
+        for col, segs in by_col.items():
+            lead = segs[0]
+            share = lead.affected_rows / total * 100
+            if share >= 50:
+                s += f". {share:.0f}% of affected rows are {col} = {lead.value}"
+            else:
+                s += f". Spread across {col}: " + ", ".join(f"{x.value} ({_n(x.affected_rows)})" for x in segs[:3])
+
+    if d.duplicate_keys_candidate > d.duplicate_keys_base:
+        s += f". WARNING: {_n(d.duplicate_keys_candidate)} duplicate key(s) on {', '.join(d.keys)}"
+    if d.sampled_pct:
+        s += f" (based on a {d.sampled_pct:g}% key sample)"
+    return s + "."
+
+
+def explain_impact(table: str, nodes: list[ImpactNode]) -> str:
+    if not nodes:
+        return f"{table}: nothing downstream found in lineage."
+    kinds: dict[str, int] = {}
+    for n in nodes:
+        kinds[n.kind] = kinds.get(n.kind, 0) + 1
+    owners = sorted({n.owner for n in nodes if n.owner})
+    s = f"{table} feeds " + ", ".join(f"{v} {k}{'s' if v > 1 else ''}" for k, v in sorted(kinds.items()))
+    if owners:
+        s += f"; owners: {', '.join(owners[:5])}"
+    return s + "."