ripple-sql 0.1.0__py3-none-any.whl

ripple/loaders/sidecar.py

@@ -0,0 +1,65 @@
+"""Base tables declared by a schema file beside no SQL.
+
+Mozilla's bigquery-etl loads many tables from outside the repo and describes
+each one only by sql/<project>/<dataset>/<table>/schema.yaml (BigQuery's
+`fields:` format). Without those columns a view's SELECT * over such a table
+cannot expand, and every view downstream of it degrades to review_required.
+A directory holding a schema file and no .sql becomes a base-table model
+carrying the declared columns, the same way CREATE TABLE (col defs) does.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import yaml
+
+from ripple.loaders.identity import directory_identity
+from ripple.loaders.types import IGNORE_DIRS, Model, relative_posix
+
+SIDECAR_NAMES = ("schema.yaml", "schema.yml", "schema.json")
+
+
+def _declared_fields(path: Path) -> list[str]:
+    try:
+        text = path.read_text(errors="replace", encoding="utf-8")
+        doc = json.loads(text) if path.suffix == ".json" else yaml.safe_load(text)
+    except (OSError, ValueError, yaml.YAMLError):
+        return []
+    fields = doc.get("fields") if isinstance(doc, dict) else doc
+    if not isinstance(fields, list):
+        return []
+    return [f["name"] for f in fields if isinstance(f, dict) and isinstance(f.get("name"), str)]
+
+
+def sidecar_base_tables(root: Path, sql_dirs: set[Path], dialect: str) -> list[Model]:
+    models: list[Model] = []
+    for name in SIDECAR_NAMES:
+        for path in sorted(root.rglob(name)):
+            parts = path.relative_to(root).parts[:-1]
+            if any(p in IGNORE_DIRS or p.startswith(".") for p in parts):
+                continue
+            if path.parent in sql_dirs or len(parts) < 1:
+                continue
+            columns = _declared_fields(path)
+            if not columns:
+                continue
+            rel = relative_posix(path, root)
+            identity = directory_identity(str(Path(rel).with_name("query.sql")))
+            if identity is None:
+                continue
+            table, dotted = identity
+            model = Model(
+                name=table,
+                sql="",
+                path=rel,
+                declared_columns=columns,
+                evidence="plain_sql",
+                dialect=dialect,
+                uid=f"{rel}::{table}",
+            )
+            model.aliases |= {a.lower() for a in dotted}
+            models.append(model)
+            sql_dirs.add(path.parent)  # one sidecar per directory wins
+    return models

ripple/loaders/sqldir.py

@@ -0,0 +1,262 @@
+"""Plain SQL directory loading, with the per-file parse budget."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ripple.engine.budget import TIMED_OUT, budget_seconds, max_sql_bytes, run_within_budget
+from ripple.loaders.identity import directory_identity
+from ripple.loaders.types import IGNORE_DIRS, Model, Project, relative_posix
+
+
+def _iter_sql_files(root: Path, exclude: list[Path] | None = None) -> tuple[list[Path], int]:
+    """Every .sql under root, minus vendored/build/hidden dirs.
+
+    Returns (kept files, count skipped) so the loader can report what it
+    passed over instead of silently dropping it. `exclude` drops whole subtrees,
+    used to keep a dbt project's macros out of the beside-dbt fallback.
+    """
+    kept: list[Path] = []
+    skipped = 0
+    excluded = [d.resolve() for d in (exclude or [])]
+    for path in sorted(root.rglob("*.sql")):
+        dirs = path.relative_to(root).parts[:-1]
+        if any(part in IGNORE_DIRS or part.startswith(".") for part in dirs):
+            skipped += 1
+            continue
+        if any(path.resolve().is_relative_to(d) for d in excluded):
+            skipped += 1
+            continue
+        kept.append(path)
+    return kept, skipped
+
+
+def _sniff_sql_dir_dialect(root: Path, sample: str) -> tuple[str, bool]:
+    """(dialect, assumed). Read the SQL itself for a dialect signal (backticks,
+    psql directives, ENGINE=, INFORMATION_SCHEMA); postgres is the honest default
+    for a loose pile of .sql, and `assumed` tells the caller to say so."""
+    if (root / "supabase" / "config.toml").is_file() or (root / "supabase").is_dir():
+        return "postgres", False
+    from ripple.engine.sql_script import sniff_dialect
+
+    sniffed = sniff_dialect(sample)
+    if sniffed:
+        return sniffed, False
+    return "postgres", True
+
+
+def _expand_within_budget(
+    stem: str,
+    text: str,
+    dialect: str | None,
+    budget: float,
+    warnings: list[str] | None = None,
+):
+    """expand_script under the shared budget; None means the budget was blown."""
+    from ripple.engine import sql_script
+
+    result = run_within_budget(
+        stem, lambda: sql_script.expand_script(stem, text, dialect, warnings=warnings), budget
+    )
+    return None if result is TIMED_OUT else result
+
+
+def _load_sql_dir(root: Path, dialect: str | None, exclude: list[Path] | None = None) -> Project:
+    files, skipped = _iter_sql_files(root, exclude)
+    texts = [(f, f.read_text(errors="replace", encoding="utf-8")) for f in files]
+
+    from ripple.engine.sql_script import sniff_dialect
+
+    warnings: list[str] = []
+    assumed = False
+    if dialect:
+        resolved = dialect
+    else:
+        # sample a slice of EVERY file, not just the first few: a bigquery signal
+        # (INFORMATION_SCHEMA) or mysql signal may live deep in the tree.
+        sample = "\n".join(t[:4000] for _, t in texts)[:200000]
+        resolved, assumed = _sniff_sql_dir_dialect(root, sample)
+        if assumed and texts:
+            warnings.append(
+                f"Assuming {resolved} dialect (no dbt profile or warehouse to read). "
+                "Pass --dialect to override."
+            )
+
+    # a .sql file can hold one query or a 15,000-statement dump. Expand each into
+    # the models it actually defines, so a dump becomes its views and tables, not
+    # one unparseable blob.
+    models: list[Model] = []
+    stem_claims: list[tuple[Model, str]] = []
+    budget = budget_seconds()
+    for sql_file, text in texts:
+        rel = relative_posix(sql_file, root)
+        # per-file dialect: one repo can hold the same schema in several dialects
+        # (Chinook ships Postgres, MySQL, Oracle, SQL Server variants side by side).
+        # An explicit --dialect wins; otherwise sniff this file, then fall back to
+        # the repo-level guess.
+        file_dialect = dialect or sniff_dialect(text) or resolved
+        limit = max_sql_bytes()
+        if limit and len(text) > limit and ";" not in text:
+            # a multi-MB file with no statement separator is one generated
+            # statement (a 3.7MB one-liner cost 13s to parse and 139s to
+            # analyze); a dump of many small statements has semicolons and
+            # still expands normally
+            warnings.append(
+                f"{rel}: a single {len(text) / 1e6:.1f}MB statement, skipped as "
+                "generated (RIPPLE_MAX_SQL_BYTES to raise)."
+            )
+            models.append(
+                Model(
+                    name=sql_file.stem,
+                    sql="",
+                    path=rel,
+                    evidence="plain_sql",
+                    dialect=file_dialect,
+                    uid=f"{rel}::{sql_file.stem}",
+                    load_error=(
+                        f"single statement is {len(text) / 1e6:.1f}MB, over the "
+                        f"{limit / 1e6:g}MB limit: {rel}"
+                    ),
+                )
+            )
+            continue
+        script_warnings: list[str] = []
+        expanded = _expand_within_budget(
+            sql_file.stem, text, file_dialect, budget, warnings=script_warnings
+        )
+        warnings.extend(f"{rel}: {w}" for w in script_warnings)
+        if expanded is None:
+            warnings.append(
+                f"{rel}: parse exceeded the {budget:g}s per-file budget; reported as "
+                "timed_out (RIPPLE_PARSE_BUDGET_S to raise)."
+            )
+            models.append(
+                Model(
+                    name=sql_file.stem,
+                    sql="",
+                    path=rel,
+                    evidence="plain_sql",
+                    dialect=file_dialect,
+                    uid=f"{rel}::{sql_file.stem}",
+                    load_error=f"parse timed out after {budget:g}s: {rel}",
+                )
+            )
+            continue
+        # dedup only WITHIN a file (a base table and a later INSERT/CTAS that fills
+        # it). Same name across different files is a real collision that
+        # _qualify_collisions path-qualifies, so it must NOT be dropped here.
+        # dedup is keyed by the QUALIFIED identity, not the bare name:
+        # sales.summary and hr.summary in one migration are different
+        # relations, and merging them would bind hr references to the sales
+        # derivation (the review of the round-3 fixes)
+        here: dict[str, Model] = {}
+        clone_here: set[str] = set()
+        for sm in expanded:
+            identity = (sm.qualified_name or sm.name).lower()
+            existing = here.get(identity)
+            if existing is not None:
+                # an empty base table upgrades to any derivation (old rule);
+                # a schema clone (select * ... where 0=1) upgrades to the
+                # later real derivation, which it exists to receive
+                # (usaspending's subaward loader, holdout round 2). A real
+                # derivation is never replaced. Parents always merge: a
+                # second statement writing the same target is a real
+                # dependency even when its SQL is not the one analyzed.
+                replaceable = not existing.sql.strip() or (
+                    identity in clone_here and not sm.schema_clone
+                )
+                if replaceable and sm.sql.strip():
+                    existing.sql = sm.sql
+                    # the analyzed SQL is now the UPDATE's; without its
+                    # self_read the graph drops the prior-state edges as
+                    # CTE loops (the review of PR #28)
+                    existing.self_read = sm.self_read
+                    if sm.schema_clone:
+                        clone_here.add(identity)
+                    else:
+                        clone_here.discard(identity)
+                elif sm.self_read and sm.sql.strip():
+                    # a later UPDATE of a target that already has a real
+                    # derivation adds lineage, it does not replace any: the
+                    # statement joins the model's analyzed set (nycdb,
+                    # PR #28 gap 3)
+                    existing.extra_sqls.append(sm.sql)
+                    existing.self_read = True
+                existing.declared_parents |= set(sm.parents)
+                continue
+            model = Model(
+                name=sm.name,
+                sql=sm.sql,
+                path=rel,
+                declared_parents=set(sm.parents),
+                declared_columns=list(sm.columns),
+                evidence="plain_sql",
+                dialect=file_dialect,
+                uid=f"{rel}::{identity}",
+                self_read=sm.self_read,
+                is_function=sm.is_function,
+            )
+            # a bare SELECT is named after its file; when the file is named
+            # for its role (query.sql), the directory is the relation
+            by_directory = (
+                directory_identity(rel) if sm.name.lower() == sql_file.stem.lower() else None
+            )
+            if by_directory:
+                model.name, dotted = by_directory
+                model.aliases |= {a.lower() for a in dotted}
+            if sm.schema_clone:
+                clone_here.add(identity)
+            # the qualified spelling the SQL wrote (disclosure.v_sum) answers
+            # queries and folds scoring; the display name stays bare
+            if sm.qualified_name and sm.qualified_name.lower() != sm.name.lower():
+                model.aliases.add(sm.qualified_name.lower())
+            here[identity] = model
+            models.append(model)
+        # a file is known to its team by its filename: claim the stem for the
+        # file's relations, granted after the sweep only if no other file and
+        # no real model owns the name. A multi-relation file's stem becomes a
+        # deliberately ambiguous alias; the graph disambiguates by the asked
+        # column (patentsview's webtool_tables, holdout round 5) and raises
+        # when several claimants carry it.
+        stem = sql_file.stem.lower()
+        for defined in here.values():
+            if defined.name.lower() != stem:
+                stem_claims.append((rel, defined, stem))
+
+    from ripple.loaders.sidecar import sidecar_base_tables
+
+    models.extend(sidecar_base_tables(root, {f.parent for f in files}, resolved))
+
+    # grant stem aliases only where the name is unowned and claimed by ONE
+    # file: a stem matching a real model, or shared by two files, would
+    # silently redirect breaks/trace to the wrong relation
+    taken = {m.name.lower() for m in models}
+    for m in models:
+        taken |= {a.lower() for a in m.aliases}
+    files_per_stem: dict[str, set[str]] = {}
+    for claim_rel, _, stem in stem_claims:
+        files_per_stem.setdefault(stem, set()).add(claim_rel)
+    for _, claimant, stem in stem_claims:
+        if len(files_per_stem[stem]) == 1 and stem not in taken:
+            claimant.stem_aliases.add(stem)
+
+    if skipped:
+        warnings.append(
+            f"Skipped {skipped} .sql file{'s' if skipped != 1 else ''} in "
+            "vendored or build directories."
+        )
+    if not models:
+        warnings.append(
+            f"No .sql files found under {root}. Run ripple inside a dbt project "
+            "or a folder that contains .sql files."
+        )
+
+    return Project(
+        root=root,
+        dialect=resolved,
+        mode="sql-dir",
+        models=models,
+        sources=[],
+        warnings=warnings,
+        dialect_assumed=assumed,
+    )

ripple/loaders/types.py

@@ -0,0 +1,197 @@
+"""Shared model/project types and discovery constants."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ADAPTER_TO_DIALECT = {
+    "snowflake": "snowflake",
+    "bigquery": "bigquery",
+    "databricks": "databricks",
+    "spark": "spark",
+    "redshift": "redshift",
+    "postgres": "postgres",
+    "duckdb": "duckdb",
+    "trino": "trino",
+}
+
+# ref()/source() anywhere in the Jinja, including nested inside macro args
+# like {{ dbt_audit(ref('base'), ...) }}. Two-arg ref('package', 'model')
+# takes the last argument as the model name.
+_REF_RE = re.compile(r"\bref\(\s*['\"]([^'\"]+)['\"]\s*(?:,\s*['\"]([^'\"]+)['\"]\s*)?\)")
+_SOURCE_RE = re.compile(r"\bsource\(\s*['\"]([^'\"]+)['\"]\s*,\s*['\"]([^'\"]+)['\"]\s*\)")
+_VAR_NAME_RE = re.compile(r"\bvar\(\s*['\"]([^'\"]+)['\"]")
+
+# Directories that never hold the project's own SQL. Skipped when scanning a
+# plain repo so the map is the code you wrote, not vendored or generated junk.
+# Hidden dirs (dotfiles) are skipped separately.
+IGNORE_DIRS = frozenset(
+    {
+        "node_modules",
+        "bower_components",
+        "venv",
+        "env",
+        "virtualenv",
+        "site-packages",
+        "__pycache__",
+        "target",
+        "dist",
+        "build",
+        "out",
+        "dbt_packages",
+        "dbt_modules",
+        "vendor",
+        "vendored",
+        "third_party",
+    }
+)
+
+
+@dataclass
+class Model:
+    name: str
+    sql: str
+    path: str
+    # names this model can be referenced by in SQL (relation name, alias, bare name)
+    aliases: set[str] = field(default_factory=set)
+    # parent model/source names declared by dbt (manifest mode) or found via ref()/source()
+    declared_parents: set[str] = field(default_factory=set)
+    is_source: bool = False
+    # "manifest" | "raw_jinja" | "plain_sql"
+    evidence: str = "plain_sql"
+    # per-model SQL dialect. In a monorepo each dbt project is its own island
+    # with its own warehouse; a model parses in its island's dialect, not one
+    # dialect forced on the whole tree. None means "use the project default".
+    dialect: str | None = None
+    # columns declared by a CREATE TABLE (the schema). A base table has these but
+    # no SQL to analyze; the graph uses them so a downstream SELECT * can resolve.
+    declared_columns: list[str] = field(default_factory=list)
+    # stable identity: dbt unique_id in manifest mode, project-relative path
+    # elsewhere. Display names can collide; this must not.
+    uid: str = ""
+    # vars declared by THIS model's own dbt_project.yml. Like dialect: set per
+    # model in a monorepo so islands keep their own values; None means "use the
+    # project default".
+    jinja_vars: dict | None = None
+    # dbt enabled config (dbt_project.yml +enabled or {{ config(enabled=...) }}).
+    # A disabled model stays a visible node but never binds refs or feeds
+    # parent schemas: dbt would not build it.
+    enabled: bool = True
+    # set when the file's parse blew the per-file budget; the graph reports the
+    # model as timed_out instead of pretending it was analyzed
+    load_error: str | None = None
+    # an UPDATE-derived model reads its own prior state; the graph keeps
+    # its self edges instead of treating them as CTE loops
+    self_read: bool = False
+    # further analyzed statements for the same relation: a table built by
+    # CREATE plus several UPDATEs (in one file or across files) is ONE
+    # model whose lineage is the union of its statements (nycdb, the
+    # cross-file gap named in PR #28)
+    extra_sqls: list[str] = field(default_factory=list)
+    # spellings granted from a multi-relation file's stem. Kept apart from
+    # aliases because they are DELIBERATELY ambiguous: the graph may pick
+    # among stem claimants by the asked column, but never among real
+    # collisions (the review of PR #28)
+    stem_aliases: set[str] = field(default_factory=set)
+    # minted from CREATE FUNCTION (a traced TVF): a table-function call by
+    # this written name binds here instead of degrading as a
+    # function/relation collision (cycle-13 review, F11)
+    is_function: bool = False
+
+    def __post_init__(self):
+        if not self.uid:
+            self.uid = self.path or self.name
+
+
+@dataclass
+class Project:
+    root: Path
+    dialect: str
+    mode: str  # "dbt-manifest" | "dbt-raw" | "sql-dir"
+    models: list[Model]
+    sources: list[Model]
+    warnings: list[str] = field(default_factory=list)
+    # True when nothing declared the dialect and it was guessed or sniffed
+    dialect_assumed: bool = False
+    # (package_name | None, macro_source_text) pairs
+    macro_sources: list = field(default_factory=list)
+    package_name: str | None = None
+    # BI edges declared as code (dbt metrics, exposures): model column -> BI node
+    downstream: list = field(default_factory=list)
+    # vars declared in dbt_project.yml, resolved by var() during tier-b renders
+    jinja_vars: dict = field(default_factory=dict)
+
+    @property
+    def name_candidates(self) -> dict[str, list[str]]:
+        """Every alias (lowercased) -> all ENABLED model/source names it could
+        mean. Disabled models never bind refs: dbt would not build them.
+
+        More than one candidate means the name is ambiguous in this project;
+        the graph layer downgrades trust instead of guessing silently.
+        """
+        return self._name_index(include_disabled=False)
+
+    @property
+    def all_name_candidates(self) -> dict[str, list[str]]:
+        """name_candidates including disabled models, for lookups that are
+        about a model's own analysis (parent schemas, ordering), not binding."""
+        return self._name_index(include_disabled=True)
+
+    def _name_index(self, include_disabled: bool) -> dict[str, list[str]]:
+        index: dict[str, list[str]] = {}
+        for m in [*self.sources, *self.models]:
+            if not include_disabled and not m.enabled:
+                continue
+            for alias in {m.name, *m.aliases, *m.stem_aliases}:
+                bucket = index.setdefault(alias.lower(), [])
+                if m.name not in bucket:
+                    bucket.append(m.name)
+        return index
+
+    @property
+    def stem_alias_names(self) -> set[str]:
+        """Lowercased spellings granted from file stems; the only names the
+        graph may disambiguate by the asked column."""
+        return {a.lower() for m in self.models for a in m.stem_aliases}
+
+    @property
+    def name_index(self) -> dict[str, str]:
+        """Every alias (lowercased) -> first canonical name. Prefer
+        name_candidates anywhere ambiguity matters."""
+        return {alias: names[0] for alias, names in self.name_candidates.items()}
+
+
+def find_project_root(start: Path) -> Path:
+    """Walk up from start looking for dbt_project.yml; fall back to start."""
+    current = start.resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / "dbt_project.yml").exists():
+            return candidate
+    return current
+
+
+def _find_dbt_projects(root: Path) -> list[Path]:
+    """Every real dbt project dir under root, deepest-first-stable.
+
+    Excludes vendored packages: dbt_packages/ and dbt_modules/ ship their own
+    dbt_project.yml, and those are dependencies, not the repo's own projects.
+    """
+    found: list[Path] = []
+    for yml in sorted(root.rglob("dbt_project.yml")):
+        parts = yml.relative_to(root).parts[:-1]
+        if any(p in IGNORE_DIRS or p.startswith(".") for p in parts):
+            continue
+        found.append(yml.parent)
+    return found
+
+
+DEFAULT_DIALECT = "snowflake"
+
+
+def relative_posix(path, root) -> str:
+    """A path relative to the project root, with forward slashes on every
+    OS, so a model's path is the same string in a PR comment written on
+    Linux and on the laptop that reads it."""
+    return path.relative_to(root).as_posix()

ripple/lookml.py

@@ -0,0 +1,163 @@
+"""Downstream reach into Looker by parsing LookML files.
+
+LookML is declarative code in git: a view binds to a warehouse table, and every
+field's `sql:` names the columns it reads. Resolving `${TABLE}.col` and `${field}`
+references gives `view.field -> table.column` with no connection to Looker. Where
+the mapping only exists at query time (Liquid branching, PDT-compiled SQL), the
+edge is marked review_required rather than guessed.
+
+Needs the optional `looker` extra (`lkml`); absent it, this yields nothing.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+from ripple.project import IGNORE_DIRS
+from ripple.semantic import DownstreamEdge
+
+_TABLE_COL = re.compile(r"\$\{TABLE\}\.(\w+)")
+_FIELD_REF = re.compile(r"\$\{(\w+)\}")  # ${other_field}, same view
+_LIQUID = re.compile(r"\{%|\{\{")  # Liquid: only resolves at query time
+_FIELD_KINDS = ("dimensions", "measures", "dimension_groups", "filters")
+
+
+def _table(view: dict) -> str:
+    """The physical table a view reads. `sql_table_name` wins, else the view name;
+    schema/database qualifiers are dropped so it matches a model node."""
+    raw = view.get("sql_table_name") or view.get("name", "")
+    return raw.split(".")[-1].strip().strip('`"') or view.get("name", "")
+
+
+def _resolve(sql: str, by_name: dict, seen: set | None = None) -> tuple[str, set[str], str]:
+    """(trust, columns, reason) for one field's SQL."""
+    seen = seen or set()
+    if _LIQUID.search(sql):
+        return (
+            "review_required",
+            set(_TABLE_COL.findall(sql)),
+            "Liquid branch, resolved at query time",
+        )
+    cols = set(_TABLE_COL.findall(sql))
+    trust, reason = "verified", ""
+    for ref in _FIELD_REF.findall(sql):
+        if ref == "TABLE" or ref in seen:
+            continue
+        seen.add(ref)
+        target = by_name.get(ref)
+        if target is None:
+            trust, reason = "review_required", "references a field outside this view"
+            continue
+        t2, sub, r2 = _resolve(target, by_name, seen)
+        cols |= sub
+        if t2 == "review_required":
+            trust, reason = "review_required", r2
+    return trust, cols, reason
+
+
+def _view_edges(view: dict) -> list[DownstreamEdge]:
+    name = view.get("name")
+    if not name:
+        return []
+    table = _table(view)
+    derived = "derived_table" in view
+    fields: dict[str, str] = {}
+    for kind in _FIELD_KINDS:
+        for f in view.get(kind) or []:
+            if isinstance(f, dict) and f.get("name"):
+                # a field with no sql defaults to the same-named column
+                fields[f["name"]] = (f.get("sql") or f"${{TABLE}}.{f['name']}").strip().rstrip(";")
+
+    edges: list[DownstreamEdge] = []
+    for field, sql in fields.items():
+        if derived:
+            # a derived table's columns come from its own SQL, not the base table
+            edges.append(
+                DownstreamEdge(
+                    table,
+                    field,
+                    f"looker:{name}.{field}",
+                    field,
+                    "review_required",
+                    "column of a derived table, verify against its SQL",
+                )
+            )
+            continue
+        trust, cols, reason = _resolve(sql, fields)
+        for col in sorted(cols):
+            edges.append(DownstreamEdge(table, col, f"looker:{name}.{field}", field, trust, reason))
+    return edges
+
+
+def _dashboard_edges(doc) -> list[DownstreamEdge]:
+    """A LookML dashboard (YAML) tile references `view.field`; that field feeds the
+    dashboard, so the field node hangs a node-level edge to the dashboard."""
+    edges: list[DownstreamEdge] = []
+    dashboards = doc if isinstance(doc, list) else [doc]
+    for dash in dashboards:
+        if not isinstance(dash, dict) or "dashboard" not in dash:
+            continue
+        dname = dash["dashboard"]
+        refs: set[str] = set()
+        for el in dash.get("elements") or []:
+            if not isinstance(el, dict):
+                continue
+            for key in ("fields", "dimensions", "measures"):
+                for ref in el.get(key) or []:
+                    if isinstance(ref, str) and "." in ref:
+                        refs.add(ref)
+        for ref in sorted(refs):
+            view, _, field = ref.rpartition(".")
+            view = view.split(".")[-1]  # drop model.explore. prefix if present
+            edges.append(
+                DownstreamEdge(
+                    f"looker:{view}.{field}",
+                    field,
+                    f"dashboard:{dname}",
+                    "*",
+                    "review_required",
+                    "dashboard tile, node-level",
+                )
+            )
+    return edges
+
+
+def load_lookml_downstream(root: Path) -> list[DownstreamEdge]:
+    """Every field-to-column edge (and dashboard leaf) resolvable from LookML files."""
+    try:
+        import lkml
+    except ImportError:
+        return []
+
+    edges: list[DownstreamEdge] = []
+    for path in sorted(root.rglob("*.lkml")):
+        parts = path.relative_to(root).parts[:-1]
+        if any(p in IGNORE_DIRS or p.startswith(".") for p in parts):
+            continue
+        try:
+            tree = lkml.load(path.read_text(errors="replace", encoding="utf-8"))
+        except Exception:
+            continue
+        for view in tree.get("views") or []:
+            edges.extend(_view_edges(view))
+
+    for path in sorted(root.rglob("*.dashboard.lookml")):
+        parts = path.relative_to(root).parts[:-1]
+        if any(p in IGNORE_DIRS or p.startswith(".") for p in parts):
+            continue
+        try:
+            doc = yaml.safe_load(path.read_text(errors="replace", encoding="utf-8"))
+        except yaml.YAMLError:
+            continue
+        edges.extend(_dashboard_edges(doc))
+
+    # dedupe
+    seen, out = set(), []
+    for e in edges:
+        if e not in seen:
+            seen.add(e)
+            out.append(e)
+    return out