Repository navigation
feat: docs_share_comments tool — list, reply to and resolve comment threads on shared dbt docs #1730
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
hkaltai
wants to merge
31
commits into
main
Choose a base branch
from
feat/docs-share-comments-tool
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+1,060
−10
Open
feat: docs_share_comments tool — list, reply to and resolve comment threads on shared dbt docs #1730
Changes from all commits
Commits
Show all changes
31 commits
Select commit
Hold shift + click to select a range
b7cfc04
feat: foundation for the dbt Power User tools
hkaltai 1eb722e
Merge remote-tracking branch 'origin/main' into feat/pu-mods-foundation
hkaltai e7c53b2
feat: docs_share_comments tool — list, reply to and resolve comment t…
hkaltai 21d0494
fix: harden the dbt Power User tool foundation
hkaltai a0f07cb
fix: docs_share_comments — a post must be acknowledged, an unexpected…
hkaltai 130aedf
Merge commit '21d0494c' into feat/docs-share-comments-tool
hkaltai 35e1ccc
fix: docs_share_comments — a malformed share, thread or status is an …
hkaltai 5da9186
test: docs_share_comments is no longer a placeholder in the allow-lis…
hkaltai 6a139dd
fix: docs_share_comments review — tolerate paginated answers and unkn…
hkaltai d8c3469
fix: send falsy API bodies, follow cancellation in apiRequest, check …
hkaltai 1e5d0b4
Merge remote-tracking branch 'origin/main' into feat/docs-share-comme…
hkaltai dace1c2
Merge remote-tracking branch 'origin/main' into feat/pu-mods-foundation
hkaltai 18a3fc4
fix: keep the stored API key out of API errors, bound the dbt config …
hkaltai 6024ac9
fix: redact the API key when a refused header races the caller's abor…
hkaltai f5159c5
docs: say which tools use the dbt adapter helper
hkaltai f57de3d
docs: rewrap and correct the adapter helper comments
hkaltai d6e37a7
Merge origin/feat/pu-mods-foundation into feat/docs-share-comments-tool
hkaltai c3dc492
fix: docs_share_comments passes the call's abort signal to every requ…
hkaltai aaff414
fix: never echo a send failure's text, so a trimmed key can't leak
hkaltai 3a98dff
fix: a rejection with no reason is a send failure, not an abort
hkaltai be4e3e2
Merge remote-tracking branch 'origin/feat/pu-mods-foundation' into fe…
hkaltai ebd7926
Merge remote-tracking branch 'origin/main' into feat/docs-share-comme…
hkaltai 50a42e9
fix: name authors by real name, check the thread before posting, keep…
hkaltai b1fb27a
merge origin/main
hkaltai e315733
fix: a failed pre-post check says nothing was sent, exact-100 threads…
hkaltai 2489f78
fix: a paginated list that is not the whole answer is reported as inc…
hkaltai 9b24389
fix: a post asks for permission, and a listing is cut at an overall size
hkaltai 6335b6b
test: the implemented docs_share_comments is not a placeholder
hkaltai 3abbb9f
fix: the listing's metadata is held to the same size budget as its ou…
hkaltai 76686b2
test: leave the shared foundation test untouched
hkaltai 253e29a
fix: a post asks for permission only once its thread is known, an unr…
hkaltai File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| import z from "zod" | ||
| import { AltimateApi } from "./client" | ||
|
|
||
| // The shared-docs comment endpoints of the Altimate backend. Shapes follow what the backend returns for | ||
| // a docs share: its threads ("conversation groups") and the messages in each. | ||
|
|
||
| export interface DocsShareMessage { | ||
| conversation_id: number | ||
| message: string | ||
| timestamp: string | ||
| user_id: number | ||
| } | ||
|
|
||
| export interface DocsShareRange { | ||
| start: { line: number; character: number } | ||
| end?: { line: number; character: number } | ||
| } | ||
|
|
||
| export interface DocsShareThread { | ||
| conversation_group_id: number | ||
| owner?: number | ||
| /** "Pending" is open; "Resolved" is closed. */ | ||
| status: "Pending" | "Resolved" | ||
| meta?: { | ||
| field?: "description" | ||
| column?: string | ||
| highlight?: string | ||
| uniqueId?: string | ||
| filePath?: string | ||
| resource_type?: string | ||
| range?: DocsShareRange | null | ||
| } | null | ||
| conversations: DocsShareMessage[] | ||
| } | ||
|
|
||
| export interface DocsShare { | ||
| share_id: number | ||
| name?: string | ||
| description?: string | ||
| project_name?: string | ||
| conversation_group: DocsShareThread[] | ||
| } | ||
|
|
||
| export interface DocsShareUser { | ||
| id: number | ||
| display_name?: string | ||
| first_name?: string | ||
| last_name?: string | ||
| email?: string | ||
| } | ||
|
|
||
| // What a share and its threads must carry for the tool to read them: an answer without these is an | ||
| // error, so a changed or broken response is never shown as "no open comments". | ||
| const Range = z.object({ | ||
| start: z.object({ line: z.number(), character: z.number() }), | ||
| end: z.object({ line: z.number(), character: z.number() }).optional(), | ||
| }) | ||
| const SharesAnswer = z.array( | ||
| z.object({ | ||
| share_id: z.number(), | ||
| name: z.string().nullish(), | ||
| project_name: z.string().nullish(), | ||
| conversation_group: z.array( | ||
| z.object({ | ||
| conversation_group_id: z.number(), | ||
| // The backend's status is a closed set: a value outside it is an error, never "no open threads". | ||
| status: z.enum(["Pending", "Resolved"]), | ||
| // A range that is partial (the editor extension can store one without a start) drops the | ||
| // line of the thread, never the thread or the list. | ||
| meta: z.object({ range: Range.nullish().catch(undefined) }).passthrough().nullish(), | ||
| conversations: z.array( | ||
| z.object({ conversation_id: z.number(), message: z.string(), timestamp: z.string(), user_id: z.number() }), | ||
| ), | ||
| }), | ||
| ), | ||
| }), | ||
| ) | ||
|
|
||
| /** The shares of the given dbt projects, each with its comment threads. */ | ||
| export async function listSharedDocs( | ||
| projects: string[], | ||
| signal?: AbortSignal, | ||
| ): Promise<{ shares: DocsShare[]; /** Set when the service says it holds more shares than it sent. */ missing?: number }> { | ||
| const params = new URLSearchParams() | ||
| for (const project of projects) params.append("projects", project) | ||
| const shares = await AltimateApi.apiRequest("GET", `/dbt/dbt_docs_share/all?${params.toString()}`, undefined, signal) | ||
| // A paginated answer wraps the shares in `items`; a bare array is accepted too. | ||
| const wrapped = shares && !Array.isArray(shares) ? shares : undefined | ||
| const list = Array.isArray(wrapped?.items) ? wrapped.items : shares | ||
| const parsed = SharesAnswer.safeParse(list) | ||
| if (!parsed.success) throw new Error("The shared docs service returned an unexpected answer for the shares.") | ||
| const total = typeof wrapped?.total === "number" ? wrapped.total : undefined | ||
| const missing = total !== undefined && total > parsed.data.length ? total - parsed.data.length : undefined | ||
| return { shares: parsed.data as DocsShare[], missing } | ||
| } | ||
|
|
||
| /** The people in the tenant, for naming who wrote each message. */ | ||
| export async function listTenantUsers(signal?: AbortSignal): Promise<DocsShareUser[]> { | ||
| const users = await AltimateApi.apiRequest("GET", "/users/chat", undefined, signal) | ||
| return Array.isArray(users) ? users : [] | ||
| } | ||
|
|
||
| export async function replyToThread(shareId: number, groupId: number, message: string, signal?: AbortSignal): Promise<{ ok: boolean }> { | ||
| return AltimateApi.apiRequest("POST", `/dbt/dbt_docs_share/${shareId}/conversation_group/${groupId}/conversation`, { message }, signal) | ||
| } | ||
|
|
||
| export async function resolveThread(shareId: number, groupId: number, signal?: AbortSignal): Promise<{ ok: boolean }> { | ||
| return AltimateApi.apiRequest("POST", `/dbt/dbt_docs_share/${shareId}/conversation_group/${groupId}/resolve`, { resolved: true }, signal) | ||
| } | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
MAJOR — one thread with a partial
meta.rangefails the whole list (Claude; Codex accepted as major)Rangerequiresstart.line/start.characterwheneverrangeis present, andSharesAnswervalidates all shares in one go. The backend passesmetathrough unchanged. The dbt Power User extension writesrange: range ? { end: range.end, start: range.start } : undefined(src/comment_provider/conversationProvider.ts), and its own test (src/test/suite/conversationProvider.test.ts) documents Range objects whosestartis undefined in the wild. So{ end: {...} }or{}can be stored.Reproduced: one good Pending thread plus one with
range: { end: { line: 1, character: 1 } }(orrange: {}) →Could not load the comment threads: The shared docs service returned an unexpected answer for the shares.Every open thread of the project disappears, for the tool and for the plugin pane.Fix: parse
rangeleniently and drop it, so the thread is kept without a line, when it doesn't have the shape. Keep the strict checks for the fields that identify a thread.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed in 50a42e9:
rangeis parsed leniently (.catch(undefined)), so a partial range drops only the thread's line; the identifying fields stay strict. Test uses a range with onlyendand an empty one.