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 坐标）：

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