Skip to content

feat: add Project Health Check (six dbt-project-evaluator dimensions)#2

Merged
datnguye merged 3 commits into
mainfrom
feat/health-check
Jun 13, 2026
Merged

feat: add Project Health Check (six dbt-project-evaluator dimensions)#2
datnguye merged 3 commits into
mainfrom
feat/health-check

Conversation

@il-dat

@il-dat il-dat commented Jun 13, 2026

Copy link
Copy Markdown
Collaborator

What & why

Adds a Project Health Check to dbdocs, derived from the static dbt artifacts
we already load — no extra dbt package, no warehouse. The manifest drives a rule
engine covering the six dbt-project-evaluator
dimensions (testing, modeling, documentation, structure, performance,
governance); an optional run_results.json adds per-test pass/fail detail. The
SPA surfaces a scorecard + collapsible dimensions page and per-model test
results on each node page. It's always built and fail-soft: a
missing/malformed run_results.json never sinks generate, and the SPA only
surfaces the section when it holds findings.

This PR also carries the supporting tooling: .github PR + issue templates, a
/dbdocs-pr skill/command, and a new UX & accessibility dimension on
dbdocs-code-review.

Type of change

  • 🐞 Bug fix (non-breaking change that fixes an issue)
  • ✨ Feature (non-breaking change that adds capability)
  • 💥 Breaking change (existing behavior changes)
  • 🧹 Refactor / internal (no user-facing change)
  • 📖 Docs only

Area

  • CLI (generate / serve / deploy) — new --run-results override
  • extract/ (nodes / erd / graph / column_lineage / health) — new extract/health/ sub-package
  • site/ (data dict / builder / 3-tier SPA / deploy) — health key + SPA pages
  • frontend/ (React Flow graph bundle) — DAG type/schema filter round-trips through the hash
  • Config (dbdocs.yml) / packaging / CI / docs — run_results/health knobs, artifact-parser dep, docs

How to test

# A plain `dbt build`/`dbt test` produces target/*.json incl. run_results.json.
task generate            # health section is built from the committed jaffle_shop fixtures
task serve               # then open http://localhost:8080/
#   → #/health           the scorecard + six collapsible dimensions
#   → any model page      the "Tests" section (data + unit tests) when present
task test                # 310 tests at 100% coverage
task frontend:test       # vitest incl. the new buildDagHash unit
task frontend:e2e        # Playwright against a real build

Checklist

  • task lint passes (ruff format --check + ruff check).
  • task test passes at 100% coverage (310 passed, TOTAL 100%).
  • I followed the load-bearing patterns in .claude/design_patterns.md (extended an existing seam, didn't fork one). Added the "always-built artifact-derived data-dict section (Health Check)" pattern + its TOC entry in this PR.
  • Data-dict / SPA changes keep producer ↔ consumer in sync (builder health key ⇄ data.js/service.js/ui.js) and don't re-inline the payload.
  • Graph-UI changes rebuilt the committed bundle (task frontend:build) and I committed dbdocs/site/bundle/assets/graph/.
  • New files under dbdocs/site/bundle/** (assets/css/icons.css) are covered by the pyproject.toml artifacts glob (dbdocs/site/bundle/**/*).
  • Docs / dbdocs.yml.example updated for the new run_results/health knobs and the --run-results flag.

Screenshots / notes

  • The Health Check works from an ordinary dbt build/dbt test — no extra dbt
    package. Without run_results.json, the manifest-derived dimensions still
    render; only the per-test pass/fail detail is skipped (a note records it).
  • Status colors are consolidated onto --status-* CSS custom properties (one
    source of truth across pills/badges/scorecard, light + dark).
  • Suggest adding before/after screenshots of the #/health page and a model
    page's Tests section here.

@il-dat il-dat force-pushed the feat/health-check branch 5 times, most recently from 15e2663 to 991044c Compare June 13, 2026 08:40
@il-dat il-dat force-pushed the feat/health-check branch from 991044c to fa99a4b Compare June 13, 2026 08:41
@datnguye datnguye merged commit 0399166 into main Jun 13, 2026
14 checks passed
@datnguye datnguye deleted the feat/health-check branch June 13, 2026 08:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants