feat: dbt_health tool: DataPilot project health insights per model

HK
27m ago
+1262-0

Issue for this PR

Part of the dbt Power User tools build (package P-06, project health). No tracker issue.

Type of change

  • New feature

What does this PR do?

Fills in the dbt_health tool (stub from the foundation). It starts the project's dbt adapter through dbt-adapter-access (needs write permission), rebuilds the manifest and waits for it, then runs DataPilot over target/manifest.json (and catalog.json when present) with the project's Python, the way dbt-integration's project_healthcheck does, using a Manual config (config_path, or DataPilot's defaults). It does not use dbt-integration's own healthcheck entry point: no integration implements it, and its All mode would run dbt docs generate.

Returns insights: [{ uniqueId, path, name, severity, message, recommendation, file, properties }]; file and properties are absolute paths under the folder as the system names it, for the project's own models. A parse that fails leaves the last good manifest: the answer says so (stale_manifest). When datapilot isn't importable it returns a message naming altimate-datapilot-cli and installs nothing. The text lists at most 100 insights; insights carries all. An answer that isn't DataPilot's, or comes with a failing exit, is a failure.

The Claude Code plugin PR (project health in the band, optional git push gate) depends on this and merges after it.

Known limits, for follow-up: a manifest without metadata.project_name gives no file/properties; a project with several thousand insights makes the result larger than the plugin's 4 MiB read limit (a models filter on the tool would fix it).

How did you verify your code works?

  • bun run typecheck and bun test test/altimate/dbt-health.test.ts test/altimate/dbt-adapter-access.test.ts (40 tests) pass.
  • Reviewed by independent Claude and Codex reviewers; every finding fixed or answered in the comments below.
  • End-to-end recording against a jaffle_shop copy with the branch build: /Users/harish/.quikim/artifacts/pu-mods/videos/P-06.mp4 (tool run, then a Claude Code session with the plugin: a hard-coded reference in orders.sql shows 1 new health issue · orders: hardcoded_refs).

Cost side effects

None. No model calls, no warehouse queries; DataPilot reads the local manifest. Starting the dbt adapter and rebuilding the manifest is the same write-permission path the other adapter-backed tools use.

Screenshots / recordings

/Users/harish/.quikim/artifacts/pu-mods/videos/P-06.mp4 (local file; not uploaded).

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR
  • I checked for cost side effects and described them: none

Changelog: dbt_health tool: DataPilot project health insights per model.

🤖 Generated with Claude Code