feat: dbt_docs_coverage and how each reached column comes from the traced one

HK
1d ago
+1165-9

Issue for this PR

Closes #

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

Two changes that let a client copy a written column description to the downstream columns that carry it, and show how documented a model is.

  • dbt_docs_coverage (replaces the foundation stub) reports which output columns of a model have no description.
  • column_reach keeps how each reached column comes from the traced one in a new optional lens_types field keyed like columns. It rates the whole path from the traced column: a column is Original or Alias only if every hop is, so a copy of a calculation is never Original; an edge with no rating gives no entry. impact_analysis already returns the whole reach in metadata.column_reach, so it needed no change.
  • When a model reads a parent through a schema-qualified relation (as a compiled ref is written), the engine rated every edge Not sure. The SQL is traced again with each parent listed under every way its relation is written, and an edge both runs report takes the second rating.

This branch contains the foundation commits (feat/pu-mods-foundation), so its diff includes them until that foundation merges.

Follow-ups, not changed here: impact_analysis still returns metadata: { success: false } without an error for a missing manifest and an unknown model, so the CLI and MCP report those as successful calls; dbt_docs_coverage is reachable through altimate tool run and MCP, and is not registered for agent sessions in src/tool/registry.ts (the plan reaches it from the plugin through the CLI).

How did you verify your code works?

bun typecheck and bun test test/altimate/column-reach.test.ts test/altimate/impact-analysis.test.ts test/altimate/dbt-docs-coverage.test.ts in packages/opencode: 76 pass, 0 fail. Fixtures only, no warehouse.

Cost side effects

None.

Changelog

  • Added dbt_docs_coverage: lists a model's output columns that have no description.
  • Column reach and impact analysis now say how each reached column comes from the traced one (lens_types).
  • Column reach no longer rates every column Not sure when the model reads its parents through schema-qualified names.

Screenshots / recordings

Demo recording (real altimate tool run calls and a Claude Code session with the plugin): /Users/harish/.quikim/artifacts/pu-mods/videos/P-10.mp4 (local file).

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR
  • I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"

🤖 Generated with Claude Code

Summary by cubic

Adds dbt_docs_coverage, a manifest-only tool that reports which output columns of a model have no description in its YAML, plus the lens_types field on column reach and impact analysis. Columns are matched case-insensitively except quoted names that differ by case, and a model that selects * without listed columns is reported as unknown rather than fully covered. Tool failures and error results carry an error so the CLI and MCP report them as errors.

Column reach and impact analysis now include an optional lens_types field keyed like columns, saying how each reached column comes from the traced one (Original, Alias, Transformation, Not sure, Non select).

  • A column is Original or Alias only if every hop is, so a copy of a calculation is never Original; edges with no classification give no entry, and a column named __proto__ keeps its rating.
  • The engine no longer rates every edge Not sure when a model reads a parent through a schema-qualified relation (as compiled refs are written): the SQL is traced again with each parent listed under every way its relation is written, and an edge both runs report takes the second run's rating.
  • This branch's diff also includes the feat/pu-mods-foundation commits: eight dbt Power User tool stubs exposed through altimate tool run, an exported AltimateApi.apiRequest for backend calls using stored credentials, and dbtAdapterFor, the shared gate that refuses read-only calls, sessions in other dbt projects, and adapters that did not start.

Summary by CodeRabbit

  • New Features
    • Added dbt documentation coverage reporting, including model and column description status.
    • Column lineage results now distinguish aliases and transformations where classifications are available.
    • Added access to additional dbt and documentation tools; several currently return an unavailable or not-implemented result.
  • Bug Fixes
    • Improved lineage ratings for edges previously marked “Not sure,” when matching classification data is available.