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
23 changes: 20 additions & 3 deletions docs/docs/usage/dbt-pr-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ Options:

| Flag | Description |
|------|-------------|
| `--base <ref>` | Base git ref. Defaults to the pull request's target branch in CI (GitHub `pull_request.base.ref` or `GITHUB_BASE_REF`, GitLab `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`), else the remote default branch. Always reduced to the merge-base with the head, so commits the base gained after the PR branched are never reviewed. In CI, a target branch that is not fetched is an error (use `fetch-depth: 0`). |
| `--base <ref>` | Base git ref. Defaults to the pull request's target branch in CI (GitHub `pull_request.base.ref` or `GITHUB_BASE_REF`, GitLab `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`), else the remote default branch. Always reduced to the merge-base with the head, so commits the base gained after the PR branched are never reviewed. In CI, a shallow checkout is handled: the target branch is fetched and the history deepened until the merge-base is found. If that fails (no `origin`, no access), the review stops with an error rather than diffing against another branch. |
| `--head <ref>` | Head git ref. Omit to review the working tree. |
| `--manifest <path>` | Path to the compiled `manifest.json`. When omitted, the reviewer walks up from the current directory to find the nearest `dbt_project.yml` and uses its adjacent `target/manifest.json`; the discovered path is logged to stderr. |
| `--mode comment\|gate` | `comment` never blocks; `gate` exits non-zero on `REQUEST_CHANGES`. |
Expand Down Expand Up @@ -203,7 +203,7 @@ jobs:

| Input | How to produce it | Unlocks |
|---|---|---|
| Full git history of the PR's target branch | `actions/checkout` with `fetch-depth: 0` | Correct base: the diff starts at the merge-base with the PR's target branch. A target branch that is not fetched is an error, never a silent fallback to `main`. |
| The PR's target branch and the merge-base | Fetched automatically from `origin` when the checkout is shallow; `fetch-depth: 0` avoids the extra fetches | Correct base: the diff starts at the merge-base with the PR's target branch. When it can't be fetched, the review stops with an error, never a silent fallback to `main`. |
| `target/manifest.json` | `dbt compile` (or `dbt parse` for lint + lineage only) | Blast radius, lineage breakage, tiering. Without it the run is lint-only. |
| `target/compiled/…` | `dbt compile` | Engine checks on the head (lint, grade, PII, grain). |
| `target-base/compiled/…` | Compile the base ref into `target-base/` (below) | Equivalence proofs and column-breakage for modified models. |
Expand Down Expand Up @@ -303,6 +303,13 @@ rubric:
rules) or `ai`. Only `engine` findings count toward REQUEST_CHANGES. A pattern
rule you trust can be allowed to block by naming its id in
`rubric.blockingRules`. The advisory AI lane never blocks.
- **Upgrading a `gate` setup.** Before this policy, any critical finding in a
`blockOn` category could block, including pattern rules such as the regex
PII check. Now pattern-rule findings comment but don't block. To keep a
pattern rule blocking, add its id to `rubric.blockingRules`. A blocking
review is dismissed only by a later run that completed: when an engine call
or a file failed, or a check (such as PII) could not analyse a model, the
earlier block stays.

### What the PR comment shows

Expand All @@ -320,7 +327,17 @@ rubric:
- **PII:** flagged only for PII columns the change newly exposes, not for
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.
warnings that may predate the PR. A model the PII check could not analyse is
listed as not fully verified.
- **Failures are never a clean pass:** if an engine check fails, a file's
review fails, or a check could not analyse a model, the comment names it and
the verdict is at most COMMENT, never APPROVE (envelope `engineErrors` and
`scope.unverified`). A failure on one file marks that file unverified and the
rest of the PR is still reviewed.
- **The gate clears itself:** when a completed rerun on the PR's current head
no longer blocks, the earlier blocking altimate review for the same dbt
project is dismissed after the new review is posted (needs
`pull-requests: write`).

### Risk-tier path tokens

Expand Down
27 changes: 17 additions & 10 deletions packages/opencode/src/altimate/review/format.ts
Original file line number Diff line number Diff line change
Expand Up @@ -208,16 +208,23 @@ export function coverageNotes(env: VerdictEnvelope): string[] {
const undecided = env.findings.filter((f) => f.degraded).length
if (undecided) notes.push(`${undecided} finding(s) could not be decided by the engine and are marked _unverified_.`)
const unverified = env.scope?.unverified ?? []
if (unverified.length) {
// One line per reason: models can lack the head compile or the base compile.
const byReason = new Map<string, string[]>()
for (const u of unverified) byReason.set(u.reason, [...(byReason.get(u.reason) ?? []), u.path])
for (const [reason, paths] of byReason) {
const head = paths.slice(0, 5).map((p) => `\`${p}\``).join(", ")
const more = paths.length > 5 ? ` and ${paths.length - 5} more` : ""
notes.push(`${paths.length} model(s) not verified by the engine — ${reason}: ${head}${more}.`)
}
notes.push("Run `dbt compile` (and compile the base into `target-base/`) for equivalence and lineage checks.")
const byReason = new Map<string, string[]>()
for (const u of unverified) {
const paths = byReason.get(u.reason)
if (paths) paths.push(u.path)
else byReason.set(u.reason, [u.path])
}
for (const [reason, paths] of byReason) {
const head = paths.slice(0, 5).map((p) => `\`${p}\``).join(", ")
const more = paths.length > 5 ? ` and ${paths.length - 5} more` : ""
const hint = /compiled SQL/.test(reason)
? " Run `dbt compile` (and compile the base into `target-base/`) for equivalence and lineage checks."
: ""
notes.push(`${paths.length} model(s) not fully verified — ${reason}: ${head}${more}.${hint}`)
}
if (env.engineErrors?.length) {
const list = env.engineErrors.map((e) => `${e.method} ×${e.count} (${e.reason})`).join("; ")

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: e.reason is not sanitized here, and PR-level lane errors can contain newlines. That breaks the > ℹ️ blockquote in the posted comment. Collapse whitespace before interpolating the reason.

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 220:

<comment>`e.reason` is not sanitized here, and PR-level lane errors can contain newlines. That breaks the `> ℹ️` blockquote in the posted comment. Collapse whitespace before interpolating the reason.</comment>

<file context>
@@ -206,13 +206,19 @@ export function coverageNotes(env: VerdictEnvelope): string[] {
+    notes.push(`${paths.length} model(s) not fully verified — ${reason}: ${head}${more}.${hint}`)
+  }
+  if (env.engineErrors?.length) {
+    const list = env.engineErrors.map((e) => `${e.method} ×${e.count} (${e.reason})`).join("; ")
+    notes.push(`Some engine checks failed and did not run: ${list}. This verdict is not a clean approval.`)
   }
</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. prLevel will collapse whitespace the way fail() does.

notes.push(`Some engine checks failed and did not run: ${list}. This verdict is not a clean approval.`)
}
if (env.scope?.outOfScopeFiles)
notes.push(`${env.scope.outOfScopeFiles} changed file(s) outside the dbt project were not reviewed.`)
Expand Down
58 changes: 55 additions & 3 deletions packages/opencode/src/altimate/review/git.ts
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,44 @@ async function mergeBase(a: string, b: string, cwd: string): Promise<string | un
}
}

/**
* A default CI checkout is shallow (`actions/checkout` fetches one commit) and
* lacks the target branch. Fetch the branch, then deepen the history until a
* merge-base exists, so the review works without `fetch-depth: 0`. Returns
* true once `found` resolves; false when it never does (no remote, no access).
*/
async function fetchTargetHistory(
branch: string,
head: string,
cwd: string,
found: () => Promise<unknown>,
): Promise<boolean> {
if (branch.startsWith("-")) return false
const shallow = async () => (await git(["rev-parse", "--is-shallow-repository"], cwd)).trim() === "true"
try {
// In a shallow checkout, fetch only recent target history; the loop below
// deepens it. A full fetch would pull the target branch's whole history.
const depth = (await shallow()) ? ["--depth=50"] : []
await git(["fetch", "--no-tags", ...depth, "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`], cwd)
} catch {
return false
}
if (await found()) return true
for (const depth of [50, 200, 1000]) {
try {
if (!(await shallow())) return false
// Deepen the history of the head being reviewed, which may differ from
// the checkout (`--head <ref>`).
const headSha = (await git(["rev-parse", "--verify", `${head}^{commit}`], cwd)).trim()
await git(["fetch", "--no-tags", `--deepen=${depth}`, "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`, headSha], cwd)

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: The deepen fetch adds headSha as a raw SHA request, which requires the remote to allow reachable SHA wants and can make otherwise-valid CI remotes reject the fetch. Remove this extra argument; the target-branch refspec is sufficient for deepening the shallow checkout.

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/git.ts, line 212:

<comment>The deepen fetch adds `headSha` as a raw SHA request, which requires the remote to allow reachable SHA wants and can make otherwise-valid CI remotes reject the fetch. Remove this extra argument; the target-branch refspec is sufficient for deepening the shallow checkout.</comment>

<file context>
@@ -191,6 +191,33 @@ async function mergeBase(a: string, b: string, cwd: string): Promise<string | un
+    try {
+      if ((await git(["rev-parse", "--is-shallow-repository"], cwd)).trim() !== "true") return false
+      const headSha = (await git(["rev-parse", "HEAD"], cwd)).trim()
+      await git(["fetch", "--no-tags", `--deepen=${depth}`, "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`, headSha], cwd)
+    } catch {
+      return false
</file context>
Suggested change
await git(["fetch", "--no-tags", `--deepen=${depth}`, "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`, headSha], cwd)
await git(["fetch", "--no-tags", `--deepen=${depth}`, "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`], cwd)

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. GitHub accepts the raw-SHA want, and on other remotes a failed fetch only means the base isn't found. A retry without the SHA is a cheap addition.

} catch {
return false
}
if (await found()) return true
}
return false
}
Comment on lines +205 to +241

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[🟠 MEDIUM] By making fetchTargetHistory return a boolean, the caller is forced to execute await find() an extra time when the fetch succeeds. Since find() invokes an external git merge-base process, this results in redundant and potentially expensive operations. It is recommended to use a generic type so the function can return the found result directly, avoiding double evaluation.

Suggested change:

Suggested change
/**
* A default CI checkout is shallow (`actions/checkout` fetches one commit) and
* lacks the target branch. Fetch the branch, then deepen the history until a
* merge-base exists, so the review works without `fetch-depth: 0`. Returns
* true once `found` resolves; false when it never does (no remote, no access).
*/
async function fetchTargetHistory(branch: string, cwd: string, found: () => Promise<unknown>): Promise<boolean> {
if (branch.startsWith("-")) return false
try {
await git(["fetch", "--no-tags", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`], cwd)
} catch {
return false
}
if (await found()) return true
for (const depth of [50, 200, 1000]) {
try {
if ((await git(["rev-parse", "--is-shallow-repository"], cwd)).trim() !== "true") return false
const headSha = (await git(["rev-parse", "HEAD"], cwd)).trim()
await git(["fetch", "--no-tags", `--deepen=${depth}`, "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`, headSha], cwd)
} catch {
return false
}
if (await found()) return true
}
return false
}
/**
* A default CI checkout is shallow (`actions/checkout` fetches one commit) and
* lacks the target branch. Fetch the branch, then deepen the history until a
* merge-base exists, so the review works without `fetch-depth: 0`. Returns
* the resolved value once `found` succeeds; undefined when it never does (no remote, no access).
*/
async function fetchTargetHistory<T>(branch: string, cwd: string, found: () => Promise<T | undefined>): Promise<T | undefined> {
if (branch.startsWith("-")) return undefined
try {
await git(["fetch", "--no-tags", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`], cwd)
} catch {
return undefined
}
let result = await found()
if (result) return result
for (const depth of [50, 200, 1000]) {
try {
if ((await git(["rev-parse", "--is-shallow-repository"], cwd)).trim() !== "true") return undefined
const headSha = (await git(["rev-parse", "HEAD"], cwd)).trim()
await git(["fetch", "--no-tags", `--deepen=${depth}`, "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`, headSha], cwd)
} catch {
return undefined
}
result = await found()
if (result) return result
}
return undefined
}

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.

Thanks. This is correct, but the cost is one extra git merge-base, and only after a deepen fetch, so we're leaving it as is for this PR. It is noted as a cleanup for when fetchTargetHistory is next touched.


/** The PR's target branch from the CI provider, when the run is for a PR/MR. */
async function ciTargetBranch(env: NodeJS.ProcessEnv): Promise<{ branch: string; source: BaseSource } | undefined> {
if (env.GITHUB_EVENT_PATH) {
Expand Down Expand Up @@ -241,10 +279,15 @@ export async function resolveReviewBase(opts: ResolveBaseOptions): Promise<Resol

const target = await ciTargetBranch(env)
if (target) {
for (const ref of [`origin/${target.branch}`, target.branch]) {
const sha = await mergeBase(ref, head, opts.cwd)
if (sha) return { ref, sha, source: target.source }
const find = async () => {
for (const ref of [`origin/${target.branch}`, target.branch]) {
const sha = await mergeBase(ref, head, opts.cwd)
if (sha) return { ref, sha, source: target.source }
}
return undefined
}
const found = (await find()) ?? ((await fetchTargetHistory(target.branch, head, opts.cwd, find)) ? await find() : undefined)
if (found) return found
throw new Error(
`PR target branch '${target.branch}' (${target.source}) is not available locally. ` +
`Fetch it (actions/checkout with fetch-depth: 0, or git fetch origin ${target.branch}) or pass --base.`,
Expand Down Expand Up @@ -293,6 +336,15 @@ export async function showAtRef(cwd: string, ref: string, rel: string): Promise<
}
}

/** The commit SHA a ref names, or undefined when it does not resolve. */
export async function resolveCommit(ref: string, cwd: string): Promise<string | undefined> {
try {
return (await git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], cwd)).trim() || undefined
} catch {
return undefined
}
}

/** Compute a short hash of the manifest file for the verdict envelope. */
export async function manifestHash(manifestPath: string, cwd: string): Promise<string | undefined> {
try {
Expand Down
Loading
Loading