diff --git a/packages/opencode/src/altimate/native/dbt/column-reach.ts b/packages/opencode/src/altimate/native/dbt/column-reach.ts index 087f9b2fa8..b2194935af 100644 --- a/packages/opencode/src/altimate/native/dbt/column-reach.ts +++ b/packages/opencode/src/altimate/native/dbt/column-reach.ts @@ -6,15 +6,24 @@ // 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" -import { missingColumn, projectLineage, selectsStar, stripSql } from "./project-lineage" +import { engineMade, missingColumn, projectLineage, selectsStar, stripSql } from "./project-lineage" export interface ColumnReachModel { name: string 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 { @@ -58,6 +67,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 = @@ -66,8 +85,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. @@ -94,6 +112,68 @@ 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, + 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) + // 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 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 } + } + 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) + // 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 + 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 @@ -274,6 +354,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)) @@ -307,7 +389,7 @@ 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 listed: LineageEdge[] = lineage?.column_lineage?.length ? lineage.column_lineage : Object.entries(lineage?.column_dict ?? {}).flatMap(([out, sources]) => (Array.isArray(sources) ? sources : [sources]).map((source) => ({ @@ -323,6 +405,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, + (id) => project.columns(id), + ) const bareName = (p: string) => { const node = lookup(p) return String(node?.alias || node?.identifier || node?.name || p).toLowerCase() @@ -346,6 +436,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) { @@ -360,10 +451,35 @@ 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() + // 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, + ) + // 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) } } + // 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) + // 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 strippedSql = stripSql(sqlText) + for (const out of carriedLens.keys()) + if (!realNames.has(out) || engineMade(out, strippedSql)) 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") @@ -376,10 +492,24 @@ 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() + // 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, + columns, + ...(Object.keys(lens_types).length > 0 && { lens_types }), + }) continue } 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 = /(? typeof value === "string" && value.trim().length > 0 + +/** 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() + const listed = new Set() + for (const [key, col] of Object.entries(yamlColumns)) { + 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 || "" + 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 { + // 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 (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}" 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\`.`, + ) + } + + 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())) + // 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 && !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 + 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: - "Documentation coverage of a dbt model: which output columns have a description, and whether the model has one.", + 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("Model name"), - manifest_path: z - .string() - .optional() - .describe("manifest.json to read (default: the dbt project's target/manifest.json)"), + 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() { - return { - title: "dbt_docs_coverage: not implemented", - metadata: { success: false, error: "not implemented" }, - output: "dbt_docs_coverage is not implemented in this build of altimate-code yet.", + async execute(args, _ctx) { + try { + const manifest = loadRawManifest(args.manifest_path) + if (!manifest) { + return { + title: "Docs coverage: NO MANIFEST", + metadata: { success: false, error: `No manifest at ${args.manifest_path}` }, + 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, error: `Model "${args.model}" not found` }, + 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'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}%`, + 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/column-reach.test.ts b/packages/opencode/test/altimate/column-reach.test.ts index 2f32d9cd8e..97ae23aad4 100644 --- a/packages/opencode/test/altimate/column-reach.test.ts +++ b/packages/opencode/test/altimate/column-reach.test.ts @@ -118,6 +118,234 @@ 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 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("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?.columns).toEqual(["foo"]) + 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(found?.columns).toEqual(["_0", "_col_0"]) + 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("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?.columns).toContain("_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", () => { + 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 + 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 + 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 [ @@ -420,9 +648,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/dbt-docs-coverage.test.ts b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts new file mode 100644 index 0000000000..b0c6a33db6 --- /dev/null +++ b/packages/opencode/test/altimate/dbt-docs-coverage.test.ts @@ -0,0 +1,210 @@ +/** + * 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, afterEach, afterAll } from "bun:test" +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" + +const inheritedTelemetry = process.env.ALTIMATE_TELEMETRY_DISABLED +beforeEach(() => { + process.env.ALTIMATE_TELEMETRY_DISABLED = "true" +}) +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 +}) + +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 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) + }) + + 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("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 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", () => { + expect(() => + docsCoverage({ ...orders, columns: {}, compiled_code: "select * from raw.orders" }, "snowflake"), + ).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 them 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") + }) +}) + +describe("dbt_docs_coverage tool", () => { + let dir: string + beforeEach(() => { + dir = mkdtempSync(join(tmpdir(), "docs-coverage-")) + }) + afterEach(() => { + 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.metadata.error).toContain('Model "nope" not found') + 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.metadata.error).toContain("No manifest") + expect(r.output).toContain("dbt compile") + }) +}) diff --git a/packages/opencode/test/altimate/impact-analysis.test.ts b/packages/opencode/test/altimate/impact-analysis.test.ts index e93083aa84..61845bbc15 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,78 @@ 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 }) + } + }) +})