dbdocs 1.1.0__tar.gz → 1.3.0__tar.gz

{dbdocs-1.1.0 → dbdocs-1.3.0}/.gitignore

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

{dbdocs-1.1.0 → dbdocs-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbdocs
-Version: 1.1.0
+Version: 1.3.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
@@ -14,8 +14,10 @@ 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.26
+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
@@ -24,7 +26,7 @@ Description-Content-Type: text/markdown
   <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, baked into one file.</b></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>
@@ -35,11 +37,26 @@ Description-Content-Type: text/markdown
   <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 single self-contained `index.html`: a browsable catalog, an interactive lineage DAG and ERD, and **column-level lineage** from your compiled SQL. No server, no database, no build step — just a file you can open or host anywhere.
+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 |
-|---|---|---|
-| ![catalog](docs/assets/img/demo-catalog.png) | ![model page](docs/assets/img/demo-model-page.png) | ![dag](docs/assets/img/demo-model-dag.png) |
+| 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 stop short of telling you *which upstream column fed this downstream column*, *which tables relate to each other*, or *what changed between builds*. dbdocs fills those gaps — no documentation framework or separate ERD tool to install.
+
+- **ERD + column-level lineage** — table relationships ([dbterd](https://github.com/datnguye/dbterd)) and column lineage from compiled SQL ([sqlglot](https://github.com/tobymao/sqlglot)).
+- **Column impact analysis** — downstream dependents for any column.
+- **Deep-link URLs** for every node, column, and DAG view.
+- **Any sqlglot dialect**, auto-detected from your manifest.
+- **Scales to 1 000s of models** without freezing the browser.
+- **Fail-soft** — an unparseable model is skipped, not fatal.
+- **Project Health Check** across the six [dbt-project-evaluator](https://dbt-labs.github.io/dbt-project-evaluator/) dimensions.
+- **Versioned deploys** with a built-in version switcher, no plugins.
+- **Full-text search** across names, columns, descriptions, tags, and SQL at the client-side, no backend.
+- **Dark / light theme.**
 
 ## Install
 
@@ -53,17 +70,13 @@ Requires Python 3.10+.
 
 ```bash
 dbt docs generate     # writes target/manifest.json + target/catalog.json
-dbdocs generate       # builds ./site/index.html with all data baked in
+dbdocs generate       # builds ./site/ with index.html + dbdocs-data.json.gz
 dbdocs serve          # static http server on http://127.0.0.1:8000
 ```
 
-Full walkthrough, configuration, and architecture live in the **[documentation](https://dbdocs.datnguye.me/)**.
+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.
 
-## Why dbdocs?
-
-dbt's own docs are great until you want lineage at the *column* level — that's the gap this fills. Everything is derived from your dbt `manifest.json` / `catalog.json` and baked into one offline-friendly SPA: catalog navigation grouped by database/schema, per-model SQL and columns, interactive React Flow graphs, column-level lineage via sqlglot, client-side search, a dark/light theme, and versioned deploys with a built-in version switcher.
-
-See the [docs](https://dbdocs.datnguye.me/) for the deep dives.
+Full walkthrough, configuration, and architecture live in the **[documentation](https://dbdocs.datnguye.me/)**.
 
 ## Contributing
 

{dbdocs-1.1.0 → dbdocs-1.3.0}/README.md

@@ -2,7 +2,7 @@
   <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, baked into one file.</b></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>
@@ -13,11 +13,26 @@
   <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 single self-contained `index.html`: a browsable catalog, an interactive lineage DAG and ERD, and **column-level lineage** from your compiled SQL. No server, no database, no build step — just a file you can open or host anywhere.
+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 |
-|---|---|---|
-| ![catalog](docs/assets/img/demo-catalog.png) | ![model page](docs/assets/img/demo-model-page.png) | ![dag](docs/assets/img/demo-model-dag.png) |
+| 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 stop short of telling you *which upstream column fed this downstream column*, *which tables relate to each other*, or *what changed between builds*. dbdocs fills those gaps — no documentation framework or separate ERD tool to install.
+
+- **ERD + column-level lineage** — table relationships ([dbterd](https://github.com/datnguye/dbterd)) and column lineage from compiled SQL ([sqlglot](https://github.com/tobymao/sqlglot)).
+- **Column impact analysis** — downstream dependents for any column.
+- **Deep-link URLs** for every node, column, and DAG view.
+- **Any sqlglot dialect**, auto-detected from your manifest.
+- **Scales to 1 000s of models** without freezing the browser.
+- **Fail-soft** — an unparseable model is skipped, not fatal.
+- **Project Health Check** across the six [dbt-project-evaluator](https://dbt-labs.github.io/dbt-project-evaluator/) dimensions.
+- **Versioned deploys** with a built-in version switcher, no plugins.
+- **Full-text search** across names, columns, descriptions, tags, and SQL at the client-side, no backend.
+- **Dark / light theme.**
 
 ## Install
 
@@ -31,17 +46,13 @@ Requires Python 3.10+.
 
 ```bash
 dbt docs generate     # writes target/manifest.json + target/catalog.json
-dbdocs generate       # builds ./site/index.html with all data baked in
+dbdocs generate       # builds ./site/ with index.html + dbdocs-data.json.gz
 dbdocs serve          # static http server on http://127.0.0.1:8000
 ```
 
-Full walkthrough, configuration, and architecture live in the **[documentation](https://dbdocs.datnguye.me/)**.
+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.
 
-## Why dbdocs?
-
-dbt's own docs are great until you want lineage at the *column* level — that's the gap this fills. Everything is derived from your dbt `manifest.json` / `catalog.json` and baked into one offline-friendly SPA: catalog navigation grouped by database/schema, per-model SQL and columns, interactive React Flow graphs, column-level lineage via sqlglot, client-side search, a dark/light theme, and versioned deploys with a built-in version switcher.
-
-See the [docs](https://dbdocs.datnguye.me/) for the deep dives.
+Full walkthrough, configuration, and architecture live in the **[documentation](https://dbdocs.datnguye.me/)**.
 
 ## Contributing
 

{dbdocs-1.1.0 → dbdocs-1.3.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.3.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.3.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.3.0/dbdocs/extract/health/dimensions.py

@@ -0,0 +1,284 @@
+"""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())
+        # Singular tests are custom-SQL test nodes (no test_metadata); generic
+        # tests (unique/not_null/…) carry test_metadata and are excluded.
+        self.singular_tests = [
+            n
+            for uid, n in self._nodes.items()
+            if uid.startswith("test.") and getattr(n, "test_metadata", None) is None
+        ]
+
+        # 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 has_source_freshness(source: Any) -> bool:
+        """Whether a source has a freshness check: a ``loaded_at_field`` plus a
+        ``warn_after``/``error_after`` threshold count."""
+        if not str(getattr(source, "loaded_at_field", "") or "").strip():
+            return False
+        freshness = getattr(source, "freshness", None)
+        if freshness is None:
+            return False
+        for bound in ("warn_after", "error_after"):
+            period = getattr(freshness, bound, None)
+            if period is not None and getattr(period, "count", None) is not None:
+                return True
+        return False
+
+    @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