footnotes-widget

1import { atom, read, update } from 'claude-code'
2import type { Elements, EngineInterface, Register, RenderElement, RenderNode, RenderSurface } from 'claude-code'
3import type { WidgetsPlace } from 'widgets'
4
5import { fit, folder, plural } from './lib'
6
7type Tags = Pick<Elements[RenderSurface], 'Box' | 'Text' | 'Button'>
8type Verdict = 'found' | 'missing' | 'short'
9type Unchecked = '' | 'no repository' | 'git failed'
10type Ref = { token: string; name: string; kind: 'path' | 'symbol'; verdict: Verdict; lines: number; isHard: boolean }
11type Last = { refs: Ref[]; unchecked: Unchecked }
12type Cited =
13  | { kind: 'path'; token: string; name: string; path: string; line: number | undefined }
14  | { kind: 'symbol'; token: string; name: string; parts: string[] }
15
16const PANE = 'widgets'
17const CARD_COLUMNS = 40
18const LONG_COLUMNS = 36
19const MAX_REFS = 20
20const MAX_ROWS = 5
21const SLOT = 'footnotes-widget:ask'
22const GIT_MS = 3000
23const USAGE = 'Usage: /footnotes-widget [on|off|show|clear]'
24const OFF = 'Footnotes is off.'
25const UNCHECKED = 'No reply checked yet.'
26const NOTHING = 'Nothing to check in the last reply.'
27const EMPTY = [UNCHECKED, "File and symbol names in Claude's replies are checked here."] as const
28const OPENING = 'Check these references from your last reply against the repository and correct what was wrong:'
29const SPAN = /`([^`]+)`/g
30const PATH = /^([A-Za-z0-9_./\\-]+?)(?::(\d+)(?:([-:])(\d+))?)?$/
31const EXTENSION =
32  /\.(?:ts|tsx|js|jsx|mjs|cjs|json|md|py|rs|go|java|kt|rb|php|c|h|cpp|hpp|cs|swift|css|scss|html|vue|svelte|yml|yaml|toml|sh|sql|txt)$/
33const SYMBOL = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/
34const SHAPED = /[._]|[a-z][A-Z]/
35const LS_FILES = ['git', '--no-optional-locks', 'ls-files', '--cached', '--others', '--exclude-standard'] as const
36const GREP = ['git', '--no-optional-locks', 'grep', '-I', '-w', '-F', '-o', '-h', '--untracked'] as const
37const site = { plugin: 'widgets', key: 'site' } as const
38const widths = { plugin: 'widgets', key: 'widths' } as const
39const isOn = atom({ plugin: 'footnotes-widget', key: 'isOn' } as const, false)
40const last = atom({ plugin: 'footnotes-widget', key: 'last' } as const, null as Last | null)
41
42const cite = (token: string): Cited | undefined => {
43  const [, written = '', first, range, second] = PATH.exec(token) ?? []
44  if (written !== '' && !token.startsWith('-') && EXTENSION.test(written)) {
45    const path = written.replaceAll('\\', '/').replace(/^\.\//, '')
46
47    return {
48      kind: 'path',
49      token,
50      name: `${path.split('/').at(-1)}${token.slice(written.length)}`,
51      path,
52      line: first === undefined ? undefined : Number(range === '-' ? second : first),
53    }
54  }
55
56  const isCall = token.endsWith(')') && token.includes('(')
57  const bare = isCall ? token.slice(0, token.indexOf('(')) : token
58  if (!SYMBOL.test(bare) || bare.length < 3 || !(isCall || SHAPED.test(bare))) return undefined
59
60  const parts = bare.split('.').filter(part => part !== 'this' && part !== 'self')
61
62  return parts.length === 0 ? undefined : { kind: 'symbol', token, name: isCall ? `${bare}()` : bare, parts }
63}
64
65const cited = (answer: string): Cited[] => {
66  const prose: string[] = []
67  let isFenced = false
68  for (const line of answer.split('\n')) {
69    if (line.trim().startsWith('```')) isFenced = !isFenced
70    else if (!isFenced) prose.push(line)
71  }
72  const tokens = prose.flatMap(line => [...line.matchAll(SPAN)].map(found => (found[1] ?? '').trim()))
73
74  return [...new Set(tokens)].flatMap(token => cite(token) ?? []).slice(0, MAX_REFS)
75}
76
77const wrapped = (sentence: string, columns: number): string[] =>
78  sentence.split(' ').reduce<string[]>((rows, word) => {
79    const held = rows.at(-1)
80
81    return held !== undefined && held.length + 1 + word.length <= columns ? [...rows.slice(0, -1), `${held} ${word}`] : [...rows, word]
82  }, [])
83
84const counted = (text: string): number => (text === '' ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0))
85
86const failed = (refs: readonly Ref[]): Ref[] => refs.filter(ref => ref.verdict !== 'found')
87
88const reason = ({ kind, verdict, lines }: Ref, isFull: boolean): string => {
89  if (verdict === 'short') return `file has ${plural(lines, 'line')}`
90  if (kind === 'path') return 'not on disk'
91
92  return isFull ? 'not found in this repository' : 'not in this repo'
93}
94
95const check = async ($: EngineInterface, answer: string): Promise<Last> => {
96  const named = cited(answer)
97  const cwd = await $.session.cwd()
98  const repo = await $.session.repo()
99  const counts = new Map<string, number>()
100  const parts = [...new Set(named.flatMap(ref => (ref.kind === 'symbol' ? ref.parts : [])))]
101  const refs: Ref[] = []
102  let entries: string[] | undefined
103  let isListed = false
104  let occurring = new Set<string>()
105  let unchecked: Unchecked = ''
106
107  if (parts.length > 0 && repo === null) unchecked = 'no repository'
108  if (parts.length > 0 && repo !== null) {
109    try {
110      const ran = await $.process.run([...GREP, ...parts.flatMap(part => ['-e', part])], { cwd: repo.root, timeoutMs: GIT_MS })
111      if (ran.isStdoutTruncated || (ran.exitCode !== 0 && ran.exitCode !== 1)) unchecked = 'git failed'
112      else if (ran.exitCode === 0) occurring = new Set(ran.stdout.split('\n').map(line => line.trim()))
113    } catch {
114      unchecked = 'git failed'
115    }
116  }
117
118  for (const ref of named) {
119    const { token, name } = ref
120    if (ref.kind === 'symbol') {
121      if (unchecked === '') {
122        const verdict = ref.parts.some(part => occurring.has(part)) ? 'found' : 'missing'
123        refs.push({ token, name, kind: 'symbol', verdict, lines: 0, isHard: false })
124      }
125      continue
126    }
127
128    const { path, line } = ref
129    let file: string | undefined
130    if (path.startsWith('/')) {
131      if (await $.fs.exists(path)) file = path
132    } else if (await $.fs.exists(`${cwd}/${path}`)) file = `${cwd}/${path}`
133    else if (path.split('/').includes('..') || repo === null) file = undefined
134    else if (folder(repo.root) !== folder(cwd) && (await $.fs.exists(`${repo.root}/${path}`))) file = `${repo.root}/${path}`
135    else {
136      if (!isListed) {
137        isListed = true
138        try {
139          const ran = await $.process.run(LS_FILES, { cwd: repo.root, timeoutMs: GIT_MS })
140          if (ran.exitCode === 0 && !ran.isStdoutTruncated) entries = ran.stdout.split('\n').map(row => row.replace(/\r$/, ''))
141        } catch {
142          continue
143        }
144      }
145      if (entries === undefined) continue
146
147      const matches = entries.filter(entry => entry === path || entry.endsWith(`/${path}`))
148      if (matches.length === 1) file = `${repo.root}/${matches[0]}`
149      else if (matches.length === 0 && (path.includes('/') || line !== undefined)) {
150        refs.push({ token, name, kind: 'path', verdict: 'missing', lines: 0, isHard: line !== undefined })
151      }
152    }
153    if (file === undefined) continue
154
155    let lines = line === undefined ? Number.POSITIVE_INFINITY : counts.get(folder(file))
156    if (lines === undefined) {
157      try {
158        lines = counted(await $.fs.read(file))
159      } catch {
160        lines = Number.POSITIVE_INFINITY
161      }
162      counts.set(folder(file), lines)
163    }
164    const isShort = line !== undefined && line > lines
165    refs.push({ token, name, kind: 'path', verdict: isShort ? 'short' : 'found', lines: isShort ? lines : 0, isHard: isShort })
166  }
167
168  return { refs, unchecked }
169}
170
171const seat = (node: RenderNode, button: RenderElement): RenderNode => {
172  if (typeof node !== 'object') return node
173  const { props, children } = node as { props?: { key?: unknown }; children?: RenderNode[] }
174  if (props?.key === SLOT) return button
175
176  return children === undefined ? node : ({ ...node, children: children.map(child => seat(child, button)) } as RenderElement)
177}
178
179const ask = async ($: EngineInterface): Promise<void> => {
180  const failures = failed((await read($, last))?.refs ?? [])
181  if (failures.length === 0) return
182
183  try {
184    await $.prompt.fill({ text: [OPENING, ...failures.map(ref => `- ${ref.token}: ${reason(ref, true)}`)].join('\n'), mode: 'append' })
185  } catch {
186    return
187  }
188}
189
190const show = async (
191  $: EngineInterface,
192  { Box, Text, Button }: Tags,
193  beneath: RenderElement,
194  place: WidgetsPlace,
195  columns: number,
196): Promise<RenderElement> => {
197  if (!(await read($, isOn))) return beneath
198  if ((await $.state.get(site)).value !== place) return beneath
199
200  const width = fit((await $.state.get(widths)).value?.['footnotes-widget'] ?? CARD_COLUMNS, columns)
201  const inner = width - 4
202  const isLong = inner >= LONG_COLUMNS
203  const held = await read($, last)
204  const refs = held?.refs ?? []
205  const failures = failed(refs)
206  const found = refs.length - failures.length
207  const rows = failures.slice(0, MAX_ROWS).map(ref => {
208    const why = reason(ref, false)
209    const room = inner - 4 - why.length
210
211    return { ref, text: !isLong ? ref.name : `${ref.name.length > room ? `${ref.name.slice(0, Math.max(0, room - 1))}…` : ref.name}: ${why}` }
212  })
213
214  const card = await $.widgets.card({
215    beneath,
216    width,
217    title: 'Footnotes',
218    note: refs.length === 0 ? '' : isLong ? `${found}/${refs.length} found` : `${found}/${refs.length}`,
219    body: (
220      <Box flexDirection="column">
221        {(held === null ? EMPTY : refs.length === 0 ? [NOTHING] : [])
222          .flatMap(sentence => wrapped(sentence, inner))
223          .map(row => (
224            <Text dimColor>{row}</Text>
225          ))}
226        {refs.length > 0 && failures.length === 0 && (
227          <Text key="all" wrap="truncate-end">
228            <Text color="green">✓</Text> {isLong ? `${refs.length} named, ${found} found` : 'all found'}
229          </Text>
230        )}
231        {rows.map(({ ref, text }, at) => (
232          <Text key={`row-${at + 1}`} wrap="truncate-end">
233            <Text color={ref.isHard ? 'red' : 'yellow'}>{ref.isHard ? '✗' : '?'}</Text> {text}
234          </Text>
235        ))}
236        {failures.length > MAX_ROWS && (
237          <Text key="more" dimColor wrap="truncate-end">
238            {`+${failures.length - MAX_ROWS} more`}
239          </Text>
240        )}
241        {failures.length > 0 && <Box key={SLOT} />}
242        {held !== null && held.unchecked !== '' && (
243          <Text key="unchecked" dimColor wrap="truncate-end">
244            {isLong ? `Symbols not checked: ${held.unchecked}` : 'No symbol check'}
245          </Text>
246        )}
247      </Box>
248    ),
249  })
250  if (failures.length === 0) return card
251
252  return seat(card, <Button key="ask" label={isLong ? 'Ask Claude to check these' : 'Ask Claude'} onPress={() => ask($)} />) as RenderElement
253}
254
255export const register: Register = on => {
256  on('session.start', async ($, e, next) => {
257    await $.command.register({
258      name: 'footnotes-widget',
259      description: "Toggle the check of file and symbol names in Claude's replies",
260      argumentHint: '[on|off|show|clear]',
261    })
262    if ((await $.store.get('isOn')) === true) await update($, isOn, () => true)
263
264    return next(e)
265  })
266
267  on('command.run', { command: 'footnotes-widget' }, async ($, e) => {
268    const arg = e.args.trim().toLowerCase()
269
270    if (arg === 'show' || arg === 'clear') {
271      if (!(await read($, isOn))) return { text: OFF }
272
273      if (arg === 'clear') {
274        await update($, last, () => null)
275
276        return { text: 'Footnotes cleared.' }
277      }
278
279      const held = await read($, last)
280      if (held === null) return { text: UNCHECKED }
281
282      const { refs, unchecked } = held
283      const skipped = unchecked === '' ? [] : [`Symbols not checked: ${unchecked}`]
284      if (refs.length === 0) return { text: [NOTHING, ...skipped].join('\n') }
285
286      return {
287        text: [
288          `${refs.length} named, ${refs.length - failed(refs).length} found:`,
289          ...refs.map(ref => (ref.verdict === 'found' ? `✓ ${ref.token}` : `${ref.isHard ? '✗' : '?'} ${ref.token}: ${reason(ref, true)}`)),
290          ...skipped,
291        ].join('\n'),
292      }
293    }
294    if (arg !== '' && arg !== 'on' && arg !== 'off') return { text: USAGE }
295
296    const isShown = await update($, isOn, shown => (arg === '' ? !(shown ?? false) : arg === 'on'))
297    await $.store.set('isOn', isShown)
298
299    return { text: isShown ? 'Footnotes on; /widgets places it.' : 'Footnotes off.' }
300  })
301
302  on('turn.complete', async ($, e, next) => {
303    const ended = await next(e)
304    if (!(await read($, isOn)) || e.agentId !== undefined || e.isAborted || e.reason !== 'answer' || e.answer.trim() === '') return ended
305
306    try {
307      const checked = await check($, e.answer)
308      await update($, last, () => checked)
309    } catch {
310      return ended
311    }
312
313    return ended
314  })
315
316  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e, next) =>
317    show($, $.ui.resolve(e), await next(e), 'side', e.props.bodyColumns),
318  )
319
320  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) =>
321    e.props.hasSurvey ? next(e) : show($, $.ui.resolve(e), await next(e), 'above', e.props.bodyColumns),
322  )
323
324  on('ui.render', { component: 'PromptHint' }, async ($, e, next) =>
325    show($, $.ui.resolve(e), await next(e), 'below', e.viewport?.columns ?? 80),
326  )
327}
328

1const MIN_CARD = 20
2const BARS = '▁▂▃▄▅▆▇█'
3
4export const fit = (wanted: number, columns: number): number => Math.min(wanted, Math.max(MIN_CARD, columns))
5
6export const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? '' : 's'}`
7
8export const span = (ms: number): string => {
9  const seconds = Math.max(0, Math.round(ms / 1000))
10  if (seconds < 60) return `${seconds}s`
11  const minutes = Math.floor(seconds / 60)
12  if (minutes < 60) return `${minutes}m ${String(seconds % 60).padStart(2, '0')}s`
13  const hours = Math.floor(minutes / 60)
14  if (hours < 24) return `${hours}h ${String(minutes % 60).padStart(2, '0')}m`
15
16  return `${Math.floor(hours / 24)}d ${hours % 24}h`
17}
18
19export const spark = (values: readonly number[], width: number): string => {
20  const shown = width > 0 ? values.slice(-width) : []
21  const top = Math.max(...shown, 0)
22
23  return shown
24    .map(value => (top <= 0 ? BARS[0] : BARS[Math.min(BARS.length - 1, Math.round((Math.max(0, value) / top) * (BARS.length - 1)))]))
25    .join('')
26}
27
28export const hash = (text: string): number => {
29  let held = 2166136261
30  for (const letter of text) held = Math.imul(held ^ (letter.codePointAt(0) ?? 0), 16777619)
31
32  return held >>> 0
33}
34
35export const shade = (color: number, factor: number): number =>
36  (Math.round((color >> 16) * factor) << 16) |
37  (Math.round(((color >> 8) & 255) * factor) << 8) |
38  Math.round((color & 255) * factor)
39
40export const folder = (path: string): string => {
41  const flat = path.replaceAll('\\', '/').replace(/\/+$/, '')
42
43  return /^[a-z]:/i.test(flat) ? flat.toLowerCase() : flat
44}
45

1export type FootnotesSwitch = boolean
2
3declare module 'claude-code' {
4  interface PluginState {
5    'footnotes-widget': {
6      isOn: FootnotesSwitch
7      last:
8        | {
9            refs: { token: string; name: string; kind: 'path' | 'symbol'; verdict: 'found' | 'missing' | 'short'; lines: number; isHard: boolean }[]
10            unchecked: '' | 'no repository' | 'git failed'
11          }
12        | null
13    }
14  }
15}
16