ripple-sql 0.1.0__py3-none-any.whl

ripple/loaders/dbt_config.py

@@ -0,0 +1,339 @@
+"""dbt_project.yml knobs: vars, enabled rules, macro and model paths."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+def _project_vars(root: Path) -> dict:
+    """Declared vars from dbt_project.yml. A sub-dict scoped under the
+    project's own name is flattened in (dbt per-package scoping); scopes for
+    other packages are left as-is since their names aren't known here."""
+    project_yml = root / "dbt_project.yml"
+    if not project_yml.is_file():
+        return {}
+    import yaml
+
+    text = project_yml.read_text(errors="replace", encoding="utf-8")
+    try:
+        parsed = yaml.safe_load(text)
+    except yaml.YAMLError:
+        # hand-edited ymls with inconsistent indentation still deserve their
+        # flat vars; salvage them line by line
+        return _flat_vars_fallback(text)
+    if not isinstance(parsed, dict) or not isinstance(parsed.get("vars"), dict):
+        return {}
+    declared = dict(parsed["vars"])
+    scoped = declared.get(parsed.get("name"))
+    if isinstance(scoped, dict):
+        declared.pop(parsed.get("name"))
+        declared.update(scoped)
+    return declared
+
+
+def _flat_vars_fallback(text: str) -> dict:
+    import yaml
+
+    lines = text.splitlines()
+    start = next(
+        (i for i, line in enumerate(lines) if re.match(r"^\s*vars:\s*(#.*)?$", line)), None
+    )
+    if start is None:
+        return {}
+    block: list[str] = []
+    for line in lines[start + 1 :]:
+        if re.match(r"^\s*[A-Za-z0-9_.-]+:\s*\S", line):
+            block.append(line.strip())
+        elif line.strip():
+            break
+    try:
+        parsed = yaml.safe_load("\n".join(block))
+    except yaml.YAMLError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _enabled_overrides(
+    root: Path, dialect: str, project_vars: dict
+) -> list[tuple[tuple[str, ...], bool]]:
+    """(path prefix under the model dir, enabled) rules from the project's own
+    models: block in dbt_project.yml. dbt packages ship every dialect variant
+    of a model and gate them with enabled configs; ignoring those poisons ref
+    binding with variants dbt would never build."""
+    project_yml = root / "dbt_project.yml"
+    if not project_yml.is_file():
+        return []
+    import yaml
+
+    try:
+        parsed = yaml.safe_load(project_yml.read_text(errors="replace", encoding="utf-8"))
+    except yaml.YAMLError:
+        return []
+    if not isinstance(parsed, dict) or not isinstance(parsed.get("models"), dict):
+        return []
+    tree = parsed["models"].get(parsed.get("name"))
+    if not isinstance(tree, dict):
+        return []
+    rules: list[tuple[tuple[str, ...], bool]] = []
+
+    def walk(node: dict, prefix: tuple[str, ...]) -> None:
+        raw = node.get("+enabled", node.get("enabled"))
+        if raw is not None and not isinstance(raw, dict):
+            decided = _eval_enabled(raw, dialect, project_vars)
+            if decided is not None:
+                rules.append((prefix, decided))
+        for key, child in node.items():
+            if isinstance(child, dict) and not key.startswith("+"):
+                walk(child, prefix + (key,))
+
+    walk(tree, ())
+    return rules
+
+
+def _enabled_for(parts: tuple[str, ...], rules: list[tuple[tuple[str, ...], bool]]) -> bool | None:
+    """Deepest matching rule wins, dbt-style. None when no rule applies."""
+    decided, best = None, -1
+    for prefix, value in rules:
+        if len(prefix) > best and parts[: len(prefix)] == prefix:
+            decided, best = value, len(prefix)
+    return decided
+
+
+_CONFIG_CALL_RE = re.compile(r"{{-?\s*config\s*\(", re.I)
+
+
+def _file_enabled(raw: str, dialect: str, project_vars: dict) -> bool | None:
+    """enabled= from a model file's own {{ config(...) }}, if it decides."""
+    match = _CONFIG_CALL_RE.search(raw)
+    if match is None:
+        return None
+    depth, i = 1, match.end()
+    while i < len(raw) and depth:
+        if raw[i] == "(":
+            depth += 1
+        elif raw[i] == ")":
+            depth -= 1
+        i += 1
+    body = raw[match.end() : i - 1]
+    arg = re.search(r"\benabled\s*=", body)
+    if arg is None:
+        return None
+    expr: list[str] = []
+    depth = 0
+    for ch in body[arg.end() :]:
+        if ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            break
+        expr.append(ch)
+    return _render_enabled("{{ (" + "".join(expr).strip() + ") }}", dialect, project_vars)
+
+
+def _eval_enabled(value, dialect: str, project_vars: dict) -> bool | None:
+    """True/False when a literal or a target/var-decided expression settles
+    it; None (treated as enabled) when it cannot be evaluated honestly."""
+    if isinstance(value, bool):
+        return value
+    if not isinstance(value, str):
+        return None
+    text = value.strip()
+    if text.lower() in ("true", "false"):
+        return text.lower() == "true"
+    if "{{" in text or "{%" in text:
+        return _render_enabled(text, dialect, project_vars)
+    return None
+
+
+def _render_enabled(template: str, dialect: str, project_vars: dict) -> bool | None:
+    """Evaluate an enabled jinja expression with target.type = the project
+    dialect and declared vars. Anything unresolvable renders as None: an
+    un-evaluatable gate must not disable a model."""
+    from jinja2 import Environment, StrictUndefined
+
+    env = Environment(undefined=StrictUndefined)
+    # dbt's as_bool coerces after render; the comparison already yields a bool
+    env.filters["as_bool"] = lambda value: value
+    missing = object()
+
+    def _var(name, default=missing):
+        if name in project_vars:
+            return project_vars[name]
+        if default is missing:
+            raise KeyError(name)
+        return default
+
+    try:
+        rendered = (
+            env.from_string(template)
+            .render(var=_var, target={"type": dialect, "name": "prod"})
+            .strip()
+        )
+    except Exception:
+        return None
+    if rendered == "True":
+        return True
+    if rendered == "False":
+        return False
+    return None
+
+
+def _macro_dir_names(project_yml: Path) -> list[str]:
+    """macro-paths from a dbt_project.yml, defaulting to dbt's ["macros"].
+
+    Real YAML parsing, because block-style lists are valid dbt config and a
+    flow-only regex silently falls back to macros/ on them, which is the same
+    zero-macros failure this exists to fix (make-open-data, holdout round 2:
+    macro-paths: ["5_macros"], every macro call rendered to nothing)."""
+    if not project_yml.is_file():
+        return ["macros"]
+    text = project_yml.read_text(errors="replace", encoding="utf-8")
+    try:
+        import yaml
+
+        data = yaml.safe_load(text) or {}
+        names = data.get("macro-paths")
+        if isinstance(names, list):
+            cleaned = [n for n in names if isinstance(n, str) and n.strip()]
+            if cleaned:
+                return cleaned
+    except Exception:
+        match = re.search(r"macro-paths:\s*\[([^\]]*)\]", text)
+        if match:
+            names = [
+                part.strip().strip("'\"") for part in match.group(1).split(",") if part.strip()
+            ]
+            if names:
+                return names
+    return ["macros"]
+
+
+def _macro_sources(root: Path) -> list[tuple[str | None, str]]:
+    """(package, source) for the project's own macros and vendored packages.
+
+    The project's own macros carry the dbt_project.yml name as their package
+    so both bare and self-namespaced calls ({{ ga4.unnest_key(...) }} inside
+    the ga4 package itself) resolve. macro-paths is honored for the root
+    project and every vendored package alike.
+    """
+    root_package = None
+    project_yml = root / "dbt_project.yml"
+    if project_yml.is_file():
+        match = re.search(
+            r"^name:\s*['\"]?([A-Za-z0-9_]+)",
+            project_yml.read_text(errors="replace", encoding="utf-8"),
+            re.M,
+        )
+        if match:
+            root_package = match.group(1)
+    pairs: list[tuple[str | None, str]] = []
+    seen_files: set[Path] = set()
+
+    def _load_dirs(base: Path, dir_names: list[str], package: str | None) -> None:
+        for dir_name in dir_names:
+            macros_dir = base / dir_name
+            if not macros_dir.is_dir():
+                continue
+            for macro_file in sorted(macros_dir.rglob("*.sql")):
+                resolved = macro_file.resolve()
+                if resolved in seen_files:
+                    continue
+                seen_files.add(resolved)
+                try:
+                    pairs.append(
+                        (package, macro_file.read_text(errors="replace", encoding="utf-8"))
+                    )
+                except OSError:
+                    continue
+
+    _load_dirs(root, _macro_dir_names(project_yml), root_package)
+    for packages_dir_name in ("dbt_packages", "dbt_modules"):
+        packages_dir = root / packages_dir_name
+        if not packages_dir.is_dir():
+            continue
+        for package_dir in sorted(p for p in packages_dir.iterdir() if p.is_dir()):
+            _load_dirs(
+                package_dir,
+                _macro_dir_names(package_dir / "dbt_project.yml"),
+                package_dir.name,
+            )
+    return pairs
+
+
+def _dbt_model_dirs(root: Path) -> list[Path]:
+    dirs = []
+    project_yml = (root / "dbt_project.yml").read_text(errors="replace", encoding="utf-8")
+    # cheap YAML-free extraction of model-paths; dbt defaults to ["models"]
+    match = re.search(r"model-paths:\s*\[([^\]]*)\]", project_yml)
+    if match:
+        names = [part.strip().strip("'\"") for part in match.group(1).split(",") if part.strip()]
+    else:
+        names = re.findall(r"model-paths:\s*\n((?:\s*-\s*.+\n?)+)", project_yml)
+        names = re.findall(r"-\s*['\"]?([^'\"\n]+)", names[0]) if names else ["models"]
+    for name in names or ["models"]:
+        candidate = root / name.strip()
+        if candidate.is_dir():
+            dirs.append(candidate)
+    return dirs or ([root / "models"] if (root / "models").is_dir() else [])
+
+
+def _seed_dirs(project_dir: Path) -> list[Path]:
+    """The configured seed-paths (default seeds/ and data/) that exist."""
+    names = ["seeds", "data"]
+    yml = project_dir / "dbt_project.yml"
+    if yml.is_file():
+        try:
+            import yaml
+
+            loaded = yaml.safe_load(yml.read_text(errors="replace", encoding="utf-8"))
+            value = (loaded or {}).get("seed-paths") if isinstance(loaded, dict) else None
+            if isinstance(value, str):
+                value = [value]
+            if isinstance(value, list) and value:
+                names = [v for v in value if isinstance(v, str) and v.strip()]
+        except Exception:
+            pass
+    return [project_dir / n for n in names if (project_dir / n).is_dir()]
+
+
+def _dbt_owned_dirs(project_dir: Path) -> list[Path]:
+    """The directories a dbt project owns: its configured model/macro/test/
+    seed/snapshot/analysis paths plus dbt's machinery. Anything else under
+    the project dir is the team's own SQL, not dbt's. Configured spellings
+    are read from dbt_project.yml (review: analysis-paths: ["queries"]
+    must not be swept into raw models); the defaults stay excluded too,
+    since stale default dirs linger on disk."""
+    defaults = {
+        "analysis-paths": ["analyses", "analysis"],
+        "test-paths": ["tests"],
+        "seed-paths": ["seeds", "data"],
+        "snapshot-paths": ["snapshots"],
+        "docs-paths": [],
+        "asset-paths": [],
+        "target-path": ["target"],
+        "packages-install-path": ["dbt_packages", "dbt_modules"],
+        "log-path": ["logs"],
+    }
+    config: dict = {}
+    yml = project_dir / "dbt_project.yml"
+    if yml.is_file():
+        try:
+            import yaml
+
+            loaded = yaml.safe_load(yml.read_text(errors="replace", encoding="utf-8"))
+            config = loaded if isinstance(loaded, dict) else {}
+        except Exception:
+            config = {}
+    names: set[str] = set()
+    for key, fallback in defaults.items():
+        value = config.get(key, [])
+        if isinstance(value, str):
+            value = [value]
+        names.update(v for v in (value or []) if isinstance(v, str) and v.strip())
+        names.update(fallback)
+    owned = [project_dir / name for name in sorted(names)]
+    owned += _dbt_model_dirs(project_dir)
+    owned += [project_dir / name for name in _macro_dir_names(project_dir / "dbt_project.yml")]
+    return [d for d in owned if d.is_dir()]

ripple/loaders/identity.py

@@ -0,0 +1,328 @@
+"""Cross-model identity: collisions, suffix lookups, ingested schemas."""
+
+from __future__ import annotations
+
+import re
+
+from ripple.loaders.types import Model, Project
+
+_WHOLE_PLACEHOLDER_RE = re.compile(r"^(\{\{[^}]*\}\}|\{[^{}]*\})$")
+
+
+def _split_outside_braces(name: str) -> list[str]:
+    parts, depth, cur = [], 0, []
+    for ch in name:
+        if ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth = max(depth - 1, 0)
+        if ch == "." and depth == 0:
+            parts.append("".join(cur))
+            cur = []
+        else:
+            cur.append(ch)
+    parts.append("".join(cur))
+    return parts
+
+
+def strip_placeholders(name: str) -> str:
+    """{hscic}.ccgs -> ccgs, {project}.hscic.bnf -> hscic.bnf,
+    {{params.dataset_name}}.blocks -> blocks. A qualifier that is wholly a
+    placeholder is deploy config, not identity (openprescribing,
+    bitcoin_etl); the relation a person ingests is what is left. A segment
+    that mixes text and a placeholder (blocks{{params.ds_postfix}}) is a
+    templated NAME, a different table each deploy, and is returned unchanged
+    so it stays cited as written (round 11)."""
+    parts = _split_outside_braces(name)
+    kept = [p for p in parts if p and not _WHOLE_PLACEHOLDER_RE.match(p)]
+    if any("{" in p for p in kept):
+        return name
+    return ".".join(kept)
+
+
+def _name_suffixes(name: str) -> set[str]:
+    """Every suffix a qualified name answers to: db.schema.t -> {db.schema.t,
+    schema.t, t}."""
+    parts = name.split(".")
+    return {".".join(parts[i:]) for i in range(len(parts))}
+
+
+def _qualifiers_by_bare_name(project: Project) -> dict[str, set[str]]:
+    """bare relation name -> every qualified form the project's SQL writes.
+
+    Only the ingest path needs this, so it parses lazily and only when a
+    schemas.json exists. Two entries for one bare name means the name does not
+    identify a relation in this repo, whatever a warehouse returned for it.
+    """
+    import sqlglot
+    from sqlglot import exp
+
+    from ripple.engine.column_ref import qualified_table_name
+
+    seen: dict[str, set[str]] = {}
+    for model in project.models:
+        if not model.sql.strip():
+            continue
+        try:
+            parsed = sqlglot.parse(
+                model.sql, dialect=model.dialect or project.dialect, error_level=None
+            )
+        except Exception:
+            continue
+        for statement in parsed:
+            if statement is None:
+                continue
+            for table in statement.find_all(exp.Table):
+                if not table.name or not (table.db or table.catalog):
+                    continue
+                # placeholder qualifiers are deploy config, not identity;
+                # counting {{ params.db }}.s.t and s.t as two relations
+                # refused bare ingested schemas as falsely ambiguous
+                qualified = strip_placeholders(qualified_table_name(table).lower())
+                if "." not in qualified:
+                    continue
+                seen.setdefault(table.name.lower(), set()).add(qualified)
+    return seen
+
+
+def _apply_ingested_schemas(project: Project, extra_roots: tuple = ()) -> None:
+    """Expose .ripple/schemas.json tables as known external relations.
+
+    A name matching an existing schema-less relation (a dbt source, a base
+    table with no columns) attaches its columns there; anything else becomes
+    a new source with declared columns. A model the project actually derives
+    keeps its own analysis: ingested schemas fill gaps, they never override.
+    """
+    from ripple.schemas import load_schemas
+
+    # the CLI and MCP write .ripple/schemas.json at the repo root they were
+    # run from; a dbt project in a subfolder (balboa's transform/) has its
+    # own root, and reading only there made every ingest a silent no-op
+    tables: dict = {}
+    for root in dict.fromkeys([project.root, *extra_roots]):
+        tables.update(load_schemas(root) or {})
+    if not tables:
+        return
+    # every relation a spelling names, not the first: a monorepo declares the
+    # same source in several projects (mattermost-dwh), and columns attached
+    # to one left the readers of the other star_only
+    index: dict[str, list[Model]] = {}
+    for m in [*project.models, *project.sources]:
+        for alias in {m.name, *m.aliases}:
+            bucket = index.setdefault(alias.lower(), [])
+            # identity, not equality: two projects' declarations of one
+            # source compare equal field by field and are distinct objects
+            if not any(existing is m for existing in bucket):
+                bucket.append(m)
+    qualifiers = _qualifiers_by_bare_name(project)
+    # a bare spelling a model owns is that model's: an ingested raw.orders
+    # granting itself "orders" made model_columns("orders") answer for the
+    # source (same rule dbt sources already follow)
+    owned = {m.name.lower() for m in project.models if m.sql.strip()}
+    for name, columns in tables.items():
+        if "." not in name:
+            # A bare ingested name cannot answer for two different relations.
+            # raw.orders and staging.orders both matched one `orders` entry and
+            # every edge came out high_confidence, when the same edges are
+            # review_required without the ingest. Refuse rather than pick one:
+            # the fix is to re-ingest qualified, and only the user knows which
+            # relation the columns came from.
+            seen = qualifiers.get(name.lower(), set())
+            if len(seen) > 1:
+                project.warnings.append(
+                    f"Ingested schema '{name}' matches {len(seen)} relations "
+                    f"({', '.join(sorted(seen))}); it was not attached. "
+                    "Re-ingest using qualified names."
+                )
+                continue
+        candidates = sorted(_name_suffixes(name), key=len, reverse=True)
+        parts = name.split(".")
+        if len(parts) >= 2:
+            candidates.append(f"{parts[-2]}__{parts[-1]}")
+        # only a schema-less relation can take these columns; a bare suffix
+        # that names a model with SQL (Mozilla's events_stream beside an
+        # ingest of mdn_fred.events_stream) must not swallow the ingest
+        targets = next(
+            (
+                [t for t in index[k] if not t.sql.strip()]
+                for k in candidates
+                if k in index and any(not t.sql.strip() for t in index[k])
+            ),
+            None,
+        )
+        if targets:
+            for target in targets:
+                known = {c.lower() for c in target.declared_columns}
+                target.declared_columns.extend(c for c in columns if c not in known)
+                target.aliases |= {a for a in _name_suffixes(name) if a.lower() not in owned}
+        else:
+            source = Model(
+                name=name,
+                sql="",
+                path="",
+                aliases={a for a in _name_suffixes(name) if a.lower() not in owned},
+                declared_columns=list(columns),
+                is_source=True,
+                evidence="ingested",
+            )
+            project.sources.append(source)
+            for alias in {source.name, *source.aliases}:
+                index.setdefault(alias.lower(), []).append(source)
+
+
+def _qualify_collisions(project: Project) -> None:
+    """Two models with the same display name must never merge into one node.
+
+    Colliding models get path-qualified canonical names; the bare name stays
+    as an alias on both, so a reference to it resolves ambiguously (which the
+    graph layer flags review_required) instead of silently binding.
+    """
+    by_name: dict[str, list[Model]] = {}
+    for model in project.models:
+        # resolution is case-insensitive (name_candidates lowercases), so
+        # collision detection in a sql dir must fold case the same way
+        key = model.name.lower() if project.mode == "sql-dir" else model.name
+        by_name.setdefault(key, []).append(model)
+    taken = {(m.name.lower() if project.mode == "sql-dir" else m.name) for m in project.models}
+    for name, group in by_name.items():
+        if len(group) < 2:
+            continue
+        if project.mode == "sql-dir":
+            group = _collapse_sql_dir_tables(project, group)
+            if len(group) < 2:
+                continue
+        project.warnings.append(
+            f"{len(group)} models share the name '{name}'; qualified by path. "
+            "References to the bare name are flagged for review."
+        )
+        # dbt compiles exactly one model per stem; a swept twin outside the
+        # dbt-owned paths (pudl's schema_inputs/ fixtures, holdout round 6)
+        # is not deployed under that name. When one member is the dbt model,
+        # the bare identity is provably its and only the twins rename.
+        dbt_owned = [m for m in group if m.evidence in ("manifest", "raw_jinja")]
+        keeper = dbt_owned[0] if len(dbt_owned) == 1 else None
+        for model in group:
+            if model is keeper:
+                continue
+            if project.mode == "sql-dir" and not model.sql.strip():
+                continue  # a base table keeps its table-level name
+            base = re.sub(r"\.sql$", "", model.path).replace("/", "__") or model.name
+            suffix = model.name.lower()
+            if base.lower() == suffix or base.lower().endswith("__" + suffix):
+                qualified = base
+            else:
+                # a multi-relation file: the path alone names the FILE, and
+                # holdout round 4 collapsed eleven FAC views into one node
+                # this way; the relation keeps its identity inside the path
+                qualified = f"{base}__{model.name}"
+            # the rename must never assign one canonical name to two
+            # relations (review: foo__bar.sql defining bar AND
+            # foo__bar); fall through to ever-longer spellings until unique
+            key = qualified.lower() if project.mode == "sql-dir" else qualified
+            if key in taken and qualified != model.name:
+                qualified = f"{base}__{model.name}"
+                key = qualified.lower() if project.mode == "sql-dir" else qualified
+            while key in taken and key != (
+                model.name.lower() if project.mode == "sql-dir" else model.name
+            ):
+                qualified = f"{qualified}__{model.name}"
+                key = qualified.lower() if project.mode == "sql-dir" else qualified
+            model.aliases.add(name)
+            model.name = qualified
+            taken.add(key)
+
+
+def _collapse_sql_dir_tables(project: Project, group: list[Model]) -> list[Model]:
+    """In a plain sql dir the same CREATE TABLE name in several dump files is
+    one table-level relation (one dump = one database), not a collision worth
+    a path-qualified name. Schema-only definitions merge; models carrying a
+    real derivation stay distinct, EXCEPT prior-state derivations: a table
+    built by CREATE plus UPDATEs across files (nycdb's add_columns.sql and
+    full_text.sql both writing dobjobs, the gap named in PR #28) is one
+    relation whose lineage is the union of its statements."""
+    tables = [m for m in group if not m.sql.strip()]
+    if len(tables) >= 2:
+        # prefer the dialect-folded (lowercase) spelling as the surviving name
+        keep = next((m for m in tables if m.name == m.name.lower()), tables[0])
+        for other in tables:
+            if other is keep:
+                continue
+            for column in other.declared_columns:
+                if column not in keep.declared_columns:
+                    keep.declared_columns.append(column)
+            keep.aliases |= other.aliases
+            project.models.remove(other)
+        group = [keep, *(m for m in group if m.sql.strip())]
+    return _merge_self_read_derivations(project, group)
+
+
+def _qualified_spellings(model: Model) -> set[str]:
+    return {a for a in model.aliases if "." in a}
+
+
+def _merge_self_read_derivations(project: Project, group: list[Model]) -> list[Model]:
+    """Fold UPDATE-derived models into the one model that owns the table.
+
+    Only prior-state (self_read) derivations merge, only when at most one
+    creator exists (two creators is a real collision), and only when the
+    qualified spellings agree: sales.summary and hr.summary stay two
+    relations whatever the bare name says (the round-3 identity rule)."""
+    creators = [m for m in group if m.sql.strip() and not m.self_read]
+    updates = [m for m in group if m.sql.strip() and m.self_read]
+    if not updates or len(creators) > 1:
+        return group
+    bases = [m for m in group if not m.sql.strip()]
+    anchor = creators[0] if creators else (bases[0] if bases else updates[0])
+    kept = [anchor, *(m for m in bases if m is not anchor)]
+    for update in updates:
+        if update is anchor:
+            continue
+        anchor_q = _qualified_spellings(anchor)
+        update_q = _qualified_spellings(update)
+        # a bare updater against a schema-qualified creator proves nothing:
+        # the update could run under any search_path (review of
+        # cycle 6); merging needs both bare or an agreeing qualification
+        if (anchor_q or update_q) and not (anchor_q & update_q):
+            kept.append(update)
+            continue
+        if not anchor.sql.strip():
+            anchor.sql = update.sql
+        else:
+            anchor.extra_sqls.append(update.sql)
+        anchor.extra_sqls.extend(update.extra_sqls)
+        anchor.self_read = True
+        anchor.declared_parents |= update.declared_parents
+        anchor.aliases |= update.aliases
+        anchor.stem_aliases |= update.stem_aliases
+        for column in update.declared_columns:
+            if column not in anchor.declared_columns:
+                anchor.declared_columns.append(column)
+        project.models.remove(update)
+    return kept
+
+
+ROLE_STEMS = frozenset({"query", "view", "model", "table", "select", "main", "definition"})
+
+
+def directory_identity(rel: str) -> tuple[str, set[str]] | None:
+    """(name, dotted aliases) for a file whose stem names its role, not the relation.
+
+    Mozilla's bigquery-etl keeps 887 query.sql and 803 view.sql files at
+    sql/<project>/<dataset>/<table>/ and references each relation as
+    `project.dataset.table`. Named by stem, every model was "query", the
+    collision handler mangled them into path names no reference could match,
+    and a 2,096-model repo came out with 0 verified edges. The directory is
+    the relation; its two nearest ancestors are the qualified spellings.
+    Returns None when the stem carries identity as usual. checks.sql and
+    script.sql are deliberately not roles: a check reads the relation, it
+    does not define it, and claiming the directory would collide with the
+    real definition beside it.
+    """
+    from pathlib import Path
+
+    parts = Path(rel).parts
+    if len(parts) < 2 or Path(parts[-1]).stem.lower() not in ROLE_STEMS:
+        return None
+    dirs = parts[:-1]
+    aliases = {".".join(dirs[-n:]) for n in (2, 3) if len(dirs) >= n}
+    return dirs[-1], aliases