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
20 changes: 20 additions & 0 deletions docs/docs/usage/dbt-pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,8 @@ mode: comment # comment | gate
severityThreshold: suggestion
manifestPath: target/manifest.json
dialect: snowflake
portability: false # cross-engine advice; default off once the engine is known
# (set true for packages that support several adapters)
reviewers: [] # empty = risk-tier defaults; or pin lanes
dataDiff: # OFF by default — see "Data-diff in CI" below
enabled: false
Expand All @@ -283,6 +285,24 @@ rubric:
skipNonProdModels: true
```

### What the PR comment shows

- **One summary comment**, updated in place on every push, capped at about
5,000 characters. Critical findings come first; anything that does not fit is
counted, and the full list is always in the verdict envelope
(`altimate review --json`). Local CLI output is never truncated.
- **Repeated rules are grouped:** the same rule on three or more models is one
bullet listing the models.
- **Inline comments only on lines of the PR's diff.** Findings computed on
compiled SQL, or on unchanged lines, stay in the summary.
- **No re-posting on reruns:** each inline comment carries the finding's
fingerprint, so a push does not repeat findings already on the PR, and a
non-blocking rerun with nothing new only updates the summary.
- **PII:** flagged only for PII columns the change newly exposes, not for
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
columns the base already surfaced. That comparison needs the base version's
SQL; when it can't be compiled, PII columns are reported as non-blocking
warnings that may predate the PR.

### Risk-tier path tokens

Named categories under `riskTierPathTokens` promote any diff touching a matching
Expand Down
8 changes: 8 additions & 0 deletions packages/opencode/src/altimate/review/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,14 @@ export const ReviewConfig = z.object({
dialect: z.string().default(""),
/** Enable the advisory LLM reviewer lane (needs a configured model). */
ai: z.boolean().default(true),
/**
* Report cross-engine portability advice ("isn't portable across
* warehouses"). Off by default once the engine is known (from the manifest's
* adapter or `dialect`), because a project that runs on one engine gains
* nothing from it. Turn on for packages that support several adapters.
* Functions missing on the project's own engine are always reported.
*/
portability: z.boolean().optional(),
/**
* Data-diff: actually run base-vs-head against the warehouse (core DataParity)
* and report row/value deltas. OPT-IN — it costs warehouse compute and needs a
Expand Down
150 changes: 124 additions & 26 deletions packages/opencode/src/altimate/review/format.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,20 @@ export function verdictHeadline(env: VerdictEnvelope): string {
return `${VERDICT_LABEL[env.verdict]} — ${counts} (${tierLabel})`
}

/** Default size budget for the posted PR comment (characters). */
export const SUMMARY_BUDGET_CHARS = 5_000
/** The same rule on this many models or more collapses into one bullet. */
export const GROUP_MIN = 3

export interface RenderOptions {
/** Character budget for the comment; findings beyond it are counted, not listed.
* `Infinity` renders everything (local CLI output). */
maxChars?: number
}

/** Full PR/MR summary comment body (markdown), prefixed with the dedup marker. */
export function renderSummary(env: VerdictEnvelope): string {
export function renderSummary(env: VerdictEnvelope, opts: RenderOptions = {}): string {
const maxChars = opts.maxChars ?? SUMMARY_BUDGET_CHARS
const lines: string[] = [REVIEW_MARKER, "", `## ${verdictHeadline(env)}`, ""]

if (env.summary.degraded) {
Expand Down Expand Up @@ -80,33 +92,15 @@ export function renderSummary(env: VerdictEnvelope): string {
lines.push(`> 🧭 **Tier: ${env.tier}** — ${shown}${overflow}`, "")
}

if (!env.findings.length) {
lines.push("No issues found in the changed dbt models. 🎉", "")
} else {
const grouped = groupBySeverity(env.findings)
for (const sev of ["critical", "warning", "suggestion"] as const) {
const items = grouped[sev]
if (!items.length) continue
lines.push(`### ${SEVERITY_EMOJI[sev]} ${capitalize(sev)} (${items.length})`, "")
for (const f of items) {
const loc = f.file + (f.startLine ? `:${f.startLine}` : "")
lines.push(
`- **${f.title}** \n ${oneLine(f.body)} \n <sub>\`${loc}\`${f.degraded ? " · _unverified_" : ""} · ${f.category}</sub>`,
)
}
lines.push("")
}
}

const tail: string[] = []
if (env.override) {
lines.push(
tail.push(
`> 🔓 **Break-glass override** by @${env.override.by}: ${env.override.reason}`,
`> (would have been \`${env.override.priorVerdict}\`)`,
"",
)
}

lines.push(
tail.push(
"---",
`<sub>altimate dbt-pr-review · verdict \`${env.verdict}\`` +
(env.signature ? ` · signed \`${env.signature.slice(0, 18)}…\`` : "") +
Expand All @@ -115,7 +109,92 @@ export function renderSummary(env: VerdictEnvelope): string {
(env.ai?.state === "ok" && env.ai.model ? ` · AI \`${env.ai.model}\`` : "") +
"</sub>",
)
return lines.join("\n")

if (!env.findings.length) {
lines.push("No issues found in the changed dbt models. 🎉", "")
return [...lines, ...tail].join("\n")
}

// Findings fill the budget left after the fixed parts, most severe first.
// What does not fit is counted, never silently dropped: the envelope keeps
// every finding.
const overflowReserve = 220
let used = [...lines, ...tail].join("\n").length + overflowReserve
let hidden = 0
const grouped = groupBySeverity(env.findings)
for (const sev of ["critical", "warning", "suggestion"] as const) {
const items = grouped[sev]
if (!items.length) continue
const heading = [`### ${SEVERITY_EMOJI[sev]} ${capitalize(sev)} (${items.length})`, ""]
const bullets = bulletsFor(items)
let headed = false
for (const b of bullets) {
const cost = b.text.length + 1 + (headed ? 0 : heading.join("\n").length + 2)
if (used + cost > maxChars) {
hidden += b.count
continue
}
if (!headed) {
lines.push(...heading)
headed = true
}
lines.push(b.text)
used += cost
}
if (headed) lines.push("")
}
if (hidden) {
lines.push(
`> … ${hidden} more finding(s) not shown to keep this comment short — the full list is in the verdict envelope ` +

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: The --output artifact this points at does not exist for the bundled action

github/review/action.yml builds its args from --mode/--manifest/--severity/--cwd/--base/--head/--post only — it never passes --json or --output, so an action user who hits the 5K budget has no --output artifact to open, and renderSummary is the only rendering they see. The uncapped list does reach the step log (the CLI writes renderSummary(env, { maxChars: Infinity }) to stdout), and the envelope is written only for an explicit CLI --output. Point readers at the job log or at altimate review --json --output <file> instead of an artifact the action never creates.

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 note should point to the job log or altimate review --json --output <file>.

"(`altimate review --json`, or the action's `--output` artifact).",

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: The bundled action does not pass --output, so this artifact is never created; point readers to the job log or explicit altimate review --json --output <file> usage.

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/format.ts, line 149:

<comment>The bundled action does not pass `--output`, so this artifact is never created; point readers to the job log or explicit `altimate review --json --output <file>` usage.</comment>

<file context>
@@ -115,7 +109,90 @@ export function renderSummary(env: VerdictEnvelope): string {
+  if (hidden) {
+    lines.push(
+      `> … ${hidden} more finding(s) not shown to keep this comment short — the full list is in the verdict envelope ` +
+        "(`altimate review --json`, or the action's `--output` artifact).",
+      "",
+    )
</file context>
Suggested change
"(`altimate review --json`, or the action's `--output` artifact).",
"(`altimate review --json`, or the job log; use `--output <file>` when running the CLI directly).",

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 as the kilo thread).

"",
)
}
return [...lines, ...tail].join("\n")
}

/** A finding's title without its leading `model: `, with backticked names
* blanked, so the same rule on different models/columns shares a key. */
function ruleTitle(f: Finding): string {
const t = f.model && f.title.startsWith(`${f.model}: `) ? f.title.slice(f.model.length + 2) : f.title
return t.replace(/`[^`]*`/g, "`…`")

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: This normalization misses findings whose producer puts the model or filename outside a model: prefix, so the promised cross-model grouping fails for rules such as removed-test findings. Group by a stable rule identity or normalize those producer-specific location fields before building the key.

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/format.ts, line 160:

<comment>This normalization misses findings whose producer puts the model or filename outside a `model: ` prefix, so the promised cross-model grouping fails for rules such as removed-test findings. Group by a stable rule identity or normalize those producer-specific location fields before building the key.</comment>

<file context>
@@ -115,7 +109,90 @@ export function renderSummary(env: VerdictEnvelope): string {
+ *  blanked, so the same rule on different models/columns shares a key. */
+function ruleTitle(f: Finding): string {
+  const t = f.model && f.title.startsWith(`${f.model}: `) ? f.title.slice(f.model.length + 2) : f.title
+  return t.replace(/`[^`]*`/g, "`…`")
+}
+
</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. Group by ruleKey/catalog rule id.

}

/** Render findings of one severity as bullets; a rule repeated on GROUP_MIN or
* more distinct models collapses into a single bullet listing the models. */
function bulletsFor(items: Finding[]): Array<{ text: string; count: number }> {
const groups = new Map<string, Finding[]>()
for (const f of items) {
const key = `${f.category}|${ruleTitle(f)}`
const g = groups.get(key)
if (g) g.push(f)
else groups.set(key, [f])
}
const out: Array<{ text: string; count: number }> = []
for (const g of groups.values()) {
// Group by distinct models: several findings of one rule on the SAME model
// (e.g. two different columns) are distinct issues and stay separate bullets.
const names = [...new Set(g.map((f) => f.model ?? f.file))]
if (names.length >= GROUP_MIN) {
const shown = names.slice(0, 8).map((n) => `\`${n}\``).join(", ")
const more = names.length > 8 ? ` (+${names.length - 8} more)` : ""
out.push({
text:
`- **${ruleTitle(g[0])}** — ${g.length} findings across ${names.length} model(s): ${shown}${more} \n` +

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: A grouped bullet still hides extra findings on an already-listed model

Grouping keys on ruleTitle(), which blanks backticked names, so it also merges several findings of one rule on the same model. When such a group reaches 3+ models this bullet renders only g[0]'s title and body while the header counts all g.length findings. Example: grain column a_id lacks not_null on A/B/C plus grain column d_id lacks not_null on A becomes one bullet that never names d_id. Those findings have no startLine (missingGrainTestLane sets none), so the summary is their only surface. When g.length > names.length, list each merged finding's column/title in the bullet (or keep same-model findings as their own bullets) instead of keeping only the first body.

` ${oneLine(g[0].body)} \n <sub>${g[0].category}</sub>`,
count: g.length,
})
continue
}
for (const f of g) {
const loc = f.file + (f.startLine ? `:${f.startLine}` : "")
out.push({
text: `- **${f.title}** \n ${oneLine(f.body)} \n <sub>\`${loc}\`${f.degraded ? " · _unverified_" : ""} · ${f.category}</sub>`,
count: 1,
})
}
}
return out
}

/**
Expand All @@ -142,6 +221,11 @@ export function coverageNotes(env: VerdictEnvelope): string[] {
}
if (env.scope?.outOfScopeFiles)
notes.push(`${env.scope.outOfScopeFiles} changed file(s) outside the dbt project were not reviewed.`)
if (env.scope?.movedUnchangedFiles)
notes.push(
`${env.scope.movedUnchangedFiles} file(s) moved without edits; their SQL was not re-reviewed. ` +
"Folder-level config in `dbt_project.yml` (`+schema`, `+materialized`, `+tags`) can still change where and how a moved model builds.",
Comment on lines +226 to +227

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: This note incorrectly claims every unchanged move has SQL that was not re-reviewed. movedUnchangedFiles also counts unchanged renames of YAML and other files, so the summary is misleading for those moves; describe unchanged content generically or restrict the counter to model files.

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/format.ts, line 221:

<comment>This note incorrectly claims every unchanged move has SQL that was not re-reviewed. `movedUnchangedFiles` also counts unchanged renames of YAML and other files, so the summary is misleading for those moves; describe unchanged content generically or restrict the counter to model files.</comment>

<file context>
@@ -216,6 +216,11 @@ export function coverageNotes(env: VerdictEnvelope): string[] {
     notes.push(`${env.scope.outOfScopeFiles} changed file(s) outside the dbt project were not reviewed.`)
+  if (env.scope?.movedUnchangedFiles)
+    notes.push(
+      `${env.scope.movedUnchangedFiles} file(s) moved without edits; their SQL was not re-reviewed. ` +
+        "Folder-level config in `dbt_project.yml` (`+schema`, `+materialized`, `+tags`) can still change where and how a moved model builds.",
+    )
</file context>
Suggested change
`${env.scope.movedUnchangedFiles} file(s) moved without edits; their SQL was not re-reviewed. ` +
"Folder-level config in `dbt_project.yml` (`+schema`, `+materialized`, `+tags`) can still change where and how a moved model builds.",
`${env.scope.movedUnchangedFiles} file(s) moved without edits; their unchanged contents were not re-reviewed. ` +
"For moved models, folder-level config in `dbt_project.yml` (`+schema`, `+materialized`, `+tags`) can still change where and how they build.",

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: wording nit.

)
if (env.ai && env.ai.state !== "ok") {
const what = { skipped: "skipped", timeout: "timed out", error: "failed" }[env.ai.state]
notes.push(`Advisory AI review ${what}${env.ai.reason ? `: ${env.ai.reason}` : ""}.`)
Expand All @@ -157,14 +241,28 @@ export interface InlineComment {
body: string
}

export function inlineComments(env: VerdictEnvelope): InlineComment[] {
/** Hidden per-finding marker on inline comments, keyed by the finding's stable
* fingerprint (rule, file, model, column — not the line), so a rerun can tell
* which findings are already on the PR. */
export function findingMarker(id: string): string {
return `<!-- altimate-finding:${id} -->`
}

/** Finding ids already posted, read from existing inline comment bodies. */
export function postedFindingIds(bodies: Array<string | null | undefined>): Set<string> {
const out = new Set<string>()
for (const b of bodies) for (const m of (b ?? "").matchAll(/<!-- altimate-finding:([\w-]+) -->/g)) out.add(m[1])
return out
}

export function inlineComments(env: VerdictEnvelope, alreadyPosted: Set<string> = new Set()): InlineComment[] {
return env.findings
.filter((f) => typeof f.startLine === "number")
.filter((f) => typeof f.startLine === "number" && !alreadyPosted.has(f.id))
.map((f) => ({
path: f.file,
line: f.startLine!,
side: "RIGHT" as const,
body: `${SEVERITY_EMOJI[f.severity]} **${f.title}**\n\n${f.body}`,
body: `${SEVERITY_EMOJI[f.severity]} **${f.title}**\n\n${f.body}\n\n${findingMarker(f.id)}`,
}))
}

Expand Down
Loading
Loading