review-ledger

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { ReviewItem } from '../types'
5
6// A per-repo ledger of review findings (H1, M3, L2...) that survives /clear.
7// Claude writes to it through a tool; merged PRs tick items off; a pane and
8// /review show it; prompts that name an item get the ledger as context.
9
10const items = atom({ plugin: 'review-ledger', key: 'items' } as const, [])
11
12const PANE = 'review-ledger'
13const TOOL = 'items'
14const TOOL_ID = `mcp__review-ledger__${TOOL}`
15const POLL_MS = 5 * 60_000
16const ITEM_REF = /\b[HMLhml]\d{1,2}\b/
17const ORDER = { H: 0, M: 1, L: 2 } as Record<string, number>
18
19let repoKey = ''
20
21async function repoRoot($: EngineInterface): Promise<string> {
22  const r = await $.process.run(['git', 'rev-parse', '--show-toplevel']).catch(() => undefined)
23  return r?.exitCode === 0 ? r.stdout.trim() : await $.session.cwd()
24}
25
26async function save($: EngineInterface, list: ReviewItem[]) {
27  const sorted = [...list].sort(
28    (a, b) => (ORDER[a.id[0]?.toUpperCase() ?? ''] ?? 9) - (ORDER[b.id[0]?.toUpperCase() ?? ''] ?? 9)
29      || Number(a.id.slice(1)) - Number(b.id.slice(1)),
30  )
31  await update($, items, () => sorted)
32  await $.store.set(repoKey, sorted)
33}
34
35function summary(list: ReviewItem[], only?: Set<string>): string {
36  const rows = list
37    .filter(i => !only || only.has(i.id) || i.status === 'open' || i.status === 'in-progress')
38    .map(i => `- ${i.id} [${i.status}${i.pr ? ` #${i.pr}` : ''}] ${i.title}${i.note ? ` (${i.note})` : ''}`)
39  const done = list.filter(i => i.status === 'done').length
40  const wont = list.filter(i => i.status === 'wontdo').length
41  return `[review-ledger] Review items for this repo (${done} done, ${wont} won't do, ${list.length - done - wont} left):\n${rows.join('\n')}\n` +
42    `Update it with the ${TOOL_ID} tool as items change.`
43}
44
45async function checkMerged($: EngineInterface) {
46  const list = await read($, items)
47  const waiting = list.filter(i => i.status === 'in-progress' && i.pr > 0)
48  if (waiting.length === 0) return
49  let changed = false
50  const next = [...list]
51  for (const item of waiting) {
52    const r = await $.process.run(['gh', 'pr', 'view', String(item.pr), '--json', 'state']).catch(() => undefined)
53    if (!r || r.exitCode !== 0) continue
54    const state = (JSON.parse(r.stdout) as { state: string }).state
55    if (state === 'MERGED') {
56      const at = next.findIndex(i => i.id === item.id)
57      next[at] = { ...item, status: 'done' }
58      changed = true
59      $.ui.toast(`${item.id} done: #${item.pr} merged`)
60    }
61  }
62  if (changed) await save($, next)
63}
64
65export const register: Register = on => {
66  on('session.start', async ($, e, next) => {
67    repoKey = `ledger:${await repoRoot($)}`
68    const saved = ((await $.store.get(repoKey)) as ReviewItem[] | undefined) ?? []
69    await update($, items, () => saved)
70
71    await $.command.register({
72      name: 'review',
73      description: 'Open the review-items pane for this repo',
74      argumentHint: '[list]',
75    })
76    await $.tool.register({
77      name: TOOL,
78      description:
79        'The persistent ledger of code/security review findings for this repo (ids like H1, M3, L2 by severity). ' +
80        'Call it with action "upsert" to record findings when you finish a review, and whenever an item\'s state ' +
81        'changes: "in-progress" with the PR number once a fix PR is open (it is marked done automatically when that PR merges), ' +
82        '"wontdo" with a note when the user declines one, "done" when fixed without a PR. Action "list" returns the ledger.',
83      inputSchema: {
84        type: 'object',
85        properties: {
86          action: { type: 'string', enum: ['list', 'upsert', 'remove'] },
87          items: {
88            type: 'array',
89            items: {
90              type: 'object',
91              properties: {
92                id: { type: 'string', description: 'Severity letter and number, e.g. H4' },
93                title: { type: 'string' },
94                status: { type: 'string', enum: ['open', 'in-progress', 'done', 'wontdo'] },
95                pr: { type: 'number' },
96                note: { type: 'string' },
97              },
98              required: ['id'],
99            },
100          },
101        },
102        required: ['action'],
103      },
104    })
105    $.clock.every(POLL_MS, () => void checkMerged($))
106    void checkMerged($)
107
108    return next(e)
109  })
110
111  on('tool.call', { tool: /^mcp__review-ledger__items$/ }, async ($, e) => {
112    const input = e as unknown as { action: string; items?: Partial<ReviewItem>[] }
113    const list = await read($, items)
114
115    if (input.action === 'upsert' || input.action === 'remove') {
116      const byId = new Map(list.map(i => [i.id, i]))
117      for (const raw of input.items ?? []) {
118        const id = String(raw.id ?? '').toUpperCase()
119        if (!id) continue
120        if (input.action === 'remove') {
121          byId.delete(id)
122          continue
123        }
124        const old = byId.get(id)
125        byId.set(id, {
126          id,
127          title: raw.title ?? old?.title ?? '',
128          status: raw.status ?? old?.status ?? 'open',
129          pr: raw.pr ?? old?.pr ?? 0,
130          note: raw.note ?? old?.note ?? '',
131        })
132      }
133      await save($, [...byId.values()])
134    }
135
136    return { result: summary(await read($, items)) }
137  })
138
139  on('command.run', { command: 'review' }, async ($, e) => {
140    const list = await read($, items)
141    if (e.args.trim() === 'list') return { text: list.length ? summary(list) : 'No review items for this repo yet.' }
142    await $.ui.open({ id: PANE, title: 'Review items' })
143    return { text: `${list.length} review item(s) for this repo.` }
144  })
145
146  on('prompt.submit', async ($, e, next) => {
147    const list = await read($, items)
148    if (list.length === 0 || e.origin.kind !== 'composer') return next(e)
149    const named = new Set([...e.text.matchAll(new RegExp(ITEM_REF, 'g'))].map(m => m[0].toUpperCase()))
150    if (named.size === 0 && !/\breview\b/i.test(e.text)) return next(e)
151    return next({ ...e, context: [...(e.context ?? []), summary(list, named)] })
152  })
153
154  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
155    const { Box, Text } = $.ui.resolve(e)
156    const list = await read($, items)
157    const mark = { open: '○', 'in-progress': '◐', done: '●', wontdo: '–' } as const
158    const color = { open: 'yellow', 'in-progress': 'cyan', done: 'green', wontdo: 'gray' } as const
159    const left = list.filter(i => i.status === 'open' || i.status === 'in-progress').length
160
161    return (
162      <Box flexDirection="column">
163        {list.length === 0 && <Text dimColor>No review items yet. Ask Claude for a review.</Text>}
164        {list.length > 0 && <Text bold>{left} left of {list.length}</Text>}
165        {list.map(i => (
166          <Box key={i.id}>
167            <Text color={color[i.status]}>{mark[i.status]} </Text>
168            <Text bold>{i.id.padEnd(4)}</Text>
169            <Text dimColor={i.status === 'done' || i.status === 'wontdo'} wrap="truncate">
170              {i.title}
171              {i.pr ? ` #${i.pr}` : ''}
172            </Text>
173          </Box>
174        ))}
175      </Box>
176    )
177  })
178}
179

1export type ReviewItem = {
2  id: string
3  title: string
4  status: 'open' | 'in-progress' | 'done' | 'wontdo'
5  pr: number
6  note: string
7}
8
9declare module 'claude-code' {
10  interface PluginState {
11    'review-ledger': {
12      items: ReviewItem[]
13    }
14  }
15}
16