lint-test-gate

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Failure, GateState } from '../types'
5import {
6  duration,
7  failureReport,
8  isGitCommit,
9  label,
10  NEEDS_NODE,
11  NOTHING_TO_RUN,
12  npmCliBeside,
13  parseConfig,
14  refusal,
15  scriptNames,
16  tail,
17} from './gate'
18import type { Check, Config } from './gate'
19
20const gate = atom({ plugin: 'lint-test-gate', key: 'gate' } as const, { kind: 'idle' } as GateState)
21
22/**
23 * Whether any surface shows the session right now. Asked before each run the
24 * mod starts and never kept. Each mod carries its own copy (ADR-0001).
25 */
26async function isShown($: EngineInterface): Promise<boolean> {
27  return (await $.session.surfaces()).length > 0
28}
29
30function report($: EngineInterface): (error: unknown) => void {
31  return error => $.ui.toast(`lint-test-gate: ${message(error)}`)
32}
33
34function message(error: unknown): string {
35  return error instanceof Error ? error.message : String(error)
36}
37
38/**
39 * How to start npm, by bare name as every program is started. On Windows npm
40 * is a .cmd shim, which a start without a shell cannot run, so npm's own CLI
41 * script runs under node instead, with no cmd.exe in the argument vector.
42 */
43async function npmArgv($: EngineInterface): Promise<{ argv: string[] } | { problem: string }> {
44  if ((await $.env.get('OS')) !== 'Windows_NT') return { argv: ['npm'] }
45  const node = await $.process.run(['node', '-p', 'process.execPath']).catch(() => undefined)
46  if (node === undefined || node.exitCode !== 0) return { problem: NEEDS_NODE }
47  const cli = npmCliBeside(node.stdout.trim())
48  if (!(await $.fs.exists(cli).catch(() => false))) {
49    return { problem: `lint-test-gate cannot find npm's own CLI script at ${cli}, beside node. List the checks in the setting instead.` }
50  }
51  return { argv: ['node', cli] }
52}
53
54/** The setting's checks, else the package.json scripts; or why there is nothing to run. */
55async function findChecks($: EngineInterface, config: Config, root: string): Promise<Check[] | string> {
56  if (config.problem !== undefined) return config.problem
57  if (config.argvs.length > 0) return config.argvs.map(argv => ({ name: argv.join(' '), argv }))
58  const packageJson = await $.fs.read(`${root}/package.json`).catch(() => '')
59  const scripts = scriptNames(packageJson)
60  if (scripts.length === 0) return NOTHING_TO_RUN
61  const npm = await npmArgv($)
62  return scripts.map(name => ('problem' in npm ? { name, problem: npm.problem } : { name, argv: [...npm.argv, 'run', name] }))
63}
64
65/** Runs one check in the project folder; undefined when it passed. */
66async function runCheck($: EngineInterface, check: Check, root: string, timeoutMs: number): Promise<Failure | undefined> {
67  if ('problem' in check) return { name: check.name, why: `could not start: ${check.problem}`, tail: '' }
68  const startedAt = await $.clock.now()
69  try {
70    const result = await $.process.run(check.argv, { cwd: root, timeoutMs })
71    if (result.exitCode === 0) return undefined
72    return { name: check.name, why: `exit ${result.exitCode}`, tail: tail([result.stdout, result.stderr].join('\n')) }
73  } catch (error) {
74    // A start that fails rejects at once; a run past its limit rejects at the limit, with what it wrote lost.
75    if ((await $.clock.now()) - startedAt >= timeoutMs) return { name: check.name, why: `timed out after ${duration(timeoutMs)}`, tail: '' }
76    return { name: check.name, why: `could not start: ${message(error)}`, tail: '' }
77  }
78}
79
80async function outcome($: EngineInterface, config: Config): Promise<GateState> {
81  const root = await $.session.root()
82  const checks = await findChecks($, config, root)
83  if (typeof checks === 'string') return { kind: 'empty', why: checks }
84  const failures: Failure[] = []
85  for (const check of checks) {
86    const failure = await runCheck($, check, root, config.timeoutMs)
87    if (failure !== undefined) failures.push(failure)
88  }
89  return failures.length === 0 ? { kind: 'passed' } : { kind: 'failed', failures }
90}
91
92// One run at a time: two runs of the same scripts in one folder would trip over each other.
93let queue: Promise<unknown> = Promise.resolve()
94
95/** Runs the checks after any run under way, showing the state on the band. */
96function runGate($: EngineInterface, config: Config): Promise<GateState> {
97  const run = queue.then(async () => {
98    await update($, gate, () => ({ kind: 'running' }))
99    const state = await outcome($, config).catch(async (error: unknown) => {
100      await update($, gate, () => ({ kind: 'idle' }))
101      throw error
102    })
103    await update($, gate, () => state)
104    return state
105  })
106  queue = run.catch(() => undefined)
107  return run
108}
109
110async function press($: EngineInterface, config: Config): Promise<void> {
111  if ((await read($, gate)).kind === 'running') return
112  const state = await runGate($, config)
113  if (state.kind === 'empty') $.ui.toast(state.why)
114}
115
116async function fill($: EngineInterface, failures: readonly Failure[]): Promise<void> {
117  // Nothing is sent: the failures join the draft, after what the person typed, and the person sends it.
118  const draft = (await $.prompt.read()).text
119  const text = draft === '' ? failureReport(failures) : `\n\n${failureReport(failures)}`
120  const filled = await $.prompt.fill({ text, mode: 'append' })
121  if (!filled.isFilled) $.ui.toast('lint-test-gate: the prompt box could not take the failures.')
122}
123
124export const register: Register = (on, options) => {
125  const config = parseConfig(options)
126
127  on('session.start', async ($, e, next) => {
128    const started = await next(e)
129    if (config.problem !== undefined && (await isShown($))) $.ui.toast(config.problem)
130    return started
131  })
132
133  // Matched by pattern: which shell tools a session has depends on the machine.
134  on('tool.call', { tool: /^(Bash|PowerShell)$/ }, async ($, e, next) => {
135    const command = 'command' in e && typeof e.command === 'string' ? e.command : ''
136    if (!isGitCommit(command) || !(await isShown($))) return next(e)
137    const state = await runGate($, config)
138    return state.kind === 'failed' ? { deny: refusal(state.failures) } : next(e)
139  })
140
141  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
142    // Whatever is beneath (another mod's band, the engine's own) keeps its row under the gate.
143    const beneath = await next(e)
144    if (e.props.hasSurvey || e.props.view.agentId !== undefined) return beneath
145    const state = await read($, gate)
146    const { Box, Button } = $.ui.resolve(e)
147
148    // The outer Box takes no width: the engine refuses its own band under a Box that sets one.
149    return (
150      <Box flexDirection="column">
151        <Box flexDirection="row" columnGap={1} width={e.props.bodyColumns}>
152          <Button
153            key="gate"
154            label={label(state)}
155            variant={state.kind === 'failed' ? 'primary' : 'secondary'}
156            onPress={() => void press($, config).catch(report($))}
157          />
158          {state.kind === 'failed' && (
159            <Button key="fill" label="fill failures" onPress={() => void fill($, state.failures).catch(report($))} />
160          )}
161        </Box>
162        {beneath}
163      </Box>
164    )
165  })
166}
167

1import type { Failure, GateState } from '../types'
2
3/** The package.json scripts run when the setting lists no checks, in this order. */
4export const SCRIPT_NAMES = ['lint', 'typecheck', 'check', 'test'] as const
5
6/** `$.process.run`'s longest time limit, and the default. */
7const MAX_TIMEOUT_MINUTES = 10
8
9/** A failing check's output is cut to its last TAIL_LINES lines, and to at most TAIL_CHARS characters of them. */
10export const TAIL_LINES = 40
11export const TAIL_CHARS = 4000
12
13export type Config = {
14  /** The checks the setting lists, each an argument vector; empty runs the package.json scripts. */
15  argvs: string[][]
16  timeoutMs: number
17  /** Why the checks setting was refused; the gate then has nothing to run. */
18  problem: string | undefined
19}
20
21/** One check to run: its argument vector, or why it cannot start. */
22export type Check = { name: string; argv: string[] } | { name: string; problem: string }
23
24const EXAMPLE = '[["npx","eslint","."],["pytest","-q"]]'
25
26function isArgv(value: unknown): value is string[] {
27  return Array.isArray(value) && value.length > 0 && value.every(arg => typeof arg === 'string' && arg !== '' && !/\p{Cc}/u.test(arg))
28}
29
30/** Parses the checks setting: a JSON list of argument lists, never a shell string. */
31function parseChecks(setting: unknown): { argvs: string[][] } | { problem: string } {
32  if (typeof setting !== 'string' || setting.trim() === '') return { argvs: [] }
33  let parsed: unknown
34  try {
35    parsed = JSON.parse(setting)
36  } catch {
37    return { problem: `lint-test-gate: the checks setting is not JSON. Write a list of commands, each a list of its arguments, such as ${EXAMPLE}.` }
38  }
39  if (!Array.isArray(parsed)) {
40    return { problem: `lint-test-gate: the checks setting is not a list. Write a list of commands, each a list of its arguments, such as ${EXAMPLE}.` }
41  }
42  const bad = parsed.findIndex(argv => !isArgv(argv))
43  if (bad >= 0) {
44    return {
45      problem: `lint-test-gate: check ${bad + 1} of the checks setting is not a list of non-empty strings. Write each command as a list of its arguments, such as ${EXAMPLE}.`,
46    }
47  }
48  return { argvs: parsed as string[][] }
49}
50
51/** Parses the manifest's userConfig values; a time limit out of range falls back to ten minutes. */
52export function parseConfig(options: Readonly<Record<string, unknown>>): Config {
53  const minutes = options.timeoutMinutes
54  const timeoutMinutes =
55    typeof minutes === 'number' && Number.isInteger(minutes) && minutes >= 1 && minutes <= MAX_TIMEOUT_MINUTES ? minutes : MAX_TIMEOUT_MINUTES
56  const checks = parseChecks(options.checks)
57  return {
58    argvs: 'argvs' in checks ? checks.argvs : [],
59    timeoutMs: timeoutMinutes * 60_000,
60    problem: 'problem' in checks ? checks.problem : undefined,
61  }
62}
63
64/** The scripts of SCRIPT_NAMES that package.json defines, in that order; none for a file that is not JSON. */
65export function scriptNames(packageJson: string): string[] {
66  let parsed: unknown
67  try {
68    parsed = JSON.parse(packageJson)
69  } catch {
70    return []
71  }
72  const scripts = typeof parsed === 'object' && parsed !== null ? (parsed as { scripts?: unknown }).scripts : undefined
73  if (typeof scripts !== 'object' || scripts === null) return []
74  return SCRIPT_NAMES.filter(name => typeof (scripts as Record<string, unknown>)[name] === 'string')
75}
76
77/** npm's own CLI script in a Windows Node.js install: `node_modules\npm\bin\npm-cli.js` beside node.exe. */
78export function npmCliBeside(nodePath: string): string {
79  const sep = nodePath.includes('\\') ? '\\' : '/'
80  const folder = nodePath.replace(/[\\/][^\\/]*$/, '')
81  return [folder, 'node_modules', 'npm', 'bin', 'npm-cli.js'].join(sep)
82}
83
84/**
85 * Whether a shell command runs `git commit`: `git`, any global options
86 * (`-C <path>`, `-c <name>=<value>`, `--flag`), then `commit` as the
87 * subcommand. Found by pattern, so a `git commit` inside a quoted string counts too.
88 */
89export function isGitCommit(command: string): boolean {
90  return /(?<![\w./\\-])git(?:\.exe)?(?:\s+(?:-[Cc]\s+(?:"[^"]*"|'[^']*'|\S+)|--?[\w-]+(?:=\S+)?))*\s+commit(?![\w-])/.test(command)
91}
92
93/** Colour and cursor sequences a check may print; a prompt shows them as junk. */
94// eslint-disable-next-line no-control-regex -- the escape character is what the pattern matches
95const ANSI = /\u001b\[[0-9;?]*[A-Za-z]/g
96
97/** The end of a check's output: its last TAIL_LINES lines, then at most TAIL_CHARS characters, starting at a line. */
98export function tail(output: string): string {
99  const lines = output.replace(ANSI, '').replace(/\r\n?/g, '\n').trimEnd().split('\n')
100  const kept = lines.slice(-TAIL_LINES).join('\n').replace(/^\n+/, '')
101  if (kept.length <= TAIL_CHARS) return kept
102  const cut = kept.slice(-TAIL_CHARS)
103  const start = cut.indexOf('\n')
104  return start < 0 ? cut : cut.slice(start + 1)
105}
106
107/** A time limit as a person reads it. */
108export function duration(ms: number): string {
109  return `${ms / 60_000} min`
110}
111
112/** The failures, each by name and why, with the end of its output: what the fill button and a refused commit hand over. */
113export function failureReport(failures: readonly Failure[]): string {
114  const count = failures.length === 1 ? '1 check failed' : `${failures.length} checks failed`
115  const sections = failures.map(failure =>
116    failure.tail === '' ? `${failure.name} (${failure.why})` : `${failure.name} (${failure.why}):\n\`\`\`\n${failure.tail}\n\`\`\``,
117  )
118  return [`${count}:`, ...sections].join('\n\n')
119}
120
121/** Why a model's commit is refused. */
122export function refusal(failures: readonly Failure[]): string {
123  return `lint-test-gate refused the commit: ${failureReport(failures)}\n\nFix the failures, then commit again.`
124}
125
126/** The gate button's label. */
127export function label(state: GateState): string {
128  switch (state.kind) {
129    case 'idle':
130      return 'gate'
131    case 'running':
132      return 'gate: running'
133    case 'passed':
134      return 'gate: passed'
135    case 'failed':
136      return `gate: ${state.failures.length} failing`
137    case 'empty':
138      return 'gate: nothing to run'
139  }
140}
141
142/** What the person sees when nothing is set and package.json has none of SCRIPT_NAMES. */
143export const NOTHING_TO_RUN = `lint-test-gate: nothing to run. The checks setting is empty, and package.json has no ${SCRIPT_NAMES.join(', ')} script.`
144
145/** What a script check says when node cannot start, on Windows, where npm runs through it. */
146export const NEEDS_NODE = 'lint-test-gate runs npm scripts on Windows through node, which did not start. Put node on the PATH, or list the checks in the setting.'
147

1/** One check that did not pass: its name, why (an exit code, a timeout, a start that failed) and the end of its output. */
2export type Failure = { name: string; why: string; tail: string }
3
4/** Where the gate stands: what its band button shows. */
5export type GateState =
6  | { kind: 'idle' }
7  | { kind: 'running' }
8  | { kind: 'passed' }
9  | { kind: 'failed'; failures: Failure[] }
10  /** There was nothing to run; `why` says what the mod looked for, or why the setting was refused. */
11  | { kind: 'empty'; why: string }
12
13declare module 'claude-code' {
14  interface PluginState {
15    'lint-test-gate': { gate: GateState }
16  }
17}
18