# 创建项目配置 = 内置配置（含三语规则注释）— 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 条规则展开为逐条 `<rule>`（保持类别引用结构）。
- 不新增"全量规则枚举"（各工具全部规则目录）。

## 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<string, 'error' | 'warn'>;      // 自 eslint.ts
export const eslintExtraTsRules: Record<string, 'error' | 'warn' | 'off'>; // 自 eslint.ts（生成文件不含，仅 adapter 使用）
export const stylelintExtraRules: Record<string, unknown>;           // 自 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-<version>/pmd_rules_java.html`

// —— 生成函数 ——
export function buildEslintProjectConfigText(lang: Language): string;
export async function buildStylelintProjectConfigText(lang: Language): Promise<string>;
export function buildSqlfluffProjectConfigText(dialect: string, lang: Language): string;
export async function buildPmdProjectRulesetText(lang: Language): Promise<string>;
```

**依赖注入**：
- `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
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="Java Rules"
    xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
    <description>Java Code Review Rules (274 active rules, 7 categories) — 与插件内置规则集一致（由插件生成）</description>
    <!-- 全部可用规则：https://docs.pmd-code.org/pmd-doc-7.26.0/pmd_rules_java.html -->

    <!-- 最佳实践类（避免空 catch、关闭流等） -->
    <rule ref="category/java/bestpractices.xml">
        <!-- 排除：不强制 switch 默认分支位于最后 -->
        <exclude name="DefaultLabelNotLastInSwitchStmt"/>
        <!-- ...（41 处排除项逐条注释） -->
    </rule>
    <!-- 代码风格类（命名规范、花括号位置等） -->
    <rule ref="category/java/codestyle.xml">...</rule>
    <!-- 设计类 / errorprone / multithreading / performance / security 同理 -->
</ruleset>
```

### 3.4 注释策略

| 文件 | 注释粒度 | 内容 |
|------|---------|------|
| `eslint.config.js` / `.stylelintrc.js` | 逐条规则 | `规则码 + 三语描述`（尾行 `//` 注释） |
| `.sqlfluff` | 逐条规则 | `rules =` 行上方注释块（`# 规则码 三语描述`） |
| `ruleset.xml` | 类别级 | 7 个 `<rule>` 类别 + 41 处 `<exclude>`（`<!-- -->`） |

- 描述来源：`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<string>`。
- 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<string, 'error' | 'warn'>;
export const eslintExtraTsRules: Record<string, 'error' | 'warn' | 'off'>;
export const stylelintExtraRules: Record<string, unknown>;
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<string>;
export function buildSqlfluffProjectConfigText(dialect: string, lang: Language): string;
export function buildPmdProjectRulesetText(lang: Language): Promise<string>;

// src/views/setupView.ts（改造）
type ConfigFileTemplate = () => string | Promise<string>;
```

## 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` = `<ext>/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 条逐条 `<rule>`，保持类别引用结构，注释以 7 类 + 41 处 exclude 为粒度。 |
| 快照行为 | 生成文件 = 内置规则快照；插件日后升级改内置规则时，已生成的项目文件不会自动同步（项目配置优先级最高）。 |

## 9. 排除范围（非本期）

- Setup 面板「规则目录」UI（查→复制→粘贴）。
- 各工具全量规则枚举（超出内置子集的规则）。
- ESLint TS 专项规则生成。