Repository navigation
feat: copy a written column description to the downstream columns that carry it, and show a model's documentation coverage - #25
Conversation
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
# Conflicts: # plugins/altimate-code/hooks/features/docs.tsx
…t carry it, and show a model's documentation coverage Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… in, drops offers for descriptions that changed or went, and keeps projects apart Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
|
Review loop result for this PR (two independent reviewers, then two fix checks). Fixes are in 520215e. Fixed:
Known and left as is:
Checks: |
…es whole, bounds what it offers and sends, quotes names as data, and withdraws offers for a file that is gone Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
|
Review round (two independent reviewers, Claude and Codex gpt-6.1-sol, as separate CLI processes) — replies to every finding: Fixed
A fresh reviewer run on these fixes returned RESOLVED; its small items (rollback scope, a misleading comment, the Not changed, with reason
Tests: |
|
review-loop: APPROVED at 8df598f (claude + codex, both APPROVE on the fix commits). Non-blocking: claude noted missing tests for Apply overlap/rollback, deleted file, model-paths '.', and the failure lines; tracked as follow-up. |
Code Review SummaryStatus: 9 Issues Found | Recommendation: Address before merge Incremental review of Overview
Issue Details (click to expand)SUGGESTION
Files Reviewed (4 files)
Validation was not run in this read-only review; no lint or test command was executed to confirm the four new tests pass. Fix these issues in Kilo Cloud Previous Review Summaries (5 snapshots, latest commit 6a25fc9)Current summary above is authoritative. Previous snapshots are kept for context only. Previous review (commit 6a25fc9)Status: 13 Issues Found (1 warning, 12 suggestions) | Recommendation: Address before merge Incremental review of Overview
Issue Details (click to expand)WARNING
SUGGESTION
Files Reviewed (4 files)
Validation was not run in this read-only review; no lint or test command was executed to confirm the new tests pass. Fix these issues in Kilo Cloud Previous review (commit 732f56d)Status: 11 Issues Found (1 warning, 10 suggestions) | Recommendation: Address before merge Incremental review of Overview
Issue Details (click to expand)WARNING
SUGGESTION
Files Reviewed (5 files)
Fix these issues in Kilo Cloud Previous review (commit e6aefd4)Status: 11 Issues Found (1 warning, 10 suggestions) | Recommendation: Address before merge Incremental review of Overview
Issue Details (click to expand)WARNING
SUGGESTION
Files Reviewed (4 files)
Fix these issues in Kilo Cloud Previous review (commit cfac01d)Status: 9 Issues Found (1 warning, 8 suggestions) | Recommendation: Address before merge Incremental review of Overview
Issue Details (click to expand)WARNING
SUGGESTION
Files Reviewed (5 files)
Fix these issues in Kilo Cloud Previous review (commit 1c3e679)Status: 6 Issues Found (all suggestions) | Recommendation: Merge Incremental review of Overview
Issue Details (click to expand)SUGGESTION
Files Reviewed (5 files)
Fix these issues in Kilo Cloud Additional previous summary content was truncated to keep this comment within platform limits. Reviewed by deepseek-v4.1-flash-1017 · Input: 93.6K · Output: 30K · Cached: 1.2M |
…were all unticked Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…n decides which groups a request covers Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
# Conflicts: # plugins/altimate-code/hooks/integrations.tsx # plugins/altimate-code/hooks/lineage.tsx # plugins/altimate-code/types/index.d.ts
…ase deadline, no tool text passed to Claude Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
|
review-loop: APPROVED at 418a3e4 (reviewers: gpt-6-astra high, gpt-6.1-sol high) First pass returned REQUEST CHANGES on two items; both were re-judged and the second pass is APPROVE from both. (1) The cost-gate/health settings and stub handlers are the shared foundation's, each replaced by its own sibling PR, outside this PR's scope. (2) Two models with the same name in different packages is outside the supported-input contract (documented limitation). |
…at/docs-propagation
sahrizvi
left a comment
There was a problem hiding this comment.
Consensus review (panel: Claude as lead, plus Codex on its default model). The OpenRouter models were out of credit and did not take part. Verdict: changes requested. Two majors are open.
Scope is this PR's own change only: the merge base with the foundation PR #30 (4c8add5) up to 418a3e4, which touches features/docs.tsx, docs.test.tsx, features/index.test.ts, task-impact.tsx and types/index.d.ts. Foundation findings are not repeated here. The branch does not have #30's last two commits (2c494ec and ac0d379).
How the YAML gets written. The plugin never rewrites a schema file itself. Apply sends Claude a prompt that names the source file and the target columns, and Claude edits the files with its Edit tool. I replayed one Apply turn on a scratch dbt-duckdb project, using the exact prompt the pane builds from real impact_analysis output from altimate-code #1733 (built from e84b6ecf9a). One file had CRLF endings, comments, a quoted column name with quote: true, a &dbl | anchor block and no trailing newline. All of that survived. Two columns that were already listed got a description, and a column that was not listed was added under its model in that model's YAML file. A column that already had {{ doc("x") }} was left unchanged and reported back. The risk therefore sits in the hand-written reader that decides what to offer, not in a writer.
Majors
- The reader assigns descriptions to the wrong model when a list item is a bare
-(inline at L169). - Coverage is not refreshed after a schema-file edit, which the PR claims it is (inline at L646).
Minors (inline): versioned models are skipped (L201), Apply uses the selection from the last render (L540), the source model is resolved by name only (L390), and offers are not re-checked after a recompile (L304). One minor is not tied to a diff line and is in the PR comment: no CHANGELOG entry, README section or version bump.
Checks. Head and foundation base both pass claude plugin validate, --strict on the root and on the plugin, tests/*.sh (7 of 7) and pytest (65 passed). claude plugin test: 374 pass at head against 349 at base, with no failures at either. The repo has no tsc or tsconfig.
Mutations. Breaking the Original/Alias filter (adding Transformation, or removing the filter), the Apply-marker skip, the said-once flag, sentGroups, the late-answer check and the leave-existing instruction is each caught by the tests. Loosening the column-key check (at === columnKey to at >= columnKey) is not caught.
Replayed CLI checks. lens_types rates order_id as Original and id_alias as Alias, rates amount * 2 as Transformation, and leaves upper(status) as Not sure. Only the first two are offered. A CLI without the tool prints Unknown tool: …, which MISSING_TOOL matches, and the message is said once. Arguments go to the CLI as an argv array, with no shell.
Merge order: altimate-code #1733 first, then #30, then this PR.
| if (!inModels) continue | ||
|
|
||
| // A list item starts a model or a column whatever key it opens with: `name` need not come first. | ||
| const dash = /^-\s+(.*)$/.exec(body) |
There was a problem hiding this comment.
Major: the reader puts descriptions on the wrong model. /^-\s+(.*)$/ does not match a bare - list item, which is valid YAML. In
models:
- name: orders
columns:
- name: order_id
description: Order identifier
-
name: customers
columns:
- name: customer_id
description: Customer identifierno new model is started at the bare -. The name: customers line then sits at modelKey, so the backfill at L193–195 renames the columns already read under orders. columnDescriptions returns customers.order_id → Order identifier and customers.customer_id → …, while a YAML parser reads two separate models. Writing orders.order_id then traces customers.order_id, and the pane offers that column's downstream targets with the orders description. A bare - under columns: drops that column instead. Suggested fix: treat ^-\s*$ (or ^-(\s+|$)) as a list item and add a test for it. (Raised by Codex, reproduced by the lead.)
There was a problem hiding this comment.
Fixed in 1890d12: a bare - now starts its own model or column, and its keys are read at the indent of the line below. Regression test added with your example, including a bare - under columns:.
There was a problem hiding this comment.
Resolved. A bare - now starts its own model or column, and the item's keys are read at the indent of the line below it. I compared the reader with a real YAML parser on 5,000 generated schema files (bare dashes, comments and blank lines before an item's keys, |/>/quoted/multi-line plain values, nested meta.description, indentless lists, any key order) and every file matched. The same generator catches the round-1 reader. On a dbt-duckdb project, a description written under a bare - item was traced as its own model. The one gap left is a - # comment item whose keys sit deeper than dash+2: it is skipped, never misattributed (a nit).
|
|
||
| /** `file.before` holds the text from before the edit only when `editReadsBefore` is true. */ | ||
| export async function editAfter($: EngineInterface, e: FileCall, result: ToolCallResult, file: EditedFile): Promise<ContextLines> { | ||
| if (/\.ya?ml$/i.test(file.path)) return schemaEdited($, file) |
There was a problem hiding this comment.
Major: coverage is not refreshed after a schema edit, which the PR says it is. The PR says coverage is "updated after an edit of a model or its schema file", but a .yml edit only goes to schemaEdited, which never calls dbt_docs_coverage or touches coverage. I replayed it with real CLI output: the YAML edit called only impact_analysis, and coverage changed only after a .sql edit. So documenting a missing column, or the model itself, leaves the pane listing it as missing. The manifest also stays stale until the next dbt compile, so the fix needs more than an extra call: run coverage for the models the edited YAML documents, or keep the claim and the pane text to "after a model SQL edit, as of the last compile".
There was a problem hiding this comment.
Kept the claim to what is true rather than adding a trace on a schema edit: coverage comes from the manifest's compiled SQL, which only dbt compile refreshes, so a schema-file edit cannot change it until the next compile. The PR description now says coverage updates after a model SQL edit, as of the last compile. Running coverage for the YAML's models on schema edits is a follow-up.
There was a problem hiding this comment.
Resolved by narrowing the claim. The PR body now says coverage updates after a model SQL edit, as of the last compile, and that a schema edit updates the offers only. That matches the code. I verified it end to end with the #1733 build: a SQL edit produced the coverage line. Removing the SQL coverage hook makes 4 tests fail.
| columnOpen = false | ||
| column = null | ||
| described = null | ||
| inColumns = key[1] === 'columns' |
There was a problem hiding this comment.
Minor: versioned models are skipped. A model's versions: key closes inColumns, and the columns: under each - v: N are never read, so a description written for a version is not offered. Coverage takes its model name from the file name (L435). On a dbt-duckdb project with orders at v1 and v2, orders_v2.sql asks for orders_v2, the CLI answers Model "orders_v2" not found, and nothing is shown. Describing the unversioned top-level columns: of orders traces only the first version the CLI finds (v1). Nothing is misattributed, but versioned models get no offers and no coverage.
There was a problem hiding this comment.
Not fixed here: versioned models (versions:) are not read, so they get no offers or coverage; nothing is misattributed. Recorded as a follow-up.
There was a problem hiding this comment.
Partly resolved. A SQL edit of orders_v2.sql now resolves to that version's unique_id, and a top-level description resolves to the declared latest version. Columns written under versions[].columns are still not read, so they get no offer. This is a minor follow-up that misses offers but never picks the wrong model, and it does not block.
| label={`Apply to ${plural(picked, 'column')}`} | ||
| onPress={() => | ||
| later($, async () => { | ||
| if (!prompt || applying) return |
There was a problem hiding this comment.
Minor: Apply uses the selection from the last render. prompt, groups and state.skipped come from the render that drew the button. If a tick toggle (or a withdrawn offer) lands before the pane re-renders, Apply still sends, and marks as applied, the old selection. The test harness re-renders between presses, so it did not reproduce there; the closure is as described. Re-read the atom inside the later callback and build the prompt from that state.
There was a problem hiding this comment.
Fixed in 1890d12: Apply now re-reads the pane state when pressed and builds the request and the cleared groups from it, not from the render that drew the button.
There was a problem hiding this comment.
Resolved. Apply re-reads the state when it is pressed and sends only offers whose key the pane drew. One follow-up remains: offerKey does not include the candidates, so a re-traced offer with the same text could send a target that was never drawn (an edge-case minor, inline at L50). Removing the drawn filter leaves the tests passing.
| const until = (await $.clock.now()) + ROUND_MS | ||
| const traced = await Promise.all( | ||
| changed.map(async one => { | ||
| const result = await runTool($, 'impact_analysis', { manifest_path: project.manifest, model: one.model, column: one.column, change_type: 'modify' }, { until, cliOnly: true }).catch(() => null) |
There was a problem hiding this comment.
Minor: the source model is resolved by name only. The source model goes to impact_analysis by name, but the CLI also accepts a unique_id. On a real project with a local package, the manifest's node order was not root-first (model.pkg.pkg_fct came before model.proj.fct). So when two packages share a model name, the trace can come from the other package, and that package's unique_ids go into the Apply request, which can then edit the wrong project's YAML. Resolving the edited file's model to its unique_id (for example from the manifest's patch_path) and passing that would close it. This is listed as a follow-up and is safe to do in one.
There was a problem hiding this comment.
Valid, not fixed here: the source model is resolved by name, so two packages with the same model name can collide. Resolving it to a unique_id through the manifest's patch_path is a follow-up; the foundation's tracing is shared by every feature.
There was a problem hiding this comment.
Resolved. The source model is traced by its own package's unique_id, resolved from the manifest. I verified this on a project with both model.shop.stg_orders and model.other.stg_orders: the trace went to model.shop.stg_orders. An id the manifest does not list returns MODEL NOT FOUND and offers nothing. The one fallback left is a dbt_project.yml written name : shop, with a space before the colon, which falls back to the bare name (an unusual-formatting minor, inline at L390).
| blocks.push( | ||
| [ | ||
| `Take the description of ${name(group.model, group.column)} as it is written in ${JSON.stringify(group.file)} (dbt project at ${JSON.stringify(group.manifest.replace(/\/target\/manifest\.json$/, ''))}), and put it on:`, | ||
| ...picked.map(one => `- ${name(one.model, one.column)}${one.id ? ` (${JSON.stringify(one.id)})` : ''}, ${one.lens === 'Alias' ? 'renamed from it' : 'carried as is'}`), |
There was a problem hiding this comment.
Minor: offers are not re-checked after a recompile. Candidates are stored when they are traced and are not re-checked when the manifest changes. After a model edit and a dbt compile, a column that was an Alias may now be a calculation, but Apply still asks Claude to copy the description onto it. The "leave a column that already has a different description" guard only protects columns that already have one. Re-checking the lens when Apply is pressed, or dropping offers when target/manifest.json changes, would fix it. This is an acknowledged follow-up and not a blocker on its own.
There was a problem hiding this comment.
Acknowledged follow-up, as you note: offers are checked when traced, not again after a recompile. Re-checking the lens at Apply time is recorded as a follow-up.
There was a problem hiding this comment.
Not resolved; it is still a listed follow-up. Offers are not re-traced when Apply is pressed, so a downstream lineage change made after the offer is not noticed. Under this round's bar it is a minor, not a blocker: it needs a change between the offer and Apply, and the edits still go through Claude's permissions. Re-checking lens_types when Apply is pressed would close it.
|
Consensus review, the rest of the findings (Claude and Codex). These are the ones not tied to a diff line, plus the nits. The formal review holds the majors and the inline minors. Minor, not on a diff line
Nits
|
…ble before-text offers nothing; Apply reads the ticks when pressed; one shell-keyword list Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ays unknown; drop unused prompt Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…at/docs-propagation Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> # Conflicts: # plugins/altimate-code/hooks/integrations.tsx
|
review-loop: APPROVED at fcb2f4a (reviewers: gpt-6-astra high, gpt-6.1-sol high) @sahrizvi on the CHANGES_REQUESTED review, point by point (earlier fixes at b2be7d6, latest at fcb2f4a):
|
… bare engine Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
| // A file that is gone writes nothing, so what was offered from it no longer holds. | ||
| const written = columnDescriptions(after ?? '') | ||
| // A before-text that could not be read says nothing about what changed: no offer rather than every description. | ||
| const fresh = after === null || (file as { beforeUnknown?: boolean }).beforeUnknown ? [] : changedDescriptions(file.before, after) |
There was a problem hiding this comment.
WARNING: The beforeUnknown guard is dead after the merge, so a failed before-read again looks like a brand-new file
The cast cannot ever be true: EditedFile is back to { path, before } (tool-chain.ts:29), beforeCall no longer produces the flag, and afterCall passes only { path, before } to the feature (tool-chain.ts:124). In installToolChain the read is readBefore: path => $.fs.read(path) (tool-chain.ts:142) under bounded(..., null, ...), so a read that rejects or times out (permission error, network mount, over the 4 MiB limit) becomes before: null. changedDescriptions(null, after) then treats the edited YAML as a file that did not exist and reports every description in it as newly written: those are traced and offered for propagation, and the context line tells Claude they were just written.
This is the regression fixed at fcb2f4a, whose tool-chain.test.ts case was dropped in the same merge; docs.test.tsx:236 now models a missing file by throwing from the read, which codifies the conflation this guard was meant to prevent. Restore the beforeUnknown field (set when the before-read rejects or times out, with its regression test), or have schemaEdited skip the offer when file.before === null for a file that exists.
There was a problem hiding this comment.
Fixed in fb0a883: the premise holds (tool-chain.ts hands the feature before:null for a failed read). The shared hook cannot be changed from this PR, so docs.tsx now treats a null before-text on an Edit (non-empty old_string, so the file must have existed) as an unknown read and offers nothing; a Write, or an Edit with an empty old_string, still counts as creating the file. docs.test.tsx covers both: the created-file case now uses Write, and a new case checks a failed Edit read offers nothing. The remaining Write-with-unreadable-before case needs the shared beforeUnknown field and is written up in shared-fixes/docs-propagation.md.
…of every description in the file Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e name in another package is never the one used Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed models are still found Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Follow-up on the open kilo-code-bot thread and the review gate. Fixed in fb0a883 (an Edit whose before-read failed offers nothing), 1c3e679 / cfac01d (a source model is traced by the manifest unique_id of its own package, falling back to the name for versioned or unreadable cases), e6aefd4 (a request the engine refused leaves Apply's offers in place). The Write-with-unreadable-before case needs the shared tool-chain change and is in shared-fixes/docs-propagation.md. review-loop: APPROVED at e6aefd4 (reviewers: gpt-6-astra high, gpt-6.1-sol high) |
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… description is read past a blank line Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
| // A plain value runs on over the lines indented more than its key. | ||
| // A blank line inside it is a paragraph break, not its end: it goes on while the next text line is still indented. | ||
| for (let i = at + 1; i < lines.length; i++) { | ||
| if (lines[i]!.trim() === '') continue |
There was a problem hiding this comment.
SUGGESTION: A comment between paragraphs is read as part of the description
Now that the loop steps over blank lines, it also reaches a # comment on a line indented deeper than the description key. inlineValue only strips a comment that follows whitespace (/\s+#.*$/), so a line that begins with # is returned verbatim and appended:
description: First paragraph
# checked against staging
- name: statusreads as First paragraph # checked against staging. Since changedDescriptions compares this text, adding or removing such a comment counts as a changed description: the column is traced and offered for propagation although its description did not change, and the pane (docs.tsx:553) shows the comment as part of it. Skip lines whose trimmed body starts with #, as the outer loop does at line 164, before appending.
There was a problem hiding this comment.
Fixed in 02a1c55: a comment line between a description's paragraphs is skipped, with a regression test in docs.test.tsx.
| if (rest.startsWith('[')) { | ||
| for (const one of rest.replace(/^\[|\]$/g, '').split(',')) names.push(one.trim().replace(/^["']|["']$/g, '')) | ||
| } else if (rest === '') { | ||
| for (let j = i + 1; j < lines.length && (/^\s*(?:#.*)?$/.test(lines[j]!) || /^\s*-\s+/.test(lines[j]!)); j++) if (/^\s*-\s+/.test(lines[j]!)) names.push(lines[j]!.replace(/^\s*-\s+/, '').replace(/\s+#.*$/, '').trim().replace(/^["']|["']$/g, '')) |
There was a problem hiding this comment.
SUGGESTION: The same list-item test is evaluated twice, which makes the line hard to verify
/^\s*-\s+/ is tested in the loop condition and again in the body, and the whole transform chain is inlined. A single pass keeps the intended behaviour (a blank or comment line does not end the list; anything else does) and removes the duplicate test:
for (let j = i + 1; j < lines.length; j++) {
const row = lines[j]!
if (/^\s*-\s+/.test(row)) names.push(row.replace(/^\s*-\s+/, '').replace(/\s+#.*$/, '').trim().replace(/^["']|["']$/g, ''))
else if (!/^\s*(?:#.*)?$/.test(row)) break
}There was a problem hiding this comment.
Fixed in 02a1c55: the model-paths loop is now a single pass (blank or comment lines continue, any other non-item line ends the list).
…package's id, never by a bare name Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ned model's latest version is the declared one Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Round on head 732f56d (panel CHANGES_REQUESTED), all handled in a4e8cbf:
review-loop: APPROVED at a4e8cbf (reviewers: gpt-6-astra high, gpt-6.1-sol high) |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
review-loop: APPROVED at 02a1c55 (reviewers: gpt-6-astra high, gpt-6.1-sol high) |
| */ | ||
| async function modelRef($: EngineInterface, project: Project, model: string, byFile = false): Promise<string> { | ||
| if (!project.package) return model | ||
| const built = `model.${project.package}.${model}` |
There was a problem hiding this comment.
SUGGESTION: built is not the unique_id of a model that has versions
A model declared with versions: is model.<package>.<model>.v<n> in the manifest, so this string never names one; the doc comment above ("gets the id dbt would give it") holds only for unversioned models. When $.fs.read of the manifest throws — the file exists but is over the 4 MiB a plugin can read (lineage.tsx:48,395), or the read fails — modelRef returns built, so a schema edit of a versioned model's top-level columns: now matches nothing and gets no offers, where the bare name sent before could still be resolved by the CLI. sqlEdited stays silent about it as well, because "Model not found" does not match MISSING_TOOL, so coverage simply never appears. Either keep the bare name for this case (the cross-package risk it had before) or say once that the model could not be resolved.
| }) | ||
|
|
||
| test('a versioned model, whose unique_id is not built from its file name, is traced as its latest version', async ($, on) => { | ||
| const manifest = { 'model.shop.stg_orders.v1': NODE('shop', 'stg_orders', 'stg_orders_v1'), 'model.shop.stg_orders.v2': NODE('shop', 'stg_orders', 'stg_orders_v2') } |
There was a problem hiding this comment.
SUGGESTION: This case pins the id-sort fallback, not the declared latest version
Neither node here carries version or latest_version, so the assertion passes only through the tie-break that sorts by unique_id descending: ...stg_orders.v2 sorts above ...stg_orders.v1, while ...stg_orders.v9 sorts above ...stg_orders.v10, so v9 would win. The declared-latest path is covered by the next test, which sets both fields. Add version/latest_version here (as the next test does), or retitle this case to say it covers a manifest that declares neither.
sahrizvi
left a comment
There was a problem hiding this comment.
Consensus re-review, round 2 (panel: Claude as lead, and Codex). Head 02a1c55f86, scope git diff e10448ca66..02a1c55f86: features/docs.tsx, docs.test.tsx and the DocsState types. No shared plugin file differs from main.
Approve. Both round-1 majors are resolved.
- The bare
-reader is fixed. I compared it with a real YAML parser on 5,000 generated schema files: bare dashes, comments and blank lines before an item's keys,|,>, quoted, multi-line plain values, nestedmeta.description, indentless lists and keys in any order. Every file matched. The same generator catches the round-1 reader. - The coverage claim now matches the code. Coverage updates after a model SQL edit, as of the last compile; a schema edit only updates the offers.
End-to-end check. I built altimate-code #1733 (ec464792ca) and used it on a scratch dbt-duckdb project that has two packages, each with a stg_orders model.
- The real hooks were fed the real files and the recorded CLI output. A description added under a bare
-item tracedmodel.shop.stg_orders, notmodel.other.stg_orders. Only the 3 Original and Alias columns were offered, and Apply sent one request naming them by unique_id. - A SQL edit produced the coverage line.
- Two Haiku turns with the exact Apply prompt only added lines. Comments, key order, quoting and a missing trailing newline were kept, and
dbt parsepasses.
Checks. claude plugin test: 438 pass at head, 402 at base. Validate and --strict pass. tests/*.sh pass, and pytest has 65 passing tests. Mutation checks: the Original/Alias filter, the item boundaries, the bare-dash lookahead, the unique_id resolution, the SQL coverage hook and the before-read-failed rule each make tests fail when broken.
Remaining minors, none blocking. Each is inline; the release one is in the combined comment.
- Stale offers after a recompile: needs a lineage change between the offer and Apply, and is a listed follow-up.
offerKeyignores the candidates: needs the same text written twice and a press that beats the re-render.name :with a space before the colon: unusual formatting.- Per-version columns are not read: missed offers, never a wrong model.
- Multi-line flow
model-paths: unusual layout, silent rather than wrong. - No coverage line for a fully documented model: cosmetic, and the pane still shows it.
- A
Writewhose before-read failed offers every description: rare, offers only, needs the shared tool-chain field. - No CHANGELOG entry or version bump: safe in the release change.
Merge order: altimate-code #1733 first, then this PR.
| // What is ticked now, not what was drawn: a tick or a withdrawn offer may have landed since the render. | ||
| const state = (await read($, docsAtom)) ?? empty() | ||
| // An offer that arrived after the draw waits for the next Apply: it was never shown. | ||
| const groups = state.groups.filter(group => group.candidates.length > 0 && drawn.has(offerKey(group))) |
There was a problem hiding this comment.
Minor (edge, safe in a follow-up): offers are still not re-checked after a recompile. An offer keeps the candidates traced when the description was written. Suppose the person then changes the downstream model so that fct.id now comes from another column, recompiles, and presses Apply. The request still names fct.id, and Claude is asked to copy the description onto a column that no longer carries the value. This needs a lineage change between the offer and Apply, the request still goes through Claude's normal edit permissions, and the PR body lists it as a follow-up, so it does not block. Re-tracing (or re-checking lens_types) when Apply is pressed would close it. Raised by Codex as major, then rated minor by Codex under this round's bar.
|
|
||
| const groupKey = (manifest: string, model: string, column: string) => `${manifest}|${model}.${column}` | ||
| /** Names one offer: the column and the description written to it. */ | ||
| const offerKey = (group: DocsGroup) => `${groupKey(group.manifest, group.model, group.column)}|${group.description}` |
There was a problem hiding this comment.
Minor (edge): offerKey does not include the candidates. Here is the sequence. The pane draws description D for m.c with target A. The description is then changed and changed back to D, and the second trace returns target B. The offer now has the same key, so an Apply handler from the earlier render sends B, which the person never saw. This needs the same text written twice and a press that lands before the re-render, so it does not block. A key that includes the candidate ids, or a check of the candidates against the drawn ones, would close it. The drawn filter has no test either: removing drawn.has(offerKey(group)) leaves all 438 tests passing.
| if (name === '' || name === '.') return path.startsWith(`${dir}/`) && !/^(?:target|dbt_packages|dbt_modules|node_modules|venv|site-packages|dist|build|\.[^/]+)\//.test(path.slice(dir.length + 1)) | ||
| return path.startsWith(`${dir}/${name}/`) | ||
| }) | ||
| const pkg = /^name:\s*['"]?([A-Za-z0-9_]+)['"]?\s*(?:#.*)?$/m.exec(text ?? '')?.[1] |
There was a problem hiding this comment.
Minor (unusual formatting): a name : line with a space before the colon leaves the package unset. name : shop is valid YAML, but this regex does not match it. modelRef then falls back to the bare model name (L354). If the last manifest only lists another package's model of that name (model.vendor.orders), that model's downstream columns are offered for shop's description. The canonical name: shop works correctly: I verified it on a dbt-duckdb project where model.other.stg_orders and model.shop.stg_orders both exist, and the trace went to model.shop.stg_orders. An unresolved qualified id returns MODEL NOT FOUND and offers nothing. Allowing \s* before the colon would close it.
| columnOpen = false | ||
| column = null | ||
| described = null | ||
| inColumns = key[1] === 'columns' |
There was a problem hiding this comment.
Minor (edge, follow-up): version-specific columns are still not read. A versions: key ends the column list, so descriptions written under versions[].columns give no offer. The rest is fixed: a SQL edit of orders_v2.sql now resolves to that version's unique_id, and a top-level description resolves to the declared latest version. Nothing is put on the wrong model; this only misses offers.
| if (!match) continue | ||
| const rest = match[1]!.replace(/\s+#.*$/, '').trim() | ||
| const names: string[] = [] | ||
| if (rest.startsWith('[')) { |
There was a problem hiding this comment.
Minor (unusual layout): a multi-line flow list in model-paths is not read. model-paths: [ followed by "sql" and ] on later lines gives ['models'], so edits under sql/ produce no offers and no coverage. This is silent rather than wrong. Block lists with comments and blank lines are now read correctly.
| const gaps = [...(view.hasDescription ? [] : ['the model itself']), ...view.missing] | ||
| // A select list that is not plain column names (a `*`, an unaliased expression, a UNION) is counted by the manifest's columns only. | ||
| const star = meta.source === 'manifest_columns' ? " · the model's select list is not plain column names (a `*`, an unaliased expression or a UNION), so only the columns the manifest lists are counted" : '' | ||
| if (!gaps.length && !star) return [] |
There was a problem hiding this comment.
Minor (cosmetic): a fully documented model gets no coverage line after a SQL edit. When there are no gaps and the source is compiled_sql, the hook returns nothing. The pane still shows the coverage, so the PR's coverage claim holds, but the edit gets no feedback in the transcript. A short "all N columns documented" line would make it consistent.
| const written = columnDescriptions(after ?? '') | ||
| // A before-text that could not be read says nothing about what changed: no offer rather than every description. | ||
| // An Edit replaces text that was in the file, so a missing before-text there is a failed read, not a new file. | ||
| const unknown = (file as { beforeUnknown?: boolean }).beforeUnknown === true || (file.before === null && !created) |
There was a problem hiding this comment.
Minor (edge, needs a shared change): a Write over an existing file whose before-read failed is treated as a creation. Every description in the file is then offered as new; only the first three are traced. This only produces offers and nothing is written without Apply. A failed read is rare. The author has noted that telling the two apart needs a beforeUnknown field from the shared tool-chain.ts, so this is fine as a follow-up.
|
Consensus re-review, round 2 (Claude and Codex) at Minor, not on a diff line
Nits
Fixed since round 1: a comment line inside a multi-line plain value is no longer folded into the preview. Apply reads the ticks when it is pressed. |
What this does
Adds the docs feature to the altimate-code plugin.
/propagateopens a pane for a model's column: it lists the downstream columns that carry the column unchanged (OriginalorAlias, from the CLI'slens_types), and copies the written description to the ones you pick. Columns that come from a calculation are never offered.dbt_docs_coverage) is shown, and updated after an edit of a model's SQL, as of the lastdbt compile; an edit of a schema file updates the offers, not the coverage.dbt_docs_coverage, that is said once, not on every edit.Depends on the altimate-code PR AltimateAI/altimate-code#1733 (
dbt_docs_coverageandlens_types); merge that first. This branch contains the foundation commits, so its diff includes them until the foundation merges.How it was checked
claude plugin validate --strict .passes.claude plugin validate --strict ./plugins/altimate-codereports the same 4 warnings thatmainreports (types/hook inventory and the missing directory icon); nothing new.claude plugin test ./plugins/altimate-code: 215 pass, 0 fail, including the newhooks/features/docs.test.tsx.tests/*.shall pass.Follow-ups, not changed here: the YAML reader takes a column or model written with
nameas its first key (dbt's own layout); a source model is identified by its name, so two packages with one model name resolve to the first one the CLI finds; offers are not re-traced when the manifest is recompiled after they were made.Demo video (hosted)
P-10.mp4 — watch on Notion (Altimate workspace; recorded from the approved head of this PR).
🤖 Generated with Claude Code