diff --git a/_AI_USAGE_LOG.md b/_AI_USAGE_LOG.md index 9d90014..24e4a28 100644 --- a/_AI_USAGE_LOG.md +++ b/_AI_USAGE_LOG.md @@ -179,3 +179,9 @@ | 2026-08-04 20:59 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 修复 AI 审查行号显示错误（整文件审查多 1 行）：根因是 AI 返回的 findings[].line 为 1 基（基于带行号代码），而 webview/report 按 0 基处理（buildIssueItem/formatLine 显示 line+1、navigate 直接作 0 基跳转），方法级审查因 commands.ts 已转 0 基而正确、两条路径基准不一致。修复：mergeResults 统一将 aiFindings.line 转 0 基（Math.max(0, f.line-1)），reviewMethod 的 aiFindings 偏移由 f.line+methodLine-1 改为 f.line+methodLine（传 1 基文件行号交 mergeResults 转换，与 customRuleResults 语义一致）；更新 merger.test.ts 排序断言（aiFindings error:3/warning:6）+ 新增 0 基转换用例 | 中间产物：无；根因追踪：先假设「mergeResults 统一转 0 基」并在 merger.test.ts 改写断言验证（4 passing）；全量测试沿用既有惯例临时移开 adapter/extension.test.js 后 70 用例全部通过（新增 1 个转换用例），恢复原文件 | src/merger/merger.ts, src/activation/commands.ts, src/test/merger.test.ts | deepseek-v4-flash | | 2026-08-04 21:20 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | SQLFluff PRS 解析错误呈现优化：sqlfluff.ts 新增可导出纯函数 buildPRSMessage（正则提取 Found unparsable section 引号内片段、正则失败回退原文、换行单行化 \\n、超 80 字符截断 +...），check() 中 v.code==='PRS' 时 message 改用 i18n 友好提示（含当前生效方言 effectiveDialect=cliDialect??fallbackDialect + 配置指引）、severity 提升为 error（解析失败时后续规则不可信）；messages.ts 新增 adapter.sqlfluffPRS 三语 key；新增 sqlfluff-prs.test.ts 4 用例（片段提取/换行单行化/截断/回退）。背景：问题面板报 PRS 显示原始 SQL 片段+重复行号前缀观感差，且 DIALECT_MAP 默认方言已改为 oracle（08-04 20:34 未提交改动）致 MySQL 风格 DDL 误报 PRS（已实证：同一 SQL mysql 方言解析通过、oracle 报 PRS） | 中间产物：测试首次用 msg.length<200 断言截断不稳定（中英模板长度差异致英文下超限，DEBUG 日志确认实际失败的是 truncate 用例而非 fallback 用例）→ 改为断言 !includes(longFragment)（验证全文被截断，不依赖模板总长）；全量测试沿用既有惯例临时移开 adapter/extension.test.js 后 74 用例全部通过（新增 4 个 PRS 用例），恢复原文件 | src/adapters/sqlfluff.ts, src/i18n/messages.ts, src/test/sqlfluff-prs.test.ts(新增) | deepseek-v4-flash | | 2026-08-04 21:45 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 修复已打开文件不静态分析、无波浪线问题：根因两处——① package.json activationEvents 为空导致插件不自动激活（onDidOpenTextDocument 对激活前已打开的文件永不触发）；② activate 未遍历存量 textDocuments。改动：package.json activationEvents 加 onStartupFinished；extension.ts 新增 scheduleAnalysis（统一按 URI 防抖调度器，gate file scheme + markers.enabled）与 analyzeOpenDocuments（遍历已打开文档、活动文件优先、串行 await runStaticAndApply），activate 时调用；onDidChangeTextDocument 改为 clear 波浪线 + 1s 防抖自动重分析；onDidSaveTextDocument 改用 scheduleAnalysis(500) 替换原独立 debounceTimers Map。复用 runStaticAndApply 版本竞态保护，行为不变。设计文档 docs/superpowers/specs/2026-08-04-auto-static-analysis-design.md 已产出 | 中间产物：无（澄清阶段就"并发 vs 串行"向用户说明各 linter 执行成本后定为串行；激活顺序定为活动文件优先）；lint/compile 通过 | package.json, src/extension.ts, docs/superpowers/specs/2026-08-04-auto-static-analysis-design.md(新增) | deepseek-v4-flash | +| 2026-08-05 22:10 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 设置面板「共通规则」区画面优化：适配器卡片名称旁与图例优先级行末尾新增「?」帮助图标，悬停 tooltip 展示分步配置说明。i18n 新增 setup.adapter.modeLegendHelp 与 pmd/sql/eslint/stylelintHelp 五组三语 key（四段式：前置条件原因 + 内置规则开箱即用 + 主路径步骤 + 全局备选），删除已无引用的 4 组 xxxGuide；setupView.ts 移除 AdapterConfigStatus.guideText 字段及 collectAdapterStatus 赋值、pushConfig i18n payload 注入 5 个 help 字段、HTML 图例行末尾加「?」、CSS 新增 .help-icon 多行 tooltip（attr(data-help)+white-space:pre-line，卡片相对 header 左对齐/图例相对 mode-legend 右对齐防溢出）与 .adapter-card-name-wrap、删除 .adapter-guide 样式；setupView.js renderAdapters 删除 guide div、卡片标题行名称旁渲染「?」并新增 escapeAttr（转义 & < > "，保证含英文双引号的 data-help 属性安全）。lint/compile 通过；全量测试受既有 stylelint-config-recommended 无 exports main 环境问题阻碍（extension 激活失败），改用 stub vscode 的 node 脚本直接校验 i18n 255 key 三语无缺失、新 5 key 存在、旧 4 key 已删 | 设计迭代：v1 分步文案被用户指出「不知道为什么装 Java / ①② 两条路（项目/全局）混淆 / ruleset.xml 用途不明」→ 改四段式；复用现有 guide 文案被否（要新增配置说明）；guide 第二句三选一（移除/动态状态提示/精简保留）用户选移除；图例「?」位置三选一（说明行末尾/副标题旁/每项单独）选说明行末尾；HTML 预览请求在计划模式被只读拦截 → 改为 inline 输出，切 build 后落盘 temp 预览文件供审核；实现中发现 escapeHtml（textContent→innerHTML）不转义双引号，英文 help 文案含 " 会使 data-help 属性提前闭合 → 新增 escapeAttr | src/i18n/messages.ts, src/views/setupView.ts, src/views/setupView.js | deepseek-v4-flash | +| 2026-08-05 22:25 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 修复图例区「?」位置与 tooltip 方向：根因——.mode-legend-desc 为 width:100% 独占第二行，紧随其后的 .help-icon 被 flex-wrap 挤到第三行且靠左，tooltip 以 right:0 锚定左移图标向右延伸溢出。改动：setupView.ts HTML 把说明文字与「?」包进 .mode-legend-desc-row（display:flex + justify-content:space-between + width:100%），「?」回到第二行行末；CSS 新增 .mode-legend-desc-row、.mode-legend-desc 去掉 width:100%（row 接管整行），图例 tooltip 保持 .mode-legend .help-icon:hover::after { right:0; left:auto } 使提示相对行末图标向左下方延伸。lint/compile 通过 | 中间产物：无（首版 CSS 就写了 right:0 锚定，实际渲染差源自图标被挤到第三行左侧，定位到根因是 flex-wrap + width:100% 独占行） | src/views/setupView.ts | deepseek-v4-flash | +| 2026-08-05 22:55 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 「快速开始」三步卡贴近实际重写：现状是卡片原三步（配置 AI / 启用自定义规则 / 保存并测试）暗示必须配 AI 才能审核，但插件静态分析实际开箱即用（onStartupFinished 自动分析+波浪线）、AI 配置只影响 AI 审核引擎、自定义规则为可选增强，且只用静态分析时原三步全灰有误导。改动：i18n 重写 setup.gettingStarted（三步启用代码审核→三步开始使用）与 step1/step2/step3 及 step3Hint 三语；setupView.js _step1Done 判定由 provider+model+apiKey+baseUrl 改为 msg.adapterStatus.some(a=>a.enabled)（任一适配器启用即完成，默认满足，如实反映静态分析开箱即用）。步骤①文案经两轮微调定稿为「插件已内置 Linter 静态分析，开箱即用，也可在共通规则中配置项目/全局规则」三语。lint/compile 通过 | 澄清阶段向用户展示「卡片文案 vs 实际行为」差距表（静态分析开箱即用/AI 仅深度审查/自定义规则可选/只用静态分析时三步全灰误导）后选「贴近实际重写三步」；标题「三步启用」与开箱即用矛盾，用户选改为「三步开始使用」；步骤①文案两轮迭代：初稿「打开代码文件自动静态分析，无需配置」→ 用户要求强调内置、去掉波浪线 →「已内置 Linter 静态分析，开箱即用，无需配置」→ 用户指出「无需配置」有歧义（易误以为不能/不必再配项目配置）→ 定稿补「也可在共通规则中配置项目/全局规则」（候选「只删无需配置」未选） | src/i18n/messages.ts, src/views/setupView.js | deepseek-v4-flash | +| 2026-08-06 19:52 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 | 生成「创建项目配置 = 内置配置（含三语规则注释）」设计书 | 中间产物：SQLFluff 内置非 rules=all 的纠错、ESLint 方案 A/B 抉择（选 B 仅 JS 零依赖）、注释语言三选一（选三语切换）、链接策略从逐条改为每文件单个索引链接、PMD 类别级注释而非 274 条展开 | docs/superpowers/specs/2026-08-06-builtin-config-template-design.md | deepseek-v4-flash | +| 2026-08-06 20:02 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 | 实现「创建项目配置 = 内置配置（含三语规则注释）」，验证 lint/compile/test 全通过 | 中间产物：ESLint 内置 JS 实际 92 条（61+31）而非方案初稿 93/32；Stylelint 顶层静态 import 纯 ESM 包为既有 bug（CJS require 报 No exports main），改为动态 import；PMD 22 条 exclude 缺描述补写进 static-rules.json；SQLFluff 内置非 rules=all 的纠错 | src/rules/builtin-rules.ts(新建) src/adapters/eslint.ts src/adapters/stylelint.ts src/adapters/sqlfluff.ts src/views/setupView.ts src/rules/static-rules.json src/i18n/messages.ts docs/superpowers/specs/2026-08-06-builtin-config-template-design.md | deepseek-v4-flash | +| 2026-08-06 20:37 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 修复安装验证发现的 3 个问题：①PMD 创建配置不生成文件（resolvePmdRulesetPath 打包后 __dirname 退级过多，改逐级向上探测 5 级 + getExtension 路径）；②static-rules.json 新增 57 条描述中文被 PowerShell stdin 管道 ASCII 编码破坏成 '?'（改 UTF-8 落盘 .mjs 脚本重写修复）；③生成 eslint.config.js/.stylelintrc.js 被插件静态分析报 no-undef 'module'（首行加 /* global module */）。重新打包 1.2.0 VSIX | 中间产物：修复②初判为 esbuild 编码问题（bundle 中文存大写 \\uXXXX 转义，运行时解码正常，排除）；仓库根因测试生成的 eslint.config.js 覆盖自身 lint 配置致 146 no-undef，已删除 | src/rules/builtin-rules.ts src/rules/static-rules.json docs/superpowers/specs/2026-08-06-builtin-config-template-design.md | deepseek-v4-flash | diff --git a/docs/superpowers/specs/2026-08-06-builtin-config-template-design.md b/docs/superpowers/specs/2026-08-06-builtin-config-template-design.md new file mode 100644 index 0000000..a6ce75f --- /dev/null +++ b/docs/superpowers/specs/2026-08-06-builtin-config-template-design.md @@ -0,0 +1,298 @@ +# 创建项目配置 = 内置配置（含三语规则注释）— Design Spec + +## 1. 概述 + +当用户在 Setup 面板点击「创建项目配置」时，插件在项目根目录生成对应适配器的配置文件（`ruleset.xml` / `.sqlfluff` / `.stylelintrc.js` / `eslint.config.js`）。 + +本设计将生成的"示例模板"改为**与插件内置运行规则完全一致的配置**，并为每条规则附加三语（zh-CN / en / ja）描述注释，帮助用户理解已启用的规则、按相同格式添加新规则。 + +## 2. 背景与问题 + +### 2.1 现状 + +| 适配器 | 内置运行配置 | 当前"创建项目配置"生成内容 | 问题 | +|--------|-------------|---------------------------|------| +| PMD | `jars/pmd/pmd-java-ruleset.xml`（7 类 274 条 + 41 处排除） | 仅引用 2 个类别（bestpractices + codestyle）的示例 | 规则范围显著缩小 | +| SQLFluff | 精选 26 项规则清单 + `max_line_length=80 / indent_unit=space / tab_space_size=4` | `rules = all` + `dialect = mysql` | 范围过大，且与内置不一致 | +| Stylelint | `stylelint-config-recommended`（41 条）+ 27 条 extra | 仅 3 条示例规则 | 规则范围显著缩小 | +| ESLint | `@eslint/js` recommended（61 条）+ 31 条 extra（JS） | 仅 3 条示例规则 | 规则范围显著缩小 | + +### 2.2 核心问题 + +1. **规则缩水**：项目配置文件的优先级高于内置配置（`eslint.ts:105-115`、`stylelint.ts:120-125`、`pmd.ts:89-92`）。一旦创建当前示例模板，实际检查范围从数十条骤降至 3 条（或 2 个类别）。 +2. **不可知**：用户看不到内置规则清单，也不知道配置文件中的规则写法，难以添加新规则。 + +### 2.3 目标 + +- 「创建项目配置」生成的 4 个文件内容 = 插件内置配置，规则范围精确一致。 +- 每条规则带三语描述注释（随插件 `ai.outputLanguage` 切换）。 +- 每个文件头部含一段"如何添加规则"注释 + **单个**"该工具全部规则索引"链接。 +- 内置规则与生成文件永远一致（单一数据源，杜绝漂移）。 + +### 2.4 非目标 + +- 不在 Setup 面板增加规则目录 UI（生成文件本身即规则清单）。 +- 不对 ESLint 生成 TypeScript 专项规则（方案 B：仅 JS，零依赖）。 +- 不将 PMD 274 条规则展开为逐条 ``（保持类别引用结构）。 +- 不新增"全量规则枚举"（各工具全部规则目录）。 + +## 3. 方案设计 + +### 3.1 架构概览 + +``` +adapters/*.ts (内置运行规则) + │ import 共享常量 + ▼ +src/rules/builtin-rules.ts (单一数据源) + │ 4 个生成函数 + ▼ +setupView.ts 模板 → 点击「创建项目配置」→ 写入项目根目录 + │ + └─ 注释语言 getLanguage() / 规则描述 static-rules.json +``` + +### 3.2 共享数据源模块 `src/rules/builtin-rules.ts`（新建） + +从各 adapter 迁出常量，adapter 与模板共用： + +```typescript +import staticRules from './static-rules.json'; +import type { Language } from '../i18n/messages'; + +// —— 共享常量（从 adapters 迁出）—— +export const eslintExtraRules: Record; // 自 eslint.ts +export const eslintExtraTsRules: Record; // 自 eslint.ts（生成文件不含，仅 adapter 使用） +export const stylelintExtraRules: Record; // 自 stylelint.ts +export const BUILTIN_SQLFLUFF_RULES: string; // 自 sqlfluff.ts（26 项） +export function buildBuiltinSqlfluffConfig(dialect: string): string; // 自 sqlfluff.ts（含行宽/缩进设置） + +// —— 规则描述查询（三语）—— +export function getRuleDescription(linter: string, ruleId: string, lang: Language): string | undefined; + +// —— 文档索引链接（每工具仅 1 个）—— +const ESLINT_RULES_URL = 'https://eslint.org/docs/latest/rules/'; +const STYLELINT_RULES_URL = 'https://stylelint.io/user-guide/rules/'; +const SQLFLUFF_RULES_URL = 'https://docs.sqlfluff.com/en/stable/reference/rules.html'; +// PMD 版本取自 staticRules.linterVersion.pmd → `https://docs.pmd-code.org/pmd-doc-/pmd_rules_java.html` + +// —— 生成函数 —— +export function buildEslintProjectConfigText(lang: Language): string; +export async function buildStylelintProjectConfigText(lang: Language): Promise; +export function buildSqlfluffProjectConfigText(dialect: string, lang: Language): string; +export async function buildPmdProjectRulesetText(lang: Language): Promise; +``` + +**依赖注入**： +- `buildEslintProjectConfigText` 内联 `@eslint/js` 的 `configs.recommended.rules`（61 条，core 规则、无插件依赖）。 +- `buildStylelintProjectConfigText` 运行时 `await import('stylelint-config-recommended')`（ESM-only）后合并 extra，序列化为纯对象（零依赖）。 + +### 3.3 生成文件内容规范 + +#### 3.3.1 ESLint `eslint.config.js`（方案 B：仅 JS，零依赖） + +```js +// ============================================================ +// 项目配置 — 与插件内置 ESLint 规则一致（由插件生成） +// 如何添加规则： +// 1. 在 rules 中新增一行，如 'no-alert': 'warn' +// 2. 带参数写法，如 'semi': ['error', 'always'] +// 全部可用规则：https://eslint.org/docs/latest/rules/ +// 注意：本文件仅包含 JS 内置规则。TS 项目如需 TS 专项规则， +// 请安装 typescript-eslint 后自行追加： +// const ts = require('typescript-eslint'); +// module.exports = [ ...本文件配置, ...ts.configs.recommended ]; +// ============================================================ +module.exports = [ + { + rules: { + // --- @eslint/js recommended (61) --- + 'constructor-super': 'error', // 在构造函数中校验 super() 的调用 + 'for-direction': 'error', // 确保 for 循环更新子句朝正确方向移动计数器 + // ...（61 条全量内联） + // --- 插件补充 (31) --- + 'eqeqeq': 'error', // 强制使用 === 和 !== + 'no-eq-null': 'error', // 禁止与 null 使用 == 比较 + // ...（31 条全量内联） + }, + }, +]; +``` + +#### 3.3.2 Stylelint `.stylelintrc.js` + +```js +// ============================================================ +// 项目配置 — 与插件内置 Stylelint 规则一致（由插件生成） +// 如何添加规则：在 rules 中新增一行，如 'indentation': 2 +// 全部可用规则：https://stylelint.io/user-guide/rules/ +// ============================================================ +module.exports = { + rules: { + 'annotation-no-unknown': true, // 禁止未知注解 + // ...（41 条 recommended 全量内联） + 'color-no-invalid-hex': true, // 禁止无效的十六进制颜色 + // ...（27 条 extra 全量内联） + }, +}; +``` + +#### 3.3.3 SQLFluff `.sqlfluff` + +```ini +[sqlfluff] +# 数据库方言：postgres / mysql / bigquery / snowflake 等 +dialect = mysql +# 想启用全部规则时改为 → rules = all +# 内置精选规则清单： +# core 核心规则组（稳定、跨方言的语法类基础规则） +# AM03 禁止隐式交叉连接 +# CV01 ...（逐条：规则码 + 三语描述，共 26 项） +# 全部可用规则：https://docs.sqlfluff.com/en/stable/reference/rules.html +rules = core,AM03,AM05,AM08,CV01,CV02,CV06,CV08,CV12,LT13,LT14,LT15,ST01,ST02,ST04,ST05,ST06,ST07,ST09,ST10,ST11,ST12,RF02,RF04,RF05,RF06 +max_line_length = 80 +indent_unit = space +tab_space_size = 4 +``` + +#### 3.3.4 PMD `ruleset.xml` + +```xml + + + Java Code Review Rules (274 active rules, 7 categories) — 与插件内置规则集一致（由插件生成） + + + + + + + + + + ... + + +``` + +### 3.4 注释策略 + +| 文件 | 注释粒度 | 内容 | +|------|---------|------| +| `eslint.config.js` / `.stylelintrc.js` | 逐条规则 | `规则码 + 三语描述`（尾行 `//` 注释） | +| `.sqlfluff` | 逐条规则 | `rules =` 行上方注释块（`# 规则码 三语描述`） | +| `ruleset.xml` | 类别级 | 7 个 `` 类别 + 41 处 ``（``） | + +- 描述来源：`static-rules.json` 的 `description` / `descriptionZh` / `descriptionJa`，按 `getLanguage()` 取对应语言。 +- exclude 描述：从 `static-rules.json` pmd 段（273 条）按规则名查询；查不到的仅保留名字、不加注释。 +- 链接：**每个文件仅 1 个**"全部可用规则"索引链接，位于文件头注释块；逐条注释不含链接。 +- 注释语言：跟随 `ai.outputLanguage`（`getLanguage()`），三语切换。 + +### 3.5 setupView 改造（`src/views/setupView.ts`） + +- `ADAPTER_METADATA` 的 `configFileTemplate` 类型：`() => string` → `() => string | Promise`。 +- 4 个模板函数全部委托给 `builtin-rules` 生成函数（删掉 `getEslintTemplate` / `getStylelintTemplate` / `getSqlfluffTemplate` / `getPmdRulesetTemplate` 的示例内容）。 +- `handleAdapterConfig`（`setupView.ts:1231`）： + ```typescript + const content = await meta.configFileTemplate(); + fs.writeFileSync(filePath, content, 'utf-8'); + ``` +- PMD 规则集读取路径（复用 `pmd.ts:26-44` 的解析逻辑）： + `ext.extensionPath/jars/pmd/pmd-java-ruleset.xml`，找不到时回退到 `out/jars` / 源码相对路径。 +- SQLFluff 方言：固定 `mysql`（用户已确认接受）。 + +### 3.6 adapter 常量抽取（`eslint.ts` / `stylelint.ts` / `sqlfluff.ts`） + +| 文件 | 迁出常量 | 改为 | +|------|---------|------| +| `src/adapters/eslint.ts` | `extraRules` / `extraTsRules` | `import { eslintExtraRules, eslintExtraTsRules } from '../rules/builtin-rules'` | +| `src/adapters/stylelint.ts` | `extraRules` | `import { stylelintExtraRules } from '../rules/builtin-rules'` | +| `src/adapters/sqlfluff.ts` | `BUILTIN_SQLFLUFF_RULES` / `buildBuiltinConfig` | 从 `builtin-rules` 导入 | + +### 3.7 static-rules.json 补充（`src/rules/static-rules.json`） + +- **stylelint**：补写 34 条 recommended 规则的三语描述（`annotation-no-unknown`、`at-rule-no-unknown`、`block-no-empty` 等），使 stylelint 段达到 68 条全覆盖（41 recommended + 27 extra）。 +- **sqlfluff**：补 `core` 规则组条目（如"SQLFluff 核心规则组（稳定、跨方言的语法类基础规则）"），使内置 26 项均有描述。 + +### 3.8 i18n 帮助文案（`src/i18n/messages.ts:515-549`） + +更新 4 个 `setup.adapter.*Help` 文案，核心变化： +- 说明「创建项目配置将生成与内置一致的规则文件（含三语规则注释）」。 +- ESLint 文案补充：生成文件仅含 JS 内置规则；TS 项目如需 TS 专项规则，自行安装 `typescript-eslint` 并参考文件头注释追加。 + +## 4. 关键接口定义 + +```typescript +// src/rules/builtin-rules.ts +export const eslintExtraRules: Record; +export const eslintExtraTsRules: Record; +export const stylelintExtraRules: Record; +export const BUILTIN_SQLFLUFF_RULES: string; +export function buildBuiltinSqlfluffConfig(dialect: string): string; +export function getRuleDescription(linter: string, ruleId: string, lang: Language): string | undefined; +export function buildEslintProjectConfigText(lang: Language): string; +export function buildStylelintProjectConfigText(lang: Language): Promise; +export function buildSqlfluffProjectConfigText(dialect: string, lang: Language): string; +export function buildPmdProjectRulesetText(lang: Language): Promise; + +// src/views/setupView.ts（改造） +type ConfigFileTemplate = () => string | Promise; +``` + +## 5. 文件变更清单 + +| 类型 | 文件 | 说明 | +|------|------|------| +| 新建 | `src/rules/builtin-rules.ts` | 共享常量 + 描述查询 + 4 个生成函数 | +| 修改 | `src/adapters/eslint.ts` | 常量改为从 builtin-rules 导入 | +| 修改 | `src/adapters/stylelint.ts` | 常量改为从 builtin-rules 导入；修复既有 CJS/ESM 加载 bug（`stylelint-config-recommended` 为纯 ESM，顶层静态 import 改动态 import） | +| 修改 | `src/adapters/sqlfluff.ts` | 内置清单/构建函数改为从 builtin-rules 导入 | +| 修改 | `src/views/setupView.ts` | 模板函数委托 + configFileTemplate 异步化 + handleAdapterConfig await | +| 修改 | `src/rules/static-rules.json` | stylelint 补 34 条、sqlfluff 补 core、pmd 补 22 条 exclude 规则描述 | +| 修改 | `src/i18n/messages.ts` | 4 个 adapter help 文案更新 | +| 修改 | `docs/superpowers/specs/2026-08-06-builtin-config-template-design.md` | 本设计书 | + +> 实现期发现并修复：`src/adapters/stylelint.ts` 顶层 `import stylelint-config-recommended`（纯 ESM 包）在 CJS 编译下必然报 "No exports main"，属既有 bug，阻塞测试套件。已改为动态 `import`（与 `getModule()` 加载 stylelint 一致）。 +> +> 实际规则数量：ESLint 内置 JS 为 **92 条**（js recommended 61 + extra 31，方案初稿误记为 93/32）；Stylelint **68 条**；SQLFluff **26 项**；PMD **37 处 exclude 全部可注释**（补写了 22 条缺失描述）。 + +## 9. 验证反馈修复（2026-08-06） + +安装 VSIX 实测发现并修复 3 个问题： + +1. **PMD「创建项目配置」不生成文件**：`resolvePmdRulesetPath` 原用 `path.resolve(__dirname, '..', '..', 'jars', ...)`，在 esbuild 打包后 `__dirname` = `/out`，该路径多退一级找不到 `jars/`（开发时 `out/rules/` 下退两级才正确）。改为从 `__dirname` 逐级向上探测 5 级目录 + `getExtension` 路径，兼容打包/开发两种布局。 +2. **生成的配置里部分注释为 `?`**：新增的 57 条规则描述（stylelint 34 + sqlfluff core + pmd 22）经 PowerShell 管道 `$s | node` 注入 `static-rules.json` 时，中文被 `$OutputEncoding`（ASCII）破坏成字面 `?`。改用 UTF-8 落盘的 .mjs 脚本重写这 57 条 `descriptionZh/descriptionJa` 修复。 +3. **生成的 eslint.config.js / .stylelintrc.js 被插件静态分析报 `[eslint:no-undef] 'module' is not defined`**：两个配置文件是 CommonJS（`module.exports`），内置规则含 `no-undef` 且未声明 Node 全局。在两个生成文件首行加 `/* global module */` 消除误报。 + +另：本仓库根目录因安装验证生成的 `eslint.config.js` 会覆盖仓库自身 lint 配置（致 146 个 no-undef），为测试产物已删除。 + +## 6. 影响范围 + +- 仅影响「创建项目配置」的文件内容与 Setup 面板帮助文案。 +- adapter 运行逻辑不变（仅常量来源变化，行为一致）。 +- 生成的配置文件位于用户项目根目录，不影响本仓库运行。 + +## 7. 验证方案 + +1. `npm run lint` — ESLint 自检 +2. `npm run compile` — tsc 编译 +3. `npm test` — @vscode/test-cli 运行测试 +4. 手工验证：打开 Setup 面板 → 点击 4 个适配器的「创建项目配置」→ 检查生成内容与 §3.3 示例一致、注释随语言切换。 + +## 8. 已知取舍 + +| 项 | 说明 | +|----|------| +| ESLint 仅 JS | TS 项目使用生成配置后，ESLint 用默认 espree 解析 `.ts` 会产生语法解析错误；文件头注释给出追加 `typescript-eslint` 的示例引导。 | +| SQLFluff 方言固定 mysql | 插件设置留空时内置回退方言为 oracle/ansi，与生成文件有差异（用户已确认接受）。 | +| PMD 类别级注释 | 不展开 274 条逐条 ``，保持类别引用结构，注释以 7 类 + 41 处 exclude 为粒度。 | +| 快照行为 | 生成文件 = 内置规则快照；插件日后升级改内置规则时，已生成的项目文件不会自动同步（项目配置优先级最高）。 | + +## 9. 排除范围（非本期） + +- Setup 面板「规则目录」UI（查→复制→粘贴）。 +- 各工具全量规则枚举（超出内置子集的规则）。 +- ESLint TS 专项规则生成。 diff --git a/images/icon.png b/images/icon.png index ba64184..87cae8b 100644 Binary files a/images/icon.png and b/images/icon.png differ diff --git a/src/adapters/eslint.ts b/src/adapters/eslint.ts index a83c921..4b9e392 100644 --- a/src/adapters/eslint.ts +++ b/src/adapters/eslint.ts @@ -7,57 +7,7 @@ import ts from 'typescript-eslint'; import type { LinterAdapter, AdapterResult, LinterDiagnostic } from './adapter'; import { getEslintConfigPath } from '../config'; import { t } from '../i18n/messages'; - -const extraRules: Record = { - 'eqeqeq': 'error', - 'no-eq-null': 'error', - 'no-self-compare': 'error', - 'no-promise-executor-return': 'error', - 'no-shadow': 'error', - 'no-unassigned-vars': 'error', - 'no-useless-assignment': 'error', - 'block-scoped-var': 'error', - 'default-case': 'error', - 'default-case-last': 'error', - 'no-unmodified-loop-condition': 'error', - 'no-unreachable-loop': 'error', - 'no-eval': 'error', - 'no-extend-native': 'error', - 'no-var': 'error', - 'no-await-in-loop': 'warn', - 'prefer-template': 'warn', - 'prefer-object-spread': 'warn', - 'prefer-rest-params': 'warn', - 'prefer-spread': 'warn', - 'prefer-object-has-own': 'warn', - 'no-useless-concat': 'warn', - 'no-useless-return': 'warn', - 'no-useless-computed-key': 'warn', - 'no-useless-rename': 'warn', - 'no-param-reassign': 'warn', - 'no-return-assign': 'error', - 'no-throw-literal': 'error', - 'camelcase': 'warn', - 'new-cap': 'warn', - 'no-array-constructor': 'error', -}; - -const extraTsRules: Record = { - '@typescript-eslint/no-non-null-assertion': 'error', - '@typescript-eslint/no-dynamic-delete': 'error', - '@typescript-eslint/no-useless-empty-export': 'error', - '@typescript-eslint/consistent-type-imports': 'error', - '@typescript-eslint/unified-signatures': 'error', - '@typescript-eslint/no-extraneous-class': 'warn', - '@typescript-eslint/no-useless-constructor': 'warn', - '@typescript-eslint/no-non-null-asserted-nullish-coalescing': 'error', - '@typescript-eslint/no-invalid-void-type': 'warn', - '@typescript-eslint/prefer-literal-enum-member': 'warn', - '@typescript-eslint/prefer-enum-initializers': 'warn', - 'no-shadow': 'off', - '@typescript-eslint/no-shadow': 'error', - 'no-array-constructor': 'off', -}; +import { eslintExtraRules, eslintExtraTsRules } from '../rules/builtin-rules'; const TS_FILES = ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts']; @@ -126,8 +76,8 @@ export class ESLintAdapter implements LinterAdapter { ESLintAdapter.defaultConfig = [ js.configs.recommended, ...ts.configs.recommended, - { rules: extraRules }, - { files: TS_FILES, rules: extraTsRules }, + { rules: eslintExtraRules }, + { files: TS_FILES, rules: eslintExtraTsRules }, ]; } return ESLintAdapter.defaultConfig; diff --git a/src/adapters/sqlfluff.ts b/src/adapters/sqlfluff.ts index 2612cee..2da2d16 100644 --- a/src/adapters/sqlfluff.ts +++ b/src/adapters/sqlfluff.ts @@ -7,6 +7,7 @@ import type { LinterAdapter, AdapterResult, LinterDiagnostic, Severity } from '. import { getSqlFluffConfigFile, getSqlFluffDialect } from '../config'; import { t } from '../i18n/messages'; import staticRules from '../rules/static-rules.json'; +import { BUILTIN_SQLFLUFF_RULES, buildBuiltinSqlfluffConfig } from '../rules/builtin-rules'; const DIALECT_MAP: Record = { sql: 'oracle', @@ -20,19 +21,6 @@ const SUPPORTED_DIALECTS = [ 'soql', 'sparksql', 'sqlite', 'starrocks', 'teradata', 'trino', 'tsql', 'vertica', ]; -const BUILTIN_SQLFLUFF_RULES = - 'core,AM03,AM05,AM08,CV01,CV02,CV06,CV08,CV12,LT13,LT14,LT15,ST01,ST02,ST04,ST05,ST06,ST07,ST09,ST10,ST11,ST12,RF02,RF04,RF05,RF06'; - -function buildBuiltinConfig(dialect: string): string { - return `[sqlfluff] -rules = ${BUILTIN_SQLFLUFF_RULES} -dialect = ${dialect} -max_line_length = 80 -indent_unit = space -tab_space_size = 4 -`; -} - interface RuleEntry { id: string; description: string; tier?: string; } const tierMap = new Map(); @@ -156,7 +144,7 @@ export class SqlFluffAdapter implements LinterAdapter { } else if (hasProjectSqlfluffConfig(workingDir)) { } else { tempConfigPath = path.join(os.tmpdir(), `vscode-code-reviewer-sqlfluff-${Date.now()}.cfg`); - fs.writeFileSync(tempConfigPath, buildBuiltinConfig(cliDialect ?? fallbackDialect), 'utf-8'); + fs.writeFileSync(tempConfigPath, buildBuiltinSqlfluffConfig(cliDialect ?? fallbackDialect), 'utf-8'); configPath = tempConfigPath; } diff --git a/src/adapters/stylelint.ts b/src/adapters/stylelint.ts index 18a0bb6..ab20cc0 100644 --- a/src/adapters/stylelint.ts +++ b/src/adapters/stylelint.ts @@ -3,7 +3,7 @@ import * as fs from 'fs'; import * as path from 'path'; import type { LinterAdapter, AdapterResult, LinterDiagnostic, Severity } from './adapter'; import { getStylelintConfigPath } from '../config'; -import recommendedConfig from 'stylelint-config-recommended'; +import { stylelintExtraRules } from '../rules/builtin-rules'; const CONFIG_FILE_NAMES = [ '.stylelintrc', @@ -16,48 +16,18 @@ const CONFIG_FILE_NAMES = [ 'stylelint.config.cjs', ]; -const extraRules: Record = { - 'color-no-invalid-hex': true, - 'function-linear-gradient-no-nonstandard-direction': true, - 'function-no-unknown': true, - 'unit-no-unknown': true, - 'no-unknown-animations': true, - 'no-unknown-custom-media': true, - 'no-unknown-custom-properties': true, - - 'at-rule-no-vendor-prefix': true, - 'media-feature-name-no-vendor-prefix': true, - 'property-no-vendor-prefix': true, - 'selector-no-vendor-prefix': true, - 'value-no-vendor-prefix': true, - - 'color-hex-length': 'short', - 'color-function-notation': 'modern', - 'length-zero-no-unit': true, - 'selector-pseudo-element-colon-notation': 'double', - 'import-notation': 'string', - 'alpha-value-notation': 'number', - 'hue-degree-notation': 'angle', - 'keyframe-selector-notation': 'percentage', - - 'declaration-block-no-redundant-longhand-properties': true, - 'shorthand-property-no-redundant-values': true, - 'block-no-redundant-nested-style-rules': true, - - 'color-named': 'never', - 'font-family-name-quotes': 'always-where-required', - - 'number-max-precision': 4, - 'comment-whitespace-inside': 'always', -}; - -const DEFAULT_CONFIG: Record = { - ...(recommendedConfig as Record), - rules: { - ...((recommendedConfig as Record).rules as Record), - ...extraRules, - }, -}; +async function getDefaultConfig(): Promise> { + const mod = await import('stylelint-config-recommended'); + const recommendedConfig = (mod.default ?? mod) as Record; + const recommendedRules = (recommendedConfig.rules ?? {}) as Record; + return { + ...recommendedConfig, + rules: { + ...recommendedRules, + ...stylelintExtraRules, + }, + }; +} interface LinterOptions { code?: string; @@ -121,7 +91,7 @@ export class StylelintAdapter implements LinterAdapter { if (globalPath && globalPath.trim() !== '') { lintOptions.configFile = globalPath; } else if (!hasExternalConfig(workingDir)) { - lintOptions.config = DEFAULT_CONFIG; + lintOptions.config = await getDefaultConfig(); } const result = await stylelint.lint(lintOptions); diff --git a/src/i18n/messages.ts b/src/i18n/messages.ts index 75b9848..adb9fbc 100644 --- a/src/i18n/messages.ts +++ b/src/i18n/messages.ts @@ -193,29 +193,29 @@ const messages: Record> = { ja: 'クイックスタート', }, 'setup.gettingStarted': { - 'zh-CN': '三步启用代码审核', - en: '3 Steps to Enable Code Review', - ja: '3ステップでコードレビューを有効化', + 'zh-CN': '三步开始使用', + en: '3 Steps to Get Started', + ja: '3ステップで使い始める', }, 'setup.step1': { - 'zh-CN': '安装插件后，配置 AI 模型及 API Key，激活智能审核能力', - en: 'After installing, configure AI model and API Key to activate intelligent review', - ja: 'インストール後、AIモデルとAPIキーを設定してインテリジェントレビューを有効化', + 'zh-CN': '插件已内置 Linter 静态分析，开箱即用，也可在共通规则中配置项目/全局规则', + en: 'The extension includes built-in Linter static analysis, ready to use out of the box, and you can also configure project/global rules in Common Rules', + ja: '拡張機能にはLinter静的解析が組み込まれており、そのまま利用できるほか、共通ルールでプロジェクト/グローバルルールも設定できます', }, 'setup.step2': { - 'zh-CN': '启用 自定义规则，补充团队特有的编码规范', - en: 'Enable custom rules to add team-specific coding standards', - ja: 'カスタムルールを有効にしてチーム固有のコーディング規約を追加', + 'zh-CN': '在 自定义规则 标签页导入团队编码规范，增强审查（可选）', + en: 'Import team coding standards in the Custom Rules tab to enhance reviews (optional)', + ja: 'カスタムルールタブでチームのコーディング規約をインポート（任意）', }, 'setup.step3': { - 'zh-CN': '保存并测试连接，验证配置无误后即可触发审核', - en: 'Save and test connection, verify config then trigger review', - ja: '保存して接続テスト、設定を確認してレビューを開始', + 'zh-CN': '配置 AI 模型与 API Key 并保存并测试连接，启用 AI 深度审查', + en: 'Configure AI model & API Key and save & test the connection to enable deep AI review', + ja: 'AIモデルとAPIキーを設定し保存して接続テスト、AI詳細レビューを有効化', }, 'setup.step3Hint': { - 'zh-CN': '按 Ctrl + Shift + R 快捷键触发审核，结果实时显示在 审核结果报告页面中', - en: 'Press Ctrl + Shift + R to trigger review, results appear in the Review Report panel', - ja: 'Ctrl + Shift + R でレビューを実行、結果はレビューレポートに表示', + 'zh-CN': '按 Ctrl + Shift + R 触发完整审核，结果实时显示在审核结果报告页面', + en: 'Press Ctrl + Shift + R to run a full review, results appear in the Review Report panel', + ja: 'Ctrl + Shift + R で完全なレビューを実行、結果はレビューレポートに表示', }, 'setup.aiConnectionConfig': { 'zh-CN': 'AI 连接配置', @@ -407,6 +407,11 @@ const messages: Record> = { en: 'Auto-selects config by priority: Built-in < Global < Project', ja: '優先順位に従って自動選択: 組み込み < グローバル < プロジェクト', }, + 'setup.adapter.modeLegendHelp': { + 'zh-CN': '三种配置来源的含义：\n· 内置规则：插件自带的规则集，开箱即用，无需配置\n· 全局配置：在 VS Code 设置中指定的文件路径，对所有项目生效\n· 项目配置：项目根目录下的配置文件，仅对当前项目生效\n\n优先级：内置 < 全局 < 项目，插件自动选择优先级最高的可用配置', + en: 'What the three config sources mean:\n· Built-in rules: bundled with the extension, work out of the box\n· Global config: a file path set in VS Code settings, applies to all projects\n· Project config: a config file in the project root, applies to the current project only\n\nPriority: Built-in < Global < Project; the highest-priority available source is used', + ja: '3つの設定ソースの意味：\n· 組み込みルール：拡張機能に同梱のルール、設定不要ですぐに使用可\n· グローバル設定：VS Code設定で指定したファイルパス、全プロジェクトに適用\n· プロジェクト設定：プロジェクト直下の設定ファイル、現在のプロジェクトのみに適用\n\n優先度：組み込み < グローバル < プロジェクト、利用可能な中で最優先のものを自動選択', + }, 'setup.adapter.configYes': { 'zh-CN': '已配置', en: 'Configured', @@ -507,40 +512,40 @@ const messages: Record> = { en: 'Java (including Java code in JSP, e.g. <% ... %>)', ja: 'Java（JSP内のJavaコードを含む、例: <% ... %>）', }, - 'setup.adapter.pmdGuide': { - 'zh-CN': '需要 Java 运行环境；项目根目录创建 ruleset.xml 或在设置中配置 pmd.rulesetPath', - en: 'Requires Java runtime; create ruleset.xml in project root or set pmd.rulesetPath in settings', - ja: 'Java実行環境が必要。プロジェクトルートにruleset.xmlを作成するか、設定でpmd.rulesetPathを設定してください', + 'setup.adapter.pmdHelp': { + 'zh-CN': 'PMD 由 Java 编写，需先安装 Java 运行环境（JDK 8+），否则无法执行。\n\n插件已内置一套 PMD 规则集（7 类 274 条），安装 Java 后即可开箱使用，无需额外配置。\n点击「创建项目配置」，会在项目根目录生成 ruleset.xml，内容与插件内置规则集完全一致（含每类规则的说明注释），方便查看与调整审查范围。\n保存文件即自动生效，无需重启。\n\n若多个项目共用同一份规则，可点「修改全局设置」，在 pmd.rulesetPath 中填写该文件路径', + en: 'PMD is written in Java, so a Java runtime (JDK 8+) must be installed first.\n\nThe extension ships a built-in PMD ruleset (7 categories, 274 rules), usable right after installing Java.\nClick "Create Project Config" to generate ruleset.xml in the project root, identical to the built-in ruleset (including per-category comment descriptions) for review and adjustment.\nChanges take effect on save, no restart needed.\n\nTo share one ruleset across projects, click "Modify Global Settings" and set pmd.rulesetPath', + ja: 'PMDはJava製のため、まずJava実行環境（JDK 8+）のインストールが必要です。\n\n拡張機能にはPMDルールセット（7カテゴリ・274ルール）が同梱されており、Java導入後すぐに利用できます。\n「プロジェクト設定を作成」をクリックすると、プロジェクト直下にruleset.xmlが生成されます。内容は組み込みルールセットと完全一致し（カテゴリごとの説明コメント付き）、確認・調整が可能です。\n保存後すぐに反映され、再起動は不要です。\n\n複数プロジェクトで同じルールを共有する場合、「グローバル設定を変更」でpmd.rulesetPathを設定してください', }, 'setup.adapter.sqlLanguages': { 'zh-CN': 'SQL', en: 'SQL', ja: 'SQL', }, - 'setup.adapter.sqlGuide': { - 'zh-CN': '需要 Python 环境和 sqlfluff；运行 pip install sqlfluff，项目根目录创建 .sqlfluff', - en: 'Requires Python and sqlfluff; run pip install sqlfluff, create .sqlfluff in project root', - ja: 'Python環境とsqlfluffが必要。pip install sqlfluff を実行し、プロジェクトルートに.sqlfluffを作成してください', + 'setup.adapter.sqlHelp': { + 'zh-CN': 'SQLFluff 是 Python 命令，需先安装 Python 环境与 sqlfluff（pip install sqlfluff），否则无法执行。\n\n插件已内置一套 SQLFluff 精选规则（26 项），安装后即可开箱使用，无需额外配置。\n点击「创建项目配置」，会在项目根目录生成 .sqlfluff，内容与插件内置配置一致（含每条规则的说明注释，以及 rules = all 的启用提示），方便查看与调整。\n保存文件即自动生效，无需重启。\n\n若多个项目共用同一份配置，可点「修改全局设置」填写全局路径', + en: 'SQLFluff is a Python command; install Python and sqlfluff (pip install sqlfluff) first.\n\nThe extension ships built-in SQLFluff curated rules (26 items), usable right after install.\nClick "Create Project Config" to generate .sqlfluff in the project root, identical to the built-in config (including per-rule comment descriptions and a rules = all hint) for review and adjustment.\nChanges take effect on save, no restart needed.\n\nTo share one config across projects, click "Modify Global Settings" and set the global path', + ja: 'SQLFluffはPython製コマンドのため、まずPython環境とsqlfluff（pip install sqlfluff）が必要です。\n\n拡張機能にはSQLFluff精選ルール（26項目）が同梱されており、インストール後すぐに利用できます。\n「プロジェクト設定を作成」をクリックすると、プロジェクト直下に.sqlfluffが生成されます。内容は組み込み設定と一致し（ルールごとの説明コメントとrules = allのヒント付き）、確認・調整が可能です。\n保存後すぐに反映され、再起動は不要です。\n\n複数プロジェクトで同じ設定を共有する場合、「グローバル設定を変更」でパスを設定してください', }, 'setup.adapter.eslintLanguages': { 'zh-CN': 'JS, TS, JSX, TSX（含 JSP 中的 JavaScript 代码，例如