dbdocs 1.0.2__tar.gz → 1.2.0__tar.gz

{dbdocs-1.0.2 → dbdocs-1.2.0}/.gitignore

@@ -152,6 +152,8 @@ frontend/dist/
 frontend/.vite/
 frontend/coverage/
 frontend/*.tsbuildinfo
+frontend/test-results/
+frontend/playwright-report/
 .eslintcache
 
 # npm / yarn / pnpm logs & debug output

dbdocs-1.2.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: dbdocs
+Version: 1.2.0
+Summary: Alternative dbt docs site: Catalog + ERD + column-level lineage
+Project-URL: Homepage, https://github.com/datnguye/dbt-docs
+Project-URL: Repository, https://github.com/datnguye/dbt-docs
+Author-email: Dat Nguyen <datnguyen.it09@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: dbt,dbterd,documentation,erd,lineage,sqlglot
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: artifact-parser[dbt]>=1.0.0
+Requires-Dist: click>=8.1
+Requires-Dist: dbterd>=1.27
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sqlglot>=25
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/logo.svg" alt="dbdocs logo" width="220" height="88">
+</p>
+
+<p align="center"><b>An alternative dbt docs site — catalog + ERD + column-level lineage + versioned deploys, all in one CLI.</b></p>
+
+<p align="center">
+  <a href="https://dbdocs.datnguye.me/latest/demo/latest/"><img src="https://img.shields.io/badge/live-demo-FF694A?style=flat&logo=rocket&logoColor=white" alt="live demo"></a>
+  <a href="https://dbdocs.datnguye.me/"><img src="https://img.shields.io/badge/docs-visit%20site-blue?style=flat&logo=gitbook&logoColor=white" alt="docs"></a>
+  <a href="https://pypi.org/project/dbdocs/"><img src="https://badge.fury.io/py/dbdocs.svg" alt="PyPI version"></a>
+  <img src="https://img.shields.io/badge/CLI-Python-FFCE3E?labelColor=14354C&logo=python&logoColor=white" alt="python-cli">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org"><img src="https://img.shields.io/badge/Python-3.10|3.11|3.12|3.13-3776AB.svg?style=flat&logo=python&logoColor=white" alt="python"></a>
+</p>
+
+Turn your dbt artifacts into a self-contained docs site: a browsable catalog, an entity-relationship diagram, an interactive lineage DAG, and **column-level lineage** traced from your compiled SQL — all in one `dbdocs generate`. Serve it with `dbdocs serve`, or deploy versioned builds anywhere a static host will take them.
+
+| Catalog | Model page | Lineage DAG | Health Check |
+|---|---|---|---|
+| ![catalog](docs/assets/img/demo-catalog.png) | ![model page](docs/assets/img/demo-model-page.png) | ![dag](docs/assets/img/demo-model-dag.png) | ![health check](docs/assets/img/demo-health.png) |
+
+## Why dbdocs?
+
+dbt's built-in docs are great — right up until you want to know *which upstream column fed this downstream column*, or *which tables relate to each other*, or *what changed between last week's docs and today's*. dbdocs fills all three gaps without asking you to install a documentation framework or maintain a separate ERD tool.
+
+**What you get that nothing else bundles together:**
+
+- **ERD + column-level lineage, side by side.** The entity-relationship diagram (powered by [dbterd](https://github.com/datnguye/dbterd)) shows table relationships; column lineage (traced by [sqlglot](https://github.com/tobymao/sqlglot) from compiled SQL) shows exactly which column fed which. Most alternatives give you one or the other — dbdocs gives you both.
+- **Column impact analysis.** Select any column and see its downstream dependents across the project, so you know what a schema change will break before you run it.
+- **Deep-link URLs.** Every focused node, column, and filtered DAG view has a shareable URL. Paste it in Slack and your teammate lands on exactly the right model, column, or graph state.
+- **Any sqlglot-supported dialect.** The dialect for column-lineage parsing is auto-detected from your manifest's `adapter_type` (Snowflake, BigQuery, Redshift, DuckDB, PostgreSQL, Databricks/Spark, Trino, and more — anything sqlglot understands). Override it per-project with `dialect:` in `dbdocs.yml` when auto-detection isn't enough.
+- **Scales without freezing.** Column-lineage parsing fans out across CPU cores automatically above 500 models, so large projects finish in roughly the same wall-clock time as small ones. The DAG is windowed by React Flow, so a 1 000-model graph doesn't turn your browser into a space heater. The payload ships as an external gzip (`dbdocs-data.json.gz`, decompressed client-side) so `index.html` stays tiny regardless of project size.
+- **Fail-soft.** One model with SQL sqlglot can't parse gets skipped and logged — it never sinks the whole generate run.
+- **Project Health Check.** A scorecard across the six [dbt-project-evaluator](https://dbt-labs.github.io/dbt-project-evaluator/) dimensions (testing, modeling, documentation, structure, performance, governance), computed straight from your `manifest.json` — no extra dbt package, no warehouse. When a `run_results.json` is also present (any `dbt build`/`dbt test`; default `<target_dir>/run_results.json`, override with `--run-results`), each test additionally shows up as a pass/fail finding grouped by what it checks (integrity, referential, validity, business logic, freshness). dbdocs only reads the artifacts — it never runs dbt or touches your warehouse. Fail-soft: a missing `run_results.json` just drops the per-test detail; the dimensions still render.
+- **Versioned deploys, no plugins.** `dbdocs deploy --version v1.2 --alias latest` generates into a plain directory tree, writes a `versions.json` index, and the SPA renders a version dropdown. No mike, no external tooling, no surprise dependencies.
+- **Catalog navigation + client-side search.** Models, seeds, and snapshots grouped by database and schema; full-text search without a backend.
+- **Dark / light theme.**
+
+## Install
+
+```bash
+pip install dbdocs --upgrade
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```bash
+dbt docs generate     # writes target/manifest.json + target/catalog.json
+dbdocs generate       # builds ./site/ with index.html + dbdocs-data.json.gz
+dbdocs serve          # static http server on http://127.0.0.1:8000
+```
+
+The site must be served over HTTP (not opened as a local file) because it fetches the data payload at load time. `dbdocs serve` handles that locally; any static host works for deployment.
+
+Full walkthrough, configuration, and architecture live in the **[documentation](https://dbdocs.datnguye.me/)**.
+
+## Contributing
+
+Contributions are welcome — bugs, features, docs, typos. See the **[Contributing Guide](https://dbdocs.datnguye.me/latest/nav/development/contributing-guide.html)**.
+
+If dbdocs saves you some clicks, consider [buying me a coffee](https://www.buymeacoffee.com/datnguye).
+
+<a href="https://www.buymeacoffee.com/datnguye"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg?logo=buy-me-a-coffee&logoColor=white&labelColor=ff813f&style=for-the-badge" alt="buy me a coffee"></a>
+
+## License
+
+[MIT](./LICENSE) © Dat Nguyen

dbdocs-1.2.0/README.md

@@ -0,0 +1,69 @@
+<p align="center">
+  <img src="docs/assets/logo.svg" alt="dbdocs logo" width="220" height="88">
+</p>
+
+<p align="center"><b>An alternative dbt docs site — catalog + ERD + column-level lineage + versioned deploys, all in one CLI.</b></p>
+
+<p align="center">
+  <a href="https://dbdocs.datnguye.me/latest/demo/latest/"><img src="https://img.shields.io/badge/live-demo-FF694A?style=flat&logo=rocket&logoColor=white" alt="live demo"></a>
+  <a href="https://dbdocs.datnguye.me/"><img src="https://img.shields.io/badge/docs-visit%20site-blue?style=flat&logo=gitbook&logoColor=white" alt="docs"></a>
+  <a href="https://pypi.org/project/dbdocs/"><img src="https://badge.fury.io/py/dbdocs.svg" alt="PyPI version"></a>
+  <img src="https://img.shields.io/badge/CLI-Python-FFCE3E?labelColor=14354C&logo=python&logoColor=white" alt="python-cli">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org"><img src="https://img.shields.io/badge/Python-3.10|3.11|3.12|3.13-3776AB.svg?style=flat&logo=python&logoColor=white" alt="python"></a>
+</p>
+
+Turn your dbt artifacts into a self-contained docs site: a browsable catalog, an entity-relationship diagram, an interactive lineage DAG, and **column-level lineage** traced from your compiled SQL — all in one `dbdocs generate`. Serve it with `dbdocs serve`, or deploy versioned builds anywhere a static host will take them.
+
+| Catalog | Model page | Lineage DAG | Health Check |
+|---|---|---|---|
+| ![catalog](docs/assets/img/demo-catalog.png) | ![model page](docs/assets/img/demo-model-page.png) | ![dag](docs/assets/img/demo-model-dag.png) | ![health check](docs/assets/img/demo-health.png) |
+
+## Why dbdocs?
+
+dbt's built-in docs are great — right up until you want to know *which upstream column fed this downstream column*, or *which tables relate to each other*, or *what changed between last week's docs and today's*. dbdocs fills all three gaps without asking you to install a documentation framework or maintain a separate ERD tool.
+
+**What you get that nothing else bundles together:**
+
+- **ERD + column-level lineage, side by side.** The entity-relationship diagram (powered by [dbterd](https://github.com/datnguye/dbterd)) shows table relationships; column lineage (traced by [sqlglot](https://github.com/tobymao/sqlglot) from compiled SQL) shows exactly which column fed which. Most alternatives give you one or the other — dbdocs gives you both.
+- **Column impact analysis.** Select any column and see its downstream dependents across the project, so you know what a schema change will break before you run it.
+- **Deep-link URLs.** Every focused node, column, and filtered DAG view has a shareable URL. Paste it in Slack and your teammate lands on exactly the right model, column, or graph state.
+- **Any sqlglot-supported dialect.** The dialect for column-lineage parsing is auto-detected from your manifest's `adapter_type` (Snowflake, BigQuery, Redshift, DuckDB, PostgreSQL, Databricks/Spark, Trino, and more — anything sqlglot understands). Override it per-project with `dialect:` in `dbdocs.yml` when auto-detection isn't enough.
+- **Scales without freezing.** Column-lineage parsing fans out across CPU cores automatically above 500 models, so large projects finish in roughly the same wall-clock time as small ones. The DAG is windowed by React Flow, so a 1 000-model graph doesn't turn your browser into a space heater. The payload ships as an external gzip (`dbdocs-data.json.gz`, decompressed client-side) so `index.html` stays tiny regardless of project size.
+- **Fail-soft.** One model with SQL sqlglot can't parse gets skipped and logged — it never sinks the whole generate run.
+- **Project Health Check.** A scorecard across the six [dbt-project-evaluator](https://dbt-labs.github.io/dbt-project-evaluator/) dimensions (testing, modeling, documentation, structure, performance, governance), computed straight from your `manifest.json` — no extra dbt package, no warehouse. When a `run_results.json` is also present (any `dbt build`/`dbt test`; default `<target_dir>/run_results.json`, override with `--run-results`), each test additionally shows up as a pass/fail finding grouped by what it checks (integrity, referential, validity, business logic, freshness). dbdocs only reads the artifacts — it never runs dbt or touches your warehouse. Fail-soft: a missing `run_results.json` just drops the per-test detail; the dimensions still render.
+- **Versioned deploys, no plugins.** `dbdocs deploy --version v1.2 --alias latest` generates into a plain directory tree, writes a `versions.json` index, and the SPA renders a version dropdown. No mike, no external tooling, no surprise dependencies.
+- **Catalog navigation + client-side search.** Models, seeds, and snapshots grouped by database and schema; full-text search without a backend.
+- **Dark / light theme.**
+
+## Install
+
+```bash
+pip install dbdocs --upgrade
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```bash
+dbt docs generate     # writes target/manifest.json + target/catalog.json
+dbdocs generate       # builds ./site/ with index.html + dbdocs-data.json.gz
+dbdocs serve          # static http server on http://127.0.0.1:8000
+```
+
+The site must be served over HTTP (not opened as a local file) because it fetches the data payload at load time. `dbdocs serve` handles that locally; any static host works for deployment.
+
+Full walkthrough, configuration, and architecture live in the **[documentation](https://dbdocs.datnguye.me/)**.
+
+## Contributing
+
+Contributions are welcome — bugs, features, docs, typos. See the **[Contributing Guide](https://dbdocs.datnguye.me/latest/nav/development/contributing-guide.html)**.
+
+If dbdocs saves you some clicks, consider [buying me a coffee](https://www.buymeacoffee.com/datnguye).
+
+<a href="https://www.buymeacoffee.com/datnguye"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg?logo=buy-me-a-coffee&logoColor=white&labelColor=ff813f&style=for-the-badge" alt="buy me a coffee"></a>
+
+## License
+
+[MIT](./LICENSE) © Dat Nguyen

{dbdocs-1.0.2 → dbdocs-1.2.0}/dbdocs/cli/main.py

@@ -26,7 +26,10 @@ __version__ = importlib.metadata.version("dbdocs")
 @click.pass_context
 def dbdocs(ctx, config_path):
     """Alternative dbt docs site: dbt docs + ERD + column-level lineage."""
-    logger.info("Run with dbdocs==%s", __version__)
+    # The version banner is useful for the build commands (generate/deploy) but
+    # is noise for the long-running `serve`, which prints its own start line.
+    if ctx.invoked_subcommand != "serve":
+        logger.info("Run with dbdocs==%s", __version__)
     try:
         ctx.obj = DbDocsConfig.load(config_path)
     except DbDocsError as exc:
@@ -38,16 +41,25 @@ def dbdocs(ctx, config_path):
 @click.option(
     "--dialect", default=None, help="SQL dialect for column lineage (default: adapter_type)."
 )
+@click.option(
+    "--run-results",
+    default=None,
+    help=(
+        "Path to run_results.json for the Health Check (default: <target_dir>/run_results.json)."
+    ),
+)
 @click.pass_obj
-def generate(config: DbDocsConfig, output_dir, dialect):
-    """Build the self-contained site from dbt artifacts."""
+def generate(config: DbDocsConfig, output_dir, dialect, run_results):
+    """Build the site from dbt artifacts (served over HTTP; data loaded externally)."""
     if dialect is not None:
         config.dialect = dialect
+    if run_results is not None:
+        config.run_results = run_results
     try:
-        out = ReportBuilder(config).generate(output_dir=output_dir)
+        ReportBuilder(config).generate(output_dir=output_dir)
     except DbDocsError as exc:
         raise click.ClickException(str(exc)) from exc
-    click.echo(f"Generated site into {out}")
+    # The builder already logs "Generated site at <path> (N nodes, M edges)".
 
 
 @dbdocs.command(name="serve")

{dbdocs-1.0.2 → dbdocs-1.2.0}/dbdocs/core/config.py

@@ -49,6 +49,13 @@ class DbDocsConfig:
     #: Project README rendered on the overview (relative to the working dir). Set
     #: empty to omit the README section. Missing file ⇒ section simply absent.
     readme: str = "README.md"
+    #: Custom header logo (path relative to the working dir). Empty ⇒ the bundled
+    #: default mark. A missing file or a path escaping the cwd is ignored
+    #: (fail-soft, like ``readme``) ⇒ the default mark.
+    logo: str = ""
+    #: Custom favicon (path relative to the working dir). Empty ⇒ the bundled
+    #: default favicon. Same fail-soft handling as ``logo``.
+    favicon: str = ""
     target_dir: str = "target"
     #: Where the generated site is written. Nested under the dbt ``target/`` by
     #: default so docs sit alongside the artifacts they're built from.
@@ -62,6 +69,18 @@ class DbDocsConfig:
     #: ``resource_type``, …) passed straight to ``DbtErd``. Configured here so the
     #: ERD shape lives in ``dbdocs.yml`` rather than a separate ``.dbterd.yml``.
     dbterd: dict = field(default_factory=dict)
+    #: Path to the ``run_results.json`` parsed for the Health Check (always on).
+    #: If ``None`` (the default), ``<target_dir>/run_results.json`` is used. A
+    #: relative path is resolved against the cwd; a path that escapes the cwd is
+    #: silently ignored (fail-soft, like ``readme`` / ``logo``). When the file is
+    #: absent the Health Check page is simply empty.
+    run_results: "str | None" = None
+    #: Health Check rule engine config (all optional):
+    #: ``thresholds`` (e.g. ``model_fanout: 5``), ``disable`` (rule names to skip),
+    #: ``disable_dimensions`` (whole dimensions to skip), and ``rules_module`` (a
+    #: dotted import path whose ``register_rule`` calls add custom rules). Entry
+    #: points under ``dbdocs.health_rules`` are also discovered automatically.
+    health: dict = field(default_factory=dict)
 
     @classmethod
     def load(cls, path: "str | Path | None" = None) -> "DbDocsConfig":
@@ -92,6 +111,8 @@ class DbDocsConfig:
         return cls(**raw)
 
     #: Build-control fields that are not part of the site's display metadata.
+    #: ``logo``/``favicon`` are excluded too — they're *source* paths; the builder
+    #: copies the files into the output and injects their *deployed* asset URLs.
     _NON_METADATA_FIELDS = (
         "target_dir",
         "output_dir",
@@ -99,6 +120,10 @@ class DbDocsConfig:
         "default_version",
         "dbterd",
         "readme",
+        "logo",
+        "favicon",
+        "run_results",
+        "health",
     )
 
     def render_context(self) -> dict:

{dbdocs-1.0.2 → dbdocs-1.2.0}/dbdocs/extract/column_lineage.py

@@ -12,6 +12,7 @@ must never sink the whole ``generate`` — it's caught, logged, and skipped, and
 the run reports how many were skipped.
 """
 
+from concurrent.futures import ProcessPoolExecutor
 from typing import Any
 
 from sqlglot import exp
@@ -27,6 +28,14 @@ _DIALECT_ALIASES = {
     "databricks": "spark",
 }
 
+#: Parse + qualify is CPU-bound and embarrassingly parallel across models. Below
+#: this model count the ProcessPoolExecutor's spawn + pickle overhead outweighs
+#: the win, so we stay serial; at or above it we fan out across cores.
+_PARALLEL_THRESHOLD = 500
+
+#: Errors a single model's lineage may raise that must not sink the whole run.
+_MODEL_ERRORS = (SqlglotError, LineageError, KeyError, ValueError, RecursionError)
+
 
 def _to_dialect(adapter_type: "str | None") -> "str | None":
     if not adapter_type:
@@ -34,6 +43,95 @@ def _to_dialect(adapter_type: "str | None") -> "str | None":
     return _DIALECT_ALIASES.get(adapter_type, adapter_type)
 
 
+def _map_table(table: exp.Table, relation_to_node: dict) -> "str | None":
+    """Map a sqlglot ``Table`` to a dbt unique_id via the relation index."""
+    candidates = [
+        f"{table.catalog}.{table.db}.{table.name}",
+        f"{table.db}.{table.name}",
+        table.name,
+    ]
+    for candidate in candidates:
+        mapped = relation_to_node.get(candidate.lower().strip("."))
+        if mapped:
+            return mapped
+    return None
+
+
+def _leaf_columns(root: Node, relation_to_node: dict) -> list:
+    """Collect distinct upstream ``{node, column}`` leaves of a lineage tree.
+
+    A leaf is a node whose source is a real ``Table`` (not a CTE/subquery scope)
+    that maps back to a dbt node. The root itself is skipped.
+    """
+    seen = set()
+    upstream = []
+    for node in root.walk():
+        if node is root:
+            continue
+        source = node.source
+        if not isinstance(source, exp.Table):
+            continue
+        mapped = _map_table(source, relation_to_node)
+        if mapped is None:
+            continue
+        column = node_name(node.name)
+        key = (mapped, column)
+        if key in seen:
+            continue
+        seen.add(key)
+        upstream.append({"node": mapped, "column": column})
+    return upstream
+
+
+def _extract_model_columns(
+    unique_id: str,
+    compiled: str,
+    output_columns: list,
+    schema: dict,
+    dialect: "str | None",
+    relation_to_node: dict,
+) -> dict:
+    """Trace every output column of one model to its upstream columns.
+
+    Pure and picklable (plain str/list/dict args, no manifest/catalog objects) so
+    it runs unchanged in the serial loop or a ``ProcessPoolExecutor`` worker.
+    Builds the scope once per model — qualify is the expensive part and is
+    identical for every column — then traces each column against it.
+    """
+    out: dict = {}
+    scope = prepare_scope(compiled, schema=schema, dialect=dialect)
+    for column in output_columns:
+        try:
+            root = lineage(column, compiled, dialect=dialect, scope=scope)
+        except SqlglotError:
+            # One unresolvable column shouldn't drop the rest of the model.
+            continue
+        upstream = _leaf_columns(root, relation_to_node)
+        if upstream:
+            out[f"{unique_id}.{column}"] = upstream
+    return out
+
+
+def _extract_model_task(work: tuple) -> tuple:
+    """Worker wrapper: returns ``(unique_id, columns_map, error_str_or_None)``.
+
+    Catching here (rather than letting the exception cross the process boundary)
+    keeps the fail-soft contract: one unparseable model is reported and skipped,
+    never sinking the pool.
+    """
+    unique_id, compiled, output_columns, schema, dialect, relation_to_node = work
+    try:
+        return (
+            unique_id,
+            _extract_model_columns(
+                unique_id, compiled, output_columns, schema, dialect, relation_to_node
+            ),
+            None,
+        )
+    except _MODEL_ERRORS as exc:
+        return unique_id, {}, str(exc)
+
+
 class ColumnLineageExtractor:
     """Build the ``columnLineage`` map for a dbt project's models.
 
@@ -54,86 +152,74 @@ class ColumnLineageExtractor:
         self.skipped = 0
 
     def extract(self) -> dict:
-        """Return the ``columnLineage`` map across all models (fail-soft)."""
+        """Return the ``columnLineage`` map across all models (fail-soft).
+
+        Runs serially for small projects; fans the per-model sqlglot work across
+        processes once a project has ``_PARALLEL_THRESHOLD`` models or more, where
+        the CPU-bound parse/qualify dominates the pool's spawn cost.
+        """
+        work = self._work_items()
+        if not work:
+            return {}
+        if len(work) >= _PARALLEL_THRESHOLD:
+            results = self._extract_parallel(work)
+        else:
+            results = (_extract_model_task(item) for item in work)
+
         result: dict = {}
+        for unique_id, columns, error in results:
+            if error is not None:
+                self.skipped += 1
+                logger.warning("Column lineage skipped for %s: %s", node_name(unique_id), error)
+                continue
+            result.update(columns)
+        if self.skipped:
+            logger.info("Column lineage: skipped %s model(s) that failed to parse.", self.skipped)
+        return result
+
+    def _extract_parallel(self, work: list) -> list:
+        """Run the per-model tasks across a process pool, returning their results."""
+        with ProcessPoolExecutor() as pool:
+            return list(pool.map(_extract_model_task, work))
+
+    def _work_items(self) -> list:
+        """Build the picklable per-model work tuples for the (serial or pool) run.
+
+        Each item is ``(unique_id, compiled, output_columns, schema, dialect,
+        relation_to_node)`` — all plain str/list/dict, so it crosses a process
+        boundary cleanly (the Pydantic manifest/catalog never do).
+        """
+        work = []
         for unique_id, model in (getattr(self.manifest, "nodes", {}) or {}).items():
             if not str(unique_id).startswith("model."):
                 continue
             compiled = getattr(model, "compiled_code", "") or ""
             if not compiled.strip():
                 continue
-            try:
-                self._extract_model(unique_id, compiled, result)
-            except (SqlglotError, LineageError, KeyError, ValueError, RecursionError) as exc:
-                self.skipped += 1
-                logger.warning("Column lineage skipped for %s: %s", node_name(unique_id), exc)
-        if self.skipped:
-            logger.info("Column lineage: skipped %s model(s) that failed to parse.", self.skipped)
-        return result
+            output_columns = self._output_columns(unique_id, model)
+            if not output_columns:
+                continue
+            work.append(
+                (
+                    unique_id,
+                    compiled,
+                    output_columns,
+                    self.schema,
+                    self.dialect,
+                    self._relation_to_node,
+                )
+            )
+        return work
 
-    def _extract_model(self, unique_id: str, compiled: str, result: dict) -> None:
-        node = self.manifest.nodes[unique_id]
-        output_columns = [c for c in (getattr(node, "columns", {}) or {})]
-        # Fall back to the catalog's column list when the manifest has none.
+    def _output_columns(self, unique_id: str, model: Any) -> list:
+        """The model's documented columns, falling back to the catalog's list."""
+        output_columns = [c for c in (getattr(model, "columns", {}) or {})]
         if not output_columns:
             catalog_node = (getattr(self.catalog, "nodes", {}) or {}).get(unique_id)
             output_columns = (
                 list(getattr(catalog_node, "columns", {}) or {}) if catalog_node else []
             )
-        if not output_columns:
-            return
-        # Build the scope once per model, then trace each column against it —
-        # qualify is the expensive part and is identical for every column.
-        scope = prepare_scope(compiled, schema=self.schema, dialect=self.dialect)
-        for column in output_columns:
-            try:
-                root = lineage(column, compiled, dialect=self.dialect, scope=scope)
-            except SqlglotError:
-                # One unresolvable column shouldn't drop the rest of the model.
-                continue
-            upstream = self._leaf_columns(root)
-            if upstream:
-                result[f"{unique_id}.{column}"] = upstream
-
-    def _leaf_columns(self, root: Node) -> list:
-        """Collect distinct upstream ``{node, column}`` leaves of a lineage tree.
-
-        A leaf is a node whose source is a real ``Table`` (not a CTE/subquery
-        scope) that we can map back to a dbt node. The root itself is skipped.
-        """
-        seen = set()
-        upstream = []
-        for node in root.walk():
-            if node is root:
-                continue
-            source = node.source
-            if not isinstance(source, exp.Table):
-                continue
-            mapped = self._map_table(source)
-            if mapped is None:
-                continue
-            column = node_name(node.name)
-            key = (mapped, column)
-            if key in seen:
-                continue
-            seen.add(key)
-            upstream.append({"node": mapped, "column": column})
-        return upstream
-
-    def _map_table(self, table: exp.Table) -> "str | None":
-        catalog = table.catalog
-        db = table.db
-        name = table.name
-        candidates = [
-            f"{catalog}.{db}.{name}",
-            f"{db}.{name}",
-            name,
-        ]
-        for candidate in candidates:
-            mapped = self._relation_to_node.get(candidate.lower().strip("."))
-            if mapped:
-                return mapped
-        return None
+        return output_columns
 
     def _relation_index(self) -> dict:
         """Map ``db.schema.table`` (and shorter forms) → dbt unique_id."""

{dbdocs-1.0.2 → dbdocs-1.2.0}/dbdocs/extract/erd.py

@@ -9,12 +9,21 @@ foreign-key edges between them, all keyed by dbt unique_id.
 
 import json
 
-from dbterd.api import DbtErd
+from dbterd.api import DbtErd, default
 
 # Importing the module registers the "json" target with dbterd's PluginRegistry.
 from dbdocs.extract import erd_json  # noqa: F401
 
 
+def erd_algo(dbterd_options: "dict | None" = None) -> str:
+    """The dbterd algorithm that detected the ERD relationships.
+
+    Reads the configured ``algo`` from the ``dbterd:`` block, falling back to
+    dbterd's own default. Surfaced into the SPA so it can explain an empty ERD.
+    """
+    return (dbterd_options or {}).get("algo") or default.default_algo()
+
+
 def build_erd(dbterd_options: "dict | None" = None, artifacts_dir: "str | None" = None) -> DbtErd:
     """Build the ERD generator (json target) from dbdocs' ``dbterd`` options.
 

dbdocs-1.2.0/dbdocs/extract/health/__init__.py

@@ -0,0 +1,12 @@
+"""Project Health Check — the six dbt-project-evaluator dimensions.
+
+The public entry point is :class:`HealthCheckExtractor`, which composes the
+manifest-derived rule engine (:mod:`dbdocs.extract.health.dimensions` +
+:mod:`dbdocs.extract.health.rules`) with the optional ``run_results.json``
+per-test detail.  Custom rules can be registered via
+:func:`dbdocs.extract.health.rules.register_rule` (see the plugin docs).
+"""
+
+from dbdocs.extract.health.extractor import HealthCheckExtractor
+
+__all__ = ["HealthCheckExtractor"]