@cloud411716/fancy-webnovel 1.0.45 → 2.2.0

package/plugins/fancy-story-builder/scripts/check-guide-compliance.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+/**
+ * check-guide-compliance.js  v1.2
+ * 源码中零反引号。
+ *
+ * v1.2 变更（修复批次 P2-2 / P2-3 + 消除字面反引号）：
+ * - 原版 RANGE_SKIP_KEYWORDS、错误代码正则、字符串字面量中含字面反引号，
+ *   本身违反本文件检查的规则，且可能破坏 markdown 渲染。
+ *   本版统一用 String.fromCharCode(96) 生成反引号字符与正则。
+ * - P2-2：路径含 audit 的文件豁免 ERROR_CODE_IN_BODY 检查
+ *   （audit 文件本质是错误代码处理手册，错误代码出现在正文是必要的）
+ * - P2-3：路径含 写作指导 的文件豁免 RANGE_IN_GUIDE 检查
+ *   （写作指导明确允许具体字数/章节号作为写法参考）
+ * - ERROR_CODE_ALLOWED_SECTION 补充 audit 文件的主要节
+ *
+ * 检查五条禁令：
+ * 1. 不出现数字区间（示例节、代码块、表格、引用段除外）
+ * 2. 不出现 - [ ] / - [x] 检查清单
+ * 3. 错误代码只允许出现在白名单节（audit 文件整体豁免）
+ * 4. 每个指导文件必须有"与其他文件的关系"节
+ * 5. 不重复枚举值（只检查显式的"X 个值：..."列举模式）
+ *
+ * 用法：
+ *   node check-guide-compliance.js --dir=references/骨架指导
+ *   node check-guide-compliance.js --file=references/骨架指导/01-positioning.md
+ *   node check-guide-compliance.js --dir=references/骨架指导 --glossary=references/glossary.md
+ * 退出码：0=通过  1=有问题  2=脚本异常
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseGlossaryFromMd } from './graph-utils.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ============================================================
+// 反引号字符与正则（零反引号约定）
+// ============================================================
+const BT_CHAR = String.fromCharCode(96);
+const BT_RE_GLOBAL = new RegExp(BT_CHAR, 'g');
+
+// ============================================================
+// 参数解析
+// ============================================================
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = { dir: null, file: null, glossary: null };
+  for (const arg of args) {
+    const m = arg.match(/^--(\w+)=(.+)$/);
+    if (m) result[m[1]] = m[2];
+  }
+  return result;
+}
+
+// ============================================================
+// 路径分类（P2-2 / P2-3）
+// ============================================================
+function classifyPath(filePath) {
+  const norm = filePath.replace(/\\/g, '/');
+  return {
+    isAudit: /\/\d+-audit\.md$/i.test(norm) || /\/audit\.md$/i.test(norm),
+    isWritingGuide: /\/写作指导\//.test(norm)
+  };
+}
+
+// ============================================================
+// 检查规则配置
+// ============================================================
+
+// 注意：示例类关键词（"示例"/"例如"/"比如"）只用于 inExampleSection 的补充，
+// 正文段落中如果写"例如：每卷 5-8 个单元"仍会被报（这是正确行为）
+const RANGE_SKIP_KEYWORDS = [
+  '见 formulas-', '由 formulas-',
+  '见 模板/', '由 模板/',
+  '见 glossary', '由 glossary',
+  '见 ' + BT_CHAR + 'formulas-',
+  '由 ' + BT_CHAR + 'formulas-',
+  '见 ' + BT_CHAR + '模板/',
+  '由 ' + BT_CHAR + '模板/',
+  '见 ' + BT_CHAR + 'glossary'
+];
+
+const RANGE_PATTERNS = [
+  { re: /至少\s*\d+\s*[个条卷章人字次位天]/, label: '至少 N 个' },
+  { re: /至多\s*\d+/, label: '至多 N' },
+  { re: /不超过\s*\d+/, label: '不超过 N' },
+  { re: /不低于\s*\d+/, label: '不低于 N' },
+  { re: /\d+\s*[-~到至]\s*\d+\s*[个条卷章人字次位天]/, label: 'N-M 区间' },
+  { re: /\bceil\(|\bfloor\(/, label: '数学函数' }
+];
+
+// 错误代码前缀
+const ERROR_CODE_PREFIXES = /^(EXTRA_FIELD|REQUIRED|TYPE|PATTERN|ENUM|ENUM_MISSING|ID_DUP|ID_ORPHAN|NAME_DUP|SKELETON_|FLESH_|G_|DERIVATION_|QUANTITY_|CAPACITY_|VOLUME_|SPAN_|RHYTHM_|CHAP_|TIMING|ARC_|XREF|ANTAG_|SELF_|BRANCH_|NODE_|MAIN_|HOOK_|ACT_|FACTION_|ENDING_|BOOK_|LOCATION_|CHARSET_|PLACEHOLDER|ARG|READ|TEMPLATE|GLOSSARY_LOAD|FORMULAS_LOAD|UPSTREAM_|FLESH_GROUP|FLESH_FREETEXT|ENUM_VALUE_|RHYTHM_COVERAGE|RHYTHM_ACT|NO_SELF_RELATION|EMPTY_HARD_CONSTRAINTS|CROSS_TYPE_NAME_DUP)/;
+
+// v1.2：白名单节补充 audit 文件的主要节（双保险，audit 文件也会被整体豁免）
+const ERROR_CODE_ALLOWED_SECTION = /与其他文件的关系|错误代码速查|常见错误|故障排查|BLOCKED|全量校验后的处理|跨文件错误的特殊处理|单文件校验失败的处理|前置检查失败的处理/;
+
+// 错误代码匹配正则（零反引号：用 BT_CHAR 拼接）
+const ERROR_CODE_RE = new RegExp(BT_CHAR + '([A-Z][A-Z_]{2,})' + BT_CHAR, 'g');
+
+// ============================================================
+// 单文件检查
+// ============================================================
+function checkFile(filePath, glossaryEnums) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+
+  const errors = [];
+  const warnings = [];
+
+  const { isAudit, isWritingGuide } = classifyPath(filePath);
+
+  let inCodeBlock = false;
+  let inExampleSection = false;
+  let inErrorCodeAllowedSection = false;
+  let hasRelationSection = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith('```')) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock) continue;
+
+    if (line.startsWith('## ')) {
+      inExampleSection = /示例/.test(line);
+      inErrorCodeAllowedSection = ERROR_CODE_ALLOWED_SECTION.test(line);
+      if (/与其他文件的关系/.test(line)) hasRelationSection = true;
+      continue;
+    }
+
+    // 检查 2：检查清单
+    if (/^\s*-\s*\[[ xX]\]/.test(line)) {
+      errors.push({
+        line: lineNum,
+        code: 'CHECKLIST_IN_GUIDE',
+        message: '出现检查清单项: ' + trimmed.slice(0, 60)
+      });
+      continue;
+    }
+
+    // 检查 1：数字区间（P2-3：写作指导豁免）
+    if (!isWritingGuide && !inExampleSection && !trimmed.startsWith('|')) {
+      let skip = false;
+      for (const kw of RANGE_SKIP_KEYWORDS) {
+        if (line.includes(kw)) { skip = true; break; }
+      }
+      if (!skip) {
+        for (const { re, label } of RANGE_PATTERNS) {
+          if (re.test(line)) {
+            warnings.push({
+              line: lineNum,
+              code: 'RANGE_IN_GUIDE',
+              message: '疑似数字区间（' + label + '）: ' + trimmed.slice(0, 60)
+            });
+            break;
+          }
+        }
+      }
+    }
+
+    // 检查 3：错误代码（P2-2：audit 文件整体豁免；其余看白名单节）
+    if (!isAudit && !inErrorCodeAllowedSection) {
+      ERROR_CODE_RE.lastIndex = 0;
+      let m;
+      while ((m = ERROR_CODE_RE.exec(line)) !== null) {
+        const code = m[1];
+        if (ERROR_CODE_PREFIXES.test(code)) {
+          warnings.push({
+            line: lineNum,
+            code: 'ERROR_CODE_IN_BODY',
+            message: '正文中出现错误代码 ' + BT_CHAR + code + BT_CHAR + '（应在"与其他文件的关系"或"错误代码速查/常见错误/故障排查/BLOCKED/全量校验后的处理/跨文件错误的特殊处理"节）'
+          });
+        }
+      }
+    }
+  }
+
+  // 检查 4：必须有"与其他文件的关系"节
+  if (!hasRelationSection) {
+    errors.push({
+      line: 0,
+      code: 'MISSING_RELATION_SECTION',
+      message: '缺少"与其他文件的关系"节'
+    });
+  }
+
+  // 检查 5：枚举值连续列举
+  const listMatches = [...content.matchAll(/(\d+)\s*个值[：:]\s*([^\n]+)/g)];
+  for (const m of listMatches) {
+    const listPart = m[2];
+    for (const [name, vals] of Object.entries(glossaryEnums)) {
+      if (vals.length < 2) continue;
+      if (vals.every(v => listPart.includes(v))) {
+        warnings.push({
+          line: 0,
+          code: 'ENUM_LIST_IN_GUIDE',
+          message: '可能重复枚举 ' + name + ' 的所有值（应改为"见 glossary 的 ' + name + '"）'
+        });
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+// ============================================================
+// 主流程
+// ============================================================
+function main() {
+  const args = parseArgs();
+
+  if (!args.dir && !args.file) {
+    process.stderr.write('需要 --dir 或 --file\n');
+    return process.exit(2);
+  }
+
+  if (!args.glossary) {
+    args.glossary = path.join(__dirname, 'glossary.md');
+  }
+
+  if (!fs.existsSync(args.glossary)) {
+    process.stderr.write('glossary.md 不存在: ' + args.glossary + '\n');
+    return process.exit(2);
+  }
+
+  let glossaryEnums = {};
+  try {
+    const parsed = parseGlossaryFromMd(fs.readFileSync(args.glossary, 'utf-8'));
+    glossaryEnums = parsed.enums;
+  } catch (e) {
+    process.stderr.write('glossary.md 解析失败: ' + e.message + '\n');
+    return process.exit(2);
+  }
+
+  const files = [];
+  if (args.file) {
+    files.push(args.file);
+  } else {
+    if (!fs.existsSync(args.dir)) {
+      process.stderr.write('目录不存在: ' + args.dir + '\n');
+      return process.exit(2);
+    }
+    for (const f of fs.readdirSync(args.dir)) {
+      if (f.endsWith('.md')) {
+        files.push(path.join(args.dir, f));
+      }
+    }
+  }
+
+  const results = [];
+  let totalErrors = 0;
+  let totalWarnings = 0;
+
+  for (const file of files) {
+    if (!fs.existsSync(file)) {
+      results.push({ file: file, errors: [{ code: 'READ', message: '文件不存在' }], warnings: [] });
+      totalErrors++;
+      continue;
+    }
+    try {
+      const result = checkFile(file, glossaryEnums);
+      results.push({ file: file, errors: result.errors, warnings: result.warnings });
+      totalErrors += result.errors.length;
+      totalWarnings += result.warnings.length;
+    } catch (e) {
+      results.push({ file: file, errors: [{ code: 'CHECK_FAILED', message: e.message }], warnings: [] });
+      totalErrors++;
+    }
+  }
+
+  const output = {
+    status: totalErrors === 0 ? 0 : 1,
+    total_files: files.length,
+    total_errors: totalErrors,
+    total_warnings: totalWarnings,
+    results: results
+  };
+
+  process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+  process.exitCode = totalErrors === 0 ? 0 : 1;
+}
+
+main();