181 lines
9.9 KiB
Markdown
181 lines
9.9 KiB
Markdown
# PMD 依赖 Classpath 自动探测 — 设计 Spec
|
||
|
||
日期：2026-08-08
|
||
状态：待审批
|
||
关联流程：① 用户提出 → ② 需求澄清 → ③ 方案设计
|
||
|
||
## 1. 背景与根因
|
||
|
||
PMD 做类型感知分析（如 `UnusedImports`、`UnnecessaryFullyQualifiedName` 等规则）时，需要能解析源码中引用的外部类型，即需要"辅助 classpath"（aux classpath）。当前插件调用 PMD 时未提供该 classpath：
|
||
|
||
1. `src/adapters/pmd.ts:104` 的 `spawn('java', args, { cwd })` 未设置 `env`，依赖 classpath 无从传入。
|
||
2. `jars/pmd/PmdRunner.java` 也未读取任何 aux classpath 来源——经源码与编译产物 `PmdRunner.class` 双重验证，其既无 `getenv` 调用，也未调用 PMD 的 `PMDConfiguration.prependAuxClasspath(String)`（pmd-core-7.26.0 中该方法存在，`javap` 已验证）。
|
||
|
||
因此即使插件侧把 classpath 设置进环境变量，PmdRunner 当前也不会消费它，需两端同时修改。
|
||
|
||
## 2. 共识（Stage ② 确认）
|
||
|
||
- **classpath 来源**：自动探测 Maven / Gradle 构建系统，不新增手动配置项。
|
||
- **探测优先级**：`pom.xml` → `build.gradle` → `build.gradle.kts`，取第一个命中项；三者都没有则不设置 aux classpath（保持现状行为，不报错）。
|
||
- **缓存策略**：按 workingDir 缓存探测结果；以构建文件路径 + mtime 作为失效键，构建文件变更后自动重新探测。
|
||
- **多模块支持**：按模块根独立探测（workingDir 即模块根），不跨模块合并 classpath。
|
||
- **失败处理**：探测失败（工具未装 / 命令报错 / 超时）降级为不带 classpath 继续审查，仅日志提示，不影响可用性。
|
||
- **classpath 范围**：runtimeClasspath 超集（compile + runtime + 传递依赖）。
|
||
|
||
## 3. 方案
|
||
|
||
### 3.1 架构概览
|
||
|
||
新增独立服务 `AuxClasspathResolver`（位于基础层 `src/services/`），对 PMD 适配器透明暴露 `resolve(workingDir) => Promise<string>`。数据流：
|
||
|
||
```
|
||
PmdAdapter.run()
|
||
├─ AuxClasspathResolver.resolve(workingDir)
|
||
│ ├─ 探测构建文件（pom.xml/build.gradle(.kts)），无 → 返回 ''
|
||
│ ├─ 缓存命中（构建文件路径+mtime 未变）→ 返回缓存 classpath
|
||
│ ├─ 未命中 → 运行 mvn/gradle 生成 classpath → 更新缓存（成功/失败均缓存）
|
||
└─ spawn('java', args, { cwd, env: { ...process.env, PMD_AUXCP } })
|
||
└─ PmdRunner.main() 读 PMD_AUXCP → config.prependAuxClasspath(aux)
|
||
```
|
||
|
||
classpath 以 `PMD_AUXCP` 环境变量经 `spawn` 的 `env` 传入子进程；`PmdRunner.java` 读取后注入 `PMDConfiguration`。
|
||
|
||
### 3.2 文件变更清单
|
||
|
||
| 文件 | 变更 | 说明 |
|
||
|------|------|------|
|
||
| `src/services/auxClasspath.ts` | 新建 | `AuxClasspathResolver`：探测 + 缓存 + Maven/Gradle 调用 |
|
||
| `src/adapters/pmd.ts` | 修改 | `run()` 中解析 aux classpath，`execPmd()` 的 spawn 传入 `env` |
|
||
| `jars/pmd/PmdRunner.java` | 修改 | 读取 `PMD_AUXCP`（兼容 `PMD_AUX_CLASSPATH`），调用 `prependAuxClasspath` |
|
||
| `jars/pmd/PmdRunner.class` | 重编译 | `javac -cp "jars/pmd/lib/*" -d jars/pmd/ jars/pmd/PmdRunner.java` |
|
||
| `package.json` | 修改 | 新增开关 `vscode-code-reviewer.pmd.autoAuxClasspath`（默认 true，见 §3.4） |
|
||
| `src/config/linter.ts` | 修改 | 新增 `getPMDAutoAuxClasspath()` 读取开关 |
|
||
|
||
### 3.3 关键接口
|
||
|
||
#### 3.3.1 `AuxClasspathResolver`（`src/services/auxClasspath.ts`）
|
||
|
||
```ts
|
||
export interface AuxClasspathInfo {
|
||
classpath: string; // '' 表示无可用 classpath
|
||
source?: 'maven' | 'gradle';
|
||
error?: string; // 探测失败时的错误信息（仅日志用）
|
||
}
|
||
|
||
export class AuxClasspathResolver {
|
||
resolve(workingDir: string): Promise<AuxClasspathInfo>;
|
||
}
|
||
```
|
||
|
||
内部实现要点：
|
||
|
||
- **缓存结构**：`Map<string, { buildFile: string; mtimeMs: number; info: AuxClasspathInfo }>`，键为 `workingDir`；外加 `Map<string, Promise<AuxClasspathInfo>>` 作 in-flight 去重，避免并发检查重复运行构建命令。
|
||
- **失效键**：`buildFile 路径 + stat.mtimeMs`。每次 `resolve` 重新探测构建文件并 `stat`，mtime 变化即重跑。
|
||
- **探测工具**：
|
||
- Maven：优先 `mvnw`/`mvnw.cmd`，回退 `mvn`/`mvn.cmd`（Windows 用 `.cmd`，避免 `spawn` PATHEXT 问题）。
|
||
- Gradle：优先 `gradlew`/`gradlew.bat`，回退 `gradle`/`gradle.bat`。
|
||
- **Maven 命令**（写临时文件再读取，避免解析 stdout 噪音）：
|
||
```
|
||
<mvn> -B -q -Dmdep.outputFile=<tempFile> dependency:build-classpath
|
||
```
|
||
读取 `tempFile` 内容 trim 后作为 classpath。插件默认 `includeScope=runtime`（`dependency:build-classpath` 默认值，符合 runtimeClasspath 超集共识）。
|
||
- **Gradle 命令**（init 脚本注册一次性任务，打印 root 工程 `sourceSets.main.runtimeClasspath.asPath`）：
|
||
```
|
||
<gradle> -q -I <initScript> _printRuntimeClasspath
|
||
```
|
||
init 脚本内容（Groovy，兼容 Groovy DSL 与 Kotlin DSL 项目）：
|
||
```groovy
|
||
allprojects { proj ->
|
||
if (proj == rootProject) {
|
||
proj.tasks.register('_printRuntimeClasspath') {
|
||
doLast {
|
||
if (proj.plugins.hasPlugin('java')) {
|
||
def main = proj.sourceSets.findByName('main')
|
||
if (main != null) {
|
||
println main.runtimeClasspath.asPath
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
取 stdout 末行非空行作为 classpath。
|
||
- **超时**：`spawn` + 手动计时（Maven 120s / Gradle 120s），超时 `proc.kill()` 并视为失败。
|
||
- **失败语义**：捕获所有异常/非零退出，返回 `{ classpath: '', error: message }`，并同样写入缓存（mtime 未变前不重跑，避免每次保存文件重复失败告警）。
|
||
|
||
#### 3.3.2 `PmdRunner.java` 改动
|
||
|
||
```java
|
||
String auxcp = System.getenv("PMD_AUXCP");
|
||
if (auxcp == null || auxcp.isEmpty()) {
|
||
auxcp = System.getenv("PMD_AUX_CLASSPATH"); // 兼容 PMD CLI 约定
|
||
}
|
||
if (auxcp != null && !auxcp.isEmpty()) {
|
||
config.prependAuxClasspath(auxcp);
|
||
}
|
||
```
|
||
|
||
放在 `config.addRuleSet(rulesetPath)` 之后、`PmdAnalysis.create(config)` 之前。
|
||
|
||
#### 3.3.3 `src/adapters/pmd.ts` 改动
|
||
|
||
- `PmdAdapter` 增加私有字段 `private auxResolver = new AuxClasspathResolver();`。
|
||
- `run()` 中 `classpath` 计算后、`execPmd` 前：
|
||
```ts
|
||
const auxInfo = await this.auxResolver.resolve(workingDir);
|
||
if (auxInfo.error) { console.warn(`[code-reviewer] PMD aux classpath resolve failed: ${auxInfo.error}`); }
|
||
const result = await this.execPmd(javaArgs, stdin, workingDir, auxInfo.classpath);
|
||
```
|
||
- `execPmd` 增加第 4 参数 `auxClasspath: string`，`spawn` 改为：
|
||
```ts
|
||
const env = { ...process.env };
|
||
if (auxClasspath && auxClasspath.trim() !== '') { env.PMD_AUXCP = auxClasspath; }
|
||
const proc = spawn('java', args, { cwd, env });
|
||
```
|
||
- Java 与 JSP 两条路径共用该逻辑（两者均可能受益于类型解析）。
|
||
|
||
### 3.4 新增配置项（待审批确认）
|
||
|
||
为自动探测提供安全阀：
|
||
|
||
```jsonc
|
||
"vscode-code-reviewer.pmd.autoAuxClasspath": {
|
||
"type": "boolean",
|
||
"default": true,
|
||
"description": "自动探测 Maven/Gradle 依赖并传给 PMD 作为辅助 classpath"
|
||
}
|
||
```
|
||
|
||
默认开启；置 `false` 时 `AuxClasspathResolver` 直接返回空，不做任何构建调用。若审批不通过可整体砍掉此项，不影响核心修复。
|
||
|
||
### 3.5 错误处理与降级
|
||
|
||
- 无构建文件 / 工具缺失 / 命令失败 / 超时 → `{ classpath: '' }`，PMD 以无 aux classpath 运行（等同现状）。
|
||
- 失败信息仅 `console.warn`，不上浮错误弹窗、不改变 `AdapterResult.status`（保持 `'ok'`，避免误报 execution-failed 干扰现有审查流程）。
|
||
- `mvn/gradle` 输出含 Windows 盘符路径或空格时作为单个 env 变量值传递，无 shell 插值风险（`spawn` 不经 shell，`env` 值原样透传）。
|
||
|
||
### 3.6 验证方式
|
||
|
||
1. `npm test`（pretest 自动 `compile` + `lint`；当前仓库无 test 用例文件，adapter.test.ts 已移出，测试仅验证扩展可激活）。
|
||
2. 手工端到端（Windows 本机）：
|
||
- 构造含 `pom.xml` 的最小 Maven 项目，被测 Java 源码引用第三方类型；确认 `.class` 的 PMD 类型敏感规则（如 `UnusedImports`）在改动前后行为差异、且无 `PMD exited with code` 报错。
|
||
- 构造含 `build.gradle` 项目跑同用例。
|
||
- 断言 `_printRuntimeClasspath` 任务输出非空；验证缓存：连续两次 check 只跑一次构建命令（改 `pom.xml` mtime 后重跑）。
|
||
- 无构建文件目录：行为与改动前一致。
|
||
3. `javac` 重编译 `PmdRunner.java` 成功，并核对 `PmdRunner.class` 中包含 `PMD_AUXCP` 字符串与 `prependAuxClasspath` 调用（`strings`/`javap` 验证）。
|
||
|
||
## 4. 影响范围
|
||
|
||
- 仅影响 PMD 适配器（Java + JSP）调用路径；无构建文件或开关关闭时行为与现状完全一致。
|
||
- 不改变规则集选择、诊断严重度映射、AI 审查流程。
|
||
- 新增基础层服务文件 1 个、PMD 适配器与 PmdRunner 修改、配置项 1 个；无 i18n 文案变更（失败仅 console 日志）。
|
||
- 首次探测某项目会额外运行一次 `mvn/gradle`（秒级），之后走缓存；可通过开关关闭。
|
||
|
||
## 5. 风险
|
||
|
||
- **Gradle init 脚本兼容性**：`build.gradle.kts` 项目与 Groovy init 脚本组合在 Gradle 8/9 下可用（init 脚本恒为 Groovy，通过 Project API 访问 sourceSets）；若项目配置特殊（无 java 插件、sourceSets 重命名），输出为空 → 降级无 classpath，不阻塞审查。
|
||
- **Maven 依赖解析失败**：私有仓库/离线场景 `dependency:build-classpath` 可能失败 → 降级，不影响审查。
|
||
- **首次延迟**：新项目首次检查多耗时（构建探测），后续缓存；可接受，且有开关兜底。
|
||
- **classpath 大小**：大型项目 runtimeClasspath 字符串可能很长，Windows 单环境变量上限约 32KB；超限时降级为无 classpath（读回为空/截断判断），不影响审查可用性。
|