verifact 0.0.0-stage → 0.2.0

package/src/core/dispositions.js

@@ -0,0 +1,292 @@
+'use strict';
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * 处置分类（dispositions）解析器。
+ *
+ * 设计来源：docs/rfc-verifact-dispositions.md（本仓，2026-10-26 合并）。
+ *
+ * 三条不可协商的规则：
+ *  1. 非 code-artifact 的声明必须指名「这个数字由谁拥有」（artifact / owner / why），
+ *     缺失即**报错**，不是静默通过 —— 豁免必须付费。
+ *  2. 只有 owner 可以从所在区域继承；artifact / since / why 必须就地声明，
+ *     否则一个区域头就成了几十条声明的共同借口。
+ *  3. 禁止推断：本模块只读声明，绝不根据数值形状或上下文猜语义。
+ *
+ * 语法（HTML 注释，GitHub 渲染不可见）：
+ *   <!-- verifact: disposition=narrative why="..." -->                                  文件级（前 5 行）
+ *   <!-- verifact: begin disposition=progress owner=docs/CHECKLIST.md --> ... <!-- verifact: end -->
+ *   | 合计 | 199/199 | <!-- verifact: disposition=progress -->                            单条级（区域里可继承 owner）
+ */
+
+const FILE_LEVEL_MAX_LINE = 5;
+
+const DISPOSITIONS = ['code-artifact', 'measured-once', 'progress', 'narrative'];
+
+const REQUIRED_ARGS = {
+  'code-artifact': [],
+  'measured-once': ['artifact'],
+  progress: ['owner'],
+  narrative: ['why']
+};
+
+// 只有 owner 可继承：其余参数逐条不同，继承等于把「每条都有出处」变成「整段共用一句借口」。
+const INHERITABLE = new Set(['owner']);
+
+const ANNOTATION_RE = /<!--\s*verifact:\s*([\s\S]*?)-->/;
+const OWN_LINE_RE = /^\s*<!--\s*verifact:[\s\S]*?-->\s*$/;
+
+/** 等长空白替换，保留换行，行号不变。 */
+function blank(text) {
+  return String(text).replace(/[^\n]/g, ' ');
+}
+
+/**
+ * 遮蔽围栏代码块（``` / ~~~），保留行号。
+ *
+ * 理由：文档里的示例声明写在围栏里，那是**示例**，不是生效声明。
+ * 本仓 claims 抽取早已这么做了（claims.js stripNoise），dispositions 之前漏了这一步：
+ * `docs/rfc-verifact-dispositions.md:192` 举例 `external-snapshot`（未实现的第五类），
+ * 解析器把示例当真 → 整份仓的门禁以 disposition_error 崩掉。
+ * 未闭合的围栏按 CommonMark 语义一直遮到文件末尾。
+ */
+function blankFencedBlocks(text) {
+  const lines = String(text).split('\n');
+  let fence = null; // { marker: '`' | '~', len: number }
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (fence) {
+      lines[i] = blank(line);
+      const close = new RegExp('^[ \\t]{0,3}' + fence.marker + '{' + fence.len + ',}[ \\t]*$');
+      if (close.test(line)) fence = null;
+      continue;
+    }
+    const open = /^[ \t]{0,3}(`{3,}|~{3,})[^\n]*$/.exec(line);
+    if (open) {
+      fence = { marker: open[1][0], len: open[1].length };
+      lines[i] = blank(line);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * 不可执行的散文之外：围栏代码块 + 行内代码。与 claims.js stripNoise 一致。
+ * RFC 里 `- 逐行扫描时优先匹配 `<!-- verifact: ... -->`;` 这种行内示例也是示例。
+ */
+function maskNonProse(text) {
+  return blankFencedBlocks(text).replace(/`[^`\n]*`/g, (m) => blank(m));
+}
+
+class DispositionError extends Error {
+  constructor(fileRef, line, message) {
+    super(fileRef + ':' + line + ': ' + message);
+    this.name = 'DispositionError';
+    this.file = String(fileRef);
+    this.line = line;
+    this.reason = 'disposition_error';
+  }
+}
+
+/** 按空白切分，但保留引号内的空格（why="a b c"）。 */
+function splitArgs(text) {
+  const out = [];
+  let cur = '';
+  let quote = null;
+  for (const ch of String(text)) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else cur += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; continue; }
+    if (/\s/.test(ch)) {
+      if (cur) { out.push(cur); cur = ''; }
+      continue;
+    }
+    cur += ch;
+  }
+  if (quote) throw new Error('引号未闭合');
+  if (cur) out.push(cur);
+  return out;
+}
+
+function parseDirective(inner, fileRef, lineNo) {
+  let parts;
+  try {
+    parts = splitArgs(inner);
+  } catch (e) {
+    throw new DispositionError(fileRef, lineNo, '处置声明无法解析：' + e.message);
+  }
+  if (!parts.length) throw new DispositionError(fileRef, lineNo, '处置声明为空');
+
+  let kind = 'single';
+  if (parts[0] === 'begin' || parts[0] === 'end') { kind = parts.shift(); }
+
+  if (kind === 'end') {
+    if (parts.length) {
+      throw new DispositionError(fileRef, lineNo, 'end 不接受参数（多余：' + parts.join(' ') + '）');
+    }
+    return { kind, line: lineNo };
+  }
+
+  let disposition = null;
+  const args = {};
+  for (const p of parts) {
+    const eq = p.indexOf('=');
+    if (eq < 0) {
+      throw new DispositionError(fileRef, lineNo, '参数缺少 "="：' + p + '（期望 key=value）');
+    }
+    const k = p.slice(0, eq).trim();
+    const v = p.slice(eq + 1).trim();
+    if (!k) throw new DispositionError(fileRef, lineNo, '参数名为空：' + p);
+    if (!v) throw new DispositionError(fileRef, lineNo, '参数值为空：' + k);
+    if (k === 'disposition') disposition = v;
+    else args[k] = v;
+  }
+
+  if (!disposition) {
+    throw new DispositionError(fileRef, lineNo, '缺少 disposition=（' + DISPOSITIONS.join(' | ') + '）');
+  }
+  if (DISPOSITIONS.indexOf(disposition) < 0) {
+    // fail closed：拼错的 narrativ 不允许退化成默认值，也不允许被猜成 narrative
+    throw new DispositionError(fileRef, lineNo,
+      '未知 disposition="' + disposition + '"（允许：' + DISPOSITIONS.join(' | ') + '）');
+  }
+
+  const extra = Object.keys(args);
+  if (disposition === 'code-artifact' && extra.length) {
+    throw new DispositionError(fileRef, lineNo, 'code-artifact 不接受参数（多余：' + extra.join(', ') + '）');
+  }
+
+  return { kind, disposition, args, line: lineNo };
+}
+
+/**
+ * 必填参数校验。inherited 只提供区域里**允许继承**的那几项（当前只有 owner），
+ * 其余缺失一律报错 —— 这是「豁免必须指名拥有者」的执行点。
+ */
+function requireArgs(directive, inherited, fileRef, lineNo) {
+  const need = REQUIRED_ARGS[directive.disposition] || [];
+  const args = Object.assign({}, directive.args);
+  for (const key of need) {
+    if (args[key]) continue;
+    if (inherited && INHERITABLE.has(key) && inherited[key]) {
+      args[key] = inherited[key];
+      continue;
+    }
+    throw new DispositionError(fileRef, lineNo,
+      directive.disposition + ' 必须声明 ' + key + '=（否则豁免就是无主数字）');
+  }
+  return Object.assign({}, directive, { args });
+}
+
+/**
+ * 扫描整篇文本，建立行号 -> 处置 的映射。
+ * 返回 { resolve(lineNo), regions, fileLevel, hasAny }。
+ */
+function buildDispositionScopes(text, fileRef) {
+  const normalized = String(text).replace(/\r\n?/g, '\n');
+  // 围栏 / 行内代码里的示例声明不生效（与 claims 抽取的遮蔽口径一致）
+  const masked = maskNonProse(normalized);
+  const lines = masked.split('\n');
+
+  const regions = [];
+  const sameLine = new Map();      // 行号 -> 声明（写在代码行尾）
+  const appliesToNext = new Map(); // 行号 -> 声明（独立成行，作用于下一行）
+  let fileLevel = null;
+  const stack = [];
+
+  const DEFAULT = { disposition: 'code-artifact', args: {}, source: 'default', at: null };
+  const hasAny = /<!--\s*verifact:/.test(masked);
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const m = ANNOTATION_RE.exec(raw);
+    if (!m) continue;
+
+    const lineNo = i + 1;
+    const own = OWN_LINE_RE.test(raw);
+    const parsed = parseDirective(m[1], fileRef, lineNo);
+    const top = stack.length ? stack[stack.length - 1] : null;
+
+    if (parsed.kind === 'begin') {
+      if (top && top.disposition !== parsed.disposition) {
+        throw new DispositionError(fileRef, lineNo,
+          '不允许嵌套不同 disposition（外层 ' + top.disposition + '，内层 ' + parsed.disposition + '）');
+      }
+      const d = requireArgs(parsed, null, fileRef, lineNo);
+      const region = { from: lineNo, to: null, disposition: d.disposition, args: d.args, at: lineNo };
+      regions.push(region);
+      stack.push(region);
+      continue;
+    }
+
+    if (parsed.kind === 'end') {
+      if (!top) throw new DispositionError(fileRef, lineNo, 'end 没有对应的 begin');
+      stack.pop().to = lineNo;
+      continue;
+    }
+
+    // 单条级：允许出现在区域内，但 disposition 必须与区域一致（否则是歧义，报错而不是让某一方静默获胜）；
+    // 必填参数里只有 owner 能向区域借，其余必须就地写。
+    if (top && top.disposition !== parsed.disposition) {
+      throw new DispositionError(fileRef, lineNo,
+        '单条处置与所在区域冲突（区域 ' + top.disposition + '，本条 ' + parsed.disposition + '）');
+    }
+    const d = requireArgs(parsed, top ? top.args : null, fileRef, lineNo);
+    const entry = { disposition: d.disposition, args: d.args, at: lineNo };
+
+    if (own) {
+      if (lineNo <= FILE_LEVEL_MAX_LINE) {
+        if (fileLevel) {
+          throw new DispositionError(fileRef, lineNo,
+            '文件级处置重复声明（前 ' + FILE_LEVEL_MAX_LINE + ' 行只允许一条）');
+        }
+        fileLevel = entry;
+      } else {
+        appliesToNext.set(lineNo + 1, entry);
+      }
+    } else {
+      sameLine.set(lineNo, entry);
+    }
+  }
+
+  if (stack.length) {
+    const open = stack[stack.length - 1];
+    throw new DispositionError(fileRef, open.at,
+      'begin 没有配对的 end（区域从第 ' + open.at + ' 行开始）');
+  }
+
+  function resolve(lineNo) {
+    const same = sameLine.get(lineNo);
+    const prev = appliesToNext.get(lineNo);
+    let region = null;
+    for (let r = regions.length - 1; r >= 0; r--) {
+      if (lineNo > regions[r].from && lineNo < regions[r].to) { region = regions[r]; break; }
+    }
+
+    // 区域 vs 单条：单条更具体，优先（单条的 disposition 已校验与区域一致）
+    if (same) return { disposition: same.disposition, args: same.args, source: 'inline', at: same.at };
+    if (prev) return { disposition: prev.disposition, args: prev.args, source: 'inline', at: prev.at };
+    if (region) return { disposition: region.disposition, args: region.args, source: 'region', at: region.at };
+    if (fileLevel) return { disposition: fileLevel.disposition, args: fileLevel.args, source: 'file', at: fileLevel.at };
+    return Object.assign({}, DEFAULT);
+  }
+
+  return { resolve, regions, fileLevel, hasAny };
+}
+
+module.exports = {
+  DISPOSITIONS,
+  REQUIRED_ARGS,
+  INHERITABLE,
+  FILE_LEVEL_MAX_LINE,
+  DispositionError,
+  blankFencedBlocks,
+  maskNonProse,
+  buildDispositionScopes,
+  parseDirective,
+  requireArgs,
+  splitArgs
+};

package/src/core/lint.js

@@ -0,0 +1,111 @@
+'use strict';
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * 用语 / 绝对化检测。规则来自 FIBEMATE 自有投稿纪律，默认全开、可逐条关闭。
+ * 输出的是「需人工复核的写作信号」，不是漏洞，也不是定稿判决。
+ */
+
+const RULES = [
+  {
+    id: 'V-A001', severity: 'high', title: '绝对化全球性主张',
+    re: /全球(首个|第一|唯一|最先|领先)|世界(首个|第一|唯一)|业界(首个|唯一)|国际上首个/g,
+    hint: '绝对化范围主张需要可核验来源；若无法核验，改写为限定范围的表述'
+  },
+  {
+    id: 'V-A002', severity: 'high', title: '安全性绝对断言',
+    re: /(绝对安全|完全安全|不可能被破解|无法被破解|不可被攻破|零风险|100%\s*安全|never\s+be\s+broken|unbreakable)/gi,
+    hint: '密码学结论不存在绝对性，改为给出攻击模型与边界条件'
+  },
+  {
+    id: 'V-A003', severity: 'medium', title: '未标注依据的最高级/唯一性表述',
+    re: /(最强|最快|最安全|最领先|唯一能够|唯一实现|首个实现|首创)/g,
+    hint: '最高级需绑到具体对比对象与指标；无依据时降级为陈述'
+  },
+  {
+    id: 'V-S001', severity: 'medium', title: '禁用词',
+    re: /(坑|其实|值得一提|恰恰|有点|挺|蛮|话说回来)/g,
+    hint: 'FIBEMATE 稿规：虚词与口语直接删'
+  },
+  {
+    id: 'V-S002', severity: 'medium', title: '禁用「值得X」句式',
+    re: /值得(?!注意|警惕|说明的)(\S{0,4})/g,
+    hint: '稿规：动词直接接宾语，去掉「值得」'
+  },
+  {
+    id: 'V-D001', severity: 'low', title: '未完成占位',
+    re: /(TODO|FIXME|XXX|<\s*待补[^>]*>|\?\?\?)/g,
+    hint: '发稿前清除占位标记'
+  }
+];
+
+function lintText(text, fileRef, opts) {
+  const options = opts || {};
+  const disabled = new Set((options.lint && options.lint.disable) || []);
+  const extra = (options.lint && options.lint.extra) || [];
+  const active = RULES.filter((r) => !disabled.has(r.id)).concat(extra);
+  const lines = String(text).replace(/\r\n?/g, '\n').split('\n');
+  const findings = [];
+
+  // 命中词出现在「不要 / 并非 / 幻觉」这类否定或讨论语境里时，是论证对象而非主张本身：
+  // 降级为 low，避免把自查文档自己打成高危。
+  const NEGATION_CUE = /(不要|不能|并非|绝非|不代表|不等同|避免|警惕|幻觉|而非|并非的)/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const rule of active) {
+      rule.re.lastIndex = 0;
+      let m;
+      while ((m = rule.re.exec(line)) !== null) {
+        if (!m[0]) { rule.re.lastIndex++; continue; }
+        const ahead = line.slice(Math.max(0, m.index - 14), m.index);
+        const quoted = /[「“"']\s*$/.test(line.slice(Math.max(0, m.index - 2), m.index));
+        const negated = NEGATION_CUE.test(ahead);
+        findings.push({
+          id: (String(fileRef).split('/').pop()) + ':L' + (i + 1) + ':' + rule.id,
+          file: fileRef,
+          line: i + 1,
+          ruleId: rule.id,
+          severity: negated ? 'low' : rule.severity,
+          baseSeverity: rule.severity,
+          downgraded: negated,
+          quoted,
+          title: rule.title,
+          matched: m[0],
+          sentence: line.trim().slice(0, 200),
+          hint: negated ? '命中词处于否定/讨论语境（' + (NEGATION_CUE.exec(ahead) || [''])[0] + '），已降级为 low：确认它不是主张本身' : rule.hint
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+/** 代码块需要跳过：把 ``` 段落按行号记录，供上层过滤。 */
+function codeLineRanges(text) {
+  const lines = String(text).replace(/\r\n?/g, '\n').split('\n');
+  const ranges = [];
+  let open = false, start = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim();
+    if (/^(```|~~~)/.test(t)) {
+      if (!open) { open = true; start = i + 1; }
+      else { ranges.push([start, i + 1]); open = false; }
+    }
+  }
+  if (open) ranges.push([start, lines.length]);
+  return ranges;
+}
+
+function inRanges(n, ranges) {
+  for (const r of ranges) if (n >= r[0] && n <= r[1]) return true;
+  return false;
+}
+
+function lintDoc(text, fileRef, opts) {
+  const raw = lintText(text, fileRef, opts);
+  if (opts && opts.lint && opts.lint.includeCodeBlocks) return raw;
+  const ranges = codeLineRanges(text);
+  return raw.filter((f) => !inRanges(f.line, ranges));
+}
+
+module.exports = { RULES, lintDoc, lintText, codeLineRanges };

package/src/core/normalize.js

@@ -0,0 +1,178 @@
+'use strict';
+// SPDX-License-Identifier: Apache-2.0
+
+// 单位表：同一 dim 内可比，base = number * factor。
+// 未知单位或未标注单位 → dim=null，仅按裸数值比对（并在报告里标 degradedComparability）。
+const UNITS = {
+  ns: { dim: 'time', factor: 1 },
+  nsec: { dim: 'time', factor: 1 },
+  us: { dim: 'time', factor: 1e3 },
+  'µs': { dim: 'time', factor: 1e3 },
+  'μs': { dim: 'time', factor: 1e3 },
+  ms: { dim: 'time', factor: 1e6 },
+  msec: { dim: 'time', factor: 1e6 },
+  s: { dim: 'time', factor: 1e9 },
+  sec: { dim: 'time', factor: 1e9 },
+  b: { dim: 'size', factor: 1 },
+  byte: { dim: 'size', factor: 1 },
+  bytes: { dim: 'size', factor: 1 },
+  kb: { dim: 'size', factor: 1024 },
+  kib: { dim: 'size', factor: 1024 },
+  mb: { dim: 'size', factor: 1048576 },
+  mib: { dim: 'size', factor: 1048576 },
+  gb: { dim: 'size', factor: 1073741824 },
+  gib: { dim: 'size', factor: 1073741824 },
+  pct: { dim: 'pct', factor: 1 },
+  states: { dim: 'count', factor: 1 },
+  cycles: { dim: 'count', factor: 1 },
+  x: { dim: 'ratio', factor: 1 }
+};
+
+const PCT_TOKEN = '%';
+
+function squash(s) {
+  return String(s == null ? '' : s).toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+
+// CJK 参与 key 上下文（文档多为中英混排），最大 CJK 连续段算一个 token。
+const TOKEN_SPLIT = /[^a-z0-9\u4e00-\u9fff]+/;
+
+function squashTokens(s) {
+  return String(s == null ? '' : s).toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff]+/g, '');
+}
+
+function tokens(s) {
+  const parts = String(s == null ? '' : s).toLowerCase().split(TOKEN_SPLIT);
+  const out = [];
+  for (const p of parts) {
+    if (!p) continue;
+    // 过长的中文连续段信息量低，丢弃避免污染相似度
+    if (/^[\u4e00-\u9fff]+$/.test(p) && p.length > 4) continue;
+    out.push(p);
+  }
+  return out;
+}
+
+function normKey(s) {
+  return tokens(s).join('-');
+}
+
+/** 把 "ML-KEM-768" 变成 "mlkem768"，用于在归一化路径里做包含判断。 */
+function dekey(s) {
+  const parts = String(s == null ? '' : s).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  return parts.join('');
+}
+
+function parseNum(raw) {
+  if (raw == null) return null;
+  const cleaned = String(raw).replace(/[,\s_]/g, '');
+  if (!/^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(cleaned)) return null;
+  const n = Number(cleaned);
+  return Number.isFinite(n) ? n : null;
+}
+
+function unitInfo(unit) {
+  if (!unit) return null;
+  const u = String(unit).toLowerCase();
+  if (u === PCT_TOKEN) return UNITS.pct;
+  return UNITS[u] || null;
+}
+
+/**
+ * 数值封装。ratio 型单独用 {type:'ratio'} 表示。
+ * @returns {{type:string, raw:string, number:number|null, unit:string|null, dim:string|null, base:number|null}}
+ */
+function mkValue(numberText, unit) {
+  const number = parseNum(numberText);
+  const info = unitInfo(unit);
+  return {
+    type: 'scalar',
+    raw: String(numberText) + (unit ? String(unit) : ''),
+    number,
+    unit: unit ? String(unit) : null,
+    dim: info ? info.dim : null,
+    base: info && number != null ? number * info.factor : null
+  };
+}
+
+function mkRatio(numeratorText, denominatorText) {
+  const a = parseNum(numeratorText);
+  const b = parseNum(denominatorText);
+  return {
+    type: 'ratio',
+    raw: numeratorText + '/' + denominatorText,
+    numerator: a,
+    denominator: b,
+    ratio: a != null && b ? a / b : null
+  };
+}
+
+/**
+ * 比对两个值。单位维度一致时按归一化 base 比；维度不一致或缺失时退化为裸数值比。
+ * @returns {{equal:boolean, comparable:boolean, reason:string}}
+ */
+function compareValues(a, b, opts) {
+  const rel = (opts && opts.relTolerance != null) ? opts.relTolerance : 0.005;
+  const abs = (opts && opts.absTolerance != null) ? opts.absTolerance : 0;
+  if (!a || !b) return { equal: false, comparable: false, reason: 'missing_value' };
+  if (a.type !== b.type) return { equal: false, comparable: false, reason: 'type_mismatch' };
+
+  if (a.type === 'ratio') {
+    if (a.numerator == null || b.numerator == null) return { equal: false, comparable: false, reason: 'unparsable' };
+    if (a.denominator != null && b.denominator != null && a.denominator !== b.denominator) {
+      return { equal: false, comparable: true, reason: 'denominator_differs' };
+    }
+    if (a.numerator !== b.numerator) return { equal: false, comparable: true, reason: 'numerator_differs' };
+    return { equal: true, comparable: true, reason: 'exact' };
+  }
+
+  if (a.number == null || b.number == null) {
+    return { equal: String(a.raw) === String(b.raw), comparable: false, reason: 'non_numeric' };
+  }
+
+  let comparable = false;
+  let x, y;
+  if (a.dim && b.dim && a.dim === b.dim && a.base != null && b.base != null) {
+    x = a.base; y = b.base; comparable = true;
+  } else if (!a.dim && !b.dim) {
+    x = a.number; y = b.number; comparable = false;
+  } else {
+    x = a.number; y = b.number; comparable = false;
+  }
+  if (x === y) return { equal: true, comparable, reason: 'exact' };
+  const tol = Math.max(abs, rel * Math.abs(x), rel * Math.abs(y));
+  if (Math.abs(x - y) <= tol) return { equal: true, comparable, reason: 'within_tolerance' };
+  return { equal: false, comparable, reason: 'value_differs' };
+}
+
+/** 从单个标量字符串里尝试构造出水印条目用的值对象（供 JSON 叶子服务）。 */
+function valueFromString(text) {
+  const t = String(text).trim();
+  let m = t.match(/^(\d[\d,]*)\s*\/\s*(\d[\d,]*)$/);
+  if (m) return mkRatio(m[1], m[2]);
+  m = t.match(/^(-?\d[\d,]*(?:\.\d+)?)\s*(ns|us|µs|μs|ms|s|sec|%|bytes|byte|b|kb|mb|gb|kib|mib|gib)$/i);
+  if (m) return mkValue(m[1], m[2]);
+  const maybe = parseNum(t);
+  if (maybe != null) return { type: 'scalar', raw: t, number: maybe, unit: null, dim: null, base: null };
+  return null;
+}
+
+/**
+ * 两边都带了「工具不认识的单位」且单位名不同 → 度量的东西多半不是一回事
+ * （例：文档 10,000 rounds vs 产出物 6 tests）。这种不做数值比较。
+ */
+function unknownUnitConflict(a, b) {
+  if (a.type !== 'ratio' && b.type === 'ratio') return false;
+  if (a.type === 'ratio' || b.type === 'ratio') return false;
+  if (!a.unit || !b.unit) return false;
+  const ua = String(a.unit).toLowerCase(), ub = String(b.unit).toLowerCase();
+  if (ua === ub) return false;
+  const ia = unitInfo(ua), ib = unitInfo(ub);
+  if (!ia || !ib) return true;            // 至少一边单位未知 → 不可比
+  return ia.dim !== ib.dim;               // 两边都已知但量纲不同 → 不可比
+}
+
+module.exports = {
+  UNITS, tokens, normKey, squash, dekey, parseNum, unitInfo,
+  mkValue, mkRatio, compareValues, valueFromString, unknownUnitConflict
+};