2026Technology-Competition/data/demo-sqlfluff/reports/demo-sqlfluff-coverage-report.md

# demo-sqlfluff 插件实测覆盖率报告

> **工程**：`demo-sqlfluff`（11 个 SQL 样例文件，无 `.sqlfluff` 工程配置 → 插件回退内置配置）
> **测试对象**：插件 SQLFluff 适配器（实测方言 ansi，内置规则集 `core` + 25 条精选 = 57 条，`max_alias_length = 30`）
> **实测日期**：2026-08-25
> **比对基线**：sqlfluff 4.3.0 + 插件内置配置逐字复刻（比对键 = 规则码 + 行号）

---

## 一、核心结论

| 指标 | 结果 | 状态 |
|---|---|---|
| 规则覆盖率（内置启用 57 条） | **57/57 种全部触发（100%）** | ✅ 全覆盖 |
| 诊断总数 | **113 处**（与基线完全一致） | ✅ |
| 逐条一致性（规则 + 行号） | **113/113 条完全一致（零偏差）** | ✅ |
| 解析错误（PRS） | **0 处** | ✅ |
| 插件缺陷 | **0 个**（JJ01 行号缺陷已修复并复测验证） | ✅ |

**实测完全达成全覆盖基准**：插件在「工程无配置文件 → 回退内置配置」路径下，内置启用的 57 条规则全部触发、113 处诊断与模拟基线逐条零偏差。此前发现的 **JJ01 行号显示 LNaN 缺陷已修复**——适配器对 sqlfluff JSON 中缺失 `end_line_no` 字段的回退已生效，复测 `08_jinja.sql` 确认 JJ01 正确显示为 `L2`。**SQLFluff 适配器静态分析链路验证通过，缺陷清零。**

---

## 二、逐文件比对（实测 vs 基线）

| 文件 | 实测 | 基线 | 一致性 | 覆盖规则 |
|---|---:|---:|---|---|
| `01_aliasing.sql` | 9 | 9 | ✅ 逐条一致 | AL02/AL04/AL05/AL08/AL09/AL10、AM05、LT02、LT12 |
| `02_ambiguity.sql` | 10 | 10 | ✅ 逐条一致 | AM01/AM02/AM03/AM05/AM06/AM08、AL05、LT02、LT12 |
| `03_caps.sql` | 25 | 25 | ✅ 逐条一致 | CP01-CP05、AL03、LT12 |
| `04_convention.sql` | 13 | 13 | ✅ 逐条一致 | CV01-CV06/CV08/CV12、AM05、LT02、ST11、LT12 |
| `05_layout.sql` | 12 | 12 | ✅ 逐条一致 | LT01/LT02/LT05-LT08/LT11/LT12、AM02 |
| `05b_layout_misc.sql` | 3 | 3 | ✅ 逐条一致 | LT14、LT15、LT12 |
| `05c_file_boundaries.sql` | 2 | 2 | ✅ 逐条一致 | LT13、LT12 |
| `06_references.sql` | 8 | 8 | ✅ 逐条一致 | RF01/RF02/RF04/RF05/RF06、AM05、LT02、LT12 |
| `07_structure.sql` | 28 | 28 | ✅ 逐条一致 | ST01-ST12、LT01/LT02/LT05/LT08/LT10、AL03/AL08、AM05、RF04、LT12 |
| `08_jinja.sql` | 2 | 2 | ✅ 逐条一致 | JJ01（L2，复测确认修复生效）、LT12 |
| `09_aliasing_length.sql` | 1 | 1 | ✅ 逐条一致 | AL06 |
| **合计** | **113** | **113** | **✅ 零偏差（113/113）** | **57/57 种** |

> 比对方法：将插件报告中每条静态诊断（规则码 + 行号）与基线做多重集合比对；11 个文件全部 `missing = 0`、`extra = 0`（含 JJ01 行号缺陷修复后的复测确认）。

---

## 三、规则分组覆盖（57/57 = 100%）

| 分组 | 规则数 | 触发规则明细 |
|---|---:|---|
| AL（aliasing 别名） | 8 | AL02、AL03、AL04、AL05、AL06、AL08、AL09、AL10 |
| AM（ambiguous 歧义） | 6 | AM01、AM02、AM03、AM05、AM06、AM08 |
| CP（capitalisation 大小写） | 5 | CP01、CP02、CP03、CP04、CP05 |
| CV（convention 约定） | 8 | CV01、CV02、CV03、CV04、CV05、CV06、CV08、CV12 |
| JJ（jinja 模板） | 1 | JJ01 |
| LT（layout 布局） | 12 | LT01、LT02、LT05、LT06、LT07、LT08、LT10、LT11、LT12、LT13、LT14、LT15 |
| RF（references 引用） | 5 | RF01、RF02、RF04、RF05、RF06 |
| ST（structure 结构） | 12 | ST01-ST12 全部 |

**严重级别**：113 处全部为 error（🔴）——内置启用的 57 条规则在插件分级表中均为 P0/P1 级（P0 × 32 + P1 × 25），与实测全 error 一致。

**诊断分布**：`07_structure.sql` 28 处最多，其次 `03_caps.sql` 25 处、`04_convention.sql` 13 处、`05_layout.sql` 12 处。

> 注：插件报告中另有 AI 审查建议 29 条（03_caps 4 / 05_layout 4 / 01_aliasing 3 / 02_ambiguity 3 / 06_references 3 / 09_aliasing_length 3 / 05b 2 / 05c 2 / 07_structure 2 / 04_convention 2 / 08_jinja 1），属 AI 增强能力，不计入静态规则覆盖口径。

---

## 四、全覆盖的达成要点

内置规则集（`core` 组 31 条 + 精选追加 25 条，合并去重 57 条）中有两条规则需要特别条件，本轮均已触发：

1. **AM02（ambiguous.union，裸 UNION 应写明 DISTINCT/ALL）**：方言门控规则，仅对 ansi/bigquery/mysql/snowflake 等支持 `UNION DISTINCT` 语法的方言生效，oracle 不在白名单。实测机按指引将插件设置 `sqlfluff.dialect` 设为 **ansi**，AM02 在 `02_ambiguity.sql:20` 与 `05_layout.sql:41` 正常触发（若用默认 oracle 方言，该规则不报，覆盖率为 56/57）。
2. **AL06（aliasing.length，别名长度上限）**：内置配置设 `max_alias_length = 30`，由补充样例 `09_aliasing_length.sql` 的 51 字符别名触发（实测报在 L8 别名定义处）。

**实测环境判定**：实测报告路径 `data\demo-sqlfluff\src\` 为单层目录，11 个文件与当前工作区版本一致（`02_ambiguity.sql` 顶部含 5 行方言说明注释、`09_aliasing_length.sql` 存在）；方言判定为 ansi 的依据：AM02 触发 + 全部 113 处行号与 ansi 基线逐条吻合（oracle 基线为 111 处且无 AM02）。

---

## 五、插件缺陷记录：JJ01 行号 LNaN（已修复验证 ✅）

**发现过程**：首轮实测中 `08_jinja.sql` 报告显示 `` `sqlfluff:JJ01` LNaN ``——规则触发正确，但行号显示为 NaN（真实位置 L2）。

**根因链**（已逐环节实证）：

1. **sqlfluff JSON 输出**：JJ01 违规项（jinja 模板类违规）只有 `start_line_no: 2` / `start_line_pos: 1`，**顶层缺失 `end_line_no` / `end_line_pos` 字段**；其余 112 处违规均有完整 end 字段（已对 11 个文件全量验证：缺失 end 字段的违规仅 JJ01 这 1 条）。
2. **插件适配器**（`sqlfluff.ts`）直接计算：`new vscode.Range(v.start_line_no - 1, v.start_line_pos - 1, v.end_line_no - 1, v.end_line_pos - 1)` → end 传入 `undefined - 1 = NaN`。
3. **vscode.Range 构造函数**：`start.isBefore(end)` 对 NaN 比较恒为 false → **交换 start/end** → `range.start` 变成 `Position(NaN, NaN)`。
4. **报告生成器**（`report.ts`）读取 `diag.range.start.line` → `L${NaN + 1}` → 显示 "LNaN"。

**修复方案**（适配器侧对缺失 end 字段回退到 start 坐标）：

```typescript
const endLine = (v.end_line_no ?? v.start_line_no) - 1;
const endPos = (v.end_line_pos ?? v.start_line_pos) - 1;
```

**修复验证**（2026-08-25 复测 `08_jinja.sql`）：

| 项 | 修复前 | 修复后 |
|---|---|---|
| `sqlfluff:JJ01` 行号 | `LNaN` | **`L2`** ✅ |
| 建议文案 | 正常（`Jinja 标签两侧应各有一个空格：{{1}}`） | 正常（新增行号前缀「第2行：」） |
| `sqlfluff:LT12` | L6 ✅ | L6 ✅ |
| 文件诊断合计 | 2 处 | 2 处 ✅ 与基线逐条一致 |

修复后 `08_jinja.sql` 复测 2/2 条与基线（JJ01 L2 + LT12 L6，sqlfluff 4.3.0 复现）逐条一致，demo-sqlfluff 整体升至 **113/113 条零偏差**。

---

## 六、工程数据勘误（coverage_map.json）

实测过程中发现工程自带的 `coverage_map.json` 存在 10 处陈旧行号（工程蓝图数据问题，非插件问题，已修正）：

| 类型 | 涉及条目 | 原因 |
|---|---|---|
| `02_ambiguity.sql` 行号整体 +4 | AM01(2→6)、AM02(16→20)、AM03(28→32)、AM05(38→42, 59→63)、AM06(50→54)、AM08(59→63)、AL05(60→64)、LT02(39→43)、LT12(61→65) | 文件顶部补充 5 行方言说明注释后未同步更新映射 |
| AL06 行号 | 6→8 | sqlfluff 实际报在 FROM 别名定义处（L8），蓝图误记为 SELECT 引用处（L6） |

---

## 七、数据口径说明

| 项 | 说明 |
|---|---|
| 覆盖率口径 | 57 条 = 插件内置配置启用规则数（`core` 组 31 + 精选追加 25，合并去重）；规则触发即计入，与 P0/P1 分级（32+25=57）完全对应 |
| 方言口径 | 实测为 **ansi**（按上轮指引设置）；默认 oracle 下 AM02 不触发（56/57 = 98.2%），属 sqlflutt 方言能力差异而非插件缺陷 |
| 比对引擎 | sqlfluff 4.3.0（4.2.2 实测行为一致：同为 113 处、行号相同、JJ01 同样缺失 end 字段），内置配置逐字复刻插件 `buildBuiltinSqlfluffConfig` |
| 基线数据 | `/data/user/work/results/sqlfluff-final-compare.json`（逐文件比对明细）；`/data/user/work/results/sqlfluff-actual-parsed.json`（实测解析结果） |
| 已知差异 | 无（JJ01 行号缺陷已修复并复测验证：LNaN → L2；113/113 条规则码 + 行号零偏差） |

---

## 八、结论与后续

**demo-sqlfluff 工程的插件实测验证完成**：

1. ✅ 内置规则全覆盖达成（57/57 种 · 113 处 · 零解析错误）
2. ✅ 插件行为零偏差（113/113 条逐条一致，含 JJ01 缺陷修复后的复测确认）
3. ✅ 插件缺陷闭环：JJ01 行号 LNaN → 修复 → 复测验证 L2（发现、定位、修复、验证全流程完成）
4. ✅ 「内置配置回退」路径验证通过（工程无 `.sqlfluff` 配置文件场景）

---

*报告生成于 2026-08-25 · demo-sqlfluff 插件实测 · 比对脚本：`sqlfluff-final-compare.mjs` · 数据：`sqlfluff-final-compare.json`*