feat: depth-limited selection, run reports and config reuse

[pannoury]

Summary

Three capabilities that were already half-built in the codebase and never connected, plus two bugs found while verifying them.

Everything here was checked against a real dbt project (duckdb, with a local package and a customers → l1 → l2 → l3 chain), not only unit tests.

---

--downstream-depth — blast-radius control

The levels parameter was stubbed with # To be implemented in the future in three places, so a change always selected its entire downstream closure. On a real project that means touching a core staging model rebuilds nearly everything — the opposite of what change-based CI is for.

Selection now walks a bounded breadth-first traversal. Measured on the chain above, with only customers modified:

Flag	Models run
--downstream-depth 0	customers
--downstream-depth 1	customers, l1
--downstream-depth 2	customers, l1, l2
(omitted, the default)	customers, l1, l2, l3

New and deleted nodes are always included regardless of depth — a new model has to run whether or not anything depends on it yet.

Worth noting the old code would have raised KeyError had anyone passed levels: it looked up a downstream_dependencies_level_N key the graph never contains. The stub was never reachable.

dbt-ci report — surfacing what was already recorded

init, run, delete, ephemeral and migration all write status, timings and resolved variables into report.json, and the change set into cache.json. Nothing ever read either back — finalize deleted them. This renders them:

• change counts and node names, grouped modified / new / deleted (long lists fold into <details>)
• exposure impact — exposures downstream of the change set
• per-command status and duration

It appends to $GITHUB_STEP_SUMMARY when set, so in GitHub Actions it needs no workflow wiring; --output writes a file (e.g. to post as a PR comment) and --format json is machine-readable.

Exposures resolve against the target graph for modified and new nodes, and against the reference graph for deleted ones — an exposure downstream of a model that was just deleted is the case most worth catching.

Settings inherited from init

dbt/flags.py was written for exactly this and never imported. init records the target and vars it ran with, and the README promises "specify state once in init, reuse everywhere" — but that was only true of state paths; every later command made you repeat --target and --vars. They are now inherited from the cache, with an explicitly passed flag still winning.

---

Bugs found while verifying

dbt-ci delete was a silent no-op without --reference-target. init overwrote the cached reference manifest with the target manifest whenever --reference-target was unset or matched --target, reasoning that "reference and target are the same". They aren't: the reference target selects which warehouse profile to compile against, the reference state is the baseline to diff against. Deleted nodes exist only in that baseline, so delete could not look up what it was meant to drop.

Reproduced: cache.json correctly recorded model.demo.stg_orders as deleted, and generate_delete_map then exited having found nothing. Every README example using a local --state directory hits this. With the fix it resolves the deletion, table id included:

{'model.demo.stg_orders': {'type': 'model', 'name': 'stg_orders',
                           'table_id': 'demo.main.stg_orders'}}

.gitignore was silently swallowing directories named dbt. The rule was an unanchored dbt, which matches that name at any depth rather than the root-level dbt project it was for. Two !dbt_ci/**/dbt negations (the same line, twice) rescued the package directory and nothing else — tests/unit/dbt/ was dropped by git add -A, so a new test module was excluded from a commit without warning and would never have run in CI. I hit this in this PR. Anchored to /dbt/; verified a root dbt/ project is still ignored while tests/unit/dbt/ and new files under dbt_ci/dbt/ are not.

Testing

220 tests, up from 179. New coverage for depth traversal (including cycles, unknown nodes and depth beyond the graph), report rendering, duration formatting, output destinations, cached-config precedence and the reference-manifest caching rules.

One bug was caught by its own test rather than by review: format_duration reported 0.0s for a still-running command, because the end-timestamp key is derived from the status and started_at is its own end key. It now reports -.

Both feature and fix commits pass the suite independently, so the history stays bisectable.

Notes for review

• --downstream-depth is opt-in; omitting it preserves today's behaviour exactly.
• The feat: commit means semantic-release will cut a minor (1.5.0) rather than a patch this time.
• Not included, and still open from the earlier discussion: warehouse-agnostic delete/migration via dbt run-operation (currently BigQuery-only), dbt 1.8+ unit tests as a tracked node type, and the Docker image / GitHub Action work.

---

Generated by Claude Code