dbdocs 1.1.0__tar.gz → 1.2.0__tar.gz

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.1.0 → 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):
+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.1.0 → dbdocs-1.2.0}/dbdocs/core/config.py

@@ -69,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":
@@ -110,6 +122,8 @@ class DbDocsConfig:
         "readme",
         "logo",
         "favicon",
+        "run_results",
+        "health",
     )
 
     def render_context(self) -> dict:

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"]

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

@@ -0,0 +1,262 @@
+"""Build the manifest-derived health *dimensions* (the DPE rule engine's host).
+
+``ManifestGraph`` indexes the dbt manifest once — parents/children adjacency,
+plus layer / materialization / access / contract helpers — and the rule functions
+in :mod:`dbdocs.extract.health.rules` run against it. ``DimensionAnalyzer.analyze()``
+runs every rule, groups findings by dimension, and returns the ``dimensions``
+block of the health data dict:
+
+    {
+      "modeling":      {"issues": N, "checked": M, "findings": [...]},
+      "documentation": {...}, "structure": {...}, "performance": {...},
+      "governance":    {...},
+    }
+
+``checked`` is how many nodes the dimension's rules could apply to (models for
+most, models+sources for some) — it gives the SPA a denominator for a score.
+Everything is pure + DOM-free; a malformed/empty manifest yields empty dimensions
+rather than raising (the caller, ``HealthCheckExtractor``, is fail-soft).
+"""
+
+from typing import Any
+
+from dbdocs.core.log import logger
+from dbdocs.extract.health.rules import (
+    DEFAULT_THRESHOLDS,
+    DIMENSION_RULES,
+    NON_PHYSICAL,
+    load_entry_point_rules,
+    load_rules_module,
+)
+
+
+class ManifestGraph:
+    """Adjacency + node metadata over a dbt manifest, for the health rules.
+
+    Wraps the dbterd-parsed manifest: ``models``/``sources``/``exposures`` lists,
+    a ``parents``/``children`` adjacency built from each node's ``depends_on``, and
+    accessors that smooth over where dbt stores a field (``config.materialized``
+    vs node, ``config.access`` vs node, ``schema_`` alias, …).
+    """
+
+    def __init__(self, manifest: "Any | None", thresholds: "dict | None" = None) -> None:
+        nodes = getattr(manifest, "nodes", None)
+        self._nodes: dict = nodes if isinstance(nodes, dict) else {}
+        sources = getattr(manifest, "sources", None)
+        self._sources: dict = sources if isinstance(sources, dict) else {}
+        exposures = getattr(manifest, "exposures", None)
+        self._exposures: dict = exposures if isinstance(exposures, dict) else {}
+
+        self.models = [n for uid, n in self._nodes.items() if uid.startswith("model.")]
+        self.sources = list(self._sources.values())
+        self.exposures = list(self._exposures.values())
+
+        # Rule thresholds: per-run overrides layered over the DPE defaults.
+        self._thresholds = {**DEFAULT_THRESHOLDS, **(thresholds or {})}
+
+        self._parents: dict[str, list[str]] = {}
+        self._children: dict[str, list[str]] = {}
+        self._build_adjacency()
+
+        self._tests_by_model: dict[str, set] = {}
+        self._index_tests()
+
+        # Memo for non_physical_chain_depth (O(nodes) across the whole pass).
+        self._chain_cache: dict[str, int] = {}
+
+    def threshold(self, name: str) -> "int | float":
+        """The configured threshold for *name* (DPE default when unset)."""
+        return self._thresholds[name]
+
+    def _build_adjacency(self) -> None:
+        """Index parent/child edges from every node + exposure ``depends_on.nodes``."""
+        everything = list(self._nodes.values()) + self.exposures
+        for node in everything:
+            uid = str(getattr(node, "unique_id", "") or "")
+            if not uid:
+                continue
+            depends_on = getattr(node, "depends_on", None)
+            parents = list(getattr(depends_on, "nodes", None) or [])
+            self._parents[uid] = parents
+            for parent in parents:
+                self._children.setdefault(parent, []).append(uid)
+
+    def _index_tests(self) -> None:
+        """Map each tested node to the set of test types attached to it."""
+        for uid, node in self._nodes.items():
+            if not uid.startswith("test."):
+                continue
+            attached = str(getattr(node, "attached_node", "") or "")
+            if not attached:
+                continue
+            metadata = getattr(node, "test_metadata", None)
+            test_type = str(getattr(metadata, "name", "") or "") if metadata else "singular"
+            self._tests_by_model.setdefault(attached, set()).add(test_type)
+
+    def tests_for(self, unique_id: str) -> set:
+        """The set of test types attached to *unique_id* (empty if untested)."""
+        return self._tests_by_model.get(unique_id, set())
+
+    # -- adjacency -----------------------------------------------------------
+
+    def parents(self, unique_id: str) -> "list[str]":
+        return self._parents.get(unique_id, [])
+
+    def children(self, unique_id: str) -> "list[str]":
+        return self._children.get(unique_id, [])
+
+    def node(self, unique_id: str) -> "Any | None":
+        """The node object for *unique_id* (model/seed/snapshot or source)."""
+        return self._nodes.get(unique_id) or self._sources.get(unique_id)
+
+    # -- node metadata -------------------------------------------------------
+
+    @staticmethod
+    def layer(model: Any) -> str:
+        """The model's layer (staging/intermediate/marts/other) from its ``fqn``.
+
+        dbt's ``fqn`` is ``[package, ...folders, name]`` — the folder segments name
+        the layer. We match the known layer folders anywhere in the fqn so a
+        ``marts/finance/`` nesting still resolves to ``marts``.
+        """
+        fqn = [str(p).lower() for p in (getattr(model, "fqn", None) or [])]
+        for layer in ("staging", "intermediate", "marts"):
+            if layer in fqn:
+                return layer
+        # dbt also uses "stg"/"int"/"core"/"mart" folder spellings; map the common ones.
+        if "stg" in fqn:
+            return "staging"
+        if "int" in fqn:
+            return "intermediate"
+        if "mart" in fqn or "marts" in fqn:
+            return "marts"
+        return "other"
+
+    @staticmethod
+    def materialization(node: Any) -> str:
+        """The node's materialization (``config.materialized``), lowercased."""
+        config = getattr(node, "config", None)
+        materialized = getattr(config, "materialized", None) if config else None
+        return str(materialized or "").lower()
+
+    @staticmethod
+    def access(model: Any) -> str:
+        """The model's access level (``config.access`` or node ``access``)."""
+        config = getattr(model, "config", None)
+        access = getattr(config, "access", None) if config else None
+        access = access or getattr(model, "access", None)
+        return str(access or "protected").lower()
+
+    @staticmethod
+    def contract_enforced(model: Any) -> bool:
+        """Whether the model has an enforced contract (``contract.enforced``)."""
+        contract = getattr(model, "contract", None)
+        return bool(getattr(contract, "enforced", False)) if contract else False
+
+    def non_physical_chain_depth(self, unique_id: str) -> int:
+        """Longest chain of consecutive non-physical (view/ephemeral) ancestors + self.
+
+        Counts this model plus the longest run of view/ephemeral models directly
+        upstream; a table/source ancestor (or a model boundary) stops the chain.
+        Mirrors DPE's ``chained_view_dependencies`` distance.
+
+        Iterative + memoized: depth is computed once per node and cached on the
+        graph (``_chain_cache``), so the whole pass is ``O(nodes)`` even on a
+        3000-deep view chain — recursion here would blow Python's stack limit and
+        be ``O(nodes²)``.
+        """
+        cache = self._chain_cache
+        if unique_id in cache:
+            return cache[unique_id]
+        # Post-order DFS via an explicit stack: push a node, then its unresolved
+        # non-physical parents; resolve a node once all its parents are cached.
+        stack = [unique_id]
+        on_stack = {unique_id}
+        while stack:
+            uid = stack[-1]
+            node = self._nodes.get(uid)
+            if node is None or self.materialization(node) not in NON_PHYSICAL:
+                cache[uid] = 0
+                stack.pop()
+                on_stack.discard(uid)
+                continue
+            best = 0
+            pending = None
+            for parent in self.parents(uid):
+                if parent in cache:
+                    best = max(best, cache[parent])
+                elif parent not in on_stack:  # unresolved, not already in progress
+                    pending = parent
+                    break
+                # parent in on_stack ⇒ a cycle; treat as a stop (contributes 0)
+            if pending is not None:
+                stack.append(pending)
+                on_stack.add(pending)
+                continue
+            cache[uid] = 1 + best
+            stack.pop()
+            on_stack.discard(uid)
+        return cache[unique_id]
+
+
+class DimensionAnalyzer:
+    """Run every manifest-derived health rule and group findings by dimension.
+
+    *config* is the optional ``health`` block from ``dbdocs.yml``:
+    ``thresholds`` (per-rule overrides), ``disable`` (rule names to skip),
+    ``disable_dimensions`` (whole dimensions to skip), and ``rules_module`` (a
+    dotted path whose ``register_rule`` calls add custom rules). Entry-point
+    plugins under ``dbdocs.health_rules`` are always discovered.
+    """
+
+    def __init__(self, manifest: "Any | None", config: "dict | None" = None) -> None:
+        config = config or {}
+        thresholds = config.get("thresholds") if isinstance(config.get("thresholds"), dict) else {}
+        self._graph = ManifestGraph(manifest, thresholds=thresholds)
+        self._disabled_rules = set(config.get("disable") or [])
+        self._disabled_dimensions = set(config.get("disable_dimensions") or [])
+
+        # Plugin loading: entry points always; an explicit rules_module on request.
+        load_entry_point_rules()
+        rules_module = config.get("rules_module")
+        if rules_module:
+            load_rules_module(str(rules_module))
+
+    def analyze(self) -> dict:
+        """Return the ``dimensions`` block: one entry per (enabled) dimension."""
+        graph = self._graph
+        model_count = len(graph.models)
+        source_count = len(graph.sources)
+        dimensions: dict = {}
+        for dimension, rules in DIMENSION_RULES.items():
+            if dimension in self._disabled_dimensions:
+                continue
+            findings: list = []
+            for rule in rules:
+                if getattr(rule, "__name__", "") in self._disabled_rules:
+                    continue
+                try:
+                    findings.extend(rule(graph))
+                except (AttributeError, TypeError, ValueError, KeyError, RecursionError) as exc:
+                    # A single malformed node / bad plugin must never sink the report.
+                    logger.warning(
+                        "Health dimension %s: rule %s failed: %s — skipping.",
+                        dimension,
+                        getattr(rule, "__name__", rule),
+                        exc,
+                    )
+            dimensions[dimension] = {
+                "issues": len(findings),
+                "checked": self._checked(dimension, model_count, source_count),
+                "findings": findings,
+            }
+        return dimensions
+
+    @staticmethod
+    def _checked(dimension: str, model_count: int, source_count: int) -> int:
+        """How many nodes a dimension's rules could apply to (the score denominator)."""
+        # Modeling/documentation/structure span models + sources; performance and
+        # governance are model/exposure-centric — count models as the denominator.
+        if dimension in ("modeling", "documentation", "structure"):
+            return model_count + source_count
+        return model_count