From 444f1f4ccfee929f5a7371498437ba13126f94d6 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 15:38:44 +0530 Subject: [PATCH 1/9] feat: column reach keeps how each reached column comes from the traced one Co-Authored-By: Claude Sonnet 5.5 --- .../src/altimate/native/dbt/column-reach.ts | 50 +++++++++-- .../test/altimate/column-reach.test.ts | 85 ++++++++++++++++++- .../test/altimate/impact-analysis.test.ts | 72 ++++++++++++++++ 3 files changed, 199 insertions(+), 8 deletions(-) diff --git a/packages/opencode/src/altimate/native/dbt/column-reach.ts b/packages/opencode/src/altimate/native/dbt/column-reach.ts index 0f1b4cbb40..71a6d43376 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -14,6 +14,14 @@ export interface ColumnReachModel { unique_id: string /** Its output columns that come from the traced column. */ columns: string[] + /** + * How each of those columns (keyed as in `columns`) comes from the traced column, as the lineage + * engine classifies it: Original (carried as is), Alias (renamed), Transformation, Not sure or + * Non select. It covers the whole path from the traced column: a column is Original or Alias only + * when every hop is, so a column read from a calculation is never Original. A column whose + * edges carry no classification has no entry. + */ + lens_types?: Record } export interface ColumnReachUnsure { @@ -54,6 +62,16 @@ export interface ColumnReach { const MAX_MODELS = 300 const TRACED = new Set(["model", "snapshot"]) +// How far a classification is from "the value arrives unchanged", least to most. +const LENS_ORDER = ["Original", "Alias", "Non select", "Not sure", "Transformation"] + +/** The classification of a path made of two: the one further from unchanged, unknown if either is. */ +function joinLens(a: string | undefined, b: string | undefined): string | undefined { + if (a === undefined || b === undefined) return undefined + const rank = (lens: string) => (LENS_ORDER.includes(lens) ? LENS_ORDER.indexOf(lens) : LENS_ORDER.length) + return rank(a) >= rank(b) ? a : b +} + /** "db"."schema"."orders"."amount" → { parts: ["db","schema","orders"], column: "amount" }, lower-cased. */ function splitSource(source: unknown): { parts: string[]; column: string; exact: string } | null { const text = @@ -62,8 +80,7 @@ function splitSource(source: unknown): { parts: string[]; column: string; exact: // Split on dots outside quotes: "a"."net.amount" is table a, column net.amount. // A doubled closing delimiter inside a quoted name is one character ("a""b" is a"b, [a]]b] is a]b). const raw = [...text.matchAll(/"((?:[^"]|"")*)"|`((?:[^`]|``)*)`|\[((?:[^\]]|\]\])*)\]|([^."`\[\]]+)/g)].map( - (m) => - m[1]?.replaceAll('""', '"') ?? m[2]?.replaceAll("``", "`") ?? m[3]?.replaceAll("]]", "]") ?? m[4] ?? "", + (m) => m[1]?.replaceAll('""', '"') ?? m[2]?.replaceAll("``", "`") ?? m[3]?.replaceAll("]]", "]") ?? m[4] ?? "", ) if (raw.length < 2) return null // `exact` keeps the column's case, for parents that document two columns differing only by case. @@ -302,6 +319,8 @@ export function columnReach(manifestPath: string, model: string, column: string, if (unsettled) spelled = [] else if (!exact && matches.length > 0) spelled = matches const trackedExact = new Map>([[targetId, new Set(spelled)]]) + // How each tracked column comes from the traced column, per node (the traced column itself is Original). + const lensOf = new Map>([[targetId, new Map([[column0, "Original"]])]]) const carries = (parent: string, source: { column: string; exact: string }) => !!tracked.get(parent)?.has(source.column) && (!caseCollides(lookup(parent), source.column) || !!trackedExact.get(parent)?.has(source.exact)) @@ -333,7 +352,8 @@ export function columnReach(manifestPath: string, model: string, column: string, unsure.add(id) continue } - const edges: { source: unknown; target: string; lineage_type?: string }[] = lineage?.column_lineage?.length + const edges: { source: unknown; target: string; lineage_type?: string; lens_type?: string }[] = lineage + ?.column_lineage?.length ? lineage.column_lineage : Object.entries(lineage?.column_dict ?? {}).flatMap(([out, sources]) => (Array.isArray(sources) ? sources : [sources]).map((source) => ({ @@ -372,6 +392,7 @@ export function columnReach(manifestPath: string, model: string, column: string, const carried = new Set() const carriedExact = new Set() + const carriedLens = new Map() let reads = false let ambiguous = false for (const edge of edges) { @@ -386,7 +407,14 @@ export function columnReach(manifestPath: string, model: string, column: string, } reads = true if (edge.lineage_type !== "indirect" && typeof edge.target === "string") { - carried.add(edge.target.toLowerCase()) + const out = edge.target.toLowerCase() + const lens = joinLens( + lensOf.get(candidates[0]!)?.get(source.column), + typeof edge.lens_type === "string" ? edge.lens_type : undefined, + ) + // Several edges into one output: it is as far from unchanged as the furthest of them. + carriedLens.set(out, carried.has(out) ? joinLens(carriedLens.get(out), lens) : lens) + carried.add(out) carriedExact.add(edge.target) } } @@ -402,10 +430,22 @@ export function columnReach(manifestPath: string, model: string, column: string, if (reads) { tracked.set(id, carried) trackedExact.set(id, carriedExact) + lensOf.set(id, carriedLens) // Outputs fed by an unsettled or ephemeral parent, or read through an ambiguous name, stay unsettled. // A NATURAL JOIN beside the column may join on it, or carry it on in another output. if (ambiguous || fromUnsure || viaEphemeral || partial || opaque) unsure.add(id) - reached.push({ name: nodes[id]?.name ?? id, unique_id: id, columns: [...carried].sort() }) + const columns = [...carried].sort() + const lens_types: Record = {} + for (const col of columns) { + const lens = carriedLens.get(col) + if (lens !== undefined) lens_types[col] = lens + } + reached.push({ + name: nodes[id]?.name ?? id, + unique_id: id, + columns, + ...(Object.keys(lens_types).length > 0 && { lens_types }), + }) continue } diff --git a/packages/opencode/test/altimate/column-reach.test.ts b/packages/opencode/test/altimate/column-reach.test.ts index e16a60030f..ec230a6c16 100644 --- a/packages/opencode/test/altimate/column-reach.test.ts +++ b/packages/opencode/test/altimate/column-reach.test.ts @@ -116,6 +116,82 @@ describe("columnReach", () => { expect(reach.truncated).toBe(false) }) + test("keeps how each reached column comes from the traced one: a rename is Alias, an aggregate Not sure", () => { + const reach = columnReach(manifestFile(), "fct_orders", "revenue") + const lens = Object.fromEntries(reach.models.map((m) => [m.name, m.lens_types])) + expect(lens).toEqual({ + fct_daily: { revenue: "Not sure" }, + mart_ltv: { ltv: "Alias" }, + // An aggregate, which the engine rates "Not sure", on an alias. + rpt_ltv: { top_ltv: "Not sure" }, + }) + }) + + test("a column copied as is is Original, and a copy of a calculation is never Original", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.stg_copy"] = model( + "stg_copy", + ["model.shop.fct_orders"], + "select order_id, revenue from fct_orders", + ["order_id", "revenue"], + ) + nodes["model.shop.mart_copy"] = model("mart_copy", ["model.shop.stg_copy"], "select revenue from stg_copy", [ + "revenue", + ]) + nodes["model.shop.mart_total"] = model( + "mart_total", + ["model.shop.stg_copy"], + "select revenue * 2 as doubled from stg_copy", + ["doubled"], + ) + nodes["model.shop.mart_total_copy"] = model( + "mart_total_copy", + ["model.shop.mart_total"], + "select doubled from mart_total", + ["doubled"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + const lens = Object.fromEntries(reach.models.map((m) => [m.name, m.lens_types])) + expect(lens.stg_copy).toEqual({ revenue: "Original" }) + expect(lens.mart_copy).toEqual({ revenue: "Original" }) + expect(lens.mart_total).toEqual({ doubled: "Transformation" }) + expect(lens.mart_total_copy).toEqual({ doubled: "Transformation" }) + }) + + test("an output fed by an Alias and a calculation is as far from unchanged as the calculation", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.mart_mix"] = model( + "mart_mix", + ["model.shop.fct_orders"], + "select coalesce(revenue, gross_revenue * 2) as rev from fct_orders", + ["rev"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + const mix = reach.models.find((m) => m.name === "mart_mix") + expect(mix?.lens_types).toEqual({ rev: "Transformation" }) + }) + + test("edges without a classification leave the column without one", () => { + const spy = spyOn(core, "columnLineage").mockImplementation( + () => + ({ + column_lineage: [ + { source: '"shop"."main"."fct_orders"."revenue"', target: "revenue", lineage_type: "direct" }, + ], + errors: [], + }) as any, + ) + try { + const reach = columnReach(manifestFile(), "fct_orders", "revenue") + expect(reach.models.length).toBeGreaterThan(0) + for (const m of reach.models) expect(m.lens_types).toBeUndefined() + } finally { + spy.mockRestore() + } + }) + test("an output alias or a comment naming the column is not a read", () => { const value = manifest() for (const sql of [ @@ -385,9 +461,12 @@ describe("columnReach where the engine's schema falls short", () => { test("stops at 300 traced models and says so", () => { const value = manifest() for (let i = 0; i < 300; i++) { - value.nodes[`model.shop.copy_${i}`] = model(`copy_${i}`, ["model.shop.fct_orders"], "select revenue from fct_orders", [ - "revenue", - ]) + value.nodes[`model.shop.copy_${i}`] = model( + `copy_${i}`, + ["model.shop.fct_orders"], + "select revenue from fct_orders", + ["revenue"], + ) } const spy = spyOn(core, "columnLineage").mockImplementation((() => ({ column_lineage: [{ source: '"shop"."main"."fct_orders"."revenue"', target: "revenue", lineage_type: "direct" }], diff --git a/packages/opencode/test/altimate/impact-analysis.test.ts b/packages/opencode/test/altimate/impact-analysis.test.ts index e93083aa84..7b528b8326 100644 --- a/packages/opencode/test/altimate/impact-analysis.test.ts +++ b/packages/opencode/test/altimate/impact-analysis.test.ts @@ -6,6 +6,9 @@ * findDownstream logic without a real napi binary or dbt project. */ import { describe, test, expect, spyOn, afterAll, beforeEach } from "bun:test" +import { mkdtempSync, rmSync, writeFileSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" import { initTool } from "./tool-fixture" import * as Dispatcher from "../../src/altimate/native/dispatcher" import { ImpactAnalysisTool } from "../../src/altimate/tools/impact-analysis" @@ -272,3 +275,72 @@ describe("impact_analysis: blast radius percentage", () => { expect(result.output).toContain("2/20") }) }) + +describe("impact_analysis: column reach carries how each column comes from the traced one", () => { + test("lens_types reach the metadata's column_reach for a rename and a calculation", async () => { + const dir = mkdtempSync(join(tmpdir(), "impact-lens-")) + try { + const node = (name: string, deps: string[], sql: string, columns: string[]) => ({ + resource_type: "model", + unique_id: `model.shop.${name}`, + name, + alias: name, + schema: "main", + database: "shop", + depends_on: { nodes: deps }, + compiled_code: sql, + columns: Object.fromEntries(columns.map((c) => [c, { name: c }])), + }) + const nodes = { + "model.shop.fct_orders": node("fct_orders", [], "select order_id, revenue from raw.orders", [ + "order_id", + "revenue", + ]), + "model.shop.mart_ltv": node("mart_ltv", ["model.shop.fct_orders"], "select revenue as ltv from fct_orders", [ + "ltv", + ]), + "model.shop.mart_double": node( + "mart_double", + ["model.shop.fct_orders"], + "select revenue * 2 as doubled from fct_orders", + ["doubled"], + ), + } + const manifestPath = join(dir, "manifest.json") + writeFileSync(manifestPath, JSON.stringify({ metadata: { adapter_type: "duckdb" }, nodes, sources: {} })) + mockDispatcher({ + "dbt.manifest": { + models: [ + { name: "fct_orders", unique_id: "model.shop.fct_orders", depends_on: [], materialized: "table" }, + { + name: "mart_ltv", + unique_id: "model.shop.mart_ltv", + depends_on: ["model.shop.fct_orders"], + materialized: "table", + }, + { + name: "mart_double", + unique_id: "model.shop.mart_double", + depends_on: ["model.shop.fct_orders"], + materialized: "table", + }, + ], + model_count: 3, + test_count: 0, + }, + }) + const tool = await initTool(ImpactAnalysisTool) + const result = await tool.execute( + { model: "fct_orders", column: "revenue", change_type: "modify", manifest_path: manifestPath, dialect: "duckdb" }, + ctx, + ) + const reach = result.metadata.column_reach as { models: { name: string; lens_types?: Record }[] } + expect(Object.fromEntries(reach.models.map((m) => [m.name, m.lens_types]))).toEqual({ + mart_ltv: { ltv: "Alias" }, + mart_double: { doubled: "Transformation" }, + }) + } finally { + rmSync(dir, { recursive: true, force: true }) + } + }) +}) From e3f24db328b05e0bbb97d5599a49f2e31b2d377a Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 16:30:42 +0530 Subject: [PATCH 2/9] feat: dbt_docs_coverage reports which output columns of a model have no description Co-Authored-By: Claude Sonnet 5.5 --- .../src/altimate/tools/dbt-docs-coverage.ts | 133 ++++++++++++++++++ .../test/altimate/dbt-docs-coverage.test.ts | 118 ++++++++++++++++ 2 files changed, 251 insertions(+) create mode 100644 packages/opencode/src/altimate/tools/dbt-docs-coverage.ts create mode 100644 packages/opencode/test/altimate/dbt-docs-coverage.test.ts diff --git a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts new file mode 100644 index 0000000000..e1de26fb13 --- /dev/null +++ b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts @@ -0,0 +1,133 @@ +// altimate_change - new file +// +// How much of a model's output is documented: the output columns of its compiled SQL, set against +// the columns the manifest gives a description (what the YAML says), and whether the model itself +// has a description. Reads the manifest only, so it needs no warehouse and no dbt adapter. +import z from "zod" +import * as core from "@altimateai/altimate-core" +import { Tool } from "../../tool/tool" +import { loadRawManifest, findModel, detectDialect } from "../native/dbt/helpers" + +export interface DocsCoverage { + model: string + unique_id: string + has_description: boolean + /** The model's output columns, as written in its compiled SQL (or the manifest's columns when the SQL has `*`). */ + output_columns: string[] + /** Output columns that have a description. */ + documented: string[] + /** Output columns without a description. */ + missing: string[] + /** Percent of output columns with a description, 0 to 100, rounded to one decimal; 100 when there are no columns. */ + percent: number + /** Where the column list came from: the compiled SQL's select list, or the manifest's columns when the select list has a `*`. */ + source: "compiled_sql" | "manifest_columns" +} + +const hasText = (value: unknown) => typeof value === "string" && value.trim().length > 0 + +/** Coverage of one manifest model node. Throws when the node has no compiled SQL or the engine cannot read it. */ +export function docsCoverage(node: any, dialect: string | undefined): DocsCoverage { + const yamlColumns: Record = node.columns ?? {} + const described = new Set() + for (const [key, col] of Object.entries(yamlColumns)) { + if (hasText(col?.description)) described.add(String(col?.name || key).toLowerCase()) + } + + const sql: string = node.compiled_code || node.compiled_sql || "" + if (!sql.trim()) { + throw new Error(`Model "${node.name}" has no compiled SQL in the manifest. Run \`dbt compile\` first.`) + } + let outputs: string[] + let source: DocsCoverage["source"] = "compiled_sql" + try { + outputs = core.extractOutputColumns(sql, dialect) + } catch (e) { + // A `select *` names no columns, so the engine refuses it; the manifest's own columns are then + // the best list there is. Any other failure is the SQL's, and is reported. + if (!/star/i.test(e instanceof Error ? e.message : String(e))) throw e + outputs = [] + source = "manifest_columns" + } + if (outputs.some((c) => c.includes("*"))) source = "manifest_columns" + if (source === "manifest_columns") { + outputs = Object.entries(yamlColumns).map(([key, col]) => String(col?.name || key)) + } + + const seen = new Set() + const columns = outputs.filter((c) => { + const k = c.toLowerCase() + if (seen.has(k)) return false + seen.add(k) + return true + }) + const documented = columns.filter((c) => described.has(c.toLowerCase())) + const missing = columns.filter((c) => !described.has(c.toLowerCase())) + const percent = columns.length === 0 ? 100 : Math.round((documented.length / columns.length) * 1000) / 10 + return { + model: node.name, + unique_id: node.unique_id ?? "", + has_description: hasText(node.description), + output_columns: columns, + documented, + missing, + percent, + source, + } +} + +export const DbtDocsCoverageTool = Tool.define("dbt_docs_coverage", { + description: [ + "Report how much of a dbt model's documentation is written: which output columns of its compiled", + "SQL have no description in the project's YAML, and whether the model has a description.", + "Reads target/manifest.json only; run `dbt compile` first so the manifest is current.", + "", + "Examples:", + '- dbt_docs_coverage({ model: "stg_orders" })', + '- dbt_docs_coverage({ model: "dim_customers", manifest_path: "target/manifest.json" })', + ].join("\n"), + parameters: z.object({ + model: z.string().describe("dbt model name or unique_id (e.g., 'stg_orders', 'model.shop.dim_customers')"), + manifest_path: z.string().optional().default("target/manifest.json").describe("Path to dbt manifest.json file"), + }), + async execute(args, _ctx) { + try { + const manifest = loadRawManifest(args.manifest_path) + if (!manifest) { + return { + title: "Docs coverage: NO MANIFEST", + metadata: { success: false }, + output: `No manifest at ${args.manifest_path}. Run \`dbt compile\` first to generate it.`, + } + } + const node = findModel(manifest.nodes ?? {}, args.model) + if (!node) { + return { + title: "Docs coverage: MODEL NOT FOUND", + metadata: { success: false }, + output: `Model "${args.model}" not found in the manifest at ${args.manifest_path}.`, + } + } + const result = docsCoverage(node, detectDialect(manifest)) + const lines = [ + `${result.model}: ${result.documented.length} of ${result.output_columns.length} columns documented (${result.percent}%)`, + `Model description: ${result.has_description ? "yes" : "missing"}`, + ] + if (result.missing.length > 0) lines.push(`Missing descriptions: ${result.missing.join(", ")}`) + if (result.source === "manifest_columns") + lines.push("The model selects `*`, so its columns are the ones the manifest lists.") + return { + title: `Docs coverage: ${result.model} ${result.percent}%`, + metadata: { success: true, ...result }, + output: lines.join("\n"), + } + } catch (e) { + const msg = e instanceof Error ? e.message : String(e) + return { + title: "Docs coverage: ERROR", + metadata: { success: false, error: msg }, + output: `Failed to read docs coverage: ${msg}`, + } + } + }, +}) diff --git a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts new file mode 100644 index 0000000000..0f50eb05b3 --- /dev/null +++ b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts @@ -0,0 +1,118 @@ +/** + * Tests for dbt_docs_coverage: output columns of the compiled SQL against the manifest's described + * columns. Fixture manifests only; nothing here reaches a warehouse or a dbt project. + */ +import { describe, test, expect, beforeEach, afterAll } from "bun:test" +import { mkdtempSync, rmSync, writeFileSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { initTool } from "./tool-fixture" +import { DbtDocsCoverageTool, docsCoverage } from "../../src/altimate/tools/dbt-docs-coverage" +import { SessionID, MessageID } from "../../src/session/schema" + +beforeEach(() => { + process.env.ALTIMATE_TELEMETRY_DISABLED = "true" +}) +afterAll(() => { + delete process.env.ALTIMATE_TELEMETRY_DISABLED +}) + +const ctx = { + sessionID: SessionID.make("ses_test"), + messageID: MessageID.make("msg_test"), + callID: "call_test", + agent: "build", + abort: AbortSignal.any([]), + messages: [], + metadata: () => {}, + ask: async () => {}, +} + +function manifest(nodes: Record) { + return { metadata: { adapter_type: "snowflake" }, nodes, sources: {} } +} + +const orders = { + resource_type: "model", + name: "orders", + unique_id: "model.shop.orders", + description: "One row per order", + compiled_code: "select o.id, o.customer_id, upper(o.status) as status, 1 as flag from raw.orders o", + columns: { + id: { name: "id", description: "Order key" }, + customer_id: { name: "customer_id", description: " " }, + status: { name: "status", description: "Order status" }, + }, +} + +describe("docsCoverage", () => { + test("splits output columns into described and missing, ignoring blank descriptions", () => { + const r = docsCoverage(orders, "snowflake") + expect(r.output_columns).toEqual(["id", "customer_id", "status", "flag"]) + expect(r.documented).toEqual(["id", "status"]) + expect(r.missing).toEqual(["customer_id", "flag"]) + expect(r.percent).toBe(50) + expect(r.has_description).toBe(true) + expect(r.source).toBe("compiled_sql") + }) + + test("matches column names case-insensitively", () => { + const r = docsCoverage( + { ...orders, columns: { ID: { name: "ID", description: "Order key" } }, compiled_code: "select id from t" }, + "snowflake", + ) + expect(r.documented).toEqual(["id"]) + expect(r.missing).toEqual([]) + }) + + test("a model without a description reports it", () => { + expect(docsCoverage({ ...orders, description: "" }, "snowflake").has_description).toBe(false) + }) + + test("select * falls back to the manifest's columns", () => { + const r = docsCoverage({ ...orders, compiled_code: "select * from raw.orders" }, "snowflake") + expect(r.source).toBe("manifest_columns") + expect(r.output_columns).toEqual(["id", "customer_id", "status"]) + expect(r.missing).toEqual(["customer_id"]) + }) + + test("a model without compiled SQL is an error, not full coverage", () => { + expect(() => docsCoverage({ ...orders, compiled_code: "" }, "snowflake")).toThrow("no compiled SQL") + }) +}) + +describe("dbt_docs_coverage tool", () => { + let dir: string + beforeEach(() => { + dir = mkdtempSync(join(tmpdir(), "docs-coverage-")) + }) + afterAll(() => { + if (dir) rmSync(dir, { recursive: true, force: true }) + }) + + test("reports coverage from a manifest file", async () => { + const path = join(dir, "manifest.json") + writeFileSync(path, JSON.stringify(manifest({ [orders.unique_id]: orders }))) + const tool = await initTool(DbtDocsCoverageTool) + const r = await tool.execute({ model: "orders", manifest_path: path }, ctx as any) + expect(r.metadata.success).toBe(true) + expect(r.metadata.missing).toEqual(["customer_id", "flag"]) + expect(r.output).toContain("Missing descriptions: customer_id, flag") + }) + + test("an unknown model names the manifest", async () => { + const path = join(dir, "manifest.json") + writeFileSync(path, JSON.stringify(manifest({ [orders.unique_id]: orders }))) + const tool = await initTool(DbtDocsCoverageTool) + const r = await tool.execute({ model: "nope", manifest_path: path }, ctx as any) + expect(r.metadata.success).toBe(false) + expect(r.output).toContain("not found") + }) + + test("a missing manifest says to compile", async () => { + const tool = await initTool(DbtDocsCoverageTool) + const r = await tool.execute({ model: "orders", manifest_path: join(dir, "absent.json") }, ctx as any) + expect(r.metadata.success).toBe(false) + expect(r.output).toContain("dbt compile") + }) +}) From b7cfc0426d60963a83f22a8f5c6053c7b7fce8e4 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 16:30:43 +0530 Subject: [PATCH 3/9] feat: foundation for the dbt Power User tools Nine tool stubs exposed through `altimate tool run` (dbt_run_results, dbt_defer_state, dbt_map_relations, docs_share_comments, dbt_cost_estimate, dbt_health, dbt_sql_graph, dbt_docs_coverage, dbt_cte_profile), an exported `AltimateApi.apiRequest` that calls the backend with the stored credentials, and `dbtAdapterFor`, the one gate every adapter-backed tool goes through: it refuses read-only calls, other projects, and an adapter that did not start. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/api/client.ts | 18 ++ .../src/altimate/tool-cli/allow-list.ts | 18 ++ .../src/altimate/tools/dbt-adapter-access.ts | 100 ++++++++ .../src/altimate/tools/dbt-cost-estimate.ts | 17 ++ .../src/altimate/tools/dbt-cte-profile.ts | 17 ++ .../src/altimate/tools/dbt-defer-state.ts | 16 ++ .../src/altimate/tools/dbt-docs-coverage.ts | 17 ++ .../opencode/src/altimate/tools/dbt-health.ts | 16 ++ .../src/altimate/tools/dbt-map-relations.ts | 18 ++ .../src/altimate/tools/dbt-run-results.ts | 16 ++ .../src/altimate/tools/dbt-sql-graph.ts | 16 ++ .../src/altimate/tools/docs-share-comments.ts | 20 ++ .../test/altimate/dbt-adapter-access.test.ts | 221 ++++++++++++++++++ 13 files changed, 510 insertions(+) create mode 100644 packages/opencode/src/altimate/tools/dbt-adapter-access.ts create mode 100644 packages/opencode/src/altimate/tools/dbt-cost-estimate.ts create mode 100644 packages/opencode/src/altimate/tools/dbt-cte-profile.ts create mode 100644 packages/opencode/src/altimate/tools/dbt-defer-state.ts create mode 100644 packages/opencode/src/altimate/tools/dbt-docs-coverage.ts create mode 100644 packages/opencode/src/altimate/tools/dbt-health.ts create mode 100644 packages/opencode/src/altimate/tools/dbt-map-relations.ts create mode 100644 packages/opencode/src/altimate/tools/dbt-run-results.ts create mode 100644 packages/opencode/src/altimate/tools/dbt-sql-graph.ts create mode 100644 packages/opencode/src/altimate/tools/docs-share-comments.ts create mode 100644 packages/opencode/test/altimate/dbt-adapter-access.test.ts diff --git a/packages/opencode/src/altimate/api/client.ts b/packages/opencode/src/altimate/api/client.ts index 7a03aeb906..069a182b7a 100644 --- a/packages/opencode/src/altimate/api/client.ts +++ b/packages/opencode/src/altimate/api/client.ts @@ -347,6 +347,24 @@ export namespace AltimateApi { // altimate_change end } + /** + * Calls an Altimate API endpoint with the stored credentials (Bearer key and x-tenant headers) and + * returns the parsed JSON body. Endpoint functions in other files go through this. Fails with a + * message naming the credentials file when none are stored or they can't be read. + */ + export async function apiRequest(method: string, endpoint: string, body?: unknown): Promise { + let creds: AltimateCredentials + try { + creds = await getCredentials() + } catch (e) { + const p = credentialsPath() + if (!(await Filesystem.exists(p))) + throw new Error(`No Altimate credentials are stored: sign in to Altimate in altimate-code first (they are saved to ${p}).`) + throw new Error(`The Altimate credentials in ${p} can't be used: ${e instanceof Error ? e.message : String(e)}`) + } + return request(creds, method, endpoint, body) + } + export async function listDatamates(creds?: AltimateCredentials) { creds ??= await getCredentials() const data = await request(creds, "GET", "/datamates/") diff --git a/packages/opencode/src/altimate/tool-cli/allow-list.ts b/packages/opencode/src/altimate/tool-cli/allow-list.ts index 33b452d75c..0bb4f18473 100644 --- a/packages/opencode/src/altimate/tool-cli/allow-list.ts +++ b/packages/opencode/src/altimate/tool-cli/allow-list.ts @@ -35,10 +35,19 @@ import { AltimateCoreTestgenTool } from "../tools/altimate-core-testgen" import { AltimateCoreTrackLineageTool } from "../tools/altimate-core-track-lineage" import { AltimateCoreValidateTool } from "../tools/altimate-core-validate" import { DataDiffTool } from "../tools/data-diff" +import { DbtCostEstimateTool } from "../tools/dbt-cost-estimate" +import { DbtCteProfileTool } from "../tools/dbt-cte-profile" +import { DbtDeferStateTool } from "../tools/dbt-defer-state" +import { DbtDocsCoverageTool } from "../tools/dbt-docs-coverage" +import { DbtHealthTool } from "../tools/dbt-health" import { DbtLineageTool } from "../tools/dbt-lineage" import { DbtManifestTool } from "../tools/dbt-manifest" +import { DbtMapRelationsTool } from "../tools/dbt-map-relations" import { DbtProfilesTool } from "../tools/dbt-profiles" +import { DbtRunResultsTool } from "../tools/dbt-run-results" +import { DbtSqlGraphTool } from "../tools/dbt-sql-graph" import { DbtUnitTestGenTool } from "../tools/dbt-unit-test-gen" +import { DocsShareCommentsTool } from "../tools/docs-share-comments" import { FinopsAnalyzeCreditsTool } from "../tools/finops-analyze-credits" import { FinopsExpensiveQueriesTool } from "../tools/finops-expensive-queries" import { FinopsQueryHistoryTool } from "../tools/finops-query-history" @@ -106,10 +115,19 @@ export const EXPOSED: Record = { altimate_core_track_lineage: AltimateCoreTrackLineageTool, altimate_core_validate: AltimateCoreValidateTool, data_diff: DataDiffTool, + dbt_cost_estimate: DbtCostEstimateTool, + dbt_cte_profile: DbtCteProfileTool, + dbt_defer_state: DbtDeferStateTool, + dbt_docs_coverage: DbtDocsCoverageTool, + dbt_health: DbtHealthTool, dbt_lineage: DbtLineageTool, dbt_manifest: DbtManifestTool, + dbt_map_relations: DbtMapRelationsTool, dbt_profiles: DbtProfilesTool, + dbt_run_results: DbtRunResultsTool, + dbt_sql_graph: DbtSqlGraphTool, dbt_unit_test_gen: DbtUnitTestGenTool, + docs_share_comments: DocsShareCommentsTool, finops_analyze_credits: FinopsAnalyzeCreditsTool, finops_expensive_queries: FinopsExpensiveQueriesTool, finops_query_history: FinopsQueryHistoryTool, diff --git a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts new file mode 100644 index 0000000000..a2711e35d1 --- /dev/null +++ b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts @@ -0,0 +1,100 @@ +import fs from "fs" +import path from "path" +import type { Tool } from "../../tool/tool" +import { projectRoot } from "../native/connections/registry" + +/** Why a tool may not use the dbt adapter. */ +export type DbtAdapterRefusal = "read_only" | "other_project" | "no_project" | "not_started" | "not_loaded" + +/** The project's dbt adapter, or why this call may not use it (`reason` is a sentence for the user). */ +export type DbtAdapterAccess = + | { adapter: any; refusal?: undefined; reason?: undefined } + | { adapter?: undefined; refusal: DbtAdapterRefusal; reason: string } + +/** Test seams. */ +export const dbtAdapterAccessInternals = { + /** How long a call waits for the dbt adapter to start before it gives up; the start goes on for the next call. */ + adapterStartTimeoutMs: 120_000, +} + +/** + * The dbt adapter for a tool call, which every adapter-backed tool goes through. Starting the adapter + * runs dbt deps and writes target/, and compiling renders Jinja, which can run SQL: a read-only call + * (no write permission, or plan mode) never starts or uses it. Nor does a session in a dbt project the + * adapter isn't set up for. The wait for the adapter to start is bounded and follows the call's abort. + */ +export async function dbtAdapterFor(ctx: Pick): Promise { + const signal = ctx.abort + if (ctx.extra?.forceReadOnly === true || ctx.agent === "plan") + return { + refusal: "read_only", + reason: "this needs the dbt adapter, which a read-only call doesn't start: re-run with --allow-write", + } + try { + const { getDbtAdapter, getDbtProjectRoot } = await import("../native/connections/register") + // The import yields: a call cancelled meanwhile starts nothing. + signal.throwIfAborted() + const project = await sessionProject() + signal.throwIfAborted() + if (project?.other) { + return { + refusal: "other_project", + reason: project.root + ? `the dbt adapter is set up for ${project.root}, not ${project.other}` + : `the dbt adapter isn't set up for ${project.other}`, + } + } + let stop = () => {} + let timer: ReturnType | undefined + const waited = new Promise((_, reject) => { + stop = () => reject(signal.reason) + signal.addEventListener("abort", stop, { once: true }) + const seconds = dbtAdapterAccessInternals.adapterStartTimeoutMs / 1000 + timer = setTimeout( + () => reject(new Error(`the dbt adapter didn't start within ${seconds} s`)), + dbtAdapterAccessInternals.adapterStartTimeoutMs, + ) + }) + const adapter = await Promise.race([getDbtAdapter(), waited]).finally(() => { + signal.removeEventListener("abort", stop) + clearTimeout(timer) + }) + if (!adapter) { + // No adapter also when the project exists but the adapter failed to start: say which. + const root = await getDbtProjectRoot() + const found = !!root && fs.existsSync(path.join(root, "dbt_project.yml")) + return found + ? { refusal: "not_started", reason: "the dbt adapter didn't start" } + : { refusal: "no_project", reason: "no dbt project here" } + } + if (adapter.isInitialized?.() === false) return { refusal: "not_loaded", reason: "the dbt adapter didn't load the project" } + return { adapter } + } catch (e) { + if (signal.aborted) throw e + return { refusal: "not_started", reason: e instanceof Error ? e.message : String(e) } + } +} + +/** + * The adapter's project root and, when the session's directory is in another dbt project, that one + * (`other`, both links resolved). Undefined when the session's directory is in no dbt project: the + * adapter's own discovery (a dbt.json, or a walk up from the working directory) decides then. + */ +async function sessionProject(): Promise<{ root?: string; other?: string } | undefined> { + const { findProjectRoot } = await import("../../../../dbt-tools/src/config") + const found = findProjectRoot(projectRoot()) + if (!found) return undefined + const { getDbtProjectRoot } = await import("../native/connections/register") + const root = await getDbtProjectRoot() + const real = (p: string) => { + try { + return fs.realpathSync(p) + } catch { + return path.resolve(p) + } + } + const here = real(found) + // path.relative ignores case on win32. + if (!root) return { other: here } + return path.relative(real(root), here) ? { root: real(root), other: here } : { root } +} diff --git a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts new file mode 100644 index 0000000000..6529d828c6 --- /dev/null +++ b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts @@ -0,0 +1,17 @@ +import z from "zod" +import { Tool } from "../../tool/tool" + +export const DbtCostEstimateTool = Tool.define("dbt_cost_estimate", { + description: "Estimate the bytes a dbt model or a SQL query would scan, from a warehouse dry run (BigQuery).", + parameters: z.object({ + model: z.string().optional().describe("Model name to compile and estimate"), + sql: z.string().optional().describe("SQL (may use Jinja) to compile and estimate"), + }), + async execute() { + return { + title: "dbt_cost_estimate: not implemented", + metadata: { success: false }, + output: "dbt_cost_estimate is not implemented in this build of altimate-code yet.", + } + }, +}) diff --git a/packages/opencode/src/altimate/tools/dbt-cte-profile.ts b/packages/opencode/src/altimate/tools/dbt-cte-profile.ts new file mode 100644 index 0000000000..e7a5bde647 --- /dev/null +++ b/packages/opencode/src/altimate/tools/dbt-cte-profile.ts @@ -0,0 +1,17 @@ +import z from "zod" +import { Tool } from "../../tool/tool" + +export const DbtCteProfileTool = Tool.define("dbt_cte_profile", { + description: "List a dbt model's CTEs, or time one CTE with a row-count query.", + parameters: z.object({ + model: z.string().describe("Model name"), + cte: z.string().optional().describe("CTE to time; without it, the CTE list is returned"), + }), + async execute() { + return { + title: "dbt_cte_profile: not implemented", + metadata: { success: false }, + output: "dbt_cte_profile is not implemented in this build of altimate-code yet.", + } + }, +}) diff --git a/packages/opencode/src/altimate/tools/dbt-defer-state.ts b/packages/opencode/src/altimate/tools/dbt-defer-state.ts new file mode 100644 index 0000000000..75cbfe19cf --- /dev/null +++ b/packages/opencode/src/altimate/tools/dbt-defer-state.ts @@ -0,0 +1,16 @@ +import z from "zod" +import { Tool } from "../../tool/tool" + +export const DbtDeferStateTool = Tool.define("dbt_defer_state", { + description: "dbt Power User's defer-to-production setting for a dbt project, and the profile's default target.", + parameters: z.object({ + project_dir: z.string().describe("dbt project folder"), + }), + async execute() { + return { + title: "dbt_defer_state: not implemented", + metadata: { success: false }, + output: "dbt_defer_state is not implemented in this build of altimate-code yet.", + } + }, +}) diff --git a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts new file mode 100644 index 0000000000..c4e0ec42d3 --- /dev/null +++ b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts @@ -0,0 +1,17 @@ +import z from "zod" +import { Tool } from "../../tool/tool" + +export const DbtDocsCoverageTool = Tool.define("dbt_docs_coverage", { + description: "Documentation coverage of a dbt model: which output columns have a description, and whether the model has one.", + parameters: z.object({ + model: z.string().describe("Model name"), + manifest_path: z.string().optional().describe("manifest.json to read (default: the dbt project's target/manifest.json)"), + }), + async execute() { + return { + title: "dbt_docs_coverage: not implemented", + metadata: { success: false }, + output: "dbt_docs_coverage is not implemented in this build of altimate-code yet.", + } + }, +}) diff --git a/packages/opencode/src/altimate/tools/dbt-health.ts b/packages/opencode/src/altimate/tools/dbt-health.ts new file mode 100644 index 0000000000..a3f26352c4 --- /dev/null +++ b/packages/opencode/src/altimate/tools/dbt-health.ts @@ -0,0 +1,16 @@ +import z from "zod" +import { Tool } from "../../tool/tool" + +export const DbtHealthTool = Tool.define("dbt_health", { + description: "DataPilot project health insights for the dbt project.", + parameters: z.object({ + config_path: z.string().optional().describe("DataPilot config file to use"), + }), + async execute() { + return { + title: "dbt_health: not implemented", + metadata: { success: false }, + output: "dbt_health is not implemented in this build of altimate-code yet.", + } + }, +}) diff --git a/packages/opencode/src/altimate/tools/dbt-map-relations.ts b/packages/opencode/src/altimate/tools/dbt-map-relations.ts new file mode 100644 index 0000000000..1216d6b2ee --- /dev/null +++ b/packages/opencode/src/altimate/tools/dbt-map-relations.ts @@ -0,0 +1,18 @@ +import z from "zod" +import { Tool } from "../../tool/tool" + +export const DbtMapRelationsTool = Tool.define("dbt_map_relations", { + description: "Map each table a raw SQL query reads to the dbt ref() or source() for it, from the manifest.", + parameters: z.object({ + sql: z.string().describe("Raw SQL to map"), + dialect: z.string().optional().describe("SQL dialect of the query"), + manifest_path: z.string().optional().describe("manifest.json to match against (default: the dbt project's target/manifest.json)"), + }), + async execute() { + return { + title: "dbt_map_relations: not implemented", + metadata: { success: false }, + output: "dbt_map_relations is not implemented in this build of altimate-code yet.", + } + }, +}) diff --git a/packages/opencode/src/altimate/tools/dbt-run-results.ts b/packages/opencode/src/altimate/tools/dbt-run-results.ts new file mode 100644 index 0000000000..86e68a1668 --- /dev/null +++ b/packages/opencode/src/altimate/tools/dbt-run-results.ts @@ -0,0 +1,16 @@ +import z from "zod" +import { Tool } from "../../tool/tool" + +export const DbtRunResultsTool = Tool.define("dbt_run_results", { + description: "The latest dbt run's results from target/run_results.json: command, duration and each node's status.", + parameters: z.object({ + project_dir: z.string().optional().describe("dbt project folder (default: the dbt project found from the working directory)"), + }), + async execute() { + return { + title: "dbt_run_results: not implemented", + metadata: { success: false }, + output: "dbt_run_results is not implemented in this build of altimate-code yet.", + } + }, +}) diff --git a/packages/opencode/src/altimate/tools/dbt-sql-graph.ts b/packages/opencode/src/altimate/tools/dbt-sql-graph.ts new file mode 100644 index 0000000000..b2af1b0f18 --- /dev/null +++ b/packages/opencode/src/altimate/tools/dbt-sql-graph.ts @@ -0,0 +1,16 @@ +import z from "zod" +import { Tool } from "../../tool/tool" + +export const DbtSqlGraphTool = Tool.define("dbt_sql_graph", { + description: "A dbt model's SQL as a graph: its CTEs, joins and filters, and the edges between them.", + parameters: z.object({ + model: z.string().describe("Model name"), + }), + async execute() { + return { + title: "dbt_sql_graph: not implemented", + metadata: { success: false }, + output: "dbt_sql_graph is not implemented in this build of altimate-code yet.", + } + }, +}) diff --git a/packages/opencode/src/altimate/tools/docs-share-comments.ts b/packages/opencode/src/altimate/tools/docs-share-comments.ts new file mode 100644 index 0000000000..2c8c0a2ab3 --- /dev/null +++ b/packages/opencode/src/altimate/tools/docs-share-comments.ts @@ -0,0 +1,20 @@ +import z from "zod" +import { Tool } from "../../tool/tool" + +export const DocsShareCommentsTool = Tool.define("docs_share_comments", { + description: "Comment threads on shared dbt docs: list open threads, reply to one, or resolve one.", + parameters: z.object({ + action: z.enum(["list", "reply", "resolve"]).describe("What to do"), + project: z.string().optional().describe("dbt project name the shared docs belong to"), + share_id: z.number().int().optional().describe("Shared docs id"), + group_id: z.number().int().optional().describe("Comment thread id"), + text: z.string().optional().describe("Reply text"), + }), + async execute() { + return { + title: "docs_share_comments: not implemented", + metadata: { success: false }, + output: "docs_share_comments is not implemented in this build of altimate-code yet.", + } + }, +}) diff --git a/packages/opencode/test/altimate/dbt-adapter-access.test.ts b/packages/opencode/test/altimate/dbt-adapter-access.test.ts new file mode 100644 index 0000000000..b565e5a58a --- /dev/null +++ b/packages/opencode/test/altimate/dbt-adapter-access.test.ts @@ -0,0 +1,221 @@ +// The tools the dbt Power User features call: their allow-list entries and placeholder answers, the +// one gate every dbt-adapter-backed tool goes through, and the API helper for new endpoint files. The +// dbt adapter is replaced through `dbtAdapterInternals`, so these tests need no Python or dbt. +import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test" +import { mkdtemp, rm, writeFile } from "node:fs/promises" +import { realpathSync } from "node:fs" +import os from "node:os" +import path from "node:path" +import { Effect } from "effect" +import type { Tool } from "@/tool/tool" +import { SessionID, MessageID } from "@/session/schema" +import { dbtAdapterInternals, resetDbtAdapter } from "@/altimate/native/connections/register" +import { dbtAdapterAccessInternals, dbtAdapterFor } from "@/altimate/tools/dbt-adapter-access" +import { EXPOSED, MCP_OPEN_WRITE_TOOLS, WRITE_TOOLS } from "@/altimate/tool-cli/allow-list" +import { AltimateApi } from "@/altimate/api/client" +import { Instance } from "@/project/instance" +import { disposeInstance } from "@/effect/instance-registry" +import { initTool } from "./tool-fixture" + +/** Each tool with the smallest arguments its parameters accept. */ +const MINIMAL_ARGS: Record> = { + dbt_run_results: {}, + dbt_defer_state: { project_dir: "." }, + dbt_map_relations: { sql: "select 1" }, + docs_share_comments: { action: "list" }, + dbt_cost_estimate: {}, + dbt_health: {}, + dbt_sql_graph: { model: "customers" }, + dbt_docs_coverage: { model: "customers" }, + dbt_cte_profile: { model: "customers" }, +} +const FEATURE_TOOLS = Object.keys(MINIMAL_ARGS) + +const ctx: Tool.Context = { + sessionID: SessionID.make("ses_dbt_adapter_access"), + messageID: MessageID.make("msg_dbt_adapter_access"), + agent: "analyst", + abort: new AbortController().signal, + messages: [], + metadata: () => Effect.void, + ask: () => Effect.void, +} + +let project: string + +function useConfig() { + dbtAdapterInternals.readConfig = async () => ({ + projectRoot: project, + pythonPath: "python3", + dbtIntegration: "corecommand", + queryLimit: 500, + }) +} + +beforeAll(async () => { + project = await mkdtemp(path.join(os.tmpdir(), "dbt-adapter-access-")) + await writeFile(path.join(project, "dbt_project.yml"), "name: jaffle_shop\n") +}) + +afterAll(async () => { + await rm(project, { recursive: true, force: true }) +}) + +beforeEach(() => resetDbtAdapter()) + +afterEach(() => { + resetDbtAdapter() + delete dbtAdapterInternals.readConfig + delete dbtAdapterInternals.create +}) + +describe("feature tools in the allow-list", () => { + test("all nine are exposed, in the map's alphabetical order, and none is a write tool", () => { + const ids = Object.keys(EXPOSED) + for (const id of FEATURE_TOOLS) { + expect(ids).toContain(id) + expect(WRITE_TOOLS.has(id)).toBe(false) + expect(MCP_OPEN_WRITE_TOOLS.has(id)).toBe(false) + } + const listed = ids.filter((id) => id.startsWith("dbt_") || id.startsWith("docs_")) + expect(listed).toEqual([...listed].sort()) + }) + + test("each placeholder answers that it isn't implemented, as a failure", async () => { + for (const id of FEATURE_TOOLS) { + const tool = await initTool(EXPOSED[id] as any) + expect(tool.id).toBe(id) + const result = await tool.execute(MINIMAL_ARGS[id], ctx) + expect(result.title).toBe(`${id}: not implemented`) + expect(result.metadata.success).toBe(false) + expect(result.output).toContain(id) + } + }) +}) + +describe("dbtAdapterFor", () => { + let created: number + beforeEach(() => { + created = 0 + useConfig() + dbtAdapterInternals.create = async () => { + created += 1 + return { isInitialized: () => true, dispose: async () => {} } + } + }) + + test("refuses a read-only call and never creates the adapter", async () => { + const access = await dbtAdapterFor({ ...ctx, extra: { forceReadOnly: true } }) + expect(access.adapter).toBeUndefined() + expect(access.refusal).toBe("read_only") + expect(access.reason).toContain("--allow-write") + expect(created).toBe(0) + }) + + test("refuses a plan-mode call", async () => { + const access = await dbtAdapterFor({ ...ctx, agent: "plan" }) + expect(access.refusal).toBe("read_only") + expect(created).toBe(0) + }) + + test("returns the adapter where writes are allowed", async () => { + const access = await dbtAdapterFor(ctx) + expect(access.refusal).toBeUndefined() + expect(access.adapter?.isInitialized()).toBe(true) + expect(created).toBe(1) + }) + + test("says when the adapter didn't load the project", async () => { + dbtAdapterInternals.create = async () => ({ isInitialized: () => false, dispose: async () => {} }) + const access = await dbtAdapterFor(ctx) + expect(access).toEqual({ refusal: "not_loaded", reason: "the dbt adapter didn't load the project" }) + }) + + test("says there is no dbt project when the config finds none", async () => { + dbtAdapterInternals.readConfig = async () => null + const access = await dbtAdapterFor(ctx) + expect(access).toEqual({ refusal: "no_project", reason: "no dbt project here" }) + }) + + test("says when the adapter doesn't start in time", async () => { + dbtAdapterInternals.create = () => new Promise(() => {}) + const saved = dbtAdapterAccessInternals.adapterStartTimeoutMs + dbtAdapterAccessInternals.adapterStartTimeoutMs = 20 + try { + const access = await dbtAdapterFor(ctx) + expect(access).toEqual({ refusal: "not_started", reason: "the dbt adapter didn't start within 0.02 s" }) + } finally { + dbtAdapterAccessInternals.adapterStartTimeoutMs = saved + } + }) + + test("a cancelled call throws rather than answering", async () => { + const controller = new AbortController() + controller.abort() + await expect(dbtAdapterFor({ ...ctx, abort: controller.signal })).rejects.toThrow() + expect(created).toBe(0) + }) + + test("a session in a dbt project the adapter isn't set up for says so", async () => { + dbtAdapterInternals.readConfig = async () => null + try { + const access = await Instance.provide({ directory: project, fn: () => dbtAdapterFor(ctx) }) + expect(access).toEqual({ + refusal: "other_project", + reason: `the dbt adapter isn't set up for ${realpathSync(project)}`, + }) + expect(created).toBe(0) + } finally { + await disposeInstance(project) + } + }) +}) + +describe("AltimateApi.apiRequest", () => { + let home: string + let saved: string | undefined + beforeEach(async () => { + home = await mkdtemp(path.join(os.tmpdir(), "altimate-api-home-")) + saved = process.env.OPENCODE_TEST_HOME + process.env.OPENCODE_TEST_HOME = home + }) + afterEach(async () => { + if (saved === undefined) delete process.env.OPENCODE_TEST_HOME + else process.env.OPENCODE_TEST_HOME = saved + await rm(home, { recursive: true, force: true }) + }) + + test("fails with a clear message when no credentials are stored", async () => { + await expect(AltimateApi.apiRequest("GET", "/dbt/v1/x")).rejects.toThrow( + `No Altimate credentials are stored: sign in to Altimate in altimate-code first (they are saved to ${path.join(home, ".altimate", "altimate.json")}).`, + ) + }) + + test("sends the stored key and tenant and returns the JSON body", async () => { + await Bun.write( + path.join(home, ".altimate", "altimate.json"), + JSON.stringify({ altimateUrl: "https://api.example.test/", altimateInstanceName: "acme", altimateApiKey: "k1" }), + ) + const original = globalThis.fetch + const seen: { url: string; init: RequestInit }[] = [] + globalThis.fetch = (async (url: string, init: RequestInit) => { + seen.push({ url, init }) + return new Response(JSON.stringify({ ok: 1 }), { status: 200 }) + }) as unknown as typeof fetch + try { + expect(await AltimateApi.apiRequest("POST", "/dbt/v1/x", { a: 1 })).toEqual({ ok: 1 }) + expect(seen[0].url).toBe("https://api.example.test/dbt/v1/x") + const headers = seen[0].init.headers as Record + expect(headers.Authorization).toBe("Bearer k1") + expect(headers["x-tenant"]).toBe("acme") + expect(seen[0].init.body).toBe(JSON.stringify({ a: 1 })) + } finally { + globalThis.fetch = original + } + }) + + test("names the file when the stored credentials can't be read", async () => { + await Bun.write(path.join(home, ".altimate", "altimate.json"), "{not json") + await expect(AltimateApi.apiRequest("GET", "/dbt/v1/x")).rejects.toThrow("can't be used") + }) +}) From 69b26cd0f62c7fdbd4fd8b14bb2a61dbe26050ff Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 16:52:23 +0530 Subject: [PATCH 4/9] fix: column reach rates a column read through a schema-qualified relation by what the SQL does, not Not sure Co-Authored-By: Claude Sonnet 5.5 --- .../src/altimate/native/dbt/column-reach.ts | 56 ++++++++++++++++++- .../test/altimate/column-reach.test.ts | 14 +++++ 2 files changed, 68 insertions(+), 2 deletions(-) diff --git a/packages/opencode/src/altimate/native/dbt/column-reach.ts b/packages/opencode/src/altimate/native/dbt/column-reach.ts index 71a6d43376..d0c91bfd30 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -6,7 +6,8 @@ // lineage engine cannot settle is reported as such: models it could not trace (no compiled SQL, or // SQL it could not parse), models that name the column only outside their select list (where the // engine reports no edge), and models that read it through a table name several parents share. -import { loadRawManifest, findModel } from "./helpers" +import * as core from "@altimateai/altimate-core" +import { loadRawManifest, findModel, detectDialect } from "./helpers" import { dbtLineage } from "./lineage" export interface ColumnReachModel { @@ -107,6 +108,56 @@ function relationKeys(node: any): string[] { return [...keys] } +type LineageEdge = { source: unknown; target: string; lineage_type?: string; lens_type?: string } + +/** + * The engine rates every edge "Not sure" when the table it reads is written with its schema + * ("db"."schema"."orders", as dbt compiles a ref) and its schema lists that table by bare name only. + * The model's SQL is traced again with each parent listed under every way its relation is written, + * and an edge both runs report (matched by output column, table name and source column, as the + * first run drops the qualification) takes the second run's rating. Anything else keeps its own. + */ +function rated( + edges: LineageEdge[], + sql: string, + dialect: string, + parents: string[], + lookup: (id: string) => any, +): LineageEdge[] { + if (!sql || parents.length === 0 || !edges.some((edge) => edge.lens_type === "Not sure")) return edges + try { + const tables: Record = {} + for (const parent of parents) { + const node = lookup(parent) + const columns = Object.entries(node?.columns ?? {}).map(([key, col]) => ({ + name: String(col?.name ?? key), + type: String(col?.data_type ?? col?.type ?? ""), + })) + if (columns.length === 0) continue + for (const key of relationKeys(node)) tables[key] = { columns } + } + if (Object.keys(tables).length === 0) return edges + const schema = core.Schema.fromJson(JSON.stringify({ tables, version: "1" })) + const again: LineageEdge[] = JSON.parse(JSON.stringify(core.columnLineage(sql, dialect, schema))).column_lineage ?? [] + const keyOf = (edge: LineageEdge) => { + const source = splitSource(edge.source) + return source ? `${String(edge.target).toLowerCase()}|${source.parts.at(-1)}.${source.column}` : null + } + const lenses = new Map() + for (const edge of again) { + const key = keyOf(edge) + if (key && typeof edge.lens_type === "string") lenses.set(key, edge.lens_type) + } + return edges.map((edge) => { + const key = edge.lens_type === "Not sure" ? keyOf(edge) : null + const lens = key ? lenses.get(key) : undefined + return lens ? { ...edge, lens_type: lens } : edge + }) + } catch { + return edges + } +} + /** * The parents an edge's source table names, matched at the qualification the edge carries: a * qualified name that matches no parent names none (it is some other relation), and a bare name @@ -352,7 +403,7 @@ export function columnReach(manifestPath: string, model: string, column: string, unsure.add(id) continue } - const edges: { source: unknown; target: string; lineage_type?: string; lens_type?: string }[] = lineage + const listed: LineageEdge[] = lineage ?.column_lineage?.length ? lineage.column_lineage : Object.entries(lineage?.column_dict ?? {}).flatMap(([out, sources]) => @@ -369,6 +420,7 @@ export function columnReach(manifestPath: string, model: string, column: string, // cannot say which one is read; a `select *` from a parent whose schema does not list the // column cannot be expanded to it. Both are possible reads with unknown outputs. const sqlText: string = nodes[id]?.compiled_code || nodes[id]?.compiled_sql || "" + const edges = rated(listed, sqlText, dialect ?? detectDialect(manifest), allParents, lookup) const bareName = (p: string) => { const node = lookup(p) return String(node?.alias || node?.identifier || node?.name || p).toLowerCase() diff --git a/packages/opencode/test/altimate/column-reach.test.ts b/packages/opencode/test/altimate/column-reach.test.ts index ec230a6c16..76e618ab20 100644 --- a/packages/opencode/test/altimate/column-reach.test.ts +++ b/packages/opencode/test/altimate/column-reach.test.ts @@ -127,6 +127,20 @@ describe("columnReach", () => { }) }) + test("a column read through a schema-qualified relation, as a compiled ref is written, keeps its real rating", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.stg_qualified"] = model( + "stg_qualified", + ["model.shop.fct_orders"], + 'select revenue as net, revenue from "shop"."main"."fct_orders"', + ["net", "revenue"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + const found = reach.models.find((m) => m.name === "stg_qualified") + expect(found?.lens_types).toEqual({ net: "Alias", revenue: "Original" }) + }) + test("a column copied as is is Original, and a copy of a calculation is never Original", () => { const value = manifest() const nodes = value.nodes as Record From 21d0494cfbb1c87a2b1b3ba6e347f4f1be149856 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 17:01:49 +0530 Subject: [PATCH 5/9] fix: harden the dbt Power User tool foundation Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/api/client.ts | 4 +- .../src/altimate/tools/dbt-adapter-access.ts | 3 +- .../src/altimate/tools/dbt-cost-estimate.ts | 2 +- .../src/altimate/tools/dbt-cte-profile.ts | 2 +- .../src/altimate/tools/dbt-defer-state.ts | 2 +- .../src/altimate/tools/dbt-docs-coverage.ts | 10 ++-- .../opencode/src/altimate/tools/dbt-health.ts | 2 +- .../src/altimate/tools/dbt-map-relations.ts | 7 ++- .../src/altimate/tools/dbt-run-results.ts | 7 ++- .../src/altimate/tools/dbt-sql-graph.ts | 2 +- .../src/altimate/tools/docs-share-comments.ts | 2 +- .../test/altimate/dbt-adapter-access.test.ts | 52 ++++++++++++++++++- 12 files changed, 78 insertions(+), 17 deletions(-) diff --git a/packages/opencode/src/altimate/api/client.ts b/packages/opencode/src/altimate/api/client.ts index 069a182b7a..cb53c0ec7b 100644 --- a/packages/opencode/src/altimate/api/client.ts +++ b/packages/opencode/src/altimate/api/client.ts @@ -359,7 +359,9 @@ export namespace AltimateApi { } catch (e) { const p = credentialsPath() if (!(await Filesystem.exists(p))) - throw new Error(`No Altimate credentials are stored: sign in to Altimate in altimate-code first (they are saved to ${p}).`) + throw new Error( + `No Altimate credentials are stored: sign in to Altimate in altimate-code first (they are saved to ${p}).`, + ) throw new Error(`The Altimate credentials in ${p} can't be used: ${e instanceof Error ? e.message : String(e)}`) } return request(creds, method, endpoint, body) diff --git a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts index a2711e35d1..d73dd7e9c5 100644 --- a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts +++ b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts @@ -67,7 +67,8 @@ export async function dbtAdapterFor(ctx: Pick { expect(tool.id).toBe(id) const result = await tool.execute(MINIMAL_ARGS[id], ctx) expect(result.title).toBe(`${id}: not implemented`) - expect(result.metadata.success).toBe(false) + expect(result.metadata).toEqual({ success: false, error: "not implemented", truncated: false }) expect(result.output).toContain(id) } }) @@ -149,6 +149,30 @@ describe("dbtAdapterFor", () => { } }) + test("says the adapter didn't start when the project exists but creating it fails", async () => { + dbtAdapterInternals.create = async () => { + created += 1 + throw new Error("dbt-integration missing") + } + const access = await dbtAdapterFor(ctx) + expect(access).toEqual({ refusal: "not_started", reason: "the dbt adapter didn't start" }) + expect(created).toBe(1) + }) + + test("a call cancelled while the adapter starts throws and stops waiting", async () => { + let entered = () => {} + const starting = new Promise((resolve) => (entered = resolve)) + dbtAdapterInternals.create = () => { + entered() + return new Promise(() => {}) + } + const controller = new AbortController() + const pending = dbtAdapterFor({ ...ctx, abort: controller.signal }) + await starting + controller.abort(new Error("cancelled")) + await expect(pending).rejects.toThrow("cancelled") + }) + test("a cancelled call throws rather than answering", async () => { const controller = new AbortController() controller.abort() @@ -169,6 +193,28 @@ describe("dbtAdapterFor", () => { await disposeInstance(project) } }) + + test("a session in another dbt project than the adapter's says which", async () => { + const other = await mkdtemp(path.join(os.tmpdir(), "dbt-adapter-other-")) + await writeFile(path.join(other, "dbt_project.yml"), "name: other\n") + dbtAdapterInternals.readConfig = async () => ({ + projectRoot: other, + pythonPath: "python3", + dbtIntegration: "corecommand", + queryLimit: 500, + }) + try { + const access = await Instance.provide({ directory: project, fn: () => dbtAdapterFor(ctx) }) + expect(access).toEqual({ + refusal: "other_project", + reason: `the dbt adapter is set up for ${realpathSync(other)}, not ${realpathSync(project)}`, + }) + expect(created).toBe(0) + } finally { + await disposeInstance(project) + await rm(other, { recursive: true, force: true }) + } + }) }) describe("AltimateApi.apiRequest", () => { @@ -216,6 +262,8 @@ describe("AltimateApi.apiRequest", () => { test("names the file when the stored credentials can't be read", async () => { await Bun.write(path.join(home, ".altimate", "altimate.json"), "{not json") - await expect(AltimateApi.apiRequest("GET", "/dbt/v1/x")).rejects.toThrow("can't be used") + await expect(AltimateApi.apiRequest("GET", "/dbt/v1/x")).rejects.toThrow( + `The Altimate credentials in ${path.join(home, ".altimate", "altimate.json")} can't be used`, + ) }) }) From 978c8cebd2b803e6aa394199afd40967d8a04ef3 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 17:02:40 +0530 Subject: [PATCH 6/9] style: format column reach and the impact analysis test Co-Authored-By: Claude Sonnet 5.5 --- packages/opencode/src/altimate/native/dbt/column-reach.ts | 6 +++--- packages/opencode/test/altimate/impact-analysis.test.ts | 8 +++++++- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/packages/opencode/src/altimate/native/dbt/column-reach.ts b/packages/opencode/src/altimate/native/dbt/column-reach.ts index d0c91bfd30..67cd38d027 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -138,7 +138,8 @@ function rated( } if (Object.keys(tables).length === 0) return edges const schema = core.Schema.fromJson(JSON.stringify({ tables, version: "1" })) - const again: LineageEdge[] = JSON.parse(JSON.stringify(core.columnLineage(sql, dialect, schema))).column_lineage ?? [] + const again: LineageEdge[] = + JSON.parse(JSON.stringify(core.columnLineage(sql, dialect, schema))).column_lineage ?? [] const keyOf = (edge: LineageEdge) => { const source = splitSource(edge.source) return source ? `${String(edge.target).toLowerCase()}|${source.parts.at(-1)}.${source.column}` : null @@ -403,8 +404,7 @@ export function columnReach(manifestPath: string, model: string, column: string, unsure.add(id) continue } - const listed: LineageEdge[] = lineage - ?.column_lineage?.length + const listed: LineageEdge[] = lineage?.column_lineage?.length ? lineage.column_lineage : Object.entries(lineage?.column_dict ?? {}).flatMap(([out, sources]) => (Array.isArray(sources) ? sources : [sources]).map((source) => ({ diff --git a/packages/opencode/test/altimate/impact-analysis.test.ts b/packages/opencode/test/altimate/impact-analysis.test.ts index 7b528b8326..61845bbc15 100644 --- a/packages/opencode/test/altimate/impact-analysis.test.ts +++ b/packages/opencode/test/altimate/impact-analysis.test.ts @@ -331,7 +331,13 @@ describe("impact_analysis: column reach carries how each column comes from the t }) const tool = await initTool(ImpactAnalysisTool) const result = await tool.execute( - { model: "fct_orders", column: "revenue", change_type: "modify", manifest_path: manifestPath, dialect: "duckdb" }, + { + model: "fct_orders", + column: "revenue", + change_type: "modify", + manifest_path: manifestPath, + dialect: "duckdb", + }, ctx, ) const reach = result.metadata.column_reach as { models: { name: string; lens_types?: Record }[] } From 2a415fe08c2af0029ea5603c6f46d629c6eff2b7 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 17:19:12 +0530 Subject: [PATCH 7/9] fix: docs coverage keeps quoted names that differ by case apart, reports unknown select * columns instead of 100%, and column reach keeps a __proto__ column's rating Co-Authored-By: Claude Sonnet 5.5 --- .../src/altimate/native/dbt/column-reach.ts | 16 +++++--- .../src/altimate/tools/dbt-docs-coverage.ts | 33 +++++++++------- .../test/altimate/column-reach.test.ts | 28 +++++++++++++ .../test/altimate/dbt-docs-coverage.test.ts | 39 +++++++++++++++++-- 4 files changed, 94 insertions(+), 22 deletions(-) diff --git a/packages/opencode/src/altimate/native/dbt/column-reach.ts b/packages/opencode/src/altimate/native/dbt/column-reach.ts index 67cd38d027..3fc024e574 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -147,7 +147,9 @@ function rated( const lenses = new Map() for (const edge of again) { const key = keyOf(edge) - if (key && typeof edge.lens_type === "string") lenses.set(key, edge.lens_type) + // Edges into one output from the same column keep the one furthest from unchanged. + if (key && typeof edge.lens_type === "string") + lenses.set(key, joinLens(lenses.get(key), edge.lens_type) ?? edge.lens_type) } return edges.map((edge) => { const key = edge.lens_type === "Not sure" ? keyOf(edge) : null @@ -487,11 +489,13 @@ export function columnReach(manifestPath: string, model: string, column: string, // A NATURAL JOIN beside the column may join on it, or carry it on in another output. if (ambiguous || fromUnsure || viaEphemeral || partial || opaque) unsure.add(id) const columns = [...carried].sort() - const lens_types: Record = {} - for (const col of columns) { - const lens = carriedLens.get(col) - if (lens !== undefined) lens_types[col] = lens - } + // Built with fromEntries: assigning to a column named __proto__ would set the prototype instead. + const lens_types: Record = Object.fromEntries( + columns.flatMap((col) => { + const lens = carriedLens.get(col) + return lens === undefined ? [] : [[col, lens] as const] + }), + ) reached.push({ name: nodes[id]?.name ?? id, unique_id: id, diff --git a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts index e1de26fb13..f7fa11f61a 100644 --- a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts +++ b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts @@ -26,12 +26,12 @@ export interface DocsCoverage { const hasText = (value: unknown) => typeof value === "string" && value.trim().length > 0 -/** Coverage of one manifest model node. Throws when the node has no compiled SQL or the engine cannot read it. */ +/** Coverage of one manifest model node. Throws when the node has no compiled SQL, the engine cannot read it, or it selects `*` and the manifest lists no columns. */ export function docsCoverage(node: any, dialect: string | undefined): DocsCoverage { const yamlColumns: Record = node.columns ?? {} const described = new Set() for (const [key, col] of Object.entries(yamlColumns)) { - if (hasText(col?.description)) described.add(String(col?.name || key).toLowerCase()) + if (hasText(col?.description)) described.add(String(col?.name || key)) } const sql: string = node.compiled_code || node.compiled_sql || "" @@ -45,24 +45,31 @@ export function docsCoverage(node: any, dialect: string | undefined): DocsCovera } catch (e) { // A `select *` names no columns, so the engine refuses it; the manifest's own columns are then // the best list there is. Any other failure is the SQL's, and is reported. - if (!/star/i.test(e instanceof Error ? e.message : String(e))) throw e + if (!/due to star\b/i.test(e instanceof Error ? e.message : String(e))) throw e outputs = [] source = "manifest_columns" } - if (outputs.some((c) => c.includes("*"))) source = "manifest_columns" + if (outputs.includes("*")) source = "manifest_columns" if (source === "manifest_columns") { outputs = Object.entries(yamlColumns).map(([key, col]) => String(col?.name || key)) } - const seen = new Set() - const columns = outputs.filter((c) => { - const k = c.toLowerCase() - if (seen.has(k)) return false - seen.add(k) - return true - }) - const documented = columns.filter((c) => described.has(c.toLowerCase())) - const missing = columns.filter((c) => !described.has(c.toLowerCase())) + if (source === "manifest_columns" && outputs.length === 0) { + throw new Error( + `Model "${node.name}" selects \`*\` and the manifest lists no columns for it, so its columns are not known. List them in its YAML or run \`dbt docs generate\`.`, + ) + } + + const columns = [...new Set(outputs)] + // Names that differ only by case are different columns when quoted, so they are matched as written; + // any other name is matched ignoring case, as a warehouse folds an unquoted one. + const byCase = new Map() + for (const c of columns) byCase.set(c.toLowerCase(), (byCase.get(c.toLowerCase()) ?? 0) + 1) + const describedFolded = new Set([...described].map((c) => c.toLowerCase())) + const isDocumented = (c: string) => + byCase.get(c.toLowerCase()) === 1 ? describedFolded.has(c.toLowerCase()) : described.has(c) + const documented = columns.filter(isDocumented) + const missing = columns.filter((c) => !isDocumented(c)) const percent = columns.length === 0 ? 100 : Math.round((documented.length / columns.length) * 1000) / 10 return { model: node.name, diff --git a/packages/opencode/test/altimate/column-reach.test.ts b/packages/opencode/test/altimate/column-reach.test.ts index 76e618ab20..bdf663468e 100644 --- a/packages/opencode/test/altimate/column-reach.test.ts +++ b/packages/opencode/test/altimate/column-reach.test.ts @@ -141,6 +141,34 @@ describe("columnReach", () => { expect(found?.lens_types).toEqual({ net: "Alias", revenue: "Original" }) }) + test("a column named __proto__ keeps its rating", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.stg_proto"] = model( + "stg_proto", + ["model.shop.fct_orders"], + 'select revenue as "__proto__" from fct_orders', + ["__proto__"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + const found = reach.models.find((m) => m.name === "stg_proto") + expect(found?.columns).toEqual(["__proto__"]) + expect(Object.entries(found?.lens_types ?? {})).toEqual([["__proto__", "Alias"]]) + }) + + test("a union of a column and a calculation of it through a qualified relation is a Transformation", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.stg_union"] = model( + "stg_union", + ["model.shop.fct_orders"], + 'select revenue from "shop"."main"."fct_orders" union all select revenue * 2 as revenue from "shop"."main"."fct_orders"', + ["revenue"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + expect(reach.models.find((m) => m.name === "stg_union")?.lens_types).toEqual({ revenue: "Transformation" }) + }) + test("a column copied as is is Original, and a copy of a calculation is never Original", () => { const value = manifest() const nodes = value.nodes as Record diff --git a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts index 0f50eb05b3..5ed1cbc236 100644 --- a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts +++ b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts @@ -2,7 +2,7 @@ * Tests for dbt_docs_coverage: output columns of the compiled SQL against the manifest's described * columns. Fixture manifests only; nothing here reaches a warehouse or a dbt project. */ -import { describe, test, expect, beforeEach, afterAll } from "bun:test" +import { describe, test, expect, beforeEach, afterEach, afterAll } from "bun:test" import { mkdtempSync, rmSync, writeFileSync } from "node:fs" import { tmpdir } from "node:os" import { join } from "node:path" @@ -76,6 +76,39 @@ describe("docsCoverage", () => { expect(r.missing).toEqual(["customer_id"]) }) + test("quoted names that differ only by case are different columns", () => { + const r = docsCoverage( + { + ...orders, + compiled_code: 'select "Foo", "foo" from t', + columns: { Foo: { name: "Foo", description: "Capital" } }, + }, + "snowflake", + ) + expect(r.output_columns).toEqual(["Foo", "foo"]) + expect(r.documented).toEqual(["Foo"]) + expect(r.missing).toEqual(["foo"]) + }) + + test("a literal asterisk in a column name is not a wildcard", () => { + const r = docsCoverage({ ...orders, compiled_code: 'select "a*b" from t' }, "snowflake") + expect(r.source).toBe("compiled_sql") + expect(r.output_columns).toEqual(["a*b"]) + expect(r.missing).toEqual(["a*b"]) + }) + + test("a column read that merely contains the letters star is the SQL's error, not a wildcard", () => { + expect(() => docsCoverage({ ...orders, compiled_code: "select start_time + 1 from t" }, "snowflake")).toThrow( + "unable to determine output column name", + ) + }) + + test("select * with no columns in the manifest is an error, not full coverage", () => { + expect(() => + docsCoverage({ ...orders, columns: {}, compiled_code: "select * from raw.orders" }, "snowflake"), + ).toThrow("its columns are not known") + }) + test("a model without compiled SQL is an error, not full coverage", () => { expect(() => docsCoverage({ ...orders, compiled_code: "" }, "snowflake")).toThrow("no compiled SQL") }) @@ -86,8 +119,8 @@ describe("dbt_docs_coverage tool", () => { beforeEach(() => { dir = mkdtempSync(join(tmpdir(), "docs-coverage-")) }) - afterAll(() => { - if (dir) rmSync(dir, { recursive: true, force: true }) + afterEach(() => { + rmSync(dir, { recursive: true, force: true }) }) test("reports coverage from a manifest file", async () => { From a05cec9fece3d43faa9ce1f7450cbb977f96bbc5 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 21:41:50 +0530 Subject: [PATCH 8/9] test: the placeholder check leaves out dbt_docs_coverage, which is implemented Co-Authored-By: Claude Sonnet 5.5 --- packages/opencode/test/altimate/dbt-adapter-access.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/opencode/test/altimate/dbt-adapter-access.test.ts b/packages/opencode/test/altimate/dbt-adapter-access.test.ts index b2a012ed58..c61bfda585 100644 --- a/packages/opencode/test/altimate/dbt-adapter-access.test.ts +++ b/packages/opencode/test/altimate/dbt-adapter-access.test.ts @@ -82,7 +82,7 @@ describe("feature tools in the allow-list", () => { }) test("each placeholder answers that it isn't implemented, as a failure", async () => { - for (const id of FEATURE_TOOLS) { + for (const id of FEATURE_TOOLS.filter((tool) => tool !== "dbt_docs_coverage")) { const tool = await initTool(EXPOSED[id] as any) expect(tool.id).toBe(id) const result = await tool.execute(MINIMAL_ARGS[id], ctx) From 0acf97071051a9b4e4c1ab23d258c271c2db23f6 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 21:49:31 +0530 Subject: [PATCH 9/9] fix: dbt_docs_coverage failures carry an error so the CLI and MCP report them as errors, and a star's note says columns added beside it are not counted Co-Authored-By: Claude Sonnet 5.5 --- .../src/altimate/tools/dbt-docs-coverage.ts | 8 +++++--- .../test/altimate/dbt-docs-coverage.test.ts | 18 ++++++++++++++++++ 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts index f7fa11f61a..6178ca2067 100644 --- a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts +++ b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts @@ -103,7 +103,7 @@ export const DbtDocsCoverageTool = Tool.define("dbt_docs_coverage", { if (!manifest) { return { title: "Docs coverage: NO MANIFEST", - metadata: { success: false }, + metadata: { success: false, error: `No manifest at ${args.manifest_path}` }, output: `No manifest at ${args.manifest_path}. Run \`dbt compile\` first to generate it.`, } } @@ -111,7 +111,7 @@ export const DbtDocsCoverageTool = Tool.define("dbt_docs_coverage", { if (!node) { return { title: "Docs coverage: MODEL NOT FOUND", - metadata: { success: false }, + metadata: { success: false, error: `Model "${args.model}" not found` }, output: `Model "${args.model}" not found in the manifest at ${args.manifest_path}.`, } } @@ -122,7 +122,9 @@ export const DbtDocsCoverageTool = Tool.define("dbt_docs_coverage", { ] if (result.missing.length > 0) lines.push(`Missing descriptions: ${result.missing.join(", ")}`) if (result.source === "manifest_columns") - lines.push("The model selects `*`, so its columns are the ones the manifest lists.") + lines.push( + "The model selects `*`, so only the columns the manifest lists are counted; a column the SQL adds beside `*` is not.", + ) return { title: `Docs coverage: ${result.model} ${result.percent}%`, metadata: { success: true, ...result }, diff --git a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts index 5ed1cbc236..9f947b2f14 100644 --- a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts +++ b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts @@ -109,6 +109,22 @@ describe("docsCoverage", () => { ).toThrow("its columns are not known") }) + test("a star beside named columns says that only the manifest's columns are counted", async () => { + const dir = mkdtempSync(join(tmpdir(), "docs-coverage-star-")) + try { + const path = join(dir, "manifest.json") + const node = { ...orders, compiled_code: "select *, 1 as extra from raw.orders" } + writeFileSync(path, JSON.stringify(manifest({ [orders.unique_id]: node }))) + const tool = await initTool(DbtDocsCoverageTool) + const r = await tool.execute({ model: "orders", manifest_path: path }, ctx as any) + expect(r.metadata.source).toBe("manifest_columns") + expect(r.metadata.output_columns).toEqual(["id", "customer_id", "status"]) + expect(r.output).toContain("a column the SQL adds beside `*` is not") + } finally { + rmSync(dir, { recursive: true, force: true }) + } + }) + test("a model without compiled SQL is an error, not full coverage", () => { expect(() => docsCoverage({ ...orders, compiled_code: "" }, "snowflake")).toThrow("no compiled SQL") }) @@ -139,6 +155,7 @@ describe("dbt_docs_coverage tool", () => { const tool = await initTool(DbtDocsCoverageTool) const r = await tool.execute({ model: "nope", manifest_path: path }, ctx as any) expect(r.metadata.success).toBe(false) + expect(r.metadata.error).toContain('Model "nope" not found') expect(r.output).toContain("not found") }) @@ -146,6 +163,7 @@ describe("dbt_docs_coverage tool", () => { const tool = await initTool(DbtDocsCoverageTool) const r = await tool.execute({ model: "orders", manifest_path: join(dir, "absent.json") }, ctx as any) expect(r.metadata.success).toBe(false) + expect(r.metadata.error).toContain("No manifest") expect(r.output).toContain("dbt compile") }) })