pre-pr-claims-check

1import type { EngineInterface, Register } from 'claude-code'
2
3import { findingsInDiff, findingsInText, refusal } from './claims'
4import type { Finding } from './claims'
5import { prCalls } from './command'
6import type { Body, PrCall } from './command'
7
8/** More context than any Markdown file has lines, so each changed file comes whole and fences can be followed. */
9const WHOLE_FILE = 1_000_000
10
11function logQuietly($: EngineInterface, what: string, error: unknown): void {
12  $.ui.log(`pre-pr-claims-check: ${what}: ${error instanceof Error ? error.message : String(error)}`, { to: 'debug' })
13}
14
15/** Runs a command that must succeed and answers its output. */
16async function output($: EngineInterface, argv: readonly string[]): Promise<string> {
17  const result = await $.process.run(argv)
18  if (result.exitCode !== 0) throw new Error(`${argv.slice(0, 3).join(' ')} failed: ${result.stderr.trim() || `exit ${result.exitCode}`}`)
19  return result.stdout
20}
21
22async function defaultBranch($: EngineInterface): Promise<string> {
23  return (await output($, ['gh', 'repo', 'view', '--json', 'defaultBranchRef', '--jq', '.defaultBranchRef.name'])).trim()
24}
25
26/** The findings on the lines the branch adds to Markdown files since it left `base`. */
27async function findingsOnBranch($: EngineInterface, base: string): Promise<Finding[]> {
28  const diff = await output($, [
29    'git',
30    'diff',
31    '--no-color',
32    '--no-ext-diff',
33    '--no-prefix',
34    '--find-renames',
35    `--unified=${WHOLE_FILE}`,
36    `origin/${base}...HEAD`,
37    '--',
38    ':(icase)*.md',
39    ':(icase)*.markdown',
40  ])
41  return findingsInDiff(diff)
42}
43
44async function findingsInBody($: EngineInterface, body: Body | undefined): Promise<Finding[]> {
45  if (body === undefined) return []
46  if ('text' in body) return findingsInText(body.text, 'PR body')
47  let text: string
48  try {
49    text = await $.fs.read(body.file)
50  } catch (error) {
51    // A file that cannot be read is gh's to report when the command runs.
52    logQuietly($, `reading ${body.file}`, error)
53    return []
54  }
55  return findingsInText(text, 'PR body')
56}
57
58/**
59 * Every finding in the calls' titles and bodies and in the branch's added Markdown lines.
60 * A git or gh call that fails leaves the branch unchecked rather than blocking the command.
61 */
62async function findingsFor($: EngineInterface, calls: readonly PrCall[]): Promise<Finding[]> {
63  const found: Finding[] = []
64  const bases = new Set<string | undefined>()
65  for (const call of calls) {
66    if (call.title !== undefined) found.push(...findingsInText(call.title, 'PR title'))
67    found.push(...(await findingsInBody($, call.body)))
68    bases.add(call.base)
69  }
70  for (const base of bases) {
71    try {
72      found.push(...(await findingsOnBranch($, base ?? (await defaultBranch($)))))
73    } catch (error) {
74      logQuietly($, 'checking the branch', error)
75    }
76  }
77  return found
78}
79
80export const register: Register = on => {
81  // Matched by pattern: which shell tools a session has depends on the machine.
82  // It runs in a headless session too: it asks no one, and starts no prompt and no headless run.
83  on('tool.call', { tool: /^(Bash|PowerShell)$/ }, async ($, e, next) => {
84    const command = 'command' in e && typeof e.command === 'string' ? e.command : ''
85    const calls = prCalls(command, e.tool === 'PowerShell' ? 'powershell' : 'bash')
86    if (calls.length === 0) return next(e)
87    const findings = await findingsFor($, calls)
88    return findings.length === 0 ? next(e) : { deny: refusal(findings) }
89  })
90}
91

1/** A banned claim: where it is (a file and line, "PR body" or "PR title"), which ban, and the text matched. */
2export type Finding = { where: string; ban: string; text: string }
3
4const UNIT = 'one|two|three|four|five|six|seven|eight|nine'
5const TEEN = 'eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen'
6const TENS = `(?:twenty|thirty|forty|fifty|sixty|seventy|eighty|ninety)(?:[- ](?:${UNIT}))?`
7const UNDER_HUNDRED = `${TEEN}|ten|${TENS}|${UNIT}`
8const LARGE = `(?:a|${UNDER_HUNDRED})[- ](?:hundred|thousand|million)(?:[- ](?:and[- ])?(?:${UNDER_HUNDRED}))?`
9// Words ending in s that are not plural nouns, so a count before them is not one.
10const NOT_PLURAL = new Set(['was', 'has', 'does', 'goes', 'its', 'yes', 'always', 'across', 'perhaps', 'whereas', 'besides'])
11const IRREGULAR_PLURAL = new Set(['people', 'children', 'men', 'women'])
12
13const BANS: readonly { ban: string; pattern: RegExp; isFinding?: (match: RegExpMatchArray) => boolean }[] = [
14  {
15    ban: 'file:line citation',
16    // A URL's host and port is not one: nothing before the name may join it to a scheme.
17    pattern: /(?<![\w.:/\\@-])(?:[A-Za-z]:[\\/])?(?:[\w.-]+[\\/])*[\w-]+(?:\.[\w-]+)*\.[A-Za-z][A-Za-z0-9]*:\d+(?:-\d+)?(?![\w/])/g,
18  },
19  {
20    ban: 'placeholder',
21    pattern: /\(PR #NN\)|(?<!\w)#(?:NN|XX)(?!\w)|\bTODO:?\s+fill\s+in\b/gi,
22  },
23  {
24    ban: 'count in words',
25    pattern: new RegExp(`\\b(?:${LARGE}|${TEEN}|${TENS})\\s+([A-Za-z]+)\\b`, 'gi'),
26    isFinding: match => isPlural(match[1]!),
27  },
28]
29
30function isPlural(word: string): boolean {
31  const lower = word.toLowerCase()
32  if (IRREGULAR_PLURAL.has(lower)) return true
33  return lower.length >= 3 && lower.endsWith('s') && !/(?:ss|us|is)$/.test(lower) && !NOT_PLURAL.has(lower)
34}
35
36/** The bans one line breaks. */
37function findingsInLine(line: string, where: string): Finding[] {
38  return BANS.flatMap(({ ban, pattern, isFinding }) =>
39    [...line.matchAll(pattern)].filter(match => isFinding?.(match) ?? true).map(match => ({ where, ban, text: match[0] })),
40  )
41}
42
43/** The run of backticks or tildes a fence line starts with; undefined for any other line. */
44function fenceOf(line: string): string | undefined {
45  return /^\s*(`{3,}|~{3,})/.exec(line)?.[1]
46}
47
48function closes(line: string, open: string): boolean {
49  const fence = fenceOf(line)
50  return fence !== undefined && fence[0] === open[0] && fence.length >= open.length && line.trim() === fence
51}
52
53/**
54 * The findings on the lines `where` names, outside fenced code blocks.
55 * Every line is read for the fences; `where` answers undefined for a line not to check.
56 */
57export function findingsIn(lines: readonly string[], where: (index: number) => string | undefined): Finding[] {
58  const found: Finding[] = []
59  let open: string | undefined
60  lines.forEach((line, index) => {
61    if (open !== undefined) {
62      if (closes(line, open)) open = undefined
63      return
64    }
65    open = fenceOf(line)
66    const place = where(index)
67    if (open === undefined && place !== undefined) found.push(...findingsInLine(line, place))
68  })
69  return found
70}
71
72/** The findings in a PR's title or body. */
73export function findingsInText(text: string, where: string): Finding[] {
74  return findingsIn(text.split(/\r?\n/), () => where)
75}
76
77/** One file as a whole-file diff shows it: its lines after the change, and which of them the change added. */
78type ChangedFile = { path: string; lines: string[]; isAdded: boolean[] }
79
80function pathOf(header: string): string {
81  const path = header.slice(4).replace(/\t$/, '')
82  return path.startsWith('"') && path.endsWith('"') ? path.slice(1, -1) : path
83}
84
85/**
86 * Reads `git diff --no-prefix` output whose context covers each whole file.
87 * A hunk is read by its line counts, so an added line that starts with `++` is not taken for a header.
88 */
89function changedFiles(diff: string): ChangedFile[] {
90  const files: ChangedFile[] = []
91  const lines = diff.split('\n')
92  let file: ChangedFile | undefined
93  for (let at = 0; at < lines.length; at += 1) {
94    const line = lines[at]!
95    if (line.startsWith('+++ ')) {
96      file = line === '+++ /dev/null' ? undefined : { path: pathOf(line), lines: [], isAdded: [] }
97      if (file !== undefined) files.push(file)
98      continue
99    }
100    const hunk = /^@@ -\d+(?:,(\d+))? \+\d+(?:,(\d+))? @@/.exec(line)
101    if (hunk === null || file === undefined) continue
102    let old = Number(hunk[1] ?? 1)
103    let added = Number(hunk[2] ?? 1)
104    while ((old > 0 || added > 0) && at + 1 < lines.length) {
105      const body = lines[(at += 1)]!.replace(/\r$/, '')
106      const mark = body[0]
107      if (mark === '\\') continue
108      if (mark !== '+') old -= 1
109      if (mark === '-') continue
110      added -= 1
111      file.lines.push(body.slice(1))
112      file.isAdded.push(mark === '+')
113    }
114  }
115  return files
116}
117
118/** The findings on the lines a whole-file diff of Markdown files adds, each placed by file and line. */
119export function findingsInDiff(diff: string): Finding[] {
120  return changedFiles(diff).flatMap(file =>
121    findingsIn(file.lines, index => (file.isAdded[index] ? `${file.path}, line ${index + 1}` : undefined)),
122  )
123}
124
125/** Why a gh call is refused: each finding, where it is and what it matched. */
126export function refusal(findings: readonly Finding[]): string {
127  return [
128    'pre-pr-claims-check: this pull request breaks the claims bans. Fix each of these, then run the command again:',
129    ...findings.map(finding => `- ${finding.where}: ${finding.ban} "${finding.text}"`),
130    'Name a file without its line number, fill in or drop each placeholder, and leave out counts typed by hand.',
131  ].join('\n')
132}
133

1export type Shell = 'bash' | 'powershell'
2
3/** Where a PR's body comes from: its text as the command gives it, or a file to read. */
4export type Body = { text: string } | { file: string }
5
6/** One `gh pr create` or `gh pr edit` in a shell command, with what it sets. */
7export type PrCall = { title?: string; body?: Body; base?: string }
8
9/**
10 * Stands in for a heredoc or a here-string taken out of the command, so a word
11 * that held one can still be traced to its text.
12 */
13const MARK = '\u0001'
14const MARKED = new RegExp(`${MARK}(\\d+)${MARK}`, 'g')
15const HEREDOC = /<<(?!<)(-?)\s*(?:'([^'\n]+)'|"([^"\n]+)"|\\?([\w.-]+))/g
16const HERE_STRING = /@(['"])\r?\n([\s\S]*?)\r?\n\1@/g
17const BREAKS = new Set([';', '&', '|', '<', '>', '(', ')', '{', '}', '\n'])
18const FLAGS: Readonly<Record<string, keyof Flags>> = {
19  '--title': 'title',
20  '-t': 'title',
21  '--body': 'body',
22  '-b': 'body',
23  '--body-file': 'bodyFile',
24  '-F': 'bodyFile',
25  '--base': 'base',
26  '-B': 'base',
27}
28
29type Flags = { title?: string; body?: string; bodyFile?: string; base?: string }
30type Inline = { command: string; texts: string[] }
31
32function mark(index: number): string {
33  return `${MARK}${index}${MARK}`
34}
35
36/** Takes each heredoc's lines out of a Bash command, leaving a mark where its `<<` was. */
37function takeHeredocs(command: string): Inline {
38  const lines = command.split('\n')
39  const kept: string[] = []
40  const texts: string[] = []
41  for (let at = 0; at < lines.length; at += 1) {
42    const opened: { delimiter: string; isTabbed: boolean }[] = []
43    kept.push(
44      lines[at]!.replace(HEREDOC, (_all, dash: string, single?: string, double?: string, bare?: string) => {
45        opened.push({ delimiter: single ?? double ?? bare ?? '', isTabbed: dash === '-' })
46        return mark(texts.length + opened.length - 1)
47      }),
48    )
49    for (const { delimiter, isTabbed } of opened) {
50      const body: string[] = []
51      for (at += 1; at < lines.length; at += 1) {
52        const line = lines[at]!.replace(/\r$/, '')
53        if ((isTabbed ? line.replace(/^\t+/, '') : line) === delimiter) break
54        body.push(line)
55      }
56      texts.push(body.join('\n'))
57    }
58  }
59  return { command: kept.join('\n'), texts }
60}
61
62/** Takes each here-string out of a PowerShell command, leaving a mark in its place. */
63function takeHereStrings(command: string): Inline {
64  const texts: string[] = []
65  const rest = command.replace(HERE_STRING, (_all, _quote, text: string) => {
66    texts.push(text)
67    return mark(texts.length - 1)
68  })
69  return { command: rest, texts }
70}
71
72/**
73 * The command's words with quotes taken off, cut into simple commands at an
74 * unquoted break (`;`, `&&`, a pipe, a redirect, a bracket or a line end).
75 */
76function simpleCommands(command: string, shell: Shell): string[][] {
77  const escape = shell === 'bash' ? '\\' : '`'
78  const all: string[][] = [[]]
79  let word: string | undefined
80  const endWord = () => {
81    if (word !== undefined) all[all.length - 1]!.push(word)
82    word = undefined
83  }
84  for (let at = 0; at < command.length; at += 1) {
85    const char = command[at]!
86    if (char === escape) {
87      // An escaped line end continues the command.
88      if (command[at + 1] !== '\n') word = (word ?? '') + (command[at + 1] ?? '')
89      at += 1
90    } else if (char === "'") {
91      const end = closing(command, at, "'", shell)
92      const text = command.slice(at + 1, end)
93      word = (word ?? '') + (shell === 'powershell' ? text.replaceAll("''", "'") : text)
94      at = end
95    } else if (char === '"') {
96      const end = closing(command, at, '"', shell)
97      word = (word ?? '') + unescapeDouble(command.slice(at + 1, end), shell)
98      at = end
99    } else if (/\s/.test(char) && char !== '\n') {
100      endWord()
101    } else if (BREAKS.has(char)) {
102      endWord()
103      all.push([])
104    } else {
105      word = (word ?? '') + char
106    }
107  }
108  endWord()
109  return all.filter(words => words.length > 0)
110}
111
112/** Where the quote opened at `start` closes, or the command's end when it never does. */
113function closing(command: string, start: number, quote: string, shell: Shell): number {
114  for (let at = start + 1; at < command.length; at += 1) {
115    const char = command[at]
116    if (quote === '"' && char === (shell === 'bash' ? '\\' : '`')) at += 1
117    else if (char === quote) {
118      // PowerShell doubles a quote to put one inside its own kind.
119      if (shell === 'powershell' && command[at + 1] === quote) at += 1
120      else return at
121    }
122  }
123  return command.length
124}
125
126function unescapeDouble(text: string, shell: Shell): string {
127  if (shell === 'bash') return text.replace(/\\([\\"$`\n])/g, (_all, char: string) => (char === '\n' ? '' : char))
128  return text.replaceAll('""', '"').replace(/`(.)/g, (_all, char: string) => (char === 'n' ? '\n' : char === 't' ? '\t' : char))
129}
130
131/** The flags a gh call sets, from the words after `gh pr create` or `gh pr edit`. */
132function readFlags(words: readonly string[]): Flags {
133  const flags: Flags = {}
134  for (let at = 0; at < words.length; at += 1) {
135    const word = words[at]!
136    const equals = word.indexOf('=')
137    const name = equals > 0 ? word.slice(0, equals) : word
138    const key = FLAGS[name]
139    if (key === undefined) continue
140    const value = equals > 0 ? word.slice(equals + 1) : words[(at += 1)]
141    if (value !== undefined) flags[key] = value
142  }
143  return flags
144}
145
146/** The text a word holds once each heredoc or here-string it names is put back. */
147function inlineIn(word: string, texts: readonly string[]): string | undefined {
148  const named = [...word.matchAll(MARKED)].map(match => texts[Number(match[1])] ?? '')
149  return named.length === 0 ? undefined : named.join('\n')
150}
151
152function bodyOf(flags: Flags, texts: readonly string[]): Body | undefined {
153  if (flags.body !== undefined) return { text: inlineIn(flags.body, texts) ?? flags.body }
154  if (flags.bodyFile === undefined) return undefined
155  // Standard input: the body is the heredoc or here-string the command carries.
156  if (flags.bodyFile === '-') return texts.length === 0 ? undefined : { text: texts.join('\n') }
157  return { file: flags.bodyFile }
158}
159
160/** Each `gh pr create` and `gh pr edit` the command runs, in order; none for any other command. */
161export function prCalls(command: string, shell: Shell): PrCall[] {
162  if (!/\bgh(?:\.exe)?\s+pr\s+(?:create|edit)\b/.test(command)) return []
163  const inline = shell === 'bash' ? takeHeredocs(command) : takeHereStrings(command)
164  const calls: PrCall[] = []
165  for (const words of simpleCommands(inline.command, shell)) {
166    const at = words.findIndex(
167      (word, index) => /^(?:.*[\\/])?gh(?:\.exe)?$/i.test(word) && words[index + 1] === 'pr' && /^(?:create|edit)$/.test(words[index + 2] ?? ''),
168    )
169    if (at < 0) continue
170    const flags = readFlags(words.slice(at + 3))
171    const call: PrCall = {}
172    if (flags.title !== undefined) call.title = inlineIn(flags.title, inline.texts) ?? flags.title
173    const body = bodyOf(flags, inline.texts)
174    if (body !== undefined) call.body = body
175    if (flags.base !== undefined) call.base = flags.base
176    calls.push(call)
177  }
178  return calls
179}
180