从《美国宪法》测试语料看 Harper 的快照回归测试机制

从《美国宪法》测试语料看 Harper 的快照回归测试机制【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harperHarper 是一款离线、隐私优先的 Rust 语法检查器。在harper-core/tests/text/目录下The Constitution of the United States.md 是一份 732 行的《美国宪法》Markdown 全文副本它不是给人阅读的文档而是 Harper 词法/语法引擎的“黄金语料”测试框架会对它逐行跑 lint 规则与词性标注把结果固化为快照文件任何规则或标注器行为变化都会让 CI 失败。读完本文你会掌握这份语料文件的结构特征、它驱动的两条快照测试流水线lint 快照与词性标注快照、快照中的具体命中样例以及如何查看和扩展这套测试资产。1. 语料文件本身一份带 Markdown 结构的宪法文本1.1 文件定位与来源该文件位于 宪法语料首行是一条 HTML 注释记录了语料的上游出处一个公开的 USA-Constitution Markdown 仓库随后才是正文。这个来源注释有两个作用一是让维护者可以追溯文本版本二是在词性标注快照中整行注释会被标注器标记为Unlintable并整体跳过不会参与 lint——从 词性标注快照 的第一行输出# Unlintable可以直接验证这一点。1.2 Markdown 标记与原貌保留文件在保留原始文本全部“不完美”特征的同时套了一层简洁的 Markdown 标题结构标题层级# The Constitution Of The United States Of America一级、## Article. I.二级、### Section. 1.三级、#### SubSection. 1.四级完整覆盖原文的条/款/节层级强调开篇 We the People 使用粗体**We the People**有序列表第一条第八款Article I, Section 8把国会 17 项权力征税、借款、管理商务、铸币、设立邮局、宣战、维持军队与海军等排成一个 1~17 的有序列表位于 L207-L261原貌拼写全部保留如chuse、chusing、Behaviour、encreased、Controul、Rhode-Island、New-York、its inspection Laws以及 Article. I. 这种带句点的编号习惯。这些“保留原貌”恰恰是语料的测试价值所在它们会在后面的 lint 快照中产生大量可复现的命中成为引擎回归的锚点。2. 语料如何进入快照测试流水线Harper 有两套互补的测试机制本语料属于其中快照机制精确计数测试run_tests.rs 中的create_test!宏针对tests/test_sources/下的文件断言 lint 总数精确等于预期值如create_test!(whack_bullets.md, 1, Dialect::American)并额外断言每个 token 的 span 都能取到真实字符快照测试针对tests/text/下的长文本语料包括宪法把全部lint 结果或词性标注整体序列化为快照文件比对。宪法语料走的是这条路径。2.1 公共入口snapshot.rssnapshot.rs 提供两条测试线共用的基础设施get_text_files()扫描tests/text/顶层的.txt/.md文件linters/、tagged/等子目录是快照输出目录不会被当作输入重复处理try_get_dialect_override()从文件名主 stem 中解析方言覆盖例如Spell.US.md的.US会解析为美式方言宪法文件名不含方言缩写因此回退到按文档内容自动猜测、再兜底为美式tag_file()核心比对逻辑——重新计算快照内容若与已提交的快照一致则通过不一致或缺失时先写出新快照再返回错误Snapshot mismatches!或No snapshot!。这意味着本地跑一次测试即可再生快照而 CI 会因比对失败而变红从而强制维护者审阅每一处行为变化snapshot_all_text_files()用 rayon 对全部语料文件并行处理任一片段出错则整体 panic。2.2 lint 快照test_most_lintslinters.rs 的test_most_lints对每份语料执行以下流程let dict FstDictionary::curated(); let document Document::new_markdown_default(source, dict); let mut linter LintGroup::new_curated( dict, dialect_override.unwrap_or_else(|| { Dialect::try_guess_from_document(document).unwrap_or(Dialect::American) }), ); let mut lints linter.lint(document); lints.sort_by(|a, b| { a.span.start.cmp(b.span.start).then(a.span.end.cmp(b.span.end)) });关键细节语料按Markdown解析Document::new_markdown_default因此标题、粗体、有序列表的结构信息会进入 token 流直接影响 lint 命中位置lint 按起始/结束偏移排序保证快照顺序稳定可复现每条 lint 输出为Lint:类型与优先级 Message:带行号与^~~下划线的源码上下文由 print_error() 渲染还会智能补一行前/后上下文以跨越句界 可选的Suggest:替换建议。输出写入 宪法 lint 快照共 1851 行。2.3 词性标注快照test_pos_taggerpos_tags.rs 的test_pos_tagger遍历文档的 fat string tokens按 文档注释中定义的格式 输出原文行以开头标签行以#开头标签与对应单词逐字对齐空格、换行忽略段落分隔则输出两行空行。结果写入 宪法词性标注快照共 1514 行。3. Lint 快照剖析语法检查器在宪法上的典型命中这份快照相当于引擎的一次全量“体检记录”。以下按快照中实际出现的类型归纳每条 lint 的优先级数字直接取自快照。3.1 标题与专有名词大写Capitalization优先级 127 的标题 Title Case 检查命中一级标题# The Constitution Of The United States Of America建议改为The Constitution of the United States of America见 快照 L1-L6优先级 31 的专有名词检查多次命中正文中的United States如 L37-L44提示“引用国家或国际组织时应按专有名词处理”#### SubSection. 1.中的SubSection被词典规则建议改写为subsection。3.2 长句可读性Readability优先级 127宪法长句密集快照中数十条 Readability lint 给出精确字数开篇 52 词、112 词、109 词、101 词最极端的一条位于 快照 L879-L912——选举人团那一段被标记为204 词的单句。消息格式固定为 This sentence is N words long.并用下划线横跨整个句子范围可跨行。3.3 拼写Spelling优先级 63语料刻意保留的历史拼写在这里批量命中且每条都附三个候选替换按编辑距离排序命中词位置候选建议chuse/chusing第 64、72、103、125、383 行附近cause / chase / chose 等Behaviour第 139 行Behavior / Behaviorsencreased第 164 行increased / encased / entreatedControul第 315 行Control / Contour / ContrailPiracies/Offences第 229-230 行Pirates / Offenses 等Habeas、facto第 271、274 行Habers / fact 等见例如 chusing 命中。注意Habeas、facto这类拉丁语术语被判为拼写问题——这正是快照测试的价值它把“引擎认为错”的样本全部固化下来供维护者决定是否扩充词典词典资产位于 dictionary.dict测试通过FstDictionary::curated()构建从源码结构看该字典即 lint 判定词形的依据。3.4 风格、一致性与冗余Style31 优先级Oxford comma 检查在 Times, Places and Manner、Trust or Profit、Trial, Judgment and Punishment 等十余处建议插入逗号Agreement第 179 行If he approve he shall sign it被标记主谓不一致建议approves快照 L479-L484第 313 行its inspection Laws被标记应使用所有格itsRedundancyand also a President pro tempore建议简化为andMiscellaneousan uniform Rule的不定冠词被建议改为a快照 L592-L599overall连写复合词检查在 like Authority 附近命中。3.5 暴露“过度纠错”的误报快照的第二价值快照中甚至保留了明显不合理的命中例如 Typo 类规则把拉丁短语pro tempore建议拆成temp ore快照 L250-L268或建议Piracies改为Piracys。这类记录并非文档缺陷而是回归基线一旦某个修复比如把tempore加入词典、或抑制该规则在拉丁短语上的触发改变了输出测试会失败并强制维护者确认每一处差异避免“修好一处、悄悄改变另一处”的隐性回归。4. 词性标注快照逐词对齐的标签输出宪法词性标注快照 的前几行L3-L16 The Constitution Of The United States Of America # Unlintable HeadingStart D NPr P D VP/J NPrPl/V3 P NPr We the People of the United States , in Order to form a more perfect Union , # IPl D NPl/VB P D VP/J NPrPl/V3 . NPr/J/R/P NSg/VB P NSg/VB D/P NPr/I/J/R/Dq NSg/VB/J NPr/VB/J .标签体系由 pos_tags.rs 的注释 完整定义受 Penn Treebank 启发N名词NSg/NPl单复数、NPr专有、NSg可数质量名词、Nᴹ质量名词、I代词、V动词VB原型、VXB助动词、VPp过去分词等、J形容词、R副词、C连词、D限定词、P介词、Dq量化限定等/表示词性不确定如NPrPl/V3既可作复数专有名词也可作第三人称单数动词表示名词短语成员关系。标点为.、数字为#Markdown 标题起始位置会额外出现HeadingStarttoken如 L19-L24 中Article前的标记。由于宪法原文保留了 18 世纪语法he approve、shall be a Senator等标签快照同时覆盖了动词屈折、代词单复数、专名/通名歧义等大量边界情形是标注器词块切分与词性标注模型资产位于 harper-brill/ 等模块从仓库结构看由该包提供最重要的回归语料之一。5. 查看与扩展指南只读参考查看语料与其快照语料在 tests/text/配套快照为 lint 版 .snap.yml 与 词性标注版运行方式在仓库根目录执行cargo test -p harper-core --test linters与cargo test -p harper-core --test pos_tags分别运行两条快照线测试内部并行处理全部语料cargo test -p harper-core --test run_tests运行精确计数线新增语料的约定来自 linters.rs 与 pos_tags.rs 的文件头注释把新文档放入tests/text/后运行测试即会在tests/text/linters与tests/text/tagged自动创建同名快照若文件名 stem 含.US等方言缩写可覆盖自动猜测的方言注意事项快照文件一旦落后于引擎行为测试会失败并在本地写出新内容需人工审阅差异tests/text/下的子目录linters/、tagged/、Difficult sentences等语料不会被当作输入重复扫描。小结这份《美国宪法》Markdown 语料是 Harper 引擎的“长期压力样本”它的 Markdown 结构验证解析器它的长句、古旧拼写、专名与代词歧义全面覆盖了 Capitalization、Readability、Spelling、Style、Agreement、Redundancy 等 lint 家族它的每一处词性标注都被逐字对齐固化。快照机制snapshot.rslinters.rspos_tags.rs保证了引擎的每个行为变化都必须显式通过审阅——这正是 Harper 能在保持离线、零配置的前提下持续演进规则集的测试基石。【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考