Skip to content

Commit eacb84a

Browse files
ralphstodomingohkaltaiclaude
authored
feat(dbt_lineage): return the dbt integration's model lineage as structured content (#1637)
`dbt_lineage` returns the dbt integration's model lineage as structured content, and a read-only call answers from the manifest without starting the dbt integration. Includes #1635: structured lineage and column reach for `dbt_lineage` and `impact_analysis`, with the review fixes for answering from the session's own dbt project and honouring a cancel while the project is read. Closes #1636 Co-authored-by: Harish Kumar <[email protected]> Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01YNQjkcTQBy2pEa6qoBZQfb
1 parent 2d59604 commit eacb84a

16 files changed

Lines changed: 3542 additions & 85 deletions

File tree

‎packages/dbt-tools/src/adapter.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,12 @@ export async function create(cfg: Config): Promise<DBTProjectIntegrationAdapter>
207207
new ModelDepthParser(term, client, config),
208208
)
209209

210-
await adapter.initialize()
210+
try {
211+
await adapter.initialize()
212+
} catch (e) {
213+
// initialize() can fail after the integration started a Python bridge; stop it.
214+
await adapter.dispose().catch(() => {})
215+
throw e
216+
}
211217
return adapter
212218
}

‎packages/opencode/src/altimate/mcp-server/server.ts‎

Lines changed: 89 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,81 @@ export async function serverInstructions(): Promise<string> {
4343
}
4444
}
4545

46+
// altimate_change start — lineage tools answer with structured content as well as text
47+
// Lineage tools also return their metadata as structured content, so a client that draws lineage
48+
// (the Claude Code plugin's lineage pane) reads edges and downstream lists without parsing text.
49+
// Claude Code shows structured content to the model in place of the text, so `report` carries the
50+
// text (for dbt_lineage only its header: the mappings and edges travel as data), only the lineage
51+
// fields are passed, and the whole is capped.
52+
const STRUCTURED_FIELDS: Record<string, readonly string[]> = {
53+
dbt_lineage: ["model_name", "model_unique_id", "confidence", "confidence_factors", "upstream", "columns", "edges", "error"],
54+
impact_analysis: [
55+
"model",
56+
"column",
57+
"change_type",
58+
"severity",
59+
"direct_count",
60+
"transitive_count",
61+
"test_count",
62+
"downstream",
63+
"exposures",
64+
"column_reach",
65+
"column_reach_error",
66+
"exposures_error",
67+
"error",
68+
],
69+
}
70+
export const STRUCTURED_TOOLS: ReadonlySet<string> = new Set(Object.keys(STRUCTURED_FIELDS))
71+
const STRUCTURED_OUTPUT_SCHEMA = {
72+
type: "object" as const,
73+
properties: {
74+
report: { type: "string", description: "The tool's text report" },
75+
truncated: { type: "boolean", description: "True when the lineage fields were left out for size; the report is kept, shortened if it is too large on its own" },
76+
},
77+
required: ["report"],
78+
additionalProperties: true,
79+
}
80+
// The structured result reaches the model in Claude Code, so it stays within the same order of
81+
// size as a text result: past this, only the report is sent. Claude Code caps an MCP result at
82+
// 25k tokens by default and JSON of ids and edges runs ~3-4 characters a token, so this stays under that.
83+
const STRUCTURED_MAX_BYTES = 60_000
84+
85+
export function structuredResult(tool: string, metadata: Record<string, unknown>, report: string): Record<string, unknown> {
86+
// A tool that builds its own structured result (dbt_lineage from the dbt integration) hands it
87+
// over whole; otherwise the lineage fields of its metadata are passed.
88+
const own = metadata.structuredContent
89+
if (own && typeof own === "object" && !Array.isArray(own)) {
90+
// The text repeats every edge that `columnLineage` already carries: only its header goes with them.
91+
const head = report.split(/\n(?:Column edges \(|Trace of )/)[0]!.trim()
92+
const full = { ...(own as Record<string, unknown>), report: head }
93+
return Buffer.byteLength(JSON.stringify(full)) <= STRUCTURED_MAX_BYTES ? full : capReport(report, true)
94+
}
95+
const fields = Object.fromEntries((STRUCTURED_FIELDS[tool] ?? []).filter((key) => key in metadata).map((key) => [key, metadata[key]]))
96+
// dbt_lineage's text prints the same mappings and edges as `columns` and `edges`: keep its header.
97+
const head = tool === "dbt_lineage" && "columns" in fields ? report.split(/\n(?:Column Mappings|Lineage Edges):/)[0]!.trim() : report
98+
const full = { ...fields, report: head }
99+
return Buffer.byteLength(JSON.stringify(full)) <= STRUCTURED_MAX_BYTES ? full : capReport(report, true)
100+
}
101+
/** An error report held to the same cap as a result, so a huge exception message cannot exceed it. */
102+
export function structuredError(message: string): Record<string, unknown> {
103+
return capReport(message, false)
104+
}
105+
// `dropped`: the result's other fields were left out, so it is marked truncated even when the
106+
// report itself fits.
107+
function capReport(message: string, dropped: boolean): Record<string, unknown> {
108+
// Measured as sent: JSON escaping can grow the text (a newline is two bytes, a control
109+
// character six), so the cap applies to the serialized result, shortening until it fits.
110+
const size = (value: Record<string, unknown>) => Buffer.byteLength(JSON.stringify(value))
111+
const whole = dropped ? { report: message, truncated: true } : { report: message }
112+
if (size(whole) <= STRUCTURED_MAX_BYTES) return whole
113+
let report = message
114+
while (report.length > 0 && size({ report, truncated: true }) > STRUCTURED_MAX_BYTES) {
115+
report = report.slice(0, Math.floor(report.length * 0.9))
116+
}
117+
return { report, truncated: true }
118+
}
119+
// altimate_change end
120+
46121
/** Spilled results: a resource_link next to the text, which keeps the preview, row count and path. */
47122
function resultLinks(metadata: Record<string, unknown>) {
48123
// A batched sql_execute call reports one saved file per spilled query.
@@ -97,6 +172,7 @@ export async function createServer(options: ServeOptions = {}) {
97172
name,
98173
description: descriptions[name] ?? tool.description,
99174
inputSchema: tool.jsonSchema as McpTool["inputSchema"],
175+
...(STRUCTURED_TOOLS.has(name) && { outputSchema: STRUCTURED_OUTPUT_SCHEMA }),
100176
})), ...(workspace?.tools ?? [])],
101177
}))
102178
// Ask the user once per session when the model weighed two readings and the client can ask; any
@@ -149,11 +225,16 @@ export async function createServer(options: ServeOptions = {}) {
149225
return {
150226
content: [{ type: "text" as const, text: result.output }, ...resultLinks(result.metadata)],
151227
isError,
228+
...(STRUCTURED_TOOLS.has(request.params.name) && {
229+
structuredContent: structuredResult(request.params.name, result.metadata, result.output),
230+
}),
152231
}
153232
} catch (error) {
233+
const message = error instanceof Error ? error.message : String(error)
154234
return {
155-
content: [{ type: "text" as const, text: error instanceof Error ? error.message : String(error) }],
235+
content: [{ type: "text" as const, text: message }],
156236
isError: true,
237+
...(STRUCTURED_TOOLS.has(request.params.name) && { structuredContent: structuredError(message) }),
157238
}
158239
}
159240
}
@@ -193,8 +274,13 @@ export async function serveStdio(options: ServeOptions = {}): Promise<void> {
193274
const onclose = server.onclose
194275
server.onclose = async () => {
195276
try {
196-
await onclose?.()
197-
await Registry.closeAll()
277+
try {
278+
await onclose?.()
279+
await Registry.closeAll()
280+
} finally {
281+
// The dbt adapter's Python bridge is stopped even when closing the rest fails.
282+
await (await import("../native/connections/register")).disposeDbtAdapter()
283+
}
198284
closed.resolve()
199285
} catch (error) {
200286
closed.reject(error)

‎packages/opencode/src/altimate/native/connections/register.ts‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,11 +55,15 @@ let dbtAdapter: any | null | undefined = undefined
5555
// permanent negative cache (`dbtAdapter === null`) is unchanged — a project that
5656
// becomes valid mid-session is still not retried.
5757
let dbtAdapterInflight: Promise<any | null> | undefined
58+
/** The project root the cached attempt read from the dbt config; null when it found none. */
59+
let dbtProjectRoot: string | null = null
5860

5961
/** Test seams for the single-flight. Production leaves `readConfig` unset. */
6062
export const dbtAdapterInternals: {
6163
/** Replaces the dbt config read, so a test can hold an attempt open. */
6264
readConfig?: () => Promise<unknown>
65+
/** Replaces dbt-tools' adapter creation, so a test can see which integration modes were tried. */
66+
create?: (config: any) => Promise<any>
6367
/** Adapter creation attempts since the last reset — what single-flight bounds. */
6468
attempts: number
6569
/** Cache writes since the last reset: only the attempt that owns the slot writes. */
@@ -101,6 +105,9 @@ async function ensureDbtAdapter(): Promise<any | null> {
101105
const dbtConfig = dbtAdapterInternals.readConfig
102106
? ((await dbtAdapterInternals.readConfig()) as Awaited<ReturnType<typeof readDbtConfig>>)
103107
: await readDbtConfig()
108+
if (dbtAdapterInflight === mine) {
109+
dbtProjectRoot = typeof dbtConfig?.projectRoot === "string" ? dbtConfig.projectRoot : null
110+
}
104111
if (!dbtConfig) return publish(null)
105112

106113
// Check if dbt_project.yml exists
@@ -113,7 +120,7 @@ async function ensureDbtAdapter(): Promise<any | null> {
113120
}
114121

115122
// Create the adapter
116-
const { create } = await import("../../../../../dbt-tools/src/adapter")
123+
const create = dbtAdapterInternals.create ?? (await import("../../../../../dbt-tools/src/adapter")).create
117124
return publish(await create(dbtConfig), dbtConfig.projectRoot)
118125
} catch {
119126
// dbt-tools not available or config invalid — fall back to native
@@ -261,6 +268,38 @@ async function tryExecuteViaDbt(
261268
}
262269
}
263270

271+
/** The project's dbt adapter, created on first use; null when there is no usable dbt project. */
272+
export function getDbtAdapter(): Promise<any | null> {
273+
return ensureDbtAdapter()
274+
}
275+
276+
/**
277+
* Stops the cached dbt adapter (its Python bridge and file watchers), for a server that is shutting
278+
* down. An attempt still starting is stopped once it settles.
279+
*/
280+
export async function disposeDbtAdapter(): Promise<void> {
281+
const settled = dbtAdapter
282+
const inflight = dbtAdapterInflight
283+
resetDbtAdapter()
284+
void inflight?.then((adapter) => adapter?.dispose?.()).catch(() => {})
285+
await settled?.dispose?.().catch(() => {})
286+
}
287+
288+
/** The dbt project's root as the adapter finds it: a dbt.json, or a walk up from the working directory. */
289+
export async function getDbtProjectRoot(): Promise<string | undefined> {
290+
// Once an adapter attempt has settled, reuse the root it read rather than reading the config again.
291+
if (dbtAdapter !== undefined) return dbtProjectRoot ?? undefined
292+
try {
293+
const config = dbtAdapterInternals.readConfig
294+
? await dbtAdapterInternals.readConfig()
295+
: await (await import("../../../../../dbt-tools/src/config")).read()
296+
const root = (config as { projectRoot?: unknown } | null)?.projectRoot
297+
return typeof root === "string" ? root : undefined
298+
} catch {
299+
return undefined
300+
}
301+
}
302+
264303
/** Reset dbt adapter (for testing). */
265304
export function resetDbtAdapter(): void {
266305
dbtAdapter = undefined
@@ -270,6 +309,7 @@ export function resetDbtAdapter(): void {
270309
dbtAdapterInflight = undefined
271310
dbtAdapterInternals.attempts = 0
272311
dbtAdapterInternals.writes = 0
312+
dbtProjectRoot = null
273313
}
274314

275315
// ---------------------------------------------------------------------------

0 commit comments

Comments
 (0)