check-doc-structure.mjs 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173
  1. #!/usr/bin/env node
  2. /**
  3. * 文档结构校验 —— 防止 Markdown 表格静默失真
  4. *
  5. * 为什么需要这个脚本:
  6. * 2026-10-14 连续两轮评审都发现「表格被空行/blockquote 截断」导致渲染失真,
  7. * 而文件本身"改成功了"。人眼极难发现,必须机器校验。
  8. *
  9. * 检查项:
  10. * 1. 表格被空行或 blockquote 截断(表体中间出现空行/`>` 后仍有 `|` 行)
  11. * 2. 表头被段落文本紧贴(GFM 规范:表格不能打断段落,否则整表不渲染)
  12. * 3. 未闭合的表格行(以 `|` 开头但不以 `|` 结尾)
  13. * 4. 表格列数不一致(数据行列数与表头不符)
  14. *
  15. * 用法:
  16. * node scripts/check-doc-structure.mjs # 检查全部 docs/
  17. * node scripts/check-doc-structure.mjs docs/ 2026-10-14 # 限定路径
  18. *
  19. * 退出码: 0 = 全部通过;1 = 发现问题
  20. */
  21. import { readFileSync, readdirSync } from 'node:fs';
  22. const root = process.argv[2] || 'docs';
  23. const SEP = /^\s*\|[\s:|-]+\|\s*$/;
  24. /**
  25. * 数表格列数。必须先把转义竖线 `\|` 与行内代码里的 `|` 排除,
  26. * 否则 `| a \| b | c |` 会被误判为 4 列(实际 3 列)。
  27. */
  28. function countCols(line) {
  29. // 1. 去掉行内代码段(`...`),其中的 | 不算分隔
  30. const noCode = line.replace(/`[^`]*`/g, '§');
  31. // 2. 转义竖线 → 占位符
  32. const noEsc = noCode.replace(/\\\|/g, '§');
  33. // 3. 去掉首尾竖线后按 | 切分
  34. const t = noEsc.trim().replace(/^\|/, '').replace(/\|$/, '');
  35. return t.split('|').length;
  36. }
  37. /** 收集所有 .md */
  38. function collect(dir) {
  39. const out = [];
  40. const walk = (d) => {
  41. let ents;
  42. try { ents = readdirSync(d, { withFileTypes: true }); } catch { return; }
  43. for (const e of ents) {
  44. const p = `${d}/${e.name}`;
  45. if (e.isDirectory()) walk(p);
  46. else if (e.name.endsWith('.md')) out.push(p);
  47. }
  48. };
  49. walk(dir);
  50. return out;
  51. }
  52. const files = collect(root);
  53. if (!files.length) {
  54. console.log(`[check-doc-structure] ${root} 下无 .md 文件`);
  55. process.exit(0);
  56. }
  57. const problems = [];
  58. for (const file of files) {
  59. const lines = readFileSync(file, 'utf8').split(/\r?\n/);
  60. const codeFenceLines = new Array(lines.length).fill(false);
  61. let fence = null;
  62. // 表格语法只适用于 Markdown 正文;shell 示例中的 `|` 是管道符,不是表格。
  63. for (let i = 0; i < lines.length; i++) {
  64. const match = lines[i].match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
  65. if (fence) {
  66. codeFenceLines[i] = true;
  67. if (
  68. match &&
  69. match[1][0] === fence.char &&
  70. match[1].length >= fence.length &&
  71. match[2].trim() === ''
  72. ) {
  73. fence = null;
  74. }
  75. continue;
  76. }
  77. if (match && (match[1][0] !== '`' || !match[2].includes('`'))) {
  78. codeFenceLines[i] = true;
  79. fence = { char: match[1][0], length: match[1].length };
  80. }
  81. }
  82. for (let i = 0; i < lines.length; i++) {
  83. if (codeFenceLines[i]) continue;
  84. const line = lines[i];
  85. // ---- 检查 2:表头被段落紧贴 ----
  86. if (SEP.test(line) && i >= 2) {
  87. const hdr = lines[i - 1].trim();
  88. const prev = lines[i - 2].trim();
  89. if (hdr.startsWith('|') && prev &&
  90. !prev.startsWith('#') && !prev.startsWith('|') &&
  91. !prev.startsWith('>') && !prev.startsWith('-') &&
  92. !prev.startsWith('*') && !prev.startsWith('`')) {
  93. problems.push({
  94. file, line: i - 1, kind: '表头被段落紧贴',
  95. detail: `表格不会渲染。需在表头前加空行。前文:「${prev.slice(0, 50)}」`,
  96. });
  97. }
  98. }
  99. // ---- 检查 1:表格被空行/blockquote 截断 ----
  100. if (SEP.test(line) && i >= 1 && lines[i - 1].trim().startsWith('|')) {
  101. const cols = countCols(lines[i - 1]);
  102. let j = i + 1;
  103. while (j < lines.length) {
  104. if (codeFenceLines[j]) break;
  105. const s = lines[j].trim();
  106. if (s.startsWith('|')) {
  107. // ---- 检查 4:列数一致性 ----
  108. const n = countCols(lines[j]);
  109. if (n !== cols) {
  110. problems.push({
  111. file, line: j + 1, kind: '表格列数不一致',
  112. detail: `表头 ${cols - 2} 列,本行 ${n - 2} 列`,
  113. });
  114. }
  115. j++;
  116. continue;
  117. }
  118. // 表体中断:空行或 blockquote
  119. if (s === '' || s.startsWith('>')) {
  120. let k = j + 1;
  121. while (k < lines.length && lines[k].trim() === '') k++;
  122. if (k < lines.length && lines[k].trim().startsWith('|')) {
  123. // 中断后仍是表格行 —— 但要区分两种情况:
  124. // a) 新表的正常开始:该行是表头,且下一行是分隔线 → 合法,不是缺陷
  125. // b) 原表的孤立续行:该行之后不是分隔线 → 缺陷(失去表头)
  126. const isNewTable = k + 1 < lines.length && SEP.test(lines[k + 1]);
  127. if (!isNewTable) {
  128. problems.push({
  129. file, line: k + 1, kind: '表格被中断后出现孤立行',
  130. detail: `第 ${j + 1} 行是${s === '' ? '空行' : 'blockquote'},表格在此终止,` +
  131. `但第 ${k + 1} 行仍是表格行且其后无分隔线 → 该行失去表头,渲染为裸文本`,
  132. });
  133. }
  134. }
  135. }
  136. break;
  137. }
  138. }
  139. // ---- 检查 3:未闭合表格行 ----
  140. const t = line.trim();
  141. if (t.startsWith('|') && !t.endsWith('|') && t.length > 1) {
  142. problems.push({
  143. file, line: i + 1, kind: '未闭合的表格行',
  144. detail: `以 | 开头但未以 | 结尾:「${t.slice(0, 60)}」`,
  145. });
  146. }
  147. }
  148. }
  149. if (problems.length) {
  150. console.error(`\n[check-doc-structure] ✗ 发现 ${problems.length} 处结构问题:\n`);
  151. for (const p of problems) {
  152. console.error(` ${p.file}:${p.line}`);
  153. console.error(` [${p.kind}] ${p.detail}\n`);
  154. }
  155. console.error('[check-doc-structure] 提示:Markdown 表格必须连续,说明性内容放表格之后。\n');
  156. process.exit(1);
  157. }
  158. console.log(`[check-doc-structure] ✓ ${files.length} 个文件,表格结构全部正常`);