From bcef49b049396805d7a5e02a1e8c4e88fc6ce06e Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 13 Nov 2026 17:08:38 +0530 Subject: [PATCH 01/10] feat: /profile-ctes times each CTE of a dbt model, slowest first Lists the model's CTEs through altimate-code's dbt_cte_profile, then times them one call at a time so the pane fills live and Stop works between queries. Marginal times and hot/warm/cool tiers are worked out in the mod. Runs only on request, and the finished profile reaches Claude with its next tool result. Co-Authored-By: Claude Sonnet 5.5 --- .../hooks/features/cte-profile.test.tsx | 148 ++++++++++ .../hooks/features/cte-profile.tsx | 269 +++++++++++++++++- plugins/altimate-code/types/index.d.ts | 24 +- 3 files changed, 427 insertions(+), 14 deletions(-) create mode 100644 plugins/altimate-code/hooks/features/cte-profile.test.tsx diff --git a/plugins/altimate-code/hooks/features/cte-profile.test.tsx b/plugins/altimate-code/hooks/features/cte-profile.test.tsx new file mode 100644 index 00000000..53214507 --- /dev/null +++ b/plugins/altimate-code/hooks/features/cte-profile.test.tsx @@ -0,0 +1,148 @@ +import { expect, mock, test } from 'claude-code/testing' + +import type { CteRow } from '../../types' +import { classifyTiers, slowestFirst, summaryOf, withTiers } from './cte-profile' + +const PANE = { + plugin: 'altimate-code', + component: 'Pane', + requestId: 'altimate-cte-profile', + props: { title: 'Profile CTEs', isFocused: true, bodyColumns: 90, placement: 'dock', scroll: { offset: 0, bodyRows: 40 }, view: {} }, +} as const + +const row = (name: string, extra: Partial = {}): CteRow => ({ name, line: 1, clause: 0, status: 'done', ...extra }) + +test('tiers: hot from half the largest marginal time, warm from a fifth, all cool when nothing took time', () => { + expect(classifyTiers([100, 50, 49, 20, 19, 0])).toEqual(['hot', 'hot', 'warm', 'warm', 'cool', 'cool']) + expect(classifyTiers([0, 0])).toEqual(['cool', 'cool']) + expect(classifyTiers([])).toEqual([]) +}) + +test('marginal time is the time over the CTE before it in the same WITH clause, never negative', () => { + const rows = withTiers([ + row('a', { queryMs: 100 }), + row('b', { queryMs: 350 }), + row('c', { queryMs: 300 }), + row('d', { queryMs: 40, clause: 99 }), + row('e', { status: 'pending' }), + ]) + expect(rows.map(one => one.marginalMs)).toEqual([100, 250, 0, 40, undefined]) + expect(rows.map(one => one.tier)).toEqual(['warm', 'hot', 'cool', 'cool', undefined]) + expect(slowestFirst(rows).map(one => one.name)).toEqual(['b', 'a', 'd', 'c', 'e']) +}) + +test('the summary for Claude lists timed CTEs slowest first and names the failed ones', () => { + const text = summaryOf({ + model: 'customers', + status: 'stopped', + rows: withTiers([row('a', { queryMs: 100, rows: 7 }), row('b', { queryMs: 400, rows: 3 }), row('c', { status: 'failed', error: 'boom' }), row('d', { status: 'pending' })]), + }) + const lines = text.split('\n') + expect(lines[0]).toContain('customers (stopped, 1 CTE not timed)') + expect(lines[1]).toContain('- b (line 1): +300 ms (hot)') + expect(lines[2]).toContain('- a (line 1): +100 ms (warm)') + expect(text).toContain('- c (line 1): boom') +}) + +type Setup = { ctes?: string[]; hold?: { cte: string; until: Promise }; times?: Record; missing?: boolean } + +async function start($: any, on: any, setup: Setup = {}) { + const clock = mock.clock(on) + const calls: { cte?: string; write: boolean }[] = [] + const toasts: string[] = [] + const ctes = setup.ctes ?? ['orders', 'payments', 'final'] + on('command.register', () => ({ value: { command: 'profile-ctes' } })) + on('session.start', (_: unknown, e: { cwd: string }) => ({ cwd: e.cwd })) + on('ui.open', () => ({ value: {} })) + on('ui.toast', (_: unknown, e: { text: string }) => { + toasts.push(e.text) + return { value: undefined } + }) + on('ui.render', ($$: any, e: any) => { + const { Box } = $$.ui.resolve(e) + return + }) + on('process.run', async (_: unknown, e: { argv: readonly string[] }) => { + const [, command, , tool] = e.argv + if (command !== 'tool' || tool !== 'dbt_cte_profile') return { value: { exitCode: 1, stdout: '', stderr: 'not this test' } } + const args = JSON.parse(String(e.argv[e.argv.indexOf('--args') + 1] ?? '{}')) + calls.push({ cte: args.cte, write: e.argv.includes('--allow-write') }) + const reply = (body: unknown, exitCode = 0) => ({ value: { exitCode, stdout: JSON.stringify(body), stderr: '' } }) + if (setup.missing) return reply({ status: 'error', output: `Unknown tool: ${tool}. Run \`altimate-code tool list\` to see the available tools.`, metadata: {} }, 1) + if (!args.cte) return reply({ status: 'ok', output: '', metadata: { success: true, ctes: ctes.map((name, index) => ({ name, line: index + 2, index, clause: 0 })) } }) + if (setup.hold && setup.hold.cte === args.cte) await setup.hold.until + return reply({ status: 'ok', output: '', metadata: { success: true, cte: args.cte, queryMs: setup.times?.[args.cte] ?? 10, rows: 5 } }) + }) + await $.session.start({ cwd: '/', surface: 'terminal', isInteractive: true }) + await clock.settle() + const run = (args: string) => $.command.run({ command: 'profile-ctes', args, origin: { kind: 'composer' }, presentation: { isFullscreen: false, columns: 120 } }) + return { clock, calls, toasts, run } +} + +test('/profile-ctes lists the CTEs read-only, then times each with write permission, slowest first', async ($, on) => { + const { clock, calls, toasts, run } = await start($, on, { times: { orders: 100, payments: 350, final: 380 } }) + const out = await run('customers') + expect(out.text).toContain('Profiling the CTEs of customers') + await clock.settle() + + expect(calls).toEqual([ + { cte: undefined, write: false }, + { cte: 'orders', write: true }, + { cte: 'payments', write: true }, + { cte: 'final', write: true }, + ]) + const ui = await $.ui.mount({ ...PANE, surface: 'terminal' }) + const texts = (await ui.findAll({ type: 'Text' })).map((one: any) => one.text as string) + const order = ['payments', 'orders', 'final'].map(name => texts.findIndex(text => text.startsWith(name))) + // payments adds 250 ms, orders 100, final 30: slowest first. + expect(order.every(at => at >= 0)).toBe(true) + expect(order).toEqual([...order].sort((a, b) => a - b)) + expect(texts.find(text => text.startsWith('payments'))).toContain('+250 ms (hot)') + expect(texts.find(text => text.startsWith('final'))).toContain('(cool)') + expect(await ui.find({ key: 'cte-send' })).toBeDefined() + expect(await ui.find({ key: 'cte-stop' })).toBeUndefined() + expect(toasts.some(text => text.includes('slowest is payments'))).toBe(true) + await ui.unmount() +}) + +test('the pane fills live and Stop ends the run between queries', async ($, on) => { + let release!: () => void + const until = new Promise(resolve => (release = resolve)) + const { clock, calls, run } = await start($, on, { hold: { cte: 'payments', until } }) + await run('customers') + await clock.settle() + + // orders is timed, payments is running (its query is held), final has not started. + const ui = await $.ui.mount({ ...PANE, surface: 'terminal' }) + expect(((await ui.find({ type: 'Text', text: /^orders/ })) as any)?.text).toContain('ms') + expect(await ui.find({ type: 'Text', text: /Timing CTE 2 of 3/ })).toBeDefined() + expect(await ui.find({ key: 'cte-stop' })).toBeDefined() + expect(calls.map(call => call.cte)).toEqual([undefined, 'orders', 'payments']) + + await ui.press({ key: 'cte-stop' }) + await clock.settle() + release() + await clock.settle() + + // The query already running finished; the next was never sent. + expect(calls.map(call => call.cte)).toEqual([undefined, 'orders', 'payments']) + expect(await ui.find({ type: 'Text', text: /Stopped: 2 of 3 timed/ })).toBeDefined() + expect(await ui.find({ key: 'cte-stop' })).toBeUndefined() + await ui.unmount() +}) + +test('an altimate-code without the tool gets one line naming what is needed, and no query is sent', async ($, on) => { + const { clock, calls, run } = await start($, on, { missing: true }) + await run('customers') + await clock.settle() + expect(calls).toEqual([{ cte: undefined, write: false }]) + const ui = await $.ui.mount({ ...PANE, surface: 'terminal' }) + expect(await ui.find({ type: 'Text', text: /needs a newer altimate-code/ })).toBeDefined() + await ui.unmount() +}) + +test('without a model name and nothing read yet, the command asks for one and runs nothing', async ($, on) => { + const { calls, run } = await start($, on) + expect((await run('')).text).toContain('Name a model') + expect(calls).toEqual([]) +}) diff --git a/plugins/altimate-code/hooks/features/cte-profile.tsx b/plugins/altimate-code/hooks/features/cte-profile.tsx index 865e2f31..f9625ae9 100644 --- a/plugins/altimate-code/hooks/features/cte-profile.tsx +++ b/plugins/altimate-code/hooks/features/cte-profile.tsx @@ -1,31 +1,259 @@ -// Profile CTEs: /profile-ctes times each CTE. +// Profile CTEs: /profile-ctes [model] times each CTE of a dbt model, one count query per CTE (each +// recomputes the CTEs before it), and lists them slowest first in a pane. // -// The plugin calls each function below at its moment, in the order features/index.ts fixes; one with -// nothing to do stays a no-op. This feature's own hooks (its commands and panes, each under a matcher -// no other part uses) go in `register`. The events the whole plugin shares (session start and end, -// turns, Bash and file tool calls, the band) come through the other functions, since a plugin hooks -// each of those once. The status-line part is set with `setStatusPart($, 'cteProfile', text)`. +// altimate-code's `dbt_cte_profile` does one thing per call: without `cte` it lists the CTEs, with +// `cte` it times one. This file drives the loop, so the pane fills live and Stop works between +// calls (a query already running cannot be cancelled). It runs only when asked, never on an edit, +// because every CTE is a warehouse query. +import { atom, read, update } from 'claude-code' import type { Args, EngineInterface, EventResult, On, RenderElement, ToolCallResult } from 'claude-code' +import type { CteProfileState, CteRow, CteTier } from '../../types' import type { BashCall, ContextLines, EditedFile, FileCall } from '../tool-chain' +import { later, runTool } from '../altimate-cli' +import { setStatusPart } from '../status-line' import type { BandUi, FeatureContext } from './index' +const PANE = 'altimate-cte-profile' +const PANE_TITLE = 'Profile CTEs' +const PANE_SIZE = { columns: 90, rows: 24 } +const COMMAND = 'profile-ctes' +const TOOL = 'dbt_cte_profile' +/** A count query can run long on a big model; each call gets this much before it is given up on. */ +const QUERY_BUDGET_MS = 300_000 +/** The listing is a file read; it gets the default budget. */ +const NEEDS_NEWER = 'Profile CTEs needs a newer altimate-code (one with the dbt_cte_profile tool): update it with `npm i -g @altimateai/altimate-code`.' + +const stateAtom = atom({ plugin: 'altimate-code', key: 'cteProfile' } as const, null as CteProfileState | null) + +// Per conversation: the model last read or edited (what a bare /profile-ctes profiles) and the result +// Claude has not been handed yet. +let lastModelPath: string | null = null +let pendingContext: string | null = null + +/** + * Hot at half the largest marginal time or more, warm at a fifth, else cool; all cool when no CTE added + * any time. The rules dbt Power User uses. + */ +export function classifyTiers(marginals: readonly number[]): CteTier[] { + const max = Math.max(0, ...marginals) + if (max === 0) return marginals.map(() => 'cool') + return marginals.map(ms => (ms / max >= 0.5 ? 'hot' : ms / max >= 0.2 ? 'warm' : 'cool')) +} + +/** Marginal times and tiers for the rows timed so far; a row's marginal time is what it adds over the last timed row of its clause. */ +export function withTiers(rows: readonly CteRow[]): CteRow[] { + const previous = new Map() + const marginals = new Map() + rows.forEach((row, i) => { + if (row.status !== 'done' || row.queryMs === undefined) return + marginals.set(i, Math.max(0, row.queryMs - (previous.get(row.clause) ?? 0))) + previous.set(row.clause, row.queryMs) + }) + const timed = [...marginals.keys()] + const tiers = classifyTiers(timed.map(i => marginals.get(i)!)) + return rows.map((row, i) => { + const at = timed.indexOf(i) + return at < 0 ? row : { ...row, marginalMs: marginals.get(i)!, tier: tiers[at] } + }) +} + +/** The rows as the pane shows them: timed ones slowest first, then the rest in source order. */ +export function slowestFirst(rows: readonly CteRow[]): CteRow[] { + const timed = rows.filter(row => row.marginalMs !== undefined) + const rest = rows.filter(row => row.marginalMs === undefined) + return [...timed.sort((a, b) => b.marginalMs! - a.marginalMs!), ...rest] +} + +function ms(value: number | undefined): string { + return value === undefined ? '' : `${Math.round(value).toLocaleString('en-US')} ms` +} + +/** The result as one note for Claude. */ +export function summaryOf(state: CteProfileState): string { + const timed = slowestFirst(state.rows).filter(row => row.marginalMs !== undefined) + const lines = timed.map(row => `- ${row.name} (line ${row.line}): +${ms(row.marginalMs)} (${row.tier}), ${ms(row.queryMs)} in total, ${row.rows ?? 0} rows`) + const failed = state.rows.filter(row => row.status === 'failed').map(row => `- ${row.name} (line ${row.line}): ${row.error ?? 'failed'}`) + const left = state.rows.filter(row => row.status === 'pending').length + return [ + `CTE profile of ${state.model}${state.status === 'stopped' ? ` (stopped, ${left} CTE${left === 1 ? '' : 's'} not timed)` : ''}, slowest first. Each time is the CTE's own part: the count query's wall time minus the one before it.`, + ...lines, + ...(failed.length ? ['Failed:', ...failed] : []), + ].join('\n') +} + +async function setState($: EngineInterface, change: (prev: CteProfileState) => CteProfileState) { + await update($, stateAtom, prev => (prev ? change(prev) : prev)) +} + +async function say($: EngineInterface, message: string) { + await update($, stateAtom, (prev): CteProfileState => ({ model: prev?.model ?? '', status: 'failed', rows: prev?.rows ?? [], message })) +} + +/** A tool this CLI does not have, or still has as the placeholder. */ +function missingTool(text: string): boolean { + return /Unknown tool|not implemented/i.test(text) +} + +async function openPane($: EngineInterface) { + await $.ui.open({ id: PANE, title: PANE_TITLE, ...PANE_SIZE, focus: true, closeOnEscape: true }) +} + +/** The model the command names, else the one last read or edited. */ +function modelFor(argument: string): string | null { + const named = argument.trim() + if (named) return named + return lastModelPath +} + +async function profile($: EngineInterface, model: string) { + const listed = await runTool($, TOOL, { model }, { cliOnly: true }).catch(error => ({ ok: false, text: String(error), metadata: null as any })) + const list = Array.isArray(listed.metadata?.ctes) ? (listed.metadata.ctes as { name: string; line: number; clause: number }[]) : null + if (!listed.ok || !list) { + await say($, missingTool(listed.text) ? NEEDS_NEWER : listed.text || `Could not list the CTEs of ${model}.`) + return + } + if (list.length === 0) { + await update($, stateAtom, (): CteProfileState => ({ model, status: 'done', rows: [], message: `${model} has no CTEs.` })) + return + } + await update($, stateAtom, (): CteProfileState => ({ + model, + status: 'running', + rows: list.map(one => ({ name: one.name, line: one.line, clause: one.clause, status: 'pending' as const })), + })) + + for (let i = 0; i < list.length; i++) { + // Stop ends the run between queries; one already running is waited for. + if ((await read($, stateAtom))?.status === 'stopping') break + await setStatusPart($, 'cteProfile', `profiling CTEs ${i + 1}/${list.length}`) + await setState($, prev => ({ ...prev, rows: prev.rows.map((row, at) => (at === i ? { ...row, status: 'running' as const } : row)) })) + const until = (await $.clock.now()) + QUERY_BUDGET_MS + const timed = await runTool($, TOOL, { model, cte: list[i]!.name }, { write: true, until }).catch(error => ({ ok: false, text: String(error), metadata: null as any })) + const queryMs = timed.ok && typeof timed.metadata?.queryMs === 'number' ? (timed.metadata.queryMs as number) : undefined + await setState($, prev => + ({ + ...prev, + rows: withTiers( + prev.rows.map((row, at) => + at !== i + ? row + : queryMs === undefined + ? { ...row, status: 'failed' as const, error: missingTool(timed.text) ? NEEDS_NEWER : timed.text || 'no answer' } + : { ...row, status: 'done' as const, queryMs, rows: Number(timed.metadata?.rows) || 0 }, + ), + ), + }), + ) + // A refusal that every later CTE would meet too ends the run: no further queries. + if (queryMs === undefined && missingTool(timed.text)) break + } + + const final = await read($, stateAtom) + if (!final) return + const status = final.rows.some(row => row.status === 'pending') ? 'stopped' : final.rows.every(row => row.status === 'failed') ? 'failed' : 'done' + const finished = { ...final, status, rows: final.rows.map(row => (row.status === 'running' ? { ...row, status: 'pending' as const } : row)) } as CteProfileState + await update($, stateAtom, () => finished) + await setStatusPart($, 'cteProfile', null) + if (finished.rows.some(row => row.status === 'done')) { + pendingContext = summaryOf(finished) + const slowest = slowestFirst(finished.rows)[0] + $.ui.toast(`◆ profile-ctes · ${finished.model}: slowest is ${slowest?.name} (+${ms(slowest?.marginalMs)})`, { timeoutMs: 8000 }) + } +} + /** Adds this feature's own hooks. */ -export function register(on: On, context: FeatureContext) {} +export function register(on: On, context: FeatureContext) { + on('command.run', { command: COMMAND }, async ($, e) => { + const model = modelFor(e.args) + const current = await read($, stateAtom) + if (current && (current.status === 'running' || current.status === 'stopping' || current.status === 'listing')) { + await openPane($).catch(() => {}) + return { text: `A CTE profile of ${current.model} is already running; the pane has a Stop button.` } + } + if (!model) return { text: 'Name a model: /profile-ctes , or read or edit one first.' } + await update($, stateAtom, (): CteProfileState => ({ model, status: 'listing', rows: [] })) + try { + await openPane($) + } catch (error) { + return { text: `Could not open Profile CTEs: ${String(error)}` } + } + // The command answers now; the queries go on and the pane fills in. + later($, () => profile($, model)) + return { text: `Profiling the CTEs of ${model}: each one is a warehouse query, the pane shows them as they finish.` } + }) + + on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => { + const { Box, Button, Text } = $.ui.resolve(e) + const state = await read($, stateAtom) + if (!state) return Run /profile-ctes <model> to time a model's CTEs. + const running = state.status === 'running' || state.status === 'listing' + const done = state.rows.filter(row => row.status === 'done' || row.status === 'failed').length + const colour = { hot: 'error', warm: 'warning', cool: 'success' } as const + return ( + + + {state.model} + + {state.status === 'listing' && 'Listing the CTEs…'} + {state.status === 'running' && `Timing CTE ${Math.min(done + 1, state.rows.length)} of ${state.rows.length}…`} + {state.status === 'stopping' && 'Stopping after the running query…'} + {state.status === 'stopped' && `Stopped: ${done} of ${state.rows.length} timed.`} + {state.status === 'done' && state.rows.length > 0 && `${state.rows.length} CTEs timed, slowest first.`} + + + {state.message && {state.message}} + + {slowestFirst(state.rows).map(row => ( + + {row.status === 'running' && '… '} + {row.status === 'failed' && '✗ '} + {row.name} · line {row.line} + {row.marginalMs !== undefined && ` · +${ms(row.marginalMs)} (${row.tier}) · ${ms(row.queryMs)} in total · ${row.rows} rows`} + {row.status === 'failed' && ` · ${row.error}`} + + ))} + + + {running &&