Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/docs/usage/dbt-pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -276,6 +276,8 @@ riskTierPathTokens: # OFF by default — see "Risk-tier path tokens" b
finops: [preset:finops] # promote any FinOps-named path to `full` tier
pii: [ssn, email, phone] # or supply your own case-insensitive tokens
allowForceTier: true # set false in gate CI: --force-tier is then rejected
checkContractColumns: false # opt-in: new columns missing from an enforced contract (CI that doesn't run `dbt build`)
consumerColumnLists: [] # OFF by default — see "Consumers outside dbt" below
rubric:
blockOn: [lineage_breakage, contract_violation, pii_exposure, semantic_change]
warningPatternThreshold: 3
Expand Down Expand Up @@ -311,6 +313,33 @@ rubric:
or a file failed, or a check (such as PII) could not analyse a model, the
earlier block stays.

### Consumers outside dbt

A column removed or renamed can break readers the dbt DAG doesn't show. With a
manifest, the review reports:

- **Exposures and contracts.** Removing a column from a model that has
`exposures` (dashboards, apps, ML) or an enforced contract names those
consumers and suggests a deprecation period or a new model version.
Downstream dbt models that select the column are reported separately, with
the models named.
- **Contract vs `SELECT` (opt-in).** A new column missing from an enforced
contract fails `dbt build`, so this is off by default. Turn it on with
`checkContractColumns: true` when CI runs only `dbt parse` or `dbt compile`.
A column the PR declares in a changed yml counts as declared even when the
manifest predates the PR. It comments; it never blocks.
- **Explicit column lists (opt-in).** Some projects copy a model's columns
into code outside dbt: an export or reverse-ETL script, a feature list, an
API schema. Name those files and the list's pattern, and when a PR adds or
removes a model's columns, each matching list must follow.

```yaml
consumerColumnLists:
- files: "exports/**/*.py" # repo-relative glob
pattern: "COLUMNS\\s*=\\s*\\[([^\\]]*)\\]" # first capture group = the list
model: fct_orders # omit: files that mention the model
```

### What the PR comment shows

- **One summary comment**, updated in place on every push, capped at about
Expand Down Expand Up @@ -461,6 +490,15 @@ The deterministic rules group into four families:
cartesian (`JOIN` without a condition), `NOT IN (… NULL)`, sum-of-a-ratio,
non-portable dialect functions, integer-multiplication overflow, PK-aware
join fan-out, timezone-in-hash-key.
- **Engine-dependent rules read an adapter table.** Where behavior differs by
engine, a rule checks the project's adapter (from the manifest or `dialect`)
instead of assuming one. Example: `int / int` (and `count(…) / count(…)`)
truncates on Postgres, Redshift, Trino/Athena and SQL Server, so it is a
correctness finding there. On Snowflake, BigQuery, Databricks and DuckDB it is
only portability advice, shown for packages (`portability: true`).
- **dbt unit tests.** A unit test whose `given` inputs are all `rows: []` is
reported: it either never tests the model's logic, or expects rows the model has nothing to

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This says every empty-input unit test is reported, but the rule only checks newly added or changed tests with inline dict fixtures; unchanged and CSV/SQL-fixture tests are skipped. Document that scope to avoid promising findings the reviewer will not emit.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/docs/usage/dbt-pr-review.md, line 487:

<comment>This says every empty-input unit test is reported, but the rule only checks newly added or changed tests with inline `dict` fixtures; unchanged and CSV/SQL-fixture tests are skipped. Document that scope to avoid promising findings the reviewer will not emit.</comment>

<file context>
@@ -448,6 +477,15 @@ The deterministic rules group into four families:
+  correctness finding there. On Snowflake, BigQuery, Databricks and DuckDB it is
+  only portability advice, shown for packages (`portability: true`).
+- **dbt unit tests.** A unit test whose `given` inputs are all `rows: []` is
+  reported: it either never tests the model's logic, or expects rows the model has nothing to
+  build from.
 - **dbt config / Jinja (`DBT0xx`).** A core **minijinja** parser reads
</file context>

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up: nit, tracked. The docs will narrow the unit-test scope.

build from.
- **dbt config / Jinja (`DBT0xx`).** A core **minijinja** parser reads
`{{ config(...) }}` and the model body: incremental model without an
`is_incremental()` guard, `merge`/`delete+insert` without a `unique_key`,
Expand Down
79 changes: 79 additions & 0 deletions packages/opencode/src/altimate/review/adapter-capabilities.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
/**
* Per-adapter behavior that review rules depend on. A rule whose correctness
* differs by engine reads this table instead of hard-coding one engine, so it
* fires where the behavior is real and stays silent elsewhere. Every entry
* cites the engine's documentation. An adapter missing from the table gets the
* generic (engine-agnostic) form of each rule only.
*
* Keys are the review's dialect names (see run.ts `ADAPTER_DIALECT`).
*/

export interface AdapterCapability {
/** `int / int` returns an integer, dropping the fraction (7 / 2 = 3). */
integerDivisionTruncates: boolean
/** Documentation backing the entries above. */
sources: string[]
}

export const ADAPTER_CAPABILITIES: Record<string, AdapterCapability> = {
postgres: {
integerDivisionTruncates: true,
sources: ["https://www.postgresql.org/docs/current/functions-math.html"],
},
redshift: {
integerDivisionTruncates: true,
sources: ["https://docs.aws.amazon.com/redshift/latest/dg/r_numeric_computations201.html"],
},
trino: {
integerDivisionTruncates: true,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WARNING: Trino/Athena / returns a floating-point quotient, so this entry (and the rule body) inverts the behavior

Trino's / operator returns a floating-point result for integer operands (7 / 2 -> 3.5); the integer-division forms are divide() (what the cited functions/math.html page documents) and the // operator. With integerDivisionTruncates: true here, the integer-division catalog rule fires as a correctness finding (title "integer division truncates", body "returns 3, not 3.5") on every int / int / count(...) / count(...) in a Trino or Athena project - exactly the false positive the adapter gate exists to prevent. Flipping trino and athena (line 33) to false makes them the portability variant like Snowflake/BigQuery/DuckDB. Worth confirming on a live Trino/Athena before merge.

sources: ["https://trino.io/docs/current/functions/math.html"],
},
athena: {
// Athena SQL runs on Trino.
integerDivisionTruncates: true,
sources: ["https://trino.io/docs/current/functions/math.html"],
},
tsql: {
integerDivisionTruncates: true,
sources: ["https://learn.microsoft.com/en-us/sql/t-sql/language-elements/divide-transact-sql"],
},
fabric: {
integerDivisionTruncates: true,
sources: ["https://learn.microsoft.com/en-us/sql/t-sql/language-elements/divide-transact-sql"],
},
snowflake: {
integerDivisionTruncates: false,
sources: ["https://docs.snowflake.com/en/sql-reference/operators-arithmetic"],
},
bigquery: {
integerDivisionTruncates: false,
sources: ["https://cloud.google.com/bigquery/docs/reference/standard-sql/operators#arithmetic_operators"],
},
databricks: {
integerDivisionTruncates: false,
sources: ["https://docs.databricks.com/en/sql/language-manual/functions/slashsign.html"],
},
duckdb: {
integerDivisionTruncates: false,
sources: ["https://duckdb.org/docs/sql/functions/numeric"],
},
mysql: {
integerDivisionTruncates: false,
sources: ["https://dev.mysql.com/doc/refman/8.0/en/arithmetic-functions.html"],
},
oracle: {
integerDivisionTruncates: false,
sources: ["https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/Arithmetic-Operators.html"],
},
clickhouse: {
integerDivisionTruncates: false,
sources: ["https://clickhouse.com/docs/en/sql-reference/functions/arithmetic-functions"],
},
}

export function capabilityFor(dialect: string | undefined): AdapterCapability | undefined {
return dialect ? ADAPTER_CAPABILITIES[dialect.toLowerCase()] : undefined

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: capabilityFor reads from a plain object, so inherited keys like constructor or toString return a non-undefined value for an unmapped dialect. That breaks the "unmapped adapters get no capability" contract. Use an own-property check.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/opencode/src/altimate/review/adapter-capabilities.ts, line 75:

<comment>`capabilityFor` reads from a plain object, so inherited keys like `constructor` or `toString` return a non-undefined value for an unmapped dialect. That breaks the "unmapped adapters get no capability" contract. Use an own-property check.</comment>

<file context>
@@ -0,0 +1,79 @@
+}
+
+export function capabilityFor(dialect: string | undefined): AdapterCapability | undefined {
+  return dialect ? ADAPTER_CAPABILITIES[dialect.toLowerCase()] : undefined
+}
+
</file context>

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up: nit, tracked (Object.hasOwn guard).

}

/** Display names of the engines where `int / int` truncates. */
export const TRUNCATING_DIVISION_ENGINES = "Postgres, Redshift, Trino/Athena and SQL Server"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SUGGESTION: Unused export duplicates the engine list

TRUNCATING_DIVISION_ENGINES is never imported anywhere, while the same engine list is hard-coded twice in rule-catalog.ts (the rule body at 1878 and portabilityBody at 1885-1886). Either use this constant in those bodies or delete it; as written the list can drift from the behavior the table documents.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up: nit, tracked. Same as the cubic engine-list comment.

15 changes: 15 additions & 0 deletions packages/opencode/src/altimate/review/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,21 @@ export const ReviewConfig = z.object({
* Functions missing on the project's own engine are always reported.
*/
portability: z.boolean().optional(),
/**
* Opt-in: report a new column missing from an enforced contract. `dbt build`
* already fails on it, so this only helps CI that runs `dbt parse`/`compile`
* without building.
*/
checkContractColumns: z.boolean().default(false),
/**
* Opt-in: explicit column lists outside dbt (loaders, exports) that must
* track a model's columns. `files` is a repo-relative glob, `pattern` a regex
* whose first capture group is the list, `model` the model it mirrors
* (omitted = files that mention the model by name).
*/
consumerColumnLists: z
.array(z.object({ files: z.string(), pattern: z.string(), model: z.string().optional() }))

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: An invalid pattern passes config parsing and only produces a stderr warning later, so the check is silently disabled. Validate the regex in the schema so parseReviewConfig rejects it, matching the fail-fast rule documented on loadReviewConfig.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/opencode/src/altimate/review/config.ts, line 51:

<comment>An invalid `pattern` passes config parsing and only produces a stderr warning later, so the check is silently disabled. Validate the regex in the schema so `parseReviewConfig` rejects it, matching the fail-fast rule documented on `loadReviewConfig`.</comment>

<file context>
@@ -35,6 +35,21 @@ export const ReviewConfig = z.object({
+   * (omitted = files that mention the model by name).
+   */
+  consumerColumnLists: z
+    .array(z.object({ files: z.string(), pattern: z.string(), model: z.string().optional() }))
+    .default([]),
   /** Allow `--force-tier` (a debug bypass of the risk classifier). Set false
</file context>
Suggested change
.array(z.object({ files: z.string(), pattern: z.string(), model: z.string().optional() }))
.array(z.object({ files: z.string().min(1), pattern: z.string().refine((p) => { try { new RegExp(p); return true } catch { return false } }, "invalid regex"), model: z.string().optional() }))

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing: a bad consumer-list pattern is skipped with a warning on purpose, so an optional list never fails the whole review. Validating it in the schema is a possible follow-up.

.default([]),
/** Allow `--force-tier` (a debug bypass of the risk classifier). Set false
* in gate CI so a run cannot skip checks by forcing a lower tier. */
allowForceTier: z.boolean().default(true),
Expand Down
106 changes: 106 additions & 0 deletions packages/opencode/src/altimate/review/consumer-lists.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
import { execFile } from "node:child_process"
import { promisify } from "node:util"

/**
* Opt-in: explicit column lists outside dbt (loaders, exports, reverse-ETL
* configs) that must stay in step with a model's columns. A project names the
* files and a regex whose first capture group holds the list in
* `.altimate/review.yml`; the review then reports model columns a list is
* missing, and list entries the model no longer selects. Off unless configured,
* since no such convention is universal.
*/

export interface ConsumerColumnListConfig {
/** Repository-relative glob of the files holding the lists. */
files: string
/** Regex whose first capture group is the column list. */
pattern: string
/** The model the lists mirror; omitted = files that mention the model by name. */
model?: string
}

export interface ConsumerColumnList {
path: string
model?: string
columns: string[]
/** File text, to match lists to models by name when `model` is omitted. */
content: string
}

const exec = promisify(execFile)
const IDENT = /^[A-Za-z_][A-Za-z0-9_$]*$/

/** One column list per match of `pattern` in `content` (each lowercased and
* de-duplicated), so two lists in one file are checked separately. */
export function extractColumnLists(content: string, pattern: RegExp): string[][] {
const flags = pattern.flags.includes("g") ? pattern.flags : pattern.flags + "g"
const re = new RegExp(pattern.source, flags)
const lists: string[][] = []
for (const m of content.matchAll(re)) {
const out = new Set<string>()
for (const token of (m[1] ?? "").split(/[,\s]+/)) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Whitespace splitting turns trailing comment words into column names, so surrogate and key are treated as list columns. A dotted entry such as o.email is dropped without notice. Strip comments and split on commas, or document that the capture group must hold bare names only.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/opencode/src/altimate/review/consumer-lists.ts, line 39:

<comment>Whitespace splitting turns trailing comment words into column names, so `surrogate` and `key` are treated as list columns. A dotted entry such as `o.email` is dropped without notice. Strip comments and split on commas, or document that the capture group must hold bare names only.</comment>

<file context>
@@ -0,0 +1,88 @@
+  const re = new RegExp(pattern.source, flags)
+  const out = new Set<string>()
+  for (const m of content.matchAll(re)) {
+    for (const token of (m[1] ?? "").split(/[,\s]+/)) {
+      const name = token.replace(/^["'`]+|["'`]+$/g, "")
+      if (IDENT.test(name)) out.add(name.toLowerCase())
</file context>

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up: low priority, tracked. The list parser will split on commas, strip comments and keep quoted and dotted names.

const name = token.replace(/^["'`]+|["'`]+$/g, "")
if (IDENT.test(name)) out.add(name.toLowerCase())

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Quoted column names containing characters outside IDENT are silently dropped, so consumer-list checks miss columns such as "order-id". Preserve valid quoted tokens, including non-identifier names, when parsing the configured list.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/opencode/src/altimate/review/consumer-lists.ts, line 41:

<comment>Quoted column names containing characters outside `IDENT` are silently dropped, so consumer-list checks miss columns such as `"order-id"`. Preserve valid quoted tokens, including non-identifier names, when parsing the configured list.</comment>

<file context>
@@ -0,0 +1,88 @@
+  for (const m of content.matchAll(re)) {
+    for (const token of (m[1] ?? "").split(/[,\s]+/)) {
+      const name = token.replace(/^["'`]+|["'`]+$/g, "")
+      if (IDENT.test(name)) out.add(name.toLowerCase())
+    }
+  }
</file context>

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up: low priority, tracked. Same parser change as above.

}
if (out.size) lists.push([...out])
}
return lists
}

/** Column names from every match of `pattern` in `content` (lowercased, de-duplicated). */
export function extractColumnList(content: string, pattern: RegExp): string[] {
return [...new Set(extractColumnLists(content, pattern).flat())]
}

/** True when a list belongs to `model`: named explicitly, or the file mentions the model. */
export function listMirrorsModel(list: ConsumerColumnList, model: string): boolean {
if (list.model) return list.model.toLowerCase() === model.toLowerCase()
return new RegExp(`\\b${model.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(list.content)
}

/**
* Read the configured lists at the head (`head` ref, or the working tree).
* An invalid pattern is reported on stderr and skipped, never fatal.
*/
export async function loadConsumerLists(opts: {
configs: ConsumerColumnListConfig[]
gitRoot: string
head?: string
read: (repoRelPath: string) => Promise<string | undefined>
}): Promise<ConsumerColumnList[]> {
const out: ConsumerColumnList[] = []
for (const cfg of opts.configs) {
let re: RegExp
try {
re = new RegExp(cfg.pattern, "g")
} catch (e) {
process.stderr.write(`⚠️ consumerColumnLists: invalid pattern ${JSON.stringify(cfg.pattern)} (${String(e)}); skipped.\n`)
continue
}
if (!/\((?!\?)/.test(cfg.pattern.replace(/\\./g, "")))
process.stderr.write(
`⚠️ consumerColumnLists: pattern ${JSON.stringify(cfg.pattern)} has no capture group; it matches no list.\n`,
)
// `git ls-tree` rejects `:(glob)` pathspec magic, so list every file and
// match the glob here, the same way for the head ref and the working tree.
const args = opts.head ? ["ls-tree", "-r", "-z", "--name-only", opts.head] : ["ls-files", "-z"]
const glob = new Bun.Glob(cfg.files)
let files: string[] = []
try {
files = (await exec("git", args, { cwd: opts.gitRoot, maxBuffer: 64 * 1024 * 1024 })).stdout
.split("\0")
.filter((f) => f && glob.match(f))
} catch (e) {
process.stderr.write(
`⚠️ consumerColumnLists: could not list files for ${JSON.stringify(cfg.files)} (${String(e).split("\n")[0]}); skipped.\n`,
)
files = []
}
for (const file of files) {
const content = await opts.read(file)
if (!content) continue
for (const columns of extractColumnLists(content, re)) out.push({ path: file, model: cfg.model, columns, content })
}
}
return out
}
11 changes: 8 additions & 3 deletions packages/opencode/src/altimate/review/dbt-patterns.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { Log } from "@/altimate/util/log"
import { type Finding, type Severity, type ReviewCategory, makeFinding } from "./finding"
import { type ChangedFile, fileKind } from "./diff-filter"
import { type Rubric, clampSeverity, exclusionReason } from "./rubric"
import { evaluateCatalog } from "./rule-catalog"
import { evaluateCatalog, type CatalogContext } from "./rule-catalog"

/** Local copy to avoid a cycle with orchestrate.ts. */
function modelNameFromPath(p: string): string {
Expand Down Expand Up @@ -765,7 +765,12 @@ const MODEL_DETECTORS: Detector[] = [
]

/** Run the dbt anti-pattern detectors over a changed MODEL file. */
export function detectModelPatterns(file: ChangedFile, newSql: string | undefined, rubric: Rubric): Finding[] {
export function detectModelPatterns(
file: ChangedFile,
newSql: string | undefined,
rubric: Rubric,
catalogCtx?: CatalogContext,
): Finding[] {
const kind = fileKind(file)
if (!isModelSql(kind) || file.status === "deleted" || !newSql) return []
const { added, removed } = splitDiff(file.diff)
Expand All @@ -784,7 +789,7 @@ export function detectModelPatterns(file: ChangedFile, newSql: string | undefine
if (f) out.push({ ...f, severity: clampSeverity(f.category, f.severity, f.confidence) })
}
// Declarative rule catalog (data-driven checks) complements the programmatic detectors.
out.push(...evaluateCatalog(file, newSql, added, removed, rubric))
out.push(...evaluateCatalog(file, newSql, added, removed, rubric, catalogCtx))
return out.filter((f) => !exclusionReason(f, rubric))
}

Expand Down
Loading
Loading