From 444f1f4ccfee929f5a7371498437ba13126f94d6 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 15:38:44 +0530 Subject: [PATCH 01/29] 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 02/29] 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 03/29] 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 04/29] 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 05/29] 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 06/29] 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 07/29] 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 08/29] 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 09/29] 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") }) }) From d8c34693b09dd856b0efd2c4a1924c7320346720 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Sun, 15 Nov 2026 22:27:01 +0530 Subject: [PATCH 10/29] fix: send falsy API bodies, follow cancellation in apiRequest, check abort before a read-only refusal - apiRequest sends any body but undefined (null, false, 0 and "" were dropped) and takes an optional signal that cancels the request along with its 15 s timeout. - dbtAdapterFor throws for a cancelled call before it would refuse a read-only or plan-mode one. - Tests cover these and a session inside the adapter's own project. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/api/client.ts | 25 ++++++-- .../src/altimate/tools/dbt-adapter-access.ts | 2 + .../test/altimate/dbt-adapter-access.test.ts | 63 +++++++++++++++++++ 3 files changed, 84 insertions(+), 6 deletions(-) diff --git a/packages/opencode/src/altimate/api/client.ts b/packages/opencode/src/altimate/api/client.ts index cb53c0ec7b..6ea7d96354 100644 --- a/packages/opencode/src/altimate/api/client.ts +++ b/packages/opencode/src/altimate/api/client.ts @@ -318,7 +318,13 @@ export namespace AltimateApi { return data.auth_token } - async function request(creds: AltimateCredentials, method: string, endpoint: string, body?: unknown) { + async function request( + creds: AltimateCredentials, + method: string, + endpoint: string, + body?: unknown, + signal?: AbortSignal, + ) { const url = `${creds.altimateUrl}${endpoint}` // altimate_change start — upstream_fix: bound every API request. Without a // signal a stalled server holds the caller indefinitely. The abort stays @@ -327,7 +333,7 @@ export namespace AltimateApi { const timeout = setTimeout(() => controller.abort(), 15_000) try { const res = await fetch(url, { - signal: controller.signal, + signal: signal ? AbortSignal.any([controller.signal, signal]) : controller.signal, method, headers: { "Content-Type": "application/json", @@ -335,7 +341,8 @@ export namespace AltimateApi { "x-tenant": creds.altimateInstanceName, ...clientHeaders(), }, - ...(body ? { body: JSON.stringify(body) } : {}), + // Any body but undefined is sent: null, false, 0 and "" are JSON values too. + ...(body !== undefined ? { body: JSON.stringify(body) } : {}), }) if (!res.ok) { throw new Error(`API ${method} ${endpoint} failed with status ${res.status}`) @@ -350,9 +357,15 @@ export namespace AltimateApi { /** * 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. + * message naming the credentials file when none are stored or they can't be read. `signal` (a tool + * call's `ctx.abort`) cancels the request as well as the 15 s timeout. */ - export async function apiRequest(method: string, endpoint: string, body?: unknown): Promise { + export async function apiRequest( + method: string, + endpoint: string, + body?: unknown, + signal?: AbortSignal, + ): Promise { let creds: AltimateCredentials try { creds = await getCredentials() @@ -364,7 +377,7 @@ export namespace AltimateApi { ) 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) + return request(creds, method, endpoint, body, signal) } export async function listDatamates(creds?: AltimateCredentials) { diff --git a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts index d73dd7e9c5..1ff9047e9a 100644 --- a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts +++ b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts @@ -25,6 +25,8 @@ export const dbtAdapterAccessInternals = { */ export async function dbtAdapterFor(ctx: Pick): Promise { const signal = ctx.abort + // A cancelled call answers nothing, refused or not. + signal.throwIfAborted() if (ctx.extra?.forceReadOnly === true || ctx.agent === "plan") return { refusal: "read_only", diff --git a/packages/opencode/test/altimate/dbt-adapter-access.test.ts b/packages/opencode/test/altimate/dbt-adapter-access.test.ts index b2a012ed58..75a2fed64d 100644 --- a/packages/opencode/test/altimate/dbt-adapter-access.test.ts +++ b/packages/opencode/test/altimate/dbt-adapter-access.test.ts @@ -125,6 +125,18 @@ describe("dbtAdapterFor", () => { expect(created).toBe(1) }) + test("returns the adapter to a session inside the adapter's own project", async () => { + try { + const access = await Instance.provide({ directory: project, fn: () => dbtAdapterFor(ctx) }) + expect(access.refusal).toBeUndefined() + expect(access.reason).toBeUndefined() + expect(access.adapter?.isInitialized()).toBe(true) + expect(created).toBe(1) + } finally { + await disposeInstance(project) + } + }) + test("says when the adapter didn't load the project", async () => { dbtAdapterInternals.create = async () => ({ isInitialized: () => false, dispose: async () => {} }) const access = await dbtAdapterFor(ctx) @@ -180,6 +192,15 @@ describe("dbtAdapterFor", () => { expect(created).toBe(0) }) + test("a cancelled read-only or plan-mode call throws rather than being refused", async () => { + const controller = new AbortController() + controller.abort() + const abort = controller.signal + await expect(dbtAdapterFor({ ...ctx, abort, extra: { forceReadOnly: true } })).rejects.toThrow() + await expect(dbtAdapterFor({ ...ctx, abort, agent: "plan" })).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 { @@ -260,6 +281,48 @@ describe("AltimateApi.apiRequest", () => { } }) + test("sends a falsy JSON body rather than dropping it", 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 bodies: unknown[] = [] + globalThis.fetch = (async (_url: string, init: RequestInit) => { + bodies.push(init.body) + return new Response("{}", { status: 200 }) + }) as unknown as typeof fetch + try { + for (const body of [null, false, 0, ""]) await AltimateApi.apiRequest("POST", "/dbt/v1/x", body) + await AltimateApi.apiRequest("GET", "/dbt/v1/x") + expect(bodies).toEqual(["null", "false", "0", '""', undefined]) + } finally { + globalThis.fetch = original + } + }) + + test("a cancelled call stops the request", 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 + globalThis.fetch = ((_url: string, init: RequestInit) => + new Promise((_, reject) => { + // Like fetch: a signal already aborted rejects at once, else the abort does. + if (init.signal?.aborted) return reject(init.signal.reason) + init.signal?.addEventListener("abort", () => reject(init.signal?.reason), { once: true }) + })) as unknown as typeof fetch + const controller = new AbortController() + try { + const pending = AltimateApi.apiRequest("GET", "/dbt/v1/x", undefined, controller.signal) + controller.abort(new Error("cancelled by the user")) + await expect(pending).rejects.toThrow("cancelled by the user") + } 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( From 18a3fc4e0bd124e8f5fb3120fdc4d152be88cbe3 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 06:39:46 +0530 Subject: [PATCH 11/29] fix: keep the stored API key out of API errors, bound the dbt config read - apiRequest names what is wrong with the credentials file (not valid JSON, which field is missing) instead of quoting the parser's message, which can quote the key. - request() redacts the key from a failed send: Bun's header check quotes `Bearer ` for a key with CR/LF, and throws before fetch returns a promise, so both a throw and a rejection are caught. - A request that times out says so; a cancelled apiRequest reads nothing. - dbtAdapterFor bounds the project lookup with the same deadline and abort as the adapter's start, and checks the abort after each wait. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/api/client.ts | 75 ++++++-- .../src/altimate/tools/dbt-adapter-access.ts | 52 ++--- .../test/altimate/dbt-adapter-access.test.ts | 179 +++++++++++++++++- 3 files changed, 265 insertions(+), 41 deletions(-) diff --git a/packages/opencode/src/altimate/api/client.ts b/packages/opencode/src/altimate/api/client.ts index 6ea7d96354..d3cfd1a887 100644 --- a/packages/opencode/src/altimate/api/client.ts +++ b/packages/opencode/src/altimate/api/client.ts @@ -318,6 +318,17 @@ export namespace AltimateApi { return data.auth_token } + /** Test seams. */ + export const requestInternals = { + /** How long an API request may take, body included, before it is aborted. */ + timeoutMs: 15_000, + } + + /** `text` with every occurrence of `secret` replaced, so an error can be shown without the key. */ + function redact(text: string, secret: string): string { + return secret ? text.split(secret).join("[redacted]") : text + } + async function request( creds: AltimateCredentials, method: string, @@ -326,24 +337,43 @@ export namespace AltimateApi { signal?: AbortSignal, ) { const url = `${creds.altimateUrl}${endpoint}` + // Bun's fetch throws at once, not as a rejection, when it refuses a header: both are caught. + const send = async (start: () => Promise) => { + try { + return await start() + } catch (e) { + // A timeout or the caller's abort rejects with its own reason, which holds no header. + if (controller.signal.aborted || signal?.aborted) throw e + // Others can quote a header: Bun's check of a header value with CR/LF quotes `Bearer `. + const message = redact(e instanceof Error ? e.message : String(e), creds.altimateApiKey) + throw new Error(`API ${method} ${endpoint} could not be sent: ${message}`) + } + } // altimate_change start — upstream_fix: bound every API request. Without a // signal a stalled server holds the caller indefinitely. The abort stays // armed until the BODY is read: `fetch` resolves on headers. const controller = new AbortController() - const timeout = setTimeout(() => controller.abort(), 15_000) + const seconds = requestInternals.timeoutMs / 1000 + const timeout = setTimeout( + () => + controller.abort(new DOMException(`API ${method} ${endpoint} timed out after ${seconds} s`, "TimeoutError")), + requestInternals.timeoutMs, + ) try { - const res = await fetch(url, { - signal: signal ? AbortSignal.any([controller.signal, signal]) : controller.signal, - method, - headers: { - "Content-Type": "application/json", - Authorization: `Bearer ${creds.altimateApiKey}`, - "x-tenant": creds.altimateInstanceName, - ...clientHeaders(), - }, - // Any body but undefined is sent: null, false, 0 and "" are JSON values too. - ...(body !== undefined ? { body: JSON.stringify(body) } : {}), - }) + const res = await send(() => + fetch(url, { + signal: signal ? AbortSignal.any([controller.signal, signal]) : controller.signal, + method, + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${creds.altimateApiKey}`, + "x-tenant": creds.altimateInstanceName, + ...clientHeaders(), + }, + // Any body but undefined is sent: null, false, 0 and "" are JSON values too. + ...(body !== undefined ? { body: JSON.stringify(body) } : {}), + }), + ) if (!res.ok) { throw new Error(`API ${method} ${endpoint} failed with status ${res.status}`) } @@ -354,11 +384,25 @@ export namespace AltimateApi { // altimate_change end } + /** What is wrong with the stored credentials, naming fields but never quoting the file's text. */ + function credentialsProblem(e: unknown): string { + // The parser's message quotes the text it stopped at, which can be the key. + if (e instanceof SyntaxError) return "the file is not valid JSON." + if (e instanceof z.ZodError) { + const fields = [...new Set(e.issues.map((issue) => issue.path.join(".")))] + if (fields.length === 0 || fields.includes("")) return "the file does not hold the credentials object." + return `${fields.join(", ")} ${fields.length === 1 ? "is" : "are"} missing or not valid.` + } + // A file system error or a missing ${env:NAME} variable: names a path or a variable, no value. + return e instanceof Error ? e.message : String(e) + } + /** * 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. `signal` (a tool - * call's `ctx.abort`) cancels the request as well as the 15 s timeout. + * call's `ctx.abort`) cancels the request as well as the 15 s timeout. No error it raises quotes the + * stored key. */ export async function apiRequest( method: string, @@ -366,6 +410,7 @@ export namespace AltimateApi { body?: unknown, signal?: AbortSignal, ): Promise { + signal?.throwIfAborted() let creds: AltimateCredentials try { creds = await getCredentials() @@ -375,7 +420,7 @@ export namespace AltimateApi { 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)}`) + throw new Error(`The Altimate credentials in ${p} can't be used: ${credentialsProblem(e)}`) } return request(creds, method, endpoint, body, signal) } diff --git a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts index 1ff9047e9a..df8fb597dc 100644 --- a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts +++ b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts @@ -21,7 +21,8 @@ export const dbtAdapterAccessInternals = { * 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. + * adapter isn't set up for. Every wait, the project lookup and the adapter's start, is bounded by one + * deadline and follows the call's abort. */ export async function dbtAdapterFor(ctx: Pick): Promise { const signal = ctx.abort @@ -32,12 +33,30 @@ export async function dbtAdapterFor(ctx: Pick {} + 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, + ) + }) + // It can reject between two races, when nothing awaits it: the next race still sees the rejection. + waited.catch(() => {}) + const bounded = async (work: Promise): Promise => { + const value = await Promise.race([work, waited]) + // An abort queued while the work settled still wins. signal.throwIfAborted() + return value + } + try { + const { getDbtAdapter, getDbtProjectRoot } = await bounded(import("../native/connections/register")) + const project = await bounded(sessionProject()) if (project?.other) { return { refusal: "other_project", @@ -46,24 +65,10 @@ export async function dbtAdapterFor(ctx: Pick {} - 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) - }) + const adapter = await bounded(getDbtAdapter()) if (!adapter) { // No adapter also when the project exists but the adapter failed to start: say which. - const root = await getDbtProjectRoot() + const root = await bounded(getDbtProjectRoot()) const found = !!root && fs.existsSync(path.join(root, "dbt_project.yml")) return found ? { refusal: "not_started", reason: "the dbt adapter didn't start" } @@ -75,6 +80,9 @@ export async function dbtAdapterFor(ctx: Pick { } }) + test("a stalled dbt config read gives up at the start timeout", async () => { + let release = () => {} + dbtAdapterInternals.readConfig = () => new Promise((resolve) => (release = () => resolve(null))) + const saved = dbtAdapterAccessInternals.adapterStartTimeoutMs + dbtAdapterAccessInternals.adapterStartTimeoutMs = 20 + try { + const access = await Instance.provide({ directory: project, fn: () => dbtAdapterFor(ctx) }) + expect(access).toEqual({ refusal: "not_started", reason: "the dbt adapter didn't start within 0.02 s" }) + expect(created).toBe(0) + } finally { + release() + dbtAdapterAccessInternals.adapterStartTimeoutMs = saved + await disposeInstance(project) + } + }) + + test("a call cancelled during a stalled dbt config read throws at once", async () => { + let release = () => {} + let entered = () => {} + const reading = new Promise((resolve) => (entered = resolve)) + dbtAdapterInternals.readConfig = () => { + entered() + return new Promise((resolve) => (release = () => resolve(null))) + } + const controller = new AbortController() + try { + const pending = Instance.provide({ + directory: project, + fn: () => dbtAdapterFor({ ...ctx, abort: controller.signal }), + }) + await reading + controller.abort(new Error("cancelled")) + await expect(pending).rejects.toThrow("cancelled") + } finally { + release() + await disposeInstance(project) + } + }) + + test("removes its abort listener and its timer whatever the outcome", async () => { + const controller = new AbortController() + const signal = controller.signal + let listening = 0 + const add = signal.addEventListener.bind(signal) + const remove = signal.removeEventListener.bind(signal) + signal.addEventListener = ((...a: Parameters) => { + if (a[0] === "abort") listening += 1 + return add(...a) + }) as typeof signal.addEventListener + signal.removeEventListener = ((...a: Parameters) => { + if (a[0] === "abort") listening -= 1 + return remove(...a) + }) as typeof signal.removeEventListener + const timers = new Set() + const set = globalThis.setTimeout + const clear = globalThis.clearTimeout + globalThis.setTimeout = ((fn: () => void, ms?: number) => { + const t = set(fn, ms) + timers.add(t) + return t + }) as typeof setTimeout + globalThis.clearTimeout = ((t: ReturnType) => { + timers.delete(t) + return clear(t) + }) as typeof clearTimeout + try { + expect((await dbtAdapterFor({ ...ctx, abort: signal })).adapter).toBeDefined() + dbtAdapterInternals.create = async () => { + throw new Error("dbt-integration missing") + } + resetDbtAdapter() + expect((await dbtAdapterFor({ ...ctx, abort: signal })).refusal).toBe("not_started") + } finally { + globalThis.setTimeout = set + globalThis.clearTimeout = clear + } + expect(listening).toBe(0) + expect(timers.size).toBe(0) + }) + 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") @@ -323,10 +403,101 @@ 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( - `The Altimate credentials in ${path.join(home, ".altimate", "altimate.json")} can't be used`, + test("names the file and the failure, never the file's text, when the credentials aren't valid JSON", async () => { + const file = path.join(home, ".altimate", "altimate.json") + await Bun.write( + file, + '{"altimateUrl":"https://x.test","altimateInstanceName":"acme","altimateApiKey": sk_SECRET123}', + ) + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(error).toBeInstanceOf(Error) + expect(error.message).toBe(`The Altimate credentials in ${file} can't be used: the file is not valid JSON.`) + expect(error.message).not.toContain("sk_SECRET123") + }) + + test("names the missing field, never a value, when the credentials are incomplete", async () => { + const file = path.join(home, ".altimate", "altimate.json") + await Bun.write(file, JSON.stringify({ altimateUrl: "https://x.test", altimateApiKey: "sk_SECRET123" })) + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(error.message).toBe( + `The Altimate credentials in ${file} can't be used: altimateInstanceName is missing or not valid.`, ) + expect(error.message).not.toContain("sk_SECRET123") + }) + + test("never shows the stored key when sending the request fails", async () => { + const key = "sk_SECRET123\r\nX: y" + await Bun.write( + path.join(home, ".altimate", "altimate.json"), + JSON.stringify({ altimateUrl: "http://127.0.0.1:9", altimateInstanceName: "acme", altimateApiKey: key }), + ) + // The real fetch: it rejects a header value with CR/LF, quoting the value. + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(error).toBeInstanceOf(Error) + expect(error.message).not.toContain("sk_SECRET123") + expect(error.message).toContain("API GET /dbt/v1/x could not be sent") + }) + + test("never shows the stored key from any fetch failure", async () => { + await Bun.write( + path.join(home, ".altimate", "altimate.json"), + JSON.stringify({ + altimateUrl: "https://api.example.test", + altimateInstanceName: "acme", + altimateApiKey: "sk_SECRET123", + }), + ) + const original = globalThis.fetch + globalThis.fetch = (async (_url: string, init: RequestInit) => { + throw new TypeError(`bad header: '${(init.headers as Record).Authorization}'`) + }) as unknown as typeof fetch + try { + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(error.message).toBe("API GET /dbt/v1/x could not be sent: bad header: 'Bearer [redacted]'") + } finally { + globalThis.fetch = original + } + }) + + test("a timed-out request says it timed out", 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 + globalThis.fetch = ((_url: string, init: RequestInit) => + new Promise((_, reject) => { + init.signal?.addEventListener("abort", () => reject(init.signal?.reason), { once: true }) + })) as unknown as typeof fetch + const saved = AltimateApi.requestInternals.timeoutMs + AltimateApi.requestInternals.timeoutMs = 10 + try { + await expect(AltimateApi.apiRequest("GET", "/dbt/v1/x")).rejects.toThrow( + "API GET /dbt/v1/x timed out after 0.01 s", + ) + } finally { + AltimateApi.requestInternals.timeoutMs = saved + globalThis.fetch = original + } + }) + + test("a call cancelled before it starts reads no credentials and sends nothing", async () => { + const original = globalThis.fetch + let sent = 0 + globalThis.fetch = (async () => { + sent += 1 + return new Response("{}") + }) as unknown as typeof fetch + const controller = new AbortController() + controller.abort(new Error("cancelled by the user")) + try { + // No credentials are stored: reading them would fail with another message. + await expect(AltimateApi.apiRequest("GET", "/dbt/v1/x", undefined, controller.signal)).rejects.toThrow( + "cancelled by the user", + ) + expect(sent).toBe(0) + } finally { + globalThis.fetch = original + } }) }) From 6024ac9b208400ff2c70f8ef07e98b1568163276 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 06:47:20 +0530 Subject: [PATCH 12/29] fix: redact the API key when a refused header races the caller's abort; assert stub failure classification Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/api/client.ts | 5 ++-- .../test/altimate/dbt-adapter-access.test.ts | 27 +++++++++++++++++++ 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/packages/opencode/src/altimate/api/client.ts b/packages/opencode/src/altimate/api/client.ts index d3cfd1a887..25a78d8bd0 100644 --- a/packages/opencode/src/altimate/api/client.ts +++ b/packages/opencode/src/altimate/api/client.ts @@ -342,8 +342,9 @@ export namespace AltimateApi { try { return await start() } catch (e) { - // A timeout or the caller's abort rejects with its own reason, which holds no header. - if (controller.signal.aborted || signal?.aborted) throw e + // A timeout or the caller's abort rejects with its own reason, which holds no header. An abort + // that raced a refused header leaves the header error, so match the reason, not the flag. + if (e === controller.signal.reason || e === signal?.reason) throw e // Others can quote a header: Bun's check of a header value with CR/LF quotes `Bearer `. const message = redact(e instanceof Error ? e.message : String(e), creds.altimateApiKey) throw new Error(`API ${method} ${endpoint} could not be sent: ${message}`) diff --git a/packages/opencode/test/altimate/dbt-adapter-access.test.ts b/packages/opencode/test/altimate/dbt-adapter-access.test.ts index 53592c8bc6..f998a83334 100644 --- a/packages/opencode/test/altimate/dbt-adapter-access.test.ts +++ b/packages/opencode/test/altimate/dbt-adapter-access.test.ts @@ -11,6 +11,7 @@ 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 { resultFailed } from "@/altimate/mcp-server/adapter" 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" @@ -89,6 +90,7 @@ describe("feature tools in the allow-list", () => { expect(result.title).toBe(`${id}: not implemented`) expect(result.metadata).toEqual({ success: false, error: "not implemented", truncated: false }) expect(result.output).toContain(id) + expect(resultFailed(result)).toBe(true) } }) }) @@ -438,6 +440,31 @@ describe("AltimateApi.apiRequest", () => { expect(error.message).toContain("API GET /dbt/v1/x could not be sent") }) + test("never shows the stored key when a header refusal races the caller's abort", async () => { + await Bun.write( + path.join(home, ".altimate", "altimate.json"), + JSON.stringify({ + altimateUrl: "https://api.example.test", + altimateInstanceName: "acme", + altimateApiKey: "sk_SECRET123", + }), + ) + const original = globalThis.fetch + const controller = new AbortController() + globalThis.fetch = (async (_url: string, init: RequestInit) => { + controller.abort(new Error("cancelled by the user")) + throw new TypeError(`bad header: '${(init.headers as Record).Authorization}'`) + }) as unknown as typeof fetch + try { + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x", undefined, controller.signal).catch( + (e: Error) => e, + ) + expect(error.message).toBe("API GET /dbt/v1/x could not be sent: bad header: 'Bearer [redacted]'") + } finally { + globalThis.fetch = original + } + }) + test("never shows the stored key from any fetch failure", async () => { await Bun.write( path.join(home, ".altimate", "altimate.json"), From f5159c51d1fcc7b8024a6d475ecc39106bbe8371 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 06:47:45 +0530 Subject: [PATCH 13/29] docs: say which tools use the dbt adapter helper Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/tools/dbt-adapter-access.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts index df8fb597dc..7f93d822e9 100644 --- a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts +++ b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts @@ -18,7 +18,7 @@ export const dbtAdapterAccessInternals = { } /** - * The dbt adapter for a tool call, which every adapter-backed tool goes through. Starting the adapter + * The dbt adapter for a tool call, which the adapter-backed tools added after dbt_lineage go 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. Every wait, the project lookup and the adapter's start, is bounded by one From f57de3da23aab9065822038372fbb2eb5e120299 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 06:52:44 +0530 Subject: [PATCH 14/29] docs: rewrap and correct the adapter helper comments Co-Authored-By: Claude Opus 5.5 --- .../opencode/src/altimate/tools/dbt-adapter-access.ts | 10 +++++----- .../opencode/test/altimate/dbt-adapter-access.test.ts | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts index 7f93d822e9..2fc2aba423 100644 --- a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts +++ b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts @@ -18,11 +18,11 @@ export const dbtAdapterAccessInternals = { } /** - * The dbt adapter for a tool call, which the adapter-backed tools added after dbt_lineage go 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. Every wait, the project lookup and the adapter's start, is bounded by one - * deadline and follows the call's abort. + * The dbt adapter for a tool call, which the adapter-backed tools added after dbt_lineage go 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. Every wait, the project lookup and the + * adapter's start, is bounded by one deadline and follows the call's abort. */ export async function dbtAdapterFor(ctx: Pick): Promise { const signal = ctx.abort diff --git a/packages/opencode/test/altimate/dbt-adapter-access.test.ts b/packages/opencode/test/altimate/dbt-adapter-access.test.ts index f998a83334..ddcf0ea183 100644 --- a/packages/opencode/test/altimate/dbt-adapter-access.test.ts +++ b/packages/opencode/test/altimate/dbt-adapter-access.test.ts @@ -1,5 +1,5 @@ // 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 +// one gate the new dbt-adapter-backed tools go 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" From cd82c9895dc0f7818e5500cc6a34bd6716336b12 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 07:48:39 +0530 Subject: [PATCH 15/29] dbt_docs_coverage: an unreadable select list falls back to the manifest's columns; a quoted "*" column is a column Co-Authored-By: Claude Sonnet 5.5 --- .../src/altimate/native/dbt/column-reach.ts | 1 + .../src/altimate/tools/dbt-docs-coverage.ts | 19 ++++++----- .../test/altimate/dbt-docs-coverage.test.ts | 32 ++++++++++++++++--- 3 files changed, 37 insertions(+), 15 deletions(-) diff --git a/packages/opencode/src/altimate/native/dbt/column-reach.ts b/packages/opencode/src/altimate/native/dbt/column-reach.ts index c2b7ecc645..baa73d339a 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -436,6 +436,7 @@ export function columnReach(manifestPath: string, model: string, column: string, reads = true if (edge.lineage_type !== "indirect" && typeof edge.target === "string") { const out = edge.target.toLowerCase() + // Only one candidate gets here: more than one is ambiguous and was skipped above. const lens = joinLens( lensOf.get(candidates[0]!)?.get(source.column), typeof edge.lens_type === "string" ? edge.lens_type : undefined, diff --git a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts index 6178ca2067..4d097f83e1 100644 --- a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts +++ b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts @@ -12,7 +12,7 @@ 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 `*`). */ + /** The model's output columns, as written in its compiled SQL (or the manifest's columns when the select list cannot be read as names). */ output_columns: string[] /** Output columns that have a description. */ documented: string[] @@ -20,13 +20,13 @@ export interface DocsCoverage { 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 `*`. */ + /** Where the column list came from: the compiled SQL's select list, or the manifest's columns when the select list cannot be read as names (`*`, an unnamed expression, a UNION). */ 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, the engine cannot read it, or it selects `*` and the manifest lists no columns. */ +/** Coverage of one manifest model node. Throws when the node has no compiled SQL, the engine cannot read it, or its select list cannot be read as column names and the manifest lists no columns. */ export function docsCoverage(node: any, dialect: string | undefined): DocsCoverage { const yamlColumns: Record = node.columns ?? {} const described = new Set() @@ -42,21 +42,20 @@ export function docsCoverage(node: any, dialect: string | undefined): DocsCovera 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 (!/due to star\b/i.test(e instanceof Error ? e.message : String(e))) throw e + } catch { + // A select list the engine cannot turn into names (a `*`, an expression with no alias, a UNION) has + // no column list to count, so the manifest's own columns are the best list there is. The engine's + // message is its own debug text and is not passed on. outputs = [] source = "manifest_columns" } - if (outputs.includes("*")) source = "manifest_columns" if (source === "manifest_columns") { outputs = Object.entries(yamlColumns).map(([key, col]) => String(col?.name || key)) } 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\`.`, + `Model "${node.name}" has a select list that cannot be read as column names (a \`*\`, an expression with no alias or a UNION) and the manifest lists no columns for it, so its columns are not known. List them in its YAML or run \`dbt docs generate\`.`, ) } @@ -123,7 +122,7 @@ 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 only the columns the manifest lists are counted; a column the SQL adds beside `*` is not.", + "The model's select list cannot be read as column names (a `*`, an expression with no alias or a UNION), so only the columns the manifest lists are counted; a column the SQL adds beside them is not.", ) return { title: `Docs coverage: ${result.model} ${result.percent}%`, diff --git a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts index 9f947b2f14..4ba693e8ee 100644 --- a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts +++ b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts @@ -97,10 +97,32 @@ describe("docsCoverage", () => { 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("a column literally named * is that column, not a wildcard", () => { + const r = docsCoverage({ ...orders, compiled_code: 'select "*" from t' }, "snowflake") + expect(r.source).toBe("compiled_sql") + expect(r.output_columns).toEqual(["*"]) + expect(r.missing).toEqual(["*"]) + }) + + test.each([ + ["an expression with no alias", "select count(*) from raw.orders"], + ["a UNION", "select id from a union all select id from b"], + ["an arithmetic expression named by nothing", "select start_time + 1 from t"], + ])("%s falls back to the manifest's columns", (_name, sql) => { + const r = docsCoverage({ ...orders, compiled_code: sql }, "snowflake") + expect(r.source).toBe("manifest_columns") + expect(r.output_columns).toEqual(["id", "customer_id", "status"]) + }) + + test("an unreadable select list with no columns in the manifest is a short error without the engine's debug text", () => { + let message = "" + try { + docsCoverage({ ...orders, columns: {}, compiled_code: "select count(*) from t" }, "snowflake") + } catch (e) { + message = (e as Error).message + } + expect(message).toContain("its columns are not known") + expect(message).not.toContain("CountFunc") }) test("select * with no columns in the manifest is an error, not full coverage", () => { @@ -119,7 +141,7 @@ describe("docsCoverage", () => { 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") + expect(r.output).toContain("a column the SQL adds beside them is not") } finally { rmSync(dir, { recursive: true, force: true }) } From e84b6ecf9ac93bcefd31ed283518cbfead677f10 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 12:10:31 +0530 Subject: [PATCH 16/29] test(learn): the publisher mocks carry publishErrorCode, which the CLI now calls Co-Authored-By: Claude Sonnet 5.5 --- packages/opencode/test/altimate/learn/cli.test.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/opencode/test/altimate/learn/cli.test.ts b/packages/opencode/test/altimate/learn/cli.test.ts index 08c0fee948..baafd7c49c 100644 --- a/packages/opencode/test/altimate/learn/cli.test.ts +++ b/packages/opencode/test/altimate/learn/cli.test.ts @@ -715,6 +715,7 @@ test("failed publish after promotion prints a retry command that publishes the e import { mock } from "bun:test" class SkillNameConflictError extends Error {} mock.module(${publisher}, () => ({ + publishErrorCode: () => null, SkillNameConflictError, explainPublishError: (error) => error.message, describePublish: (report) => 'Updated "' + report.name + '" in the workspace', @@ -941,6 +942,7 @@ import { mock } from "bun:test" import fs from "node:fs/promises" import path from "node:path" mock.module(${publisher}, () => ({ + publishErrorCode: () => null, publishSkill: async ({ skillDirectory }) => { const skill = await fs.readFile(path.join(skillDirectory, "SKILL.md"), "utf8") if (!skill.includes(${JSON.stringify(Playbook.HEADER)}) || !skill.includes(${JSON.stringify(text)})) From aaff4148345d9e6735a119d27ea540a3d2929a9d Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 13:21:13 +0530 Subject: [PATCH 17/29] fix: never echo a send failure's text, so a trimmed key can't leak Bun trims a header value before quoting it in its validation error, so redacting exact copies of the stored key missed keys with a line break and trailing whitespace. A send failure now reports only a fixed reason for a refused header, or the error's name and code otherwise. Also: a missing ${env:...} variable no longer quotes its name from the credentials file; a credentials directory that can't be searched is reported as unreadable, not as no credentials; the adapter deadline says "wasn't ready" since it covers the config read too. Regression tests go through the real fetch for CR/LF and trailing-whitespace keys, via apiRequest and listDatamates, and check stubs still validate input. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/api/client.ts | 40 ++++-- .../src/altimate/tools/dbt-adapter-access.ts | 2 +- .../test/altimate/dbt-adapter-access.test.ts | 121 ++++++++++++++---- 3 files changed, 126 insertions(+), 37 deletions(-) diff --git a/packages/opencode/src/altimate/api/client.ts b/packages/opencode/src/altimate/api/client.ts index 25a78d8bd0..a7a668183e 100644 --- a/packages/opencode/src/altimate/api/client.ts +++ b/packages/opencode/src/altimate/api/client.ts @@ -1,6 +1,6 @@ import z from "zod" import path from "path" -import { rm } from "node:fs/promises" +import { rm, stat } from "node:fs/promises" import { Global } from "../../global" import { Filesystem } from "../../util/filesystem" import { currentCredentials } from "./credentials-context" @@ -86,11 +86,14 @@ export namespace AltimateApi { return Filesystem.exists(credentialsPath()) } + /** A `${env:NAME}` in the credentials file names a variable that isn't set. */ + class MissingEnvVar extends Error {} + function resolveEnvVars(obj: unknown): unknown { if (typeof obj === "string") { return obj.replace(/\$\{env:([^}]+)\}/g, (_, envVar) => { const value = process.env[envVar] - if (value === undefined) throw new Error(`Environment variable ${envVar} not found`) + if (value === undefined) throw new MissingEnvVar(`Environment variable ${envVar} not found`) return value }) } @@ -324,9 +327,18 @@ export namespace AltimateApi { timeoutMs: 15_000, } - /** `text` with every occurrence of `secret` replaced, so an error can be shown without the key. */ - function redact(text: string, secret: string): string { - return secret ? text.split(secret).join("[redacted]") : text + /** + * Why a request couldn't be sent, never quoting the error's text. Bun refuses a header value with a + * control character as a TypeError that quotes the value after trimming it, so no redaction of the + * stored key can be relied on: only the error's name and code are shown. + */ + function sendFailure(e: unknown): string { + if (e instanceof TypeError) + return "the request was refused before it was sent (TypeError): the stored API key or tenant name may not be a valid header value." + const word = (v: unknown) => (typeof v === "string" && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(v) ? v : undefined) + const name = (e instanceof Error && word(e.name)) || "Error" + const code = word((e as { code?: unknown } | null)?.code) + return code ? `${name} (${code}).` : `${name}.` } async function request( @@ -346,8 +358,7 @@ export namespace AltimateApi { // that raced a refused header leaves the header error, so match the reason, not the flag. if (e === controller.signal.reason || e === signal?.reason) throw e // Others can quote a header: Bun's check of a header value with CR/LF quotes `Bearer `. - const message = redact(e instanceof Error ? e.message : String(e), creds.altimateApiKey) - throw new Error(`API ${method} ${endpoint} could not be sent: ${message}`) + throw new Error(`API ${method} ${endpoint} could not be sent: ${sendFailure(e)}`) } } // altimate_change start — upstream_fix: bound every API request. Without a @@ -394,7 +405,9 @@ export namespace AltimateApi { if (fields.length === 0 || fields.includes("")) return "the file does not hold the credentials object." return `${fields.join(", ")} ${fields.length === 1 ? "is" : "are"} missing or not valid.` } - // A file system error or a missing ${env:NAME} variable: names a path or a variable, no value. + // The variable's name is the file's text, which can be a key written in its place. + if (e instanceof MissingEnvVar) return "an ${env:…} variable it refers to is not set." + // A file system error names a path, not a value. return e instanceof Error ? e.message : String(e) } @@ -403,7 +416,7 @@ export namespace AltimateApi { * 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. `signal` (a tool * call's `ctx.abort`) cancels the request as well as the 15 s timeout. No error it raises quotes the - * stored key. + * stored key or the credentials file's text. */ export async function apiRequest( method: string, @@ -417,7 +430,14 @@ export namespace AltimateApi { creds = await getCredentials() } catch (e) { const p = credentialsPath() - if (!(await Filesystem.exists(p))) + // Only a file that isn't there is "not stored": a directory without search permission hides it too. + const unseen = await stat(p).then( + () => undefined, + (err: NodeJS.ErrnoException) => err, + ) + if (unseen && unseen.code !== "ENOENT" && unseen.code !== "ENOTDIR") + throw new Error(`The Altimate credentials in ${p} can't be read (${unseen.code ?? unseen.name}).`) + if (unseen) throw new Error( `No Altimate credentials are stored: sign in to Altimate in altimate-code first (they are saved to ${p}).`, ) diff --git a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts index 2fc2aba423..d51d2b4d2b 100644 --- a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts +++ b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts @@ -42,7 +42,7 @@ export async function dbtAdapterFor(ctx: Pick reject(new Error(`the dbt adapter didn't start within ${seconds} s`)), + () => reject(new Error(`the dbt adapter wasn't ready within ${seconds} s`)), dbtAdapterAccessInternals.adapterStartTimeoutMs, ) }) diff --git a/packages/opencode/test/altimate/dbt-adapter-access.test.ts b/packages/opencode/test/altimate/dbt-adapter-access.test.ts index ddcf0ea183..6e3d7958c6 100644 --- a/packages/opencode/test/altimate/dbt-adapter-access.test.ts +++ b/packages/opencode/test/altimate/dbt-adapter-access.test.ts @@ -2,7 +2,7 @@ // one gate the new dbt-adapter-backed tools go 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 { chmod, mkdtemp, rm, writeFile } from "node:fs/promises" import { realpathSync } from "node:fs" import os from "node:os" import path from "node:path" @@ -93,6 +93,25 @@ describe("feature tools in the allow-list", () => { expect(resultFailed(result)).toBe(true) } }) + + test("each placeholder still checks its arguments before it refuses", async () => { + for (const id of FEATURE_TOOLS) { + const tool = await initTool(EXPOSED[id] as any) + // A string where an object is expected fails every schema, whatever its required fields. + const failed = await Promise.resolve() + .then(() => tool.execute("not an object" as any, ctx)) + .then( + (result) => ({ result }), + (error: unknown) => ({ error }), + ) + if ("result" in failed) { + expect(failed.result.title).not.toBe(`${id}: not implemented`) + expect(resultFailed(failed.result)).toBe(true) + } else { + expect(String(failed.error)).toContain("invalid arguments") + } + } + }) }) describe("dbtAdapterFor", () => { @@ -157,7 +176,7 @@ describe("dbtAdapterFor", () => { 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" }) + expect(access).toEqual({ refusal: "not_started", reason: "the dbt adapter wasn't ready within 0.02 s" }) } finally { dbtAdapterAccessInternals.adapterStartTimeoutMs = saved } @@ -224,7 +243,7 @@ describe("dbtAdapterFor", () => { dbtAdapterAccessInternals.adapterStartTimeoutMs = 20 try { const access = await Instance.provide({ directory: project, fn: () => dbtAdapterFor(ctx) }) - expect(access).toEqual({ refusal: "not_started", reason: "the dbt adapter didn't start within 0.02 s" }) + expect(access).toEqual({ refusal: "not_started", reason: "the dbt adapter wasn't ready within 0.02 s" }) expect(created).toBe(0) } finally { release() @@ -427,17 +446,53 @@ describe("AltimateApi.apiRequest", () => { expect(error.message).not.toContain("sk_SECRET123") }) - test("never shows the stored key when sending the request fails", async () => { - const key = "sk_SECRET123\r\nX: y" + const HEADER_REFUSED = + "could not be sent: the request was refused before it was sent (TypeError): the stored API key or tenant name may not be a valid header value." + + /** Every substring of `key` long enough to identify it, so a trimmed or split copy is caught too. */ + function expectNoPartOf(text: string, key: string) { + for (const part of key.split(/\s+/).filter((p) => p.length >= 4)) expect(text).not.toContain(part) + expect(text).not.toContain("Bearer") + } + + // The real fetch: Bun refuses a header value with CR/LF, quoting it after trimming its whitespace. + for (const key of [ + "sk_SECRET123\r\nX: y", + "sk_SECRET123ABCDEFGH\nPART2\n", + "sk_SECRET123ABCDEFGH\r\nX \t", + " sk_SECRET123ABCDEFGH\nPART2 ", + ]) { + test(`never shows any part of a key that isn't a valid header value: ${JSON.stringify(key)}`, async () => { + await Bun.write( + path.join(home, ".altimate", "altimate.json"), + JSON.stringify({ altimateUrl: "http://127.0.0.1:9", altimateInstanceName: "acme", altimateApiKey: key }), + ) + const viaRequest = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(viaRequest).toBeInstanceOf(Error) + expect(viaRequest.message).toBe(`API GET /dbt/v1/x ${HEADER_REFUSED}`) + expectNoPartOf(`${viaRequest.message}\n${viaRequest.stack}`, key) + const viaList = (await AltimateApi.listDatamates().catch((e: Error) => e)) as Error + expect(viaList).toBeInstanceOf(Error) + expect(viaList.message).toBe(`API GET /datamates/ ${HEADER_REFUSED}`) + expectNoPartOf(`${viaList.message}\n${viaList.stack}`, key) + }) + } + + test("names a network failure by its code, never by the error's text", async () => { await Bun.write( path.join(home, ".altimate", "altimate.json"), - JSON.stringify({ altimateUrl: "http://127.0.0.1:9", altimateInstanceName: "acme", altimateApiKey: key }), + JSON.stringify({ altimateUrl: "http://127.0.0.1:9", altimateInstanceName: "acme", altimateApiKey: "k1" }), ) - // The real fetch: it rejects a header value with CR/LF, quoting the value. - const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) - expect(error).toBeInstanceOf(Error) - expect(error.message).not.toContain("sk_SECRET123") - expect(error.message).toContain("API GET /dbt/v1/x could not be sent") + const original = globalThis.fetch + globalThis.fetch = (async () => { + throw Object.assign(new Error("Unable to connect: Bearer k1"), { code: "ConnectionRefused" }) + }) as unknown as typeof fetch + try { + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(error.message).toBe("API GET /dbt/v1/x could not be sent: Error (ConnectionRefused).") + } finally { + globalThis.fetch = original + } }) test("never shows the stored key when a header refusal races the caller's abort", async () => { @@ -459,33 +514,47 @@ describe("AltimateApi.apiRequest", () => { const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x", undefined, controller.signal).catch( (e: Error) => e, ) - expect(error.message).toBe("API GET /dbt/v1/x could not be sent: bad header: 'Bearer [redacted]'") + expect(error.message).toBe(`API GET /dbt/v1/x ${HEADER_REFUSED}`) } finally { globalThis.fetch = original } }) - test("never shows the stored key from any fetch failure", async () => { + test("never quotes the credentials file when an ${env:…} variable it names isn't set", async () => { + const file = path.join(home, ".altimate", "altimate.json") await Bun.write( - path.join(home, ".altimate", "altimate.json"), + file, JSON.stringify({ - altimateUrl: "https://api.example.test", + altimateUrl: "https://x.test", altimateInstanceName: "acme", - altimateApiKey: "sk_SECRET123", + altimateApiKey: "${env:sk_SECRET123_UNSET}", }), ) - const original = globalThis.fetch - globalThis.fetch = (async (_url: string, init: RequestInit) => { - throw new TypeError(`bad header: '${(init.headers as Record).Authorization}'`) - }) as unknown as typeof fetch - try { - const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) - expect(error.message).toBe("API GET /dbt/v1/x could not be sent: bad header: 'Bearer [redacted]'") - } finally { - globalThis.fetch = original - } + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(error.message).toBe( + `The Altimate credentials in ${file} can't be used: an \${env:…} variable it refers to is not set.`, + ) }) + test.skipIf(process.platform === "win32" || process.getuid?.() === 0)( + "says the credentials can't be read, not that none are stored, when their directory can't be searched", + async () => { + const dir = path.join(home, ".altimate") + const file = path.join(dir, "altimate.json") + await Bun.write( + file, + JSON.stringify({ altimateUrl: "https://x.test", altimateInstanceName: "a", altimateApiKey: "k" }), + ) + await chmod(dir, 0o600) + try { + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(error.message).toBe(`The Altimate credentials in ${file} can't be read (EACCES).`) + } finally { + await chmod(dir, 0o700) + } + }, + ) + test("a timed-out request says it timed out", async () => { await Bun.write( path.join(home, ".altimate", "altimate.json"), From 3a98dff47e9a501dae418bbe16098ee2fe742550 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 13:29:38 +0530 Subject: [PATCH 18/29] fix: a rejection with no reason is a send failure, not an abort Before either signal aborts, its reason is undefined, so a fetch that rejected with undefined matched it and was rethrown raw. Match a reason only once its signal has aborted. The cleanup test now also covers a timed-out and a cancelled call. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/api/client.ts | 4 +- .../test/altimate/dbt-adapter-access.test.ts | 79 +++++++++++++++---- 2 files changed, 68 insertions(+), 15 deletions(-) diff --git a/packages/opencode/src/altimate/api/client.ts b/packages/opencode/src/altimate/api/client.ts index a7a668183e..123630d58b 100644 --- a/packages/opencode/src/altimate/api/client.ts +++ b/packages/opencode/src/altimate/api/client.ts @@ -356,7 +356,9 @@ export namespace AltimateApi { } catch (e) { // A timeout or the caller's abort rejects with its own reason, which holds no header. An abort // that raced a refused header leaves the header error, so match the reason, not the flag. - if (e === controller.signal.reason || e === signal?.reason) throw e + // A signal that isn't aborted has no reason yet: a rejection with none is a send failure. + if ((controller.signal.aborted && e === controller.signal.reason) || (signal?.aborted && e === signal.reason)) + throw e // Others can quote a header: Bun's check of a header value with CR/LF quotes `Bearer `. throw new Error(`API ${method} ${endpoint} could not be sent: ${sendFailure(e)}`) } diff --git a/packages/opencode/test/altimate/dbt-adapter-access.test.ts b/packages/opencode/test/altimate/dbt-adapter-access.test.ts index 6e3d7958c6..d3a587135e 100644 --- a/packages/opencode/test/altimate/dbt-adapter-access.test.ts +++ b/packages/opencode/test/altimate/dbt-adapter-access.test.ts @@ -276,19 +276,26 @@ describe("dbtAdapterFor", () => { }) test("removes its abort listener and its timer whatever the outcome", async () => { - const controller = new AbortController() - const signal = controller.signal - let listening = 0 - const add = signal.addEventListener.bind(signal) - const remove = signal.removeEventListener.bind(signal) - signal.addEventListener = ((...a: Parameters) => { - if (a[0] === "abort") listening += 1 - return add(...a) - }) as typeof signal.addEventListener - signal.removeEventListener = ((...a: Parameters) => { - if (a[0] === "abort") listening -= 1 - return remove(...a) - }) as typeof signal.removeEventListener + /** A signal that counts the abort listeners still attached to it. */ + const tracked = () => { + const controller = new AbortController() + const signal = controller.signal + const state = { controller, signal, listening: 0 } + const add = signal.addEventListener.bind(signal) + const remove = signal.removeEventListener.bind(signal) + signal.addEventListener = ((...a: Parameters) => { + if (a[0] === "abort") state.listening += 1 + return add(...a) + }) as typeof signal.addEventListener + signal.removeEventListener = ((...a: Parameters) => { + if (a[0] === "abort") state.listening -= 1 + return remove(...a) + }) as typeof signal.removeEventListener + return state + } + const settled = tracked() + const cancelled = tracked() + const signal = settled.signal const timers = new Set() const set = globalThis.setTimeout const clear = globalThis.clearTimeout @@ -308,11 +315,37 @@ describe("dbtAdapterFor", () => { } resetDbtAdapter() expect((await dbtAdapterFor({ ...ctx, abort: signal })).refusal).toBe("not_started") + // Timed out. + dbtAdapterInternals.create = () => new Promise(() => {}) + resetDbtAdapter() + const saved = dbtAdapterAccessInternals.adapterStartTimeoutMs + dbtAdapterAccessInternals.adapterStartTimeoutMs = 20 + try { + expect(await dbtAdapterFor({ ...ctx, abort: signal })).toEqual({ + refusal: "not_started", + reason: "the dbt adapter wasn't ready within 0.02 s", + }) + } finally { + dbtAdapterAccessInternals.adapterStartTimeoutMs = saved + } + // Cancelled while waiting. + let entered = () => {} + const starting = new Promise((resolve) => (entered = resolve)) + dbtAdapterInternals.create = () => { + entered() + return new Promise(() => {}) + } + resetDbtAdapter() + const pending = dbtAdapterFor({ ...ctx, abort: cancelled.signal }) + await starting + cancelled.controller.abort(new Error("cancelled")) + await expect(pending).rejects.toThrow("cancelled") } finally { globalThis.setTimeout = set globalThis.clearTimeout = clear } - expect(listening).toBe(0) + expect(settled.listening).toBe(0) + expect(cancelled.listening).toBe(0) expect(timers.size).toBe(0) }) @@ -478,6 +511,24 @@ describe("AltimateApi.apiRequest", () => { }) } + test("a fetch that rejects with no reason is a send failure, not taken for an abort", async () => { + await Bun.write( + path.join(home, ".altimate", "altimate.json"), + JSON.stringify({ altimateUrl: "http://127.0.0.1:9", altimateInstanceName: "acme", altimateApiKey: "k1" }), + ) + const original = globalThis.fetch + globalThis.fetch = (() => Promise.reject(undefined)) as unknown as typeof fetch + try { + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x", undefined, new AbortController().signal).catch( + (e: unknown) => e, + ) + expect(error).toBeInstanceOf(Error) + expect((error as Error).message).toBe("API GET /dbt/v1/x could not be sent: Error.") + } finally { + globalThis.fetch = original + } + }) + test("names a network failure by its code, never by the error's text", async () => { await Bun.write( path.join(home, ".altimate", "altimate.json"), From f648aee660f76f249f269765947266db0bb24807 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 13:43:18 +0530 Subject: [PATCH 19/29] docs: the docsCoverage contract describes the manifest-columns fallback Co-Authored-By: Claude Sonnet 5.5 --- packages/opencode/src/altimate/tools/dbt-docs-coverage.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts index 4d097f83e1..04b9f6fce1 100644 --- a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts +++ b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts @@ -26,7 +26,7 @@ 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, the engine cannot read it, or its select list cannot be read as column names and the manifest lists no columns. */ +/** Coverage of one manifest model node. Throws when the node has no compiled SQL, or when its select list cannot be read as column names and the manifest lists no columns; with manifest columns, those are counted instead (`source: "manifest_columns"`). */ export function docsCoverage(node: any, dialect: string | undefined): DocsCoverage { const yamlColumns: Record = node.columns ?? {} const described = new Set() From 67f4dae7f0f487b56522120f5caeaeacd0d43732 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 13:49:53 +0530 Subject: [PATCH 20/29] fix: a coded or pre-send TypeError is not a header refusal; bind the adapter to the checked project A send failure with a network code now reports that code even when it is a TypeError. The URL is checked and the body serialised before fetch, so an uncoded TypeError there can only be the header check. dbtAdapterFor compares the root the adapter started from with the project it checked, refusing as other_project when a later config read named another. The leak assertions now check every 8-character run of the key. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/api/client.ts | 18 +++-- .../src/altimate/tools/dbt-adapter-access.ts | 25 +++++-- .../test/altimate/dbt-adapter-access.test.ts | 71 ++++++++++++++++++- 3 files changed, 100 insertions(+), 14 deletions(-) diff --git a/packages/opencode/src/altimate/api/client.ts b/packages/opencode/src/altimate/api/client.ts index 123630d58b..54d7625e65 100644 --- a/packages/opencode/src/altimate/api/client.ts +++ b/packages/opencode/src/altimate/api/client.ts @@ -333,12 +333,15 @@ export namespace AltimateApi { * stored key can be relied on: only the error's name and code are shown. */ function sendFailure(e: unknown): string { - if (e instanceof TypeError) - return "the request was refused before it was sent (TypeError): the stored API key or tenant name may not be a valid header value." const word = (v: unknown) => (typeof v === "string" && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(v) ? v : undefined) const name = (e instanceof Error && word(e.name)) || "Error" const code = word((e as { code?: unknown } | null)?.code) - return code ? `${name} (${code}).` : `${name}.` + // A network failure carries its code, whatever its class. + if (code) return `${name} (${code}).` + // The URL and the body are checked before sending, so an uncoded TypeError is the header check. + if (e instanceof TypeError) + return "the request was refused before it was sent (TypeError): the stored API key or tenant name may not be a valid header value." + return `${name}.` } async function request( @@ -349,6 +352,12 @@ export namespace AltimateApi { signal?: AbortSignal, ) { const url = `${creds.altimateUrl}${endpoint}` + // Checked here so that only the header check can make fetch throw a TypeError before sending. + if (!URL.canParse(url)) + throw new Error(`API ${method} ${endpoint} could not be sent: the stored API URL is not a valid URL.`) + // Any body but undefined is sent: null, false, 0 and "" are JSON values too. A body that can't be + // serialised fails here with its own error, which quotes no credential. + const payload = body !== undefined ? JSON.stringify(body) : undefined // Bun's fetch throws at once, not as a rejection, when it refuses a header: both are caught. const send = async (start: () => Promise) => { try { @@ -384,8 +393,7 @@ export namespace AltimateApi { "x-tenant": creds.altimateInstanceName, ...clientHeaders(), }, - // Any body but undefined is sent: null, false, 0 and "" are JSON values too. - ...(body !== undefined ? { body: JSON.stringify(body) } : {}), + ...(payload !== undefined ? { body: payload } : {}), }), ) if (!res.ok) { diff --git a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts index d51d2b4d2b..8c81cb0980 100644 --- a/packages/opencode/src/altimate/tools/dbt-adapter-access.ts +++ b/packages/opencode/src/altimate/tools/dbt-adapter-access.ts @@ -74,6 +74,15 @@ export async function dbtAdapterFor(ctx: Pick { - 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 } diff --git a/packages/opencode/test/altimate/dbt-adapter-access.test.ts b/packages/opencode/test/altimate/dbt-adapter-access.test.ts index d3a587135e..4f2c9eb8d9 100644 --- a/packages/opencode/test/altimate/dbt-adapter-access.test.ts +++ b/packages/opencode/test/altimate/dbt-adapter-access.test.ts @@ -349,6 +349,29 @@ describe("dbtAdapterFor", () => { expect(timers.size).toBe(0) }) + test("refuses an adapter started from a later config read naming another project", async () => { + const other = await mkdtemp(path.join(os.tmpdir(), "dbt-adapter-moved-")) + await writeFile(path.join(other, "dbt_project.yml"), "name: other\n") + let reads = 0 + // The session check reads the session's project; the adapter's own start reads another. + dbtAdapterInternals.readConfig = async () => ({ + projectRoot: reads++ === 0 ? project : 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 ${other}, not ${project}`, + }) + } finally { + await disposeInstance(project) + await rm(other, { recursive: true, force: true }) + } + }) + 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") @@ -482,9 +505,11 @@ describe("AltimateApi.apiRequest", () => { const HEADER_REFUSED = "could not be sent: the request was refused before it was sent (TypeError): the stored API key or tenant name may not be a valid header value." - /** Every substring of `key` long enough to identify it, so a trimmed or split copy is caught too. */ + /** No 8-character run of `key` (or of a shorter piece of it) appears, so a trimmed or split copy is caught too. */ function expectNoPartOf(text: string, key: string) { - for (const part of key.split(/\s+/).filter((p) => p.length >= 4)) expect(text).not.toContain(part) + for (const piece of key.split(/\s+/).filter((p) => p.length >= 4)) + for (let i = 0; i + Math.min(8, piece.length) <= piece.length; i++) + expect(text).not.toContain(piece.slice(i, i + Math.min(8, piece.length))) expect(text).not.toContain("Bearer") } @@ -529,6 +554,48 @@ describe("AltimateApi.apiRequest", () => { } }) + test("a coded TypeError is a network failure, not a header refusal", async () => { + await Bun.write( + path.join(home, ".altimate", "altimate.json"), + JSON.stringify({ altimateUrl: "http://127.0.0.1:9", altimateInstanceName: "acme", altimateApiKey: "k1" }), + ) + const original = globalThis.fetch + globalThis.fetch = (async () => { + throw Object.assign(new TypeError("fetch failed"), { code: "ECONNREFUSED" }) + }) as unknown as typeof fetch + try { + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(error.message).toBe("API GET /dbt/v1/x could not be sent: TypeError (ECONNREFUSED).") + } finally { + globalThis.fetch = original + } + }) + + test("a stored URL that isn't one, or a body that can't be serialised, is not called a bad header", async () => { + const file = path.join(home, ".altimate", "altimate.json") + await Bun.write( + file, + JSON.stringify({ altimateUrl: "api.example.test", altimateInstanceName: "a", altimateApiKey: "k1" }), + ) + const badUrl = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(badUrl.message).toBe("API GET /dbt/v1/x could not be sent: the stored API URL is not a valid URL.") + await Bun.write( + file, + JSON.stringify({ altimateUrl: "http://127.0.0.1:9", altimateInstanceName: "a", altimateApiKey: "k1" }), + ) + const original = globalThis.fetch + let sent = 0 + globalThis.fetch = (async () => (sent++, new Response("{}"))) as unknown as typeof fetch + try { + const badBody = await AltimateApi.apiRequest("POST", "/dbt/v1/x", { n: 1n }).catch((e: Error) => e) + expect(badBody).toBeInstanceOf(TypeError) + expect(badBody.message).not.toContain("header") + expect(sent).toBe(0) + } finally { + globalThis.fetch = original + } + }) + test("names a network failure by its code, never by the error's text", async () => { await Bun.write( path.join(home, ".altimate", "altimate.json"), From caa4c7c4f0dab2c59939166221a6ed1fc0a45f7d Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 14:08:59 +0530 Subject: [PATCH 21/29] fix: send API requests only to an http(s) URL "localhost:3000" parses as a URL with the scheme "localhost:", so fetch threw an uncoded TypeError that was reported as a bad header value. Co-Authored-By: Claude Opus 5.5 --- packages/opencode/src/altimate/api/client.ts | 7 ++++--- .../test/altimate/dbt-adapter-access.test.ts | 16 ++++++++++++++-- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/packages/opencode/src/altimate/api/client.ts b/packages/opencode/src/altimate/api/client.ts index 54d7625e65..4c1b153ca1 100644 --- a/packages/opencode/src/altimate/api/client.ts +++ b/packages/opencode/src/altimate/api/client.ts @@ -352,9 +352,10 @@ export namespace AltimateApi { signal?: AbortSignal, ) { const url = `${creds.altimateUrl}${endpoint}` - // Checked here so that only the header check can make fetch throw a TypeError before sending. - if (!URL.canParse(url)) - throw new Error(`API ${method} ${endpoint} could not be sent: the stored API URL is not a valid URL.`) + // Checked here so that only the header check can make fetch throw a TypeError before sending. Only + // http(s) is sent: "localhost:3000" parses as a URL with the scheme "localhost:". + if (!URL.canParse(url) || !["http:", "https:"].includes(new URL(url).protocol)) + throw new Error(`API ${method} ${endpoint} could not be sent: the stored API URL is not an http(s) URL.`) // Any body but undefined is sent: null, false, 0 and "" are JSON values too. A body that can't be // serialised fails here with its own error, which quotes no credential. const payload = body !== undefined ? JSON.stringify(body) : undefined diff --git a/packages/opencode/test/altimate/dbt-adapter-access.test.ts b/packages/opencode/test/altimate/dbt-adapter-access.test.ts index 4f2c9eb8d9..4317672e42 100644 --- a/packages/opencode/test/altimate/dbt-adapter-access.test.ts +++ b/packages/opencode/test/altimate/dbt-adapter-access.test.ts @@ -577,8 +577,20 @@ describe("AltimateApi.apiRequest", () => { file, JSON.stringify({ altimateUrl: "api.example.test", altimateInstanceName: "a", altimateApiKey: "k1" }), ) - const badUrl = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) - expect(badUrl.message).toBe("API GET /dbt/v1/x could not be sent: the stored API URL is not a valid URL.") + const realFetch = globalThis.fetch + let urlSends = 0 + globalThis.fetch = (async () => (urlSends++, new Response("{}"))) as unknown as typeof fetch + try { + // Not a URL, or a URL whose scheme isn't http(s): "localhost:3000" parses with the scheme "localhost:". + for (const altimateUrl of ["api.example.test", "localhost:3000", "file:///tmp", "ftp://api.example.test"]) { + await Bun.write(file, JSON.stringify({ altimateUrl, altimateInstanceName: "a", altimateApiKey: "k1" })) + const badUrl = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(badUrl.message).toBe("API GET /dbt/v1/x could not be sent: the stored API URL is not an http(s) URL.") + } + expect(urlSends).toBe(0) + } finally { + globalThis.fetch = realFetch + } await Bun.write( file, JSON.stringify({ altimateUrl: "http://127.0.0.1:9", altimateInstanceName: "a", altimateApiKey: "k1" }), From b9bd43dc2ccdf527f2b035ec6ae27391834a3d72 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 14:16:25 +0530 Subject: [PATCH 22/29] fix: case-colliding outputs get no rating, an exact blank YAML entry wins, a network TypeError is not a bad header Co-Authored-By: Claude Sonnet 5.5 --- packages/opencode/src/altimate/api/client.ts | 11 ++-- .../src/altimate/native/dbt/column-reach.ts | 26 +++++++++- .../src/altimate/tools/dbt-docs-coverage.ts | 9 +++- .../test/altimate/column-reach.test.ts | 50 +++++++++++++++++++ .../test/altimate/dbt-adapter-access.test.ts | 17 +++++++ .../test/altimate/dbt-docs-coverage.test.ts | 14 ++++++ 6 files changed, 120 insertions(+), 7 deletions(-) diff --git a/packages/opencode/src/altimate/api/client.ts b/packages/opencode/src/altimate/api/client.ts index 123630d58b..7d98d37beb 100644 --- a/packages/opencode/src/altimate/api/client.ts +++ b/packages/opencode/src/altimate/api/client.ts @@ -333,11 +333,16 @@ export namespace AltimateApi { * stored key can be relied on: only the error's name and code are shown. */ function sendFailure(e: unknown): string { - if (e instanceof TypeError) - return "the request was refused before it was sent (TypeError): the stored API key or tenant name may not be a valid header value." const word = (v: unknown) => (typeof v === "string" && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(v) ? v : undefined) + // A refused header is a TypeError with no code and no cause; a failed connection is a TypeError too + // (`fetch failed`) but carries one or the other. + const cause = (e as { cause?: unknown } | null)?.cause + const evidence = word((e as { code?: unknown } | null)?.code) || cause !== undefined + if (e instanceof TypeError && !evidence) + return "the request was refused before it was sent (TypeError): the stored API key or tenant name may not be a valid header value." const name = (e instanceof Error && word(e.name)) || "Error" - const code = word((e as { code?: unknown } | null)?.code) + const code = + word((e as { code?: unknown } | null)?.code) || word((cause as { code?: unknown } | null | undefined)?.code) return code ? `${name} (${code}).` : `${name}.` } diff --git a/packages/opencode/src/altimate/native/dbt/column-reach.ts b/packages/opencode/src/altimate/native/dbt/column-reach.ts index baa73d339a..db612032b7 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -127,16 +127,20 @@ function rated( dialect: string, parents: string[], lookup: (id: string) => any, + columnsOf: (id: string) => { name: string; type?: string }[], ): 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]) => ({ + // The columns the first trace reads the parent against: the YAML's, or the compiled SQL's when it lists none. + const declared = Object.entries(node?.columns ?? {}).map(([key, col]) => ({ name: String(col?.name ?? key), type: String(col?.data_type ?? col?.type ?? ""), })) + const columns = + declared.length > 0 ? declared : columnsOf(parent).map((col) => ({ name: col.name, type: String(col.type ?? "") })) if (columns.length === 0) continue for (const key of relationKeys(node)) tables[key] = { columns } } @@ -396,7 +400,14 @@ 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 edges = rated( + listed, + sqlText, + dialect || detectDialect(manifest), + allParents, + lookup, + (id) => project.columns(id), + ) const bareName = (p: string) => { const node = lookup(p) return String(node?.alias || node?.identifier || node?.name || p).toLowerCase() @@ -447,6 +458,17 @@ export function columnReach(manifestPath: string, model: string, column: string, carriedExact.add(edge.target) } } + // Outputs whose names differ only by case are different columns, but the result keys them in lower + // case: a rating there could name either one, so none is published. + // Every output the engine traced counts, not only those carrying the column: a sibling output + // that shares the lower-cased name is the one a rating could be mistaken for. + const exactByLower = new Map>() + for (const edge of edges) { + if (typeof edge.target !== "string") continue + const lower = edge.target.toLowerCase() + exactByLower.set(lower, (exactByLower.get(lower) ?? new Set()).add(edge.target)) + } + for (const [out, exact] of exactByLower) if (exact.size > 1) carriedLens.set(out, undefined) // The engine has no schema for the tables inside an inlined ephemeral parent, so it reports no // edge through it: unknown, not unread, even when another parent's edges are traced. const viaEphemeral = parents.some((p) => lookup(p)?.config?.materialized === "ephemeral") diff --git a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts index 04b9f6fce1..aaff322182 100644 --- a/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts +++ b/packages/opencode/src/altimate/tools/dbt-docs-coverage.ts @@ -30,8 +30,11 @@ const hasText = (value: unknown) => typeof value === "string" && value.trim().le export function docsCoverage(node: any, dialect: string | undefined): DocsCoverage { const yamlColumns: Record = node.columns ?? {} const described = new Set() + const listed = new Set() for (const [key, col] of Object.entries(yamlColumns)) { - if (hasText(col?.description)) described.add(String(col?.name || key)) + const name = String(col?.name || key) + listed.add(name) + if (hasText(col?.description)) described.add(name) } const sql: string = node.compiled_code || node.compiled_sql || "" @@ -65,8 +68,10 @@ export function docsCoverage(node: any, dialect: string | undefined): DocsCovera 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())) + // A YAML entry with exactly this name speaks for the column, blank or not; only without one is the + // name matched ignoring case. const isDocumented = (c: string) => - byCase.get(c.toLowerCase()) === 1 ? describedFolded.has(c.toLowerCase()) : described.has(c) + byCase.get(c.toLowerCase()) === 1 && !listed.has(c) ? 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 diff --git a/packages/opencode/test/altimate/column-reach.test.ts b/packages/opencode/test/altimate/column-reach.test.ts index b53b35f52f..bef89d94a1 100644 --- a/packages/opencode/test/altimate/column-reach.test.ts +++ b/packages/opencode/test/altimate/column-reach.test.ts @@ -143,6 +143,56 @@ describe("columnReach", () => { expect(found?.lens_types).toEqual({ net: "Alias", revenue: "Original" }) }) + test("outputs that differ only by case publish no rating, as the lower-cased key could name either", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.stg_case"] = model( + "stg_case", + ["model.shop.fct_orders"], + 'select revenue as "Foo", gross_revenue as "foo" from "shop"."main"."fct_orders"', + ["Foo", "foo"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + const found = reach.models.find((m) => m.name === "stg_case") + expect(found?.lens_types).toBeUndefined() + }) + + test("a parent that lists no YAML columns is rated by the columns its SQL gives it", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.stg_bare"] = model( + "stg_bare", + ["model.shop.fct_orders"], + 'select revenue, gross_revenue from "shop"."main"."fct_orders"', + [], + ) + nodes["model.shop.mart_bare"] = model( + "mart_bare", + ["model.shop.stg_bare"], + 'select revenue as net from "shop"."main"."stg_bare"', + ["net"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + expect(reach.models.find((m) => m.name === "mart_bare")?.lens_types).toEqual({ net: "Alias" }) + }) + + test("two qualified relations sharing a column name are rated each by its own read", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.dim_rates"] = model("dim_rates", [], "select order_id, revenue from raw.rates", [ + "order_id", + "revenue", + ]) + nodes["model.shop.stg_two"] = model( + "stg_two", + ["model.shop.fct_orders", "model.shop.dim_rates"], + 'select o.revenue as kept, r.revenue * 2 as scaled from "shop"."main"."fct_orders" o join "shop"."main"."dim_rates" r on o.order_id = r.order_id', + ["kept", "scaled"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + expect(reach.models.find((m) => m.name === "stg_two")?.lens_types).toEqual({ kept: "Alias" }) + }) + test("a column named __proto__ keeps its rating", () => { const value = manifest() const nodes = value.nodes as Record diff --git a/packages/opencode/test/altimate/dbt-adapter-access.test.ts b/packages/opencode/test/altimate/dbt-adapter-access.test.ts index 0b6e1a1d0c..63b0dd9594 100644 --- a/packages/opencode/test/altimate/dbt-adapter-access.test.ts +++ b/packages/opencode/test/altimate/dbt-adapter-access.test.ts @@ -546,6 +546,23 @@ describe("AltimateApi.apiRequest", () => { } }) + test("a TypeError carrying a code or cause is a network failure, not a bad header", async () => { + await Bun.write( + path.join(home, ".altimate", "altimate.json"), + JSON.stringify({ altimateUrl: "http://127.0.0.1:9", altimateInstanceName: "acme", altimateApiKey: "k1" }), + ) + const original = globalThis.fetch + globalThis.fetch = (async () => { + throw Object.assign(new TypeError("fetch failed: Bearer k1"), { cause: { code: "ECONNREFUSED" } }) + }) as unknown as typeof fetch + try { + const error = await AltimateApi.apiRequest("GET", "/dbt/v1/x").catch((e: Error) => e) + expect(error.message).toBe("API GET /dbt/v1/x could not be sent: TypeError (ECONNREFUSED).") + } finally { + globalThis.fetch = original + } + }) + test("never shows the stored key when a header refusal races the caller's abort", async () => { await Bun.write( path.join(home, ".altimate", "altimate.json"), diff --git a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts index 4ba693e8ee..9f12e0808d 100644 --- a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts +++ b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts @@ -65,6 +65,20 @@ describe("docsCoverage", () => { expect(r.missing).toEqual([]) }) + test("a blank entry with the column's exact name is not overridden by another entry's description", () => { + const r = docsCoverage( + { + ...orders, + columns: { Foo: { name: "Foo", description: "described" }, foo: { name: "foo", description: "" } }, + compiled_code: 'select "foo" from t', + }, + "snowflake", + ) + expect(r.documented).toEqual([]) + expect(r.missing).toEqual(["foo"]) + expect(r.percent).toBe(0) + }) + test("a model without a description reports it", () => { expect(docsCoverage({ ...orders, description: "" }, "snowflake").has_description).toBe(false) }) From 316d5502bef09617dcea44578bd57dc0b146b01a Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 16:13:45 +0530 Subject: [PATCH 23/29] fix: retry schema merges YAML and compiled columns; case-collision test pins the reach Co-Authored-By: Claude Sonnet 5.5 --- .../opencode/src/altimate/native/dbt/column-reach.ts | 11 ++++++++--- packages/opencode/test/altimate/column-reach.test.ts | 1 + 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/packages/opencode/src/altimate/native/dbt/column-reach.ts b/packages/opencode/src/altimate/native/dbt/column-reach.ts index db612032b7..9105c01593 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -134,13 +134,18 @@ function rated( const tables: Record = {} for (const parent of parents) { const node = lookup(parent) - // The columns the first trace reads the parent against: the YAML's, or the compiled SQL's when it lists none. + // The columns the first trace reads the parent against: the YAML's, plus any the compiled SQL gives it that the YAML omits. const declared = Object.entries(node?.columns ?? {}).map(([key, col]) => ({ name: String(col?.name ?? key), type: String(col?.data_type ?? col?.type ?? ""), })) - const columns = - declared.length > 0 ? declared : columnsOf(parent).map((col) => ({ name: col.name, type: String(col.type ?? "") })) + const known = new Set(declared.map((col) => col.name.toLowerCase())) + const columns = [ + ...declared, + ...columnsOf(parent) + .filter((col) => !known.has(col.name.toLowerCase())) + .map((col) => ({ name: col.name, type: String(col.type ?? "") })), + ] if (columns.length === 0) continue for (const key of relationKeys(node)) tables[key] = { columns } } diff --git a/packages/opencode/test/altimate/column-reach.test.ts b/packages/opencode/test/altimate/column-reach.test.ts index bef89d94a1..b361f5e65a 100644 --- a/packages/opencode/test/altimate/column-reach.test.ts +++ b/packages/opencode/test/altimate/column-reach.test.ts @@ -154,6 +154,7 @@ describe("columnReach", () => { ) const reach = columnReach(manifestFile(value), "fct_orders", "revenue") const found = reach.models.find((m) => m.name === "stg_case") + expect(found?.columns).toEqual(["foo"]) expect(found?.lens_types).toBeUndefined() }) From ec464792ca4c11635f85c717f7e25e1cbeb60264 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Tue, 17 Nov 2026 21:09:21 +0530 Subject: [PATCH 24/29] test: restore the inherited telemetry setting after the docs coverage tests Co-Authored-By: Claude Sonnet 5.5 --- packages/opencode/test/altimate/dbt-docs-coverage.test.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts index 9f12e0808d..89c926bec4 100644 --- a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts +++ b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts @@ -10,11 +10,13 @@ import { initTool } from "./tool-fixture" import { DbtDocsCoverageTool, docsCoverage } from "../../src/altimate/tools/dbt-docs-coverage" import { SessionID, MessageID } from "../../src/session/schema" +const inheritedTelemetry = process.env.ALTIMATE_TELEMETRY_DISABLED beforeEach(() => { process.env.ALTIMATE_TELEMETRY_DISABLED = "true" }) afterAll(() => { - delete process.env.ALTIMATE_TELEMETRY_DISABLED + if (inheritedTelemetry === undefined) delete process.env.ALTIMATE_TELEMETRY_DISABLED + else process.env.ALTIMATE_TELEMETRY_DISABLED = inheritedTelemetry }) const ctx = { From e2a9f935ba4703d405e18370fbebab532c7ba63d Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Wed, 18 Nov 2026 13:37:08 +0530 Subject: [PATCH 25/29] fix: column_reach rates only a model's real output names Co-Authored-By: Claude Sonnet 5.5 --- .../src/altimate/native/dbt/column-reach.ts | 3 +++ .../opencode/test/altimate/column-reach.test.ts | 14 ++++++++++++++ 2 files changed, 17 insertions(+) diff --git a/packages/opencode/src/altimate/native/dbt/column-reach.ts b/packages/opencode/src/altimate/native/dbt/column-reach.ts index 9105c01593..ec5c496d9f 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -474,6 +474,9 @@ export function columnReach(manifestPath: string, model: string, column: string, exactByLower.set(lower, (exactByLower.get(lower) ?? new Set()).add(edge.target)) } for (const [out, exact] of exactByLower) if (exact.size > 1) carriedLens.set(out, undefined) + // A name the engine invents for an unaliased calculation (`_0`) is no column of the model: it gets no rating. + const realNames = new Set(project.columns(id).map((col) => col.name)) + for (const out of carriedLens.keys()) if (!realNames.has(out)) carriedLens.set(out, undefined) // The engine has no schema for the tables inside an inlined ephemeral parent, so it reports no // edge through it: unknown, not unread, even when another parent's edges are traced. const viaEphemeral = parents.some((p) => lookup(p)?.config?.materialized === "ephemeral") diff --git a/packages/opencode/test/altimate/column-reach.test.ts b/packages/opencode/test/altimate/column-reach.test.ts index 48258591d8..e3e8e8aeca 100644 --- a/packages/opencode/test/altimate/column-reach.test.ts +++ b/packages/opencode/test/altimate/column-reach.test.ts @@ -158,6 +158,20 @@ describe("columnReach", () => { expect(found?.lens_types).toBeUndefined() }) + test("an unaliased calculation's engine-made output name gets no rating", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.stg_calc"] = model( + "stg_calc", + ["model.shop.fct_orders"], + 'select revenue + 1 from "shop"."main"."fct_orders"', + [], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + const found = reach.models.find((m) => m.name === "stg_calc") + expect(Object.values(found?.lens_types ?? {})).not.toContain("Original") + }) + test("a parent that lists no YAML columns is rated by the columns its SQL gives it", () => { const value = manifest() const nodes = value.nodes as Record From c1c73387b35d36a5fbd46627e98a7c9e78af73a1 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Wed, 18 Nov 2026 14:14:57 +0530 Subject: [PATCH 26/29] fix: a documented engine-style output name gets no rating; sharper tests, telemetry cleanup Co-Authored-By: Claude Sonnet 5.5 --- .../src/altimate/native/dbt/column-reach.ts | 5 ++++- .../test/altimate/column-reach.test.ts | 18 +++++++++++++++++- .../test/altimate/dbt-docs-coverage.test.ts | 5 ++++- 3 files changed, 25 insertions(+), 3 deletions(-) diff --git a/packages/opencode/src/altimate/native/dbt/column-reach.ts b/packages/opencode/src/altimate/native/dbt/column-reach.ts index ec5c496d9f..44a4611d32 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -476,7 +476,10 @@ export function columnReach(manifestPath: string, model: string, column: string, for (const [out, exact] of exactByLower) if (exact.size > 1) carriedLens.set(out, undefined) // A name the engine invents for an unaliased calculation (`_0`) is no column of the model: it gets no rating. const realNames = new Set(project.columns(id).map((col) => col.name)) - for (const out of carriedLens.keys()) if (!realNames.has(out)) carriedLens.set(out, undefined) + // A documented `_0` is the engine's placeholder all the same unless the SQL writes that name itself. + const writes = (name: string) => new RegExp(`(? lookup(p)?.config?.materialized === "ephemeral") diff --git a/packages/opencode/test/altimate/column-reach.test.ts b/packages/opencode/test/altimate/column-reach.test.ts index e3e8e8aeca..2e6093f816 100644 --- a/packages/opencode/test/altimate/column-reach.test.ts +++ b/packages/opencode/test/altimate/column-reach.test.ts @@ -169,7 +169,23 @@ describe("columnReach", () => { ) const reach = columnReach(manifestFile(value), "fct_orders", "revenue") const found = reach.models.find((m) => m.name === "stg_calc") - expect(Object.values(found?.lens_types ?? {})).not.toContain("Original") + expect(found?.columns).toEqual(["_0", "_col_0"]) + expect(found?.lens_types).toBeUndefined() + }) + + test("a documented engine-style name the SQL never writes gets no rating", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.stg_doc"] = model( + "stg_doc", + ["model.shop.fct_orders"], + 'select revenue + 1 from "shop"."main"."fct_orders"', + ["_0"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + const found = reach.models.find((m) => m.name === "stg_doc") + expect(found).toBeDefined() + expect(found?.lens_types).toBeUndefined() }) test("a parent that lists no YAML columns is rated by the columns its SQL gives it", () => { diff --git a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts index 89c926bec4..b0c6a33db6 100644 --- a/packages/opencode/test/altimate/dbt-docs-coverage.test.ts +++ b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts @@ -6,6 +6,7 @@ import { describe, test, expect, beforeEach, afterEach, afterAll } from "bun:tes import { mkdtempSync, rmSync, writeFileSync } from "node:fs" import { tmpdir } from "node:os" import { join } from "node:path" +import { Telemetry } from "../../src/telemetry" import { initTool } from "./tool-fixture" import { DbtDocsCoverageTool, docsCoverage } from "../../src/altimate/tools/dbt-docs-coverage" import { SessionID, MessageID } from "../../src/session/schema" @@ -14,7 +15,9 @@ const inheritedTelemetry = process.env.ALTIMATE_TELEMETRY_DISABLED beforeEach(() => { process.env.ALTIMATE_TELEMETRY_DISABLED = "true" }) -afterAll(() => { +afterAll(async () => { + // Drops any events the tool buffered while telemetry was disabled, so a later suite cannot flush them. + await Telemetry.shutdown() if (inheritedTelemetry === undefined) delete process.env.ALTIMATE_TELEMETRY_DISABLED else process.env.ALTIMATE_TELEMETRY_DISABLED = inheritedTelemetry }) From 813466f974c968c31551bedd23247dd5bdc8f876 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Wed, 18 Nov 2026 15:07:51 +0530 Subject: [PATCH 27/29] refactor: column_reach reuses engineMade; pin the SQL-written engine-style name keeps its rating Co-Authored-By: Claude Sonnet 5.5 --- .../src/altimate/native/dbt/column-reach.ts | 6 +++--- .../src/altimate/native/dbt/project-lineage.ts | 2 +- .../opencode/test/altimate/column-reach.test.ts | 14 ++++++++++++++ 3 files changed, 18 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 44a4611d32..b2194935af 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -9,7 +9,7 @@ import * as core from "@altimateai/altimate-core" import { loadRawManifest, findModel, detectDialect } from "./helpers" import { dbtLineage } from "./lineage" -import { missingColumn, projectLineage, selectsStar, stripSql } from "./project-lineage" +import { engineMade, missingColumn, projectLineage, selectsStar, stripSql } from "./project-lineage" export interface ColumnReachModel { name: string @@ -477,9 +477,9 @@ export function columnReach(manifestPath: string, model: string, column: string, // A name the engine invents for an unaliased calculation (`_0`) is no column of the model: it gets no rating. const realNames = new Set(project.columns(id).map((col) => col.name)) // A documented `_0` is the engine's placeholder all the same unless the SQL writes that name itself. - const writes = (name: string) => new RegExp(`(? lookup(p)?.config?.materialized === "ephemeral") diff --git a/packages/opencode/src/altimate/native/dbt/project-lineage.ts b/packages/opencode/src/altimate/native/dbt/project-lineage.ts index ab22c8dc07..3d3a64e50a 100644 --- a/packages/opencode/src/altimate/native/dbt/project-lineage.ts +++ b/packages/opencode/src/altimate/native/dbt/project-lineage.ts @@ -98,7 +98,7 @@ const COLUMNS_CALL = /(? { expect(found?.lens_types).toBeUndefined() }) + test("an engine-style output name the SQL writes itself keeps its rating", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.stg_named"] = model( + "stg_named", + ["model.shop.fct_orders"], + 'select revenue as _0 from "shop"."main"."fct_orders"', + ["_0"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + const found = reach.models.find((m) => m.name === "stg_named") + expect(found?.lens_types).toEqual({ _0: "Alias" }) + }) + test("a documented engine-style name the SQL never writes gets no rating", () => { const value = manifest() const nodes = value.nodes as Record From 9834f0c469ecf2275146b095621f83ba135824eb Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Wed, 18 Nov 2026 15:11:46 +0530 Subject: [PATCH 28/29] test: column_reach engine-style name mentioned only in a comment or literal gets no rating Co-Authored-By: Claude Sonnet 5.5 --- .../opencode/test/altimate/column-reach.test.ts | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/packages/opencode/test/altimate/column-reach.test.ts b/packages/opencode/test/altimate/column-reach.test.ts index e1def89b91..fb3c9aecd0 100644 --- a/packages/opencode/test/altimate/column-reach.test.ts +++ b/packages/opencode/test/altimate/column-reach.test.ts @@ -187,6 +187,21 @@ describe("columnReach", () => { expect(found?.lens_types).toEqual({ _0: "Alias" }) }) + test("an engine-style name that only a comment or literal mentions gets no rating", () => { + const value = manifest() + const nodes = value.nodes as Record + nodes["model.shop.stg_mention"] = model( + "stg_mention", + ["model.shop.fct_orders"], + "select revenue + 1 /* _0 */, '_0' as note from \"shop\".\"main\".\"fct_orders\"", + ["_0"], + ) + const reach = columnReach(manifestFile(value), "fct_orders", "revenue") + const found = reach.models.find((m) => m.name === "stg_mention") + expect(found).toBeDefined() + expect(found?.lens_types).toBeUndefined() + }) + test("a documented engine-style name the SQL never writes gets no rating", () => { const value = manifest() const nodes = value.nodes as Record From dc28a3e55838ad2babd7a538229778b5213f86aa Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Wed, 18 Nov 2026 15:15:40 +0530 Subject: [PATCH 29/29] test: pin that the comment-only engine-style name is carried Co-Authored-By: Claude Sonnet 5.5 --- packages/opencode/test/altimate/column-reach.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/opencode/test/altimate/column-reach.test.ts b/packages/opencode/test/altimate/column-reach.test.ts index fb3c9aecd0..97ae23aad4 100644 --- a/packages/opencode/test/altimate/column-reach.test.ts +++ b/packages/opencode/test/altimate/column-reach.test.ts @@ -198,7 +198,7 @@ describe("columnReach", () => { ) const reach = columnReach(manifestFile(value), "fct_orders", "revenue") const found = reach.models.find((m) => m.name === "stg_mention") - expect(found).toBeDefined() + expect(found?.columns).toContain("_0") expect(found?.lens_types).toBeUndefined() })