#57 — source() binding: extend messy-import-CTE fallback to dbt source() references

[cmbays]

Summary

Extends the messy-import-CTE fallback (#34 / PR 17) to dbt source('a', 'b') references — the v0.2-deferred half of #34. dbt compiles {{ source('a','b') }} into the resolved relation at compile time, so binding resolves the authored pair through the manifest's top-level sources block instead of the compiled SQL.

Closes #57

What changed

• Domain — SourceNode POD (separate type, not a Node kind-variant: sources carry no checksum, and fusion keeps them a distinct type end-to-end) + Manifest.sources map. Manifest::with_sources builder (the Node::with_column_descriptions precedent — 40 existing Manifest::new call sites untouched); source_by_name resolves the authored (source_name, name) pair case-insensitively.
• Adapter (manifest) — WireSource tolerant projection: every field #[serde(default)] Option per the feat: surface incremental-model unit-test semantics (incremental badge + expect=merged-rows tooltip) #145 engine-divergence rule (dbt-core emits explicit nulls; fusion omits keys entirely). A degenerate entry never fails the manifest (ADR-5) — it just never matches, fail-open.
• Adapter (render) — parse_source_ref, the exact sibling of parse_ref_name (both engines serialize given[].input verbatim; source() takes exactly two args — fusion-source-verified, SHA-pinned in the research note). Binding flow: resolve the pair → derive the leaf token (identifier → last segment of relation_name → name, quote-stripped) → feed through the existing two-pass find_import_node_id. No new matching machinery, no preflight change, no new PreflightError variant (sources are referenced by models, never analyzed).
• Node detail panel — surfaces the bound given via the existing bound_to_node + interaction.js filter; zero template changes (kept clear of builder-198's surface).
• Fixture — tests/fixtures/ref-and-source-import-cte.json: a model with BOTH a ref-based and a source-based import CTE, unit test mocking both, sources block in both engine dialects (core-style explicit nulls + fusion-style absent keys). Registered in tests/fixtures/MANIFEST.toml (synthetic_only = true, SHA-256 pinned).
• Docs — README: removed the now-closed "source() references are not bound" fidelity limit (replaced with the residual authored-form caveat) and documented the sources-resolution hop in the Import-CTE binding section. AUDIT.md has no messy-import-CTE narrative section — its §4 fixture-provenance index picks the new fixture up mechanically via MANIFEST.toml, so no AUDIT.md edit was needed.

Tests

• Domain: POD accessors, serde round-trips (incl. fusion-minimal absent keys), pre-feature: source() binding — extend messy-import-CTE fallback to dbt source() references #57 manifests deserialize to an empty sources map, pair-lookup hit/miss/case-insensitivity.
• Adapter: core-style (explicit-null) entry, fusion-style (absent-key) entry, degenerate-entry tolerance.
• Render: full parse_source_ref suite mirroring parse_ref_name's, token-derivation fallbacks (identifier override, embedded-quote "GROUP" case, relation-name fallback, name fallback), payload binding (canonical with source as (…) shape, identifier override, fusion-minimal entry, unresolvable pair → unbound, no-sources-map → unbound, ref+source mixed test binding each given to its own CTE).
• Integration: file → Stage-1 → sources → payload binding against the committed fixture.
• Headless (Chrome, verified locally): clicking the source-bound CTE renders the given's fixture card in the Node-detail panel — input name, mocked rows, no empty-state copy.

Gates (all run directly — lefthook skips in fresh worktrees)

Gate	Result
cargo fmt --check	pass
cargo clippy --all-targets --locked -- -D warnings	pass (exit 0)
cargo nextest run	1079 passed
cargo test --test bdd	14 features / 109 scenarios / 684 steps passed (no new scenarios → feature-count gates untouched)
cargo test --test headless_zero_egress --locked -- --ignored	2 passed
cargo test --test headless_toggle --locked -- --ignored	37 passed (incl. the new #57 test)
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked	pass
cargo deny check	pass
cargo llvm-cov + crap4rs --config crap4rs.toml	PASS — 0 above threshold 25, worst 23.0

Goldens

All three golden examples (jaffle-shop, playground, diff-showcase) regenerated per the example-report-check matrix — zero byte diff, as expected: no committed example carries a source() given yet, and the binding adds no payload keys to ref-only reports.

Coordination

Real-fixture verification vs the regenerated playground pair lands when #64 merges; this PR will rebase + verify then (the playground at c8270a4 carries test_stg_synthea__patients_renames_and_hashes_source_columns with input: source('synthea_raw', 'patients') — exactly the canonical shape this PR's synthetic fixture mirrors). This PR deliberately does not touch tests/fixtures/playground-*, examples/playground-report.html, or any template/CSS surface.

🤖 Generated with Claude Code

---

Summary by CodeRabbit

Release Notes

• New Features

  • Added support for binding source() calls in unit test givens, enabling unit tests to resolve source-based import CTEs alongside existing ref() support.

• Documentation

  • Updated documentation clarifying source() parsing limits in unit test givens (positional single-quoted form only) and refined Import-CTE binding behavior for source resolution with fallback handling.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The PR extends cute-dbt's messy import-CTE fallback to handle dbt source('schema', 'table') references in unit-test givens. It adds a domain SourceNode type, parses dbt manifest sources, implements a source() parser and binding flow that resolves source pairs through the manifest to relation tokens, and validates the feature end-to-end with fixtures and integration tests.

Changes

Source binding for unit test givens

Layer / File(s)	Summary
Domain sources model src/domain/manifest.rs, src/domain/mod.rs	SourceNode POD type with owned fields (id, source_name, name, identifier, schema, database, relation_name) and #[serde(default)] optional handling. Manifest gains a sources map, with_sources(...) builder, and source_by_name(source_name, name) case-insensitive lookup accessor.
Manifest adapter sources parsing src/adapters/manifest.rs	WireManifest ingests dbt's top-level sources block via tolerant WireSource struct with defaulting serde fields. During domain translation, sources map is built and attached to Manifest via with_sources(). Tests validate core-style, fusion-style, and degenerate source entries.
Source reference parser src/adapters/render.rs (lines 145–186)	New exported parse_source_ref(input: &str) -> Option<(&str, &str)> extracts (source_name, table_name) from source('NAME','TABLE')-shaped strings; single-quoted args only, case-insensitive, whitespace-tolerant.
Source binding resolution src/adapters/render.rs (lines 1536–1783)	build_test_payload tries ref binding first, then attempts source via new helpers: find_source_import_node_id resolves (source_name, table_name) through manifest, derives leaf relation token via source_relation_token (with identifier override and quote-stripping), and reuses find_import_node_id for CTE-leaf matching. Test helper manifest_with_sources(...) enables source binding tests.
Fixtures and integration tests tests/fixtures/MANIFEST.toml, tests/fixtures/ref-and-source-import-cte.json, tests/render_integration.rs, tests/headless_toggle.rs	New ref-and-source-import-cte.json fixture exercises mixed ref + source import CTEs with unit test givens; two render integration tests validate end-to-end binding from committed fixtures, and a headless Chromium test asserts the Node-detail panel renders the source fixture card correctly.
Documentation README.md	Updated "Known v0.1 fidelity limits" and "Import-CTE binding" sections document that source() parsing supports only single-quoted positional form, and that binding resolves via manifest sources with fail-open semantics for missing entries.

Sequence Diagram(s)

sequenceDiagram
  participant given as Given input
  participant parse as parse_source_ref
  participant manifest as Manifest.sources
  participant derive as source_relation_token
  participant cte as find_import_node_id
  given->>parse: source('a','b')
  parse->>parse: extract (a,b)
  parse-->>given: Some((a,b))
  given->>manifest: source_by_name(a,b)
  manifest-->>given: SourceNode
  given->>derive: compute leaf token
  derive->>derive: strip identifier quotes
  derive-->>given: unquoted_token
  given->>cte: match token in CTE body
  cte-->>given: matched_node_id

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• breezy-bays-labs/cute-dbt#38: Added the core renderer and initial ref('...')→CTE binding; this PR extends the same binding path to also parse and resolve source('...','...') through manifest sources.

Poem

🐰 A source by any name, when parsed just right,
flows through the manifest in CTE light,
ref and source now dance as one,
binding givens till the tests are done!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title accurately summarizes the main change: extending source() binding support to the messy-import-CTE fallback mechanism, directly referencing issue #57.
Linked Issues check	✅ Passed	All acceptance criteria from #57 are met: Manifest gains sources map with SourceNode, adapter parses sources block, parser recognizes source() shape, binding resolves via sources → relation_name match, synthetic fixture included, and README updated.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to #57 objectives: domain/adapter/render/test extensions for source() binding, fixture addition, and docs updates; no unrelated refactoring or peripheral changes detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch domain-57-source-binding

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ghost]

Ready to review this PR? Stage has broken it down into 5 individual chapters for you:

	Title
1	Define SourceNode domain and Manifest extensions
2	Implement manifest adapter for source ingestion
3	Implement source reference parsing and binding
4	Add integration tests and fixtures
5	Verify UI rendering and update documentation

_{Chapters generated by Stage for commit 478e7f8 on Jun 11, 2026 2:43am UTC.}

[github-actions]

📄 Rendered report preview

All golden examples regenerated cleanly.

🟡 Golden examples

Committed to examples/ and byte-identity gated — the canonical reports contributors and consumers browse. Stable across PRs.

Report	View	Download
playground-report.html	▶ Open ↗	⬇ Download
diff-showcase-report.html	▶ Open ↗	⬇ Download
jaffle-shop-report.html	▶ Open ↗	⬇ Download

🐶 Live dogfood preview

This PR doesn't touch dbt-project/, so there's no live dogfood preview.

▶ Open ↗ opens the report in your browser in one click —
published to this repo's GitHub Pages under /pr-204/.
⬇ Download fetches the same self-contained HTML as a workflow
artifact (auth-gated; works fully offline). Either way the report
makes zero external resource requests.

The Pages preview may take ~1 min to update after this comment
posts. On PRs from forks the Open link is unavailable (read-only
token) — use Download.

Alternative: GitHub CLI

# gh CLI >= 2.63 extracts into ./report-preview-playground/.
gh run download 27320273995 -R breezy-bays-labs/cute-dbt -n report-preview-playground
open report-preview-playground/playground-report.html

---

_{Posted by report-preview.yml for 478e7f8251360872b07f8ce83bad808d04874da8. Affordance only — never blocks merge.}

[gemini-code-assist]

Code Review

This pull request implements support for binding source() unit-test inputs to leaf CTE nodes (cute-dbt#57). It introduces a new SourceNode domain model, updates manifest parsing to handle both dbt-core and dbt-fusion dialects of the top-level sources block, and adds logic to resolve and bind source('source_name', 'table_name') inputs. The review feedback suggests optimizing performance in src/adapters/render.rs by returning a &str slice from source_relation_token instead of an owned String to avoid redundant heap allocations, and consequently passing the token directly to find_import_node_id without double referencing.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[cmbays]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.