dbdocs 1.2.0__tar.gz → 1.4.0__tar.gz

{dbdocs-1.2.0 → dbdocs-1.4.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.2.0 → dbdocs-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbdocs
-Version: 1.2.0
+Version: 1.4.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
@@ -16,7 +16,7 @@ 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: dbterd>=1.28
 Requires-Dist: pydantic>=2.13.4
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: sqlglot>=25
@@ -45,19 +45,17 @@ Turn your dbt artifacts into a self-contained docs site: a browsable catalog, an
 
 ## 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.
+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

dbdocs-1.4.0/README.md

@@ -0,0 +1,67 @@
+<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 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
+
+```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.4.0/dbdocs/extract/erd.py

@@ -0,0 +1,150 @@
+"""Structured ERD data via dbterd's official ``json`` target.
+
+dbterd 1.28.0 ships a built-in, schema-validated ``json`` target that emits
+``{nodes, edges, metadata}``. Each node carries ``id`` (the dbt unique_id),
+``name``, ``schema_name``, ``database``, ``resource_type``, and ``columns``
+(with ``data_type``, ``is_primary_key``, ``is_foreign_key``). Each edge carries
+``id``, ``from_id`` (FK/child side), ``to_id`` (referenced/parent side),
+``from_columns``, ``to_columns``, ``label``, and ``cardinality``.
+
+``build_erd_data`` maps that shape into the SPA's ``{nodes, edges}`` — the
+React Flow bundle reads ``nodes`` (entities + column flags) and ``edges``
+(FK relationships, ``source``/``target`` keyed by dbt unique_id).
+"""
+
+import json
+
+from dbterd.api import DbtErd, default
+
+
+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.
+
+    ``dbterd_options`` is the ``dbterd:`` block of ``dbdocs.yml`` (``algo``,
+    ``entity_name_format``, ``resource_type``, ``select``, …) passed straight to
+    ``DbtErd``. We force ``target="json"`` — the SPA needs structured data — but
+    let everything else come from the project's config so the ERD matches what
+    the team configured. (Config lives in ``dbdocs.yml``, not a separate
+    ``.dbterd.yml``.)
+
+    ``artifacts_dir`` is the dbt target dir (``config.target_dir``). dbterd reads
+    the manifest/catalog directly from this dir; without it dbterd would default
+    to ``./target`` and ignore the configured ``target_dir``. An explicit
+    ``artifacts_dir`` in ``dbterd_options`` still wins.
+    """
+    dbterd_kwargs = {k: v for k, v in (dbterd_options or {}).items() if k != "target"}
+    if artifacts_dir is not None:
+        dbterd_kwargs.setdefault("artifacts_dir", artifacts_dir)
+    return DbtErd(target="json", **dbterd_kwargs)
+
+
+def build_erd_data(erd: DbtErd) -> dict:
+    """Parse dbterd's official ``{nodes, edges}`` payload into the SPA shape.
+
+    dbterd's ``json`` target emits nodes keyed by dbt unique_id (``id`` field).
+    When ``entity_name_format`` is configured, dbterd emits edge ``from_id`` /
+    ``to_id`` as the formatted entity name (e.g. ``orders``) rather than the
+    full unique_id (e.g. ``model.jaffle_shop.orders``). A ``name_to_id`` map
+    resolves those short names back to the node id before building edges, so the
+    SPA's ``source``/``target`` always reference a valid node ``id``.
+
+    Some dbterd algos (e.g. ``model_contract``) do not set ``is_foreign_key``
+    on node columns even when those columns appear in FK edges. After building
+    edges, any column named in an edge's ``from_columns`` (the FK/child side)
+    has its ``is_foreign_key`` flag back-filled to ``True`` on the target node.
+
+    SPA edge direction: ``source`` is the referenced (parent) side, ``target``
+    is the FK (child) side — matching dbterd's ``to_id`` and ``from_id``
+    respectively.
+    """
+    payload = json.loads(erd.get_erd())
+    raw_nodes = payload.get("nodes", [])
+    raw_edges = payload.get("edges", [])
+    nodes = [_build_node(n) for n in raw_nodes]
+    node_ids = {n["id"] for n in nodes}
+    # Count occurrences first; ambiguous names (more than one node) are excluded
+    # so a collision can't silently resolve to the wrong node.
+    name_counts: dict[str, int] = {}
+    for n in raw_nodes:
+        nm = n.get("name")
+        if nm:
+            name_counts[nm] = name_counts.get(nm, 0) + 1
+    name_to_id = {
+        n.get("name"): n["id"]
+        for n in raw_nodes
+        if n.get("name") and name_counts[n.get("name")] == 1
+    }
+    edges = [_build_edge(e, i, node_ids, name_to_id) for i, e in enumerate(raw_edges)]
+    _backfill_fk_flags(nodes, edges)
+    return {"nodes": nodes, "edges": edges}
+
+
+def _backfill_fk_flags(nodes: "list[dict]", edges: "list[dict]") -> None:
+    """Set is_foreign_key=True on columns named in each edge's from_columns.
+
+    Keyed by node id so the lookup is O(1) per column per edge.
+    """
+    nodes_by_id = {n["id"]: n for n in nodes}
+    for edge in edges:
+        target_node = nodes_by_id.get(edge["target"])
+        if target_node is None:
+            continue
+        fk_cols = {c.lower() for c in edge.get("from_columns", [])}
+        if not fk_cols:
+            continue
+        for col in target_node["columns"]:
+            if col["name"].lower() in fk_cols:
+                col["is_foreign_key"] = True
+
+
+def _build_node(node: dict) -> dict:
+    return {
+        "id": node["id"],
+        "label": node.get("name") or "",
+        "database": node.get("database") or "",
+        "schema": node.get("schema_name") or "",
+        "resource_type": node.get("resource_type") or "model",
+        "columns": [
+            {
+                "name": c["name"],
+                "type": c.get("data_type") or "",
+                "description": c.get("description") or "",
+                "is_primary_key": bool(c.get("is_primary_key")),
+                "is_foreign_key": bool(c.get("is_foreign_key")),
+            }
+            for c in node.get("columns", [])
+        ],
+    }
+
+
+def _resolve_edge_id(raw: str, node_ids: "set[str]", name_to_id: "dict[str, str]") -> str:
+    # If raw is already a valid node id, keep it (the no-entity_name_format case).
+    # Otherwise resolve through the name→id map built from node labels.
+    if raw in node_ids:
+        return raw
+    return name_to_id.get(raw, raw)
+
+
+def _build_edge(edge: dict, index: int, node_ids: "set[str]", name_to_id: "dict[str, str]") -> dict:
+    # from_id is the FK/child side; to_id is the referenced/parent side.
+    # SPA convention: source = parent (to_id), target = child (from_id).
+    raw_from = edge.get("from_id") or ""
+    raw_to = edge.get("to_id") or ""
+    return {
+        "id": edge.get("id") or f"e{index}",
+        "source": _resolve_edge_id(raw_to, node_ids, name_to_id),
+        "target": _resolve_edge_id(raw_from, node_ids, name_to_id),
+        "from_columns": edge.get("from_columns") or [],
+        "to_columns": edge.get("to_columns") or [],
+        "label": edge.get("label") or "",
+        "type": edge.get("cardinality") or "",
+    }

{dbdocs-1.2.0 → dbdocs-1.4.0}/dbdocs/extract/health/dimensions.py

@@ -50,6 +50,13 @@ class ManifestGraph:
         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 {})}
@@ -147,6 +154,21 @@ class ManifestGraph:
         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``)."""

{dbdocs-1.2.0 → dbdocs-1.4.0}/dbdocs/extract/health/rules/__init__.py

@@ -24,6 +24,7 @@ of :mod:`base` and :mod:`registry`; no implementation lives here.
 
 from dbdocs.extract.health.rules.base import DEFAULT_THRESHOLDS, NON_PHYSICAL, docs_url, finding
 from dbdocs.extract.health.rules.dimensions.documentation import (
+    documentation_coverage,
     undocumented_models,
     undocumented_source_tables,
     undocumented_sources,
@@ -35,7 +36,9 @@ from dbdocs.extract.health.rules.dimensions.governance import (
 )
 from dbdocs.extract.health.rules.dimensions.modeling import (
     direct_join_to_source,
+    downstream_models_dependent_on_source,
     duplicate_sources,
+    hard_coded_references,
     model_fanout,
     multiple_sources_joined,
     rejoining_of_upstream_concepts,
@@ -54,8 +57,13 @@ from dbdocs.extract.health.rules.dimensions.structure import (
     model_directories,
     model_naming_conventions,
     source_directories,
+    test_directories,
+)
+from dbdocs.extract.health.rules.dimensions.testing import (
+    missing_primary_key_tests,
+    missing_source_freshness,
+    test_coverage,
 )
-from dbdocs.extract.health.rules.dimensions.testing import missing_primary_key_tests, test_coverage
 from dbdocs.extract.health.rules.registry import (
     DIMENSION_RULES,
     ENTRY_POINT_GROUP,
@@ -81,8 +89,11 @@ __all__ = [
     # rule functions (re-exported for direct access / testing)
     "test_coverage",
     "missing_primary_key_tests",
+    "missing_source_freshness",
     "direct_join_to_source",
+    "downstream_models_dependent_on_source",
     "duplicate_sources",
+    "hard_coded_references",
     "model_fanout",
     "multiple_sources_joined",
     "rejoining_of_upstream_concepts",
@@ -92,12 +103,14 @@ __all__ = [
     "staging_dependent_on_marts_or_intermediate",
     "unused_sources",
     "too_many_joins",
+    "documentation_coverage",
     "undocumented_models",
     "undocumented_sources",
     "undocumented_source_tables",
     "model_naming_conventions",
     "model_directories",
     "source_directories",
+    "test_directories",
     "chained_view_dependencies",
     "exposure_parents_materializations",
     "public_models_without_contracts",

{dbdocs-1.2.0 → dbdocs-1.4.0}/dbdocs/extract/health/rules/base.py

@@ -14,6 +14,16 @@ DEFAULT_THRESHOLDS = {
     "model_fanout": 3,
     "too_many_joins": 7,
     "chained_view_dependencies": 4,
+    "documentation_coverage": 100,
+}
+
+# DPE anchors that don't equal the rule name kebab-cased. The auto-derived anchor
+# (``rule.replace("_", "-")``) is the DPE heading for most rules; these few have a
+# different published heading, so map the rule name to its real anchor explicitly.
+_RULE_ANCHORS = {
+    "too_many_joins": "models-with-too-many-joins",
+    "staging_dependent_on_marts_or_intermediate": "staging-models-dependent-on-downstream-models",
+    "staging_dependent_on_staging": "staging-models-dependent-on-other-staging-models",
 }
 
 # Materializations that are *not* a physical table (for chained-view detection).
@@ -28,8 +38,13 @@ LAYER_PREFIXES = {
 
 
 def docs_url(category: str, rule: str) -> str:
-    """The DPE docs URL for a rule under *category* (anchor = the rule name)."""
-    return f"{_RULES_BASE}/{category}/#{rule.replace('_', '-')}"
+    """The DPE docs URL for a rule under *category*.
+
+    The anchor is the rule name kebab-cased, except for the few rules whose DPE
+    heading differs (see ``_RULE_ANCHORS``).
+    """
+    anchor = _RULE_ANCHORS.get(rule, rule.replace("_", "-"))
+    return f"{_RULES_BASE}/{category}/#{anchor}"
 
 
 def finding(rule: str, category: str, node: str, node_type: str, message: str) -> dict:

{dbdocs-1.2.0 → dbdocs-1.4.0}/dbdocs/extract/health/rules/dimensions/documentation.py

@@ -54,6 +54,36 @@ def undocumented_sources(graph: "ManifestGraph") -> "list[dict]":
     return out
 
 
+def documentation_coverage(graph: "ManifestGraph") -> "list[dict]":
+    """One project-level finding when the share of documented models is below target.
+
+    Mirrors DPE's ``fct_documentation_coverage`` — an aggregate percentage rather
+    than a per-model flag. The ``documentation_coverage`` threshold (default 100)
+    is the minimum acceptable percentage; coverage at or above it is clean.
+
+    Being an aggregate, its finding's ``node`` is the pseudo-id ``"project"`` (not a
+    real ``unique_id``); the SPA renders an unresolvable node as plain text rather
+    than a node-page link, so this degrades gracefully.
+    """
+    models = graph.models
+    if not models:
+        return []
+    documented = sum(1 for m in models if str(getattr(m, "description", "") or "").strip())
+    coverage = round(documented * 100 / len(models), 1)
+    if coverage >= graph.threshold("documentation_coverage"):
+        return []
+    return [
+        finding(
+            "documentation_coverage",
+            "documentation",
+            "project",
+            "project",
+            f"Only {coverage}% of models are documented "
+            f"({documented}/{len(models)}) — below the configured target.",
+        )
+    ]
+
+
 def undocumented_source_tables(graph: "ManifestGraph") -> "list[dict]":
     """Source tables (the individual relations) with no description."""
     out = []

{dbdocs-1.2.0 → dbdocs-1.4.0}/dbdocs/extract/health/rules/dimensions/modeling.py

@@ -4,14 +4,29 @@ Each rule is ``(graph) -> list[dict]``; see ``dbdocs.extract.health.rules``
 for the shared finding shape and the registry that assembles these.
 """
 
+import re
 from typing import Any
 
+import sqlglot
+from sqlglot import exp
+from sqlglot.errors import SqlglotError
+from sqlglot.optimizer.scope import build_scope
+
 from dbdocs.extract.health.rules.base import finding
 
 # ``ManifestGraph`` annotations are strings (forward ref) to avoid a circular
 # import (rules ← graph ← analyzer); resolved lazily by the type checker only.
 ManifestGraph = Any
 
+# A ``{{ ref(...) }}`` / ``{{ source(...) }}`` call is rewritten to a uniquely
+# numbered sentinel table before parsing (``__dbt_ref_0__``, ``__dbt_ref_1__``, …)
+# — unique so sqlglot's scope analysis doesn't choke on a repeated alias — so any
+# *other* real table left in the SQL is a hard-coded relation. Any remaining
+# ``{{ ... }}`` macro is blanked so it doesn't masquerade as a table.
+_REF_SENTINEL_PREFIX = "__dbt_ref_"
+_REF_OR_SOURCE = re.compile(r"{{[-\s]*(?:ref|source)\s*\(.*?\)[-\s]*}}", re.IGNORECASE | re.DOTALL)
+_OTHER_JINJA = re.compile(r"{[{%].*?[%}]}", re.DOTALL)
+
 
 def direct_join_to_source(graph: "ManifestGraph") -> "list[dict]":
     """Models that ref a model AND a source in the same query (missing staging)."""
@@ -121,6 +136,87 @@ def rejoining_of_upstream_concepts(graph: "ManifestGraph") -> "list[dict]":
     return out
 
 
+def downstream_models_dependent_on_source(graph: "ManifestGraph") -> "list[dict]":
+    """Non-staging models that ref a source directly (only staging should touch sources)."""
+    out = []
+    for model in graph.models:
+        if graph.layer(model) == "staging":
+            continue
+        if any(p.startswith("source.") for p in graph.parents(model.unique_id)):
+            out.append(
+                finding(
+                    "downstream_models_dependent_on_source",
+                    "modeling",
+                    model.unique_id,
+                    "model",
+                    "A non-staging model selects from a source — route it through a staging model.",
+                )
+            )
+    return out
+
+
+def _number_refs(raw_code: str) -> str:
+    """Replace each ref()/source() jinja call with a uniquely numbered sentinel."""
+    out = []
+    last = 0
+    for index, match in enumerate(_REF_OR_SOURCE.finditer(raw_code)):
+        out.append(raw_code[last : match.start()])
+        out.append(f"{_REF_SENTINEL_PREFIX}{index}__")
+        last = match.end()
+    out.append(raw_code[last:])
+    return "".join(out)
+
+
+def _hard_coded_relations(raw_code: str) -> "list[str]":
+    """Real table names a model's raw SQL selects from outside ref()/source().
+
+    dbt references are jinja (``{{ ref(...) }}`` / ``{{ source(...) }}``), so they
+    are rewritten to uniquely numbered sentinel tables before parsing (so sqlglot's
+    scope analysis doesn't choke on a repeated alias); any other real table its
+    scope analysis finds is a hard-coded relation. CTEs are excluded by walking
+    ``scope.selected_sources`` rather than every ``exp.Table``. Unparseable SQL
+    yields nothing (fail-soft — one model never sinks the pass).
+    """
+    sql = _number_refs(raw_code)
+    sql = _OTHER_JINJA.sub(" ", sql)
+    if not sql.strip():
+        return []
+    try:
+        # parse_one returns a node or raises for non-empty input (empty is guarded
+        # above); build_scope returns None for a non-query statement (DDL/SET).
+        root = build_scope(sqlglot.parse_one(sql))
+        if root is None:
+            return []
+        relations = [
+            source.sql()
+            for scope in root.traverse()
+            for _alias, (_node, source) in scope.selected_sources.items()
+            if isinstance(source, exp.Table) and not source.name.startswith(_REF_SENTINEL_PREFIX)
+        ]
+    except SqlglotError:  # OptimizeError (e.g. duplicate alias) is a SqlglotError subclass.
+        return []
+    return relations
+
+
+def hard_coded_references(graph: "ManifestGraph") -> "list[dict]":
+    """Models whose SQL selects from a literal relation instead of ref()/source()."""
+    out = []
+    for model in graph.models:
+        relations = _hard_coded_relations(str(getattr(model, "raw_code", "") or ""))
+        if relations:
+            shown = ", ".join(sorted(set(relations)))
+            out.append(
+                finding(
+                    "hard_coded_references",
+                    "modeling",
+                    model.unique_id,
+                    "model",
+                    f"Hard-coded relation(s) {shown} — replace with ref()/source().",
+                )
+            )
+    return out
+
+
 def root_models(graph: "ManifestGraph") -> "list[dict]":
     """Models with zero parents (no ref/source) — untraceable lineage."""
     out = []

{dbdocs-1.2.0 → dbdocs-1.4.0}/dbdocs/extract/health/rules/dimensions/structure.py

@@ -57,6 +57,24 @@ def model_directories(graph: "ManifestGraph") -> "list[dict]":
     return out
 
 
+def test_directories(graph: "ManifestGraph") -> "list[dict]":
+    """Singular (custom SQL) tests not stored under a ``tests/`` directory."""
+    out = []
+    for test in graph.singular_tests:
+        path = str(getattr(test, "original_file_path", "") or getattr(test, "path", "") or "")
+        if "tests" not in path.split("/"):
+            out.append(
+                finding(
+                    "test_directories",
+                    "structure",
+                    test.unique_id,
+                    "test",
+                    "Singular test is not under a 'tests/' directory.",
+                )
+            )
+    return out
+
+
 def source_directories(graph: "ManifestGraph") -> "list[dict]":
     """Source YAML not under a staging/ directory."""
     out = []

{dbdocs-1.2.0 → dbdocs-1.4.0}/dbdocs/extract/health/rules/dimensions/testing.py

@@ -49,3 +49,22 @@ def missing_primary_key_tests(graph: "ManifestGraph") -> "list[dict]":
                 )
             )
     return out
+
+
+def missing_source_freshness(graph: "ManifestGraph") -> "list[dict]":
+    """Sources with no freshness check (no ``loaded_at_field`` + warn/error threshold)."""
+    out = []
+    for src in graph.sources:
+        if not graph.has_source_freshness(src):
+            name = str(getattr(src, "source_name", "") or "") or src.unique_id
+            table = str(getattr(src, "name", "") or "")
+            out.append(
+                finding(
+                    "missing_source_freshness",
+                    "testing",
+                    src.unique_id,
+                    "source",
+                    f"Source '{name}.{table}' has no freshness check configured.",
+                )
+            )
+    return out