p3c-guard

1import type { EngineInterface, Register } from 'claude-code'
2
3const JAR_VERSION = '3.0.1'
4const JAR_NAME = `p3c-pmd-jdk21-${JAR_VERSION}-cli.jar`
5const JAR_URL = `https://repo1.maven.org/maven2/io/github/loong95/p3c-pmd-jdk21/${JAR_VERSION}/${JAR_NAME}`
6const JAR_SHA256 = '4caf54a3a8f33cc079a16857147168f268cae7e86072413e9ab07365dc311a16'
7const RULESET = 'rulesets/java/ali-all.xml'
8const MAX_LISTED = 10
9
10// How to fix the rules whose own message does not say; shown after it.
11const FIXES: Readonly<Record<string, string>> = {
12  ThreadPoolCreationRule:
13    '用 new ThreadPoolExecutor(...) 显式给出核心数、最大数、有界队列和带名字的 ThreadFactory；Spring 项目注入已配置的 ThreadPoolTaskExecutor。',
14  AvoidManuallyCreateThreadRule: '把任务提交给已有的线程池，不要 new Thread()。',
15  ThreadShouldSetNameRule: '给 ThreadFactory 或线程池设置有业务含义的线程名前缀。',
16  AvoidCallStaticSimpleDateFormatRule:
17    '改用线程安全的 DateTimeFormatter，或每次调用新建 SimpleDateFormat。',
18  ThreadLocalShouldRemoveRule: '在 finally 里调用 remove()。',
19  AvoidUseTimerRule: '改用 ScheduledThreadPoolExecutor。',
20  LockShouldWithTryFinallyRule: 'lock() 紧接 try，unlock() 放在 finally 的第一行。',
21  DontModifyInForeachCircleRule: '改用 Iterator.remove() 或 Collection.removeIf(...)。',
22  WrapperTypeEqualityRule: '用 Objects.equals(a, b) 比较包装类型。',
23  AvoidDoubleOrFloatEqualCompareRule: '用 BigDecimal.compareTo，或比较差值是否小于给定误差。',
24  AvoidApacheBeanUtilsCopyRule: '改用 Spring BeanUtils 或 MapStruct。',
25  AvoidNewDateGetTimeRule: '改用 System.currentTimeMillis()。',
26  AvoidPatternCompileInMethodRule: '把 Pattern.compile(...) 提成 private static final 常量。',
27  EqualsAvoidNullRule: '把常量或确定非空的值放在 equals 左边，或用 Objects.equals。',
28}
29
30// PMD exits 4 when it found violations and 5 when a file did not parse.
31const PMD_OK = [0, 4, 5]
32
33type Engine = EngineInterface
34
35export type Violation = {
36  rule: string
37  line: number
38  priority: number
39  description: string
40}
41
42type PmdReport = {
43  files?: {
44    filename: string
45    violations: {
46      rule: string
47      beginline: number
48      priority: number
49      description: string
50    }[]
51  }[]
52  processingErrors?: { filename: string }[]
53}
54
55/** The file's text once the edit is applied, or undefined when it would not apply. */
56export const applyEdit = (
57  text: string,
58  oldString: string,
59  newString: string,
60  replaceAll: boolean,
61): string | undefined => {
62  if (oldString === '' || !text.includes(oldString)) {
63    return undefined
64  }
65
66  return replaceAll
67    ? text.split(oldString).join(newString)
68    : text.replace(oldString, () => newString)
69}
70
71/** The violations in `after` that `before` did not already have, at or above the blocking level. */
72export const addedViolations = (
73  before: readonly Violation[],
74  after: readonly Violation[],
75  blockPriority: number,
76): Violation[] => {
77  const known = new Map<string, number>()
78
79  for (const one of before) {
80    const key = `${one.rule}\n${one.description}`
81    known.set(key, (known.get(key) ?? 0) + 1)
82  }
83
84  return after.filter(one => {
85    if (one.priority > blockPriority) {
86      return false
87    }
88
89    const key = `${one.rule}\n${one.description}`
90    const left = known.get(key) ?? 0
91    known.set(key, left - 1)
92
93    return left <= 0
94  })
95}
96
97const state = {
98  blockPriority: 2,
99  isEnabled: true,
100  blocked: 0,
101  passed: 0,
102  jar: undefined as Promise<string> | undefined,
103  isJarReady: false,
104}
105
106const fetchJar = async ($: Engine): Promise<string> => {
107  const home = await $.env.get('HOME')
108
109  if (home === undefined) {
110    throw new Error('HOME is not set')
111  }
112
113  const dir = `${home}/.cache/p3c-guard`
114  const path = `${dir}/${JAR_NAME}`
115
116  if (!(await $.fs.exists(path))) {
117    const part = `${path}.part`
118    await $.process.run(['mkdir', '-p', dir])
119    const got = await $.process.run(
120      ['curl', '-fsSL', '-o', part, JAR_URL],
121      { timeoutMs: 300_000 },
122    )
123
124    if (got.exitCode !== 0) {
125      throw new Error(`download failed: ${got.stderr.slice(0, 200)}`)
126    }
127
128    const sum = await $.process.run(['shasum', '-a', '256', part])
129
130    if (!sum.stdout.startsWith(JAR_SHA256)) {
131      await $.process.run(['rm', '-f', part])
132      throw new Error('the downloaded jar does not match its checksum')
133    }
134
135    await $.process.run(['mv', part, path])
136  }
137
138  state.isJarReady = true
139
140  return path
141}
142
143const check = async (
144  $: Engine,
145  jarPath: string,
146  id: string,
147  name: string,
148  before: string | undefined,
149  after: string,
150): Promise<Violation[] | undefined> => {
151  const dir = `${jarPath.slice(0, jarPath.lastIndexOf('/'))}/work/${id}`
152
153  try {
154    await $.fs.write(`${dir}/after/${name}`, after)
155
156    if (before !== undefined) {
157      await $.fs.write(`${dir}/before/${name}`, before)
158    }
159
160    const ran = await $.process.run(
161      [
162        'java', '-XX:TieredStopAtLevel=1', '-jar', jarPath, 'check',
163        '-d', dir, '-R', RULESET, '-f', 'json', '--no-cache', '--no-progress',
164      ],
165      { timeoutMs: 20_000 },
166    )
167
168    if (!PMD_OK.includes(ran.exitCode)) {
169      throw new Error(`pmd exited ${ran.exitCode}: ${ran.stderr.slice(0, 200)}`)
170    }
171
172    const report = JSON.parse(ran.stdout) as PmdReport
173    const isAfter = (path: string) => path.includes(`/${id}/after/`)
174
175    // A file that does not parse is the compiler's to refuse, not ours.
176    if (report.processingErrors?.some(one => isAfter(one.filename))) {
177      return undefined
178    }
179
180    const read = (wanted: boolean): Violation[] =>
181      (report.files ?? [])
182        .filter(file => isAfter(file.filename) === wanted)
183        .flatMap(file => file.violations)
184        .map(one => ({
185          rule: one.rule,
186          line: one.beginline,
187          priority: one.priority,
188          description: one.description,
189        }))
190
191    return addedViolations(read(false), read(true), state.blockPriority)
192  } finally {
193    await $.process.run(['rm', '-rf', dir]).catch(() => undefined)
194  }
195}
196
197const showCounts = ($: Engine) =>
198  $.ui.status(`p3c 拦 ${state.blocked} · 过 ${state.passed}`)
199
200/** Answers a refusal for the write, or undefined to let it through. */
201const judge = async (
202  $: Engine,
203  id: string,
204  filePath: string,
205  before: string | undefined,
206  after: string,
207): Promise<string | undefined> => {
208  try {
209    state.jar ??= fetchJar($)
210
211    // The first Java write of a machine starts the download and is not held for it.
212    if (!state.isJarReady) {
213      void state.jar.catch(() => {
214        state.jar = undefined
215      })
216      const ready = await Promise.race([
217        state.jar.then(() => true, () => false),
218        $.clock.sleep(1500).then(() => false),
219      ])
220
221      if (!ready) {
222        $.ui.status('p3c 正在准备规则引擎，本次未检查')
223
224        return undefined
225      }
226    }
227
228    const name = filePath.slice(filePath.lastIndexOf('/') + 1)
229    const added = await check($, await state.jar, id, name, before, after)
230
231    if (added === undefined || added.length === 0) {
232      state.passed += 1
233      showCounts($)
234
235      return undefined
236    }
237
238    state.blocked += 1
239    showCounts($)
240    const listed = added
241      .slice(0, MAX_LISTED)
242      .map(one => {
243        const fix = FIXES[one.rule]
244
245        return `- 第 ${one.line} 行 [${one.rule}] ${one.description}${fix === undefined ? '' : ` 改法：${fix}`}`
246      })
247    const more = added.length > MAX_LISTED
248      ? [`- 另有 ${added.length - MAX_LISTED} 处未列出`]
249      : []
250
251    return [
252      `p3c-guard：这次写入会给 ${name} 新增 ${added.length} 处阿里 Java 规约违规，未写入。`,
253      ...listed,
254      ...more,
255      '行号是写入后文件里的行号。请修正后重新写入；文件原有的违规不在此列。',
256    ].join('\n')
257  } catch (error) {
258    // A jar that went missing is fetched again by the next write.
259    state.jar = undefined
260    state.isJarReady = false
261    $.ui.status(`p3c 未检查：${String(error).slice(0, 60)}`)
262
263    return undefined
264  }
265}
266
267export const register: Register = (on, options) => {
268  state.blockPriority = Number(options?.blockPriority ?? '2') || 2
269  state.isEnabled = true
270  state.blocked = 0
271  state.passed = 0
272  state.jar = undefined
273  state.isJarReady = false
274
275  on('session.start', async ($, e, next) => {
276    await $.command.register({
277      name: 'p3c',
278      description: 'p3c-guard：/p3c 看状态，/p3c off 暂停，/p3c on 恢复',
279    })
280
281    return next(e)
282  })
283
284  on('command.run', { command: 'p3c' }, (_$, e) => {
285    const arg = e.args.trim()
286
287    if (arg === 'off' || arg === 'on') {
288      state.isEnabled = arg === 'on'
289    }
290
291    return {
292      text: `p3c-guard ${state.isEnabled ? '已开启' : '已暂停'}：拦截级别 ${state.blockPriority}，本会话拦 ${state.blocked} 次、放行 ${state.passed} 次。`,
293    }
294  })
295
296  on('tool.call', { tool: 'Write' }, async ($, e, next) => {
297    if (!state.isEnabled || !e.file_path.endsWith('.java')) {
298      return next(e)
299    }
300
301    const before = (await $.fs.exists(e.file_path))
302      ? await $.fs.read(e.file_path).catch(() => undefined)
303      : undefined
304    const deny = await judge($, e.tool_use_id, e.file_path, before, e.content)
305
306    return deny === undefined ? next(e) : { deny }
307  }).catch(($, e, next) => next(e))
308
309  on('tool.call', { tool: 'Edit' }, async ($, e, next) => {
310    if (!state.isEnabled || !e.file_path.endsWith('.java')) {
311      return next(e)
312    }
313
314    const before = await $.fs.read(e.file_path).catch(() => undefined)
315    const after = before === undefined
316      ? undefined
317      : applyEdit(before, e.old_string, e.new_string, e.replace_all === true)
318
319    // An edit that does not apply is the tool's own to refuse.
320    if (after === undefined) {
321      return next(e)
322    }
323
324    const deny = await judge($, e.tool_use_id, e.file_path, before, after)
325
326    return deny === undefined ? next(e) : { deny }
327  }).catch(($, e, next) => next(e))
328}
329