Prettier Markdown 列表缩进规范化解析issue-19146 回归测试与列表打印实现原理【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier本篇以 tests/format/markdown/list/parser-regression/issue-19146.md 这个 3 行的 Markdown 回归测试夹具为核心讲解 Prettier 如何处理列表项前导空白中 Tab 与空格混合的“脏”缩进。读完你能掌握该测试的输入/输出契约、它在 Jest 快照体系中的运行方式以及 src/language-markdown/print/list.js 中前缀计算与“4 空格红线”的源码级实现。一、回归测试用例本体一行 Tab 缩进的嵌套列表issue-19146.md 的全部正文只有 3 行其价值恰恰在于每一行的前导空白都刻意不同- foo - bar - baz逐行拆解其缩进结构\t表示 Tab 字符行前导空白内容特点11 个空格- foo列表项允许最多 3 个前导空格这里只占 1 个23 个空格- bar嵌套层缩进用了 3 空格而非惯常的 2 空格31 个 Tab 1 个空格- bazTab 与空格混用的缩进也就是说这份输入是一个三层嵌套的无序列表foo 包含 barbar 包含 baz但源文件用“空格 1、空格 3、Tab空格”三种不一致的方式表达了层级关系。文件名中的19146对应上游仓库的 issue 编号——该目录 tests/format/markdown/list/parser-regression/ 按命名约定专门归集“解析/打印回归”夹具同目录还有 issue-7474、issue-9314、issue-10063、issue-11202、issue-12677、issue-17778、issue-19152 等兄弟用例。这类测试的意义在于CommonMark 对缩进相当宽容3 个空格以内的前导空白、Tab 的列宽展开规则都可能出现在真实文档中但格式化工具的输出必须是确定且稳定的——同样的嵌套结构无论源文件用空格还是 Tab 表达层级都必须收敛到同一种规范缩进。二、期望输出快照文件中的输入/输出契约该夹具的预期结果固化在 Jest 快照 tests/format/markdown/list/parser-regression/snapshots/format.test.js.snap 中issue-19146.md - {proseWrap:always} format 1条目。快照头部记录的测试选项为parsers: [markdown]、proseWrap: always、printWidth: 80 (default)。输入与输出对照输入 输出 - foo - foo - bar - bar - baz 4 个空格- baz规范化结果体现为三条可验证的规律前导空白被完全重写顶层- foo之前的 1 个空格被去除列表对齐到第 0 列层级缩进收敛为等宽递进第 2 层 2 个空格、第 3 层 4 个空格与默认tabWidth: 2一致——源文件里的“3 空格”和“Tab空格”全部被抹平Tab 被替换为空格输出中不再出现 Tab 字符Prettier 的 Markdown 列表缩进一律以空格表达。三、测试如何运行runFormatTest 与快照机制同目录的 tests/format/markdown/list/parser-regression/format.test.js 只有一行核心代码runFormatTest(import.meta, [markdown], { proseWrap: always });即对当前目录下所有夹具文件以markdownparser 加上proseWrap: always选项执行格式化成对测试并把每次运行的选项、输入、输出写入快照文件。这解释了为什么快照中的输入/输出是逐字匹配的任何一次改动若让- foo / 3 空格 / Tab这组输入产生不同的缩进例如 Tab 被错误保留、或嵌套层级被解析丢失快照比对就会失败从而把回归问题拦在提交之前。本地复验方式在仓库根目录Jest 配置见 jest.config.js针对该目录运行 Jest例如npx jest tests/format/markdown/list/parser-regression即可看到该用例的输入、输出与快照比对结果。四、源码级原理列表打印机如何决定每行的缩进Markdown 打印入口在 src/language-markdown/print/其中列表由 src/language-markdown/print/list.js 的printList/printListItem负责。结合 issue-19146 这个用例可以把输出结果逐行对应回源码逻辑。4.1 前缀生成getPrefix只关心“有序/无序与兄弟序号”printList内部通过闭包函数getPrefix见 src/language-markdown/print/list.js#L56-L90计算每个列表项的标记前缀无序列表根据列表在兄弟节点中的序号奇偶取-或*作为前缀有序列表则按start序号与分隔符./)拼接。对 issue-19146 而言三层列表全部是无序列表每层前缀都是 2 字符的-。关键点在于前缀的计算完全不读取源文件的原始缩进。解析阶段解析管线位于 src/language-markdown/parse/包含 micromark 扩展等模块从源码结构看 Prettier 基于 unified/micromark 系工具产出 AST已经只保留了“foo 是 bar 的父项、bar 是 baz 的父项”这一结构信息- foo的 1 个前导空格、- bar的 3 个前导空格、Tab 的列宽展开都不再参与输出——这正是“Tab 缩进被规范化为 2/4 空格”的根因缩进是由树深度重新生成的而不是从原文继承的。4.2 缩进逐层叠加align文档构造器每层列表项的内容被包裹在文档构造器align中src/language-markdown/print/list.js#L48-L54align定义于 src/document/builders/align.jsreturn [ prefix, align( .repeat(prefix.length), printListItem(path, options, print, prefix), ), ];语义是为列表项内容的每一行叠加“前缀长度”的列偏移。issue-19146 的三层结构因此产生递进偏移——顶层项偏移 0第二层列表位于第一项内容内继承 2 列偏移后自身前缀又贡献 2 列得到- bar第三层再叠加 2 列得到 4 空格的- baz。输出中 2/4 空格的等差递进就是“每层前缀长度 2”沿align链逐层累加的直接结果与源文件用了何种空白字符无关。printListItem内对子节点的处理器src/language-markdown/print/list.js#L95-L117还有第二道对齐钳制const alignment .repeat( clamp(options.tabWidth - listPrefix.length, 0, 3), // 4 will cause indented code block );tabWidth与列表前缀长度之差被钳制在 03 之间本例中2 - 2 0即不再额外补位。4.3 “4 空格红线”为什么补位上限是 3源码中多处出现同一句注释——4 will cause indented code block见 src/language-markdown/print/list.js#L80-L84 与 L110-L112。这是 CommonMark 的硬约束列表项内容相对起始列额外缩进 4 个空格或 Tab时会被解析为缩进代码块。因此打印器在需要为“紧随列表的缩进代码块”让路时requiredIndent函数见 src/language-markdown/print/list.js#L125-L143前缀补位也刻意截断在 34 空格的阈值内避免格式化行为把普通文本意外变成代码块。issue-19146 虽然不触发这条路径但它与 issue-19152.md- foo/-\t\tfoo即标记后过度缩进的输入共同守护着这条边界前者验证“缩进不足/Tab 混用被收敛”后者验证“过度缩进不会导致内容丢失或被误解析为代码块”。4.4 预处理的两个辅助标记打印前AST 会经过 src/language-markdown/print/preprocess.js 的预处理markAlignedListL369-L407为每个列表打isAligned标记对无序列表源码结构上isAligned恒为trueif (!list.ordered) return true而有序列表则依据首两项起始列与tabWidth的关系判定是否“对齐式缩进”。由于alignListPrefix前缀补齐到tabWidth倍数只在isAligned node.ordered时启用issue-19146 的三层无序列表走的是普通前缀路径输出保持简洁的-前缀transformIndentedCodeblockL255-L271用/^\n?(?: {4,}|\t)/识别以 4 空格或 Tab 起始的代码节点并标记isIndented为上文“4 空格红线”提供解析侧依据。五、小结一份 3 行夹具守护的格式契约issue-19146 用最小的输入覆盖了一个高价值契约Markdown 列表的层级结构以解析出的 AST 为准缩进由tabWidth和前缀长度按层重新生成源文件中的前导空格、3 空格缩进、Tab空格混合缩进均不会泄漏到输出中。配合快照文件snapshots/format.test.js.snap与 format.test.js 的runFormatTest配置它能在每次 CI 中自动验证该契约。若要进一步研究可以沿着本文引用的 print/list.js、print/preprocess.js 与 print/children.js 继续深入 Prettier 的 Markdown 打印管线。【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考