verifact 0.0.0-stage → 0.2.1

package/src/core/claims.js

@@ -0,0 +1,329 @@
+'use strict';
+// SPDX-License-Identifier: Apache-2.0
+
+const { tokens, mkValue, mkRatio, parseNum } = require('./normalize');
+const { buildDispositionScopes } = require('./dispositions');
+const { assignStableKeys } = require('./stable-key');
+
+/**
+ * 硬数字声明抽取器。
+ *
+ * 纪律：
+ *  - 只做结构抽取，不做语义判断；抽到的是「待核验的声明」，不是结论。
+ *  - 宁可漏报，不可误报：拿捏不准的模式（裸大数字）默认关闭。
+ *  - 行号必须准：清洗噪声时用等长空白替换，绝不删字符改变行数。
+ */
+
+// 关键前缀词：出现在数字前，直接接管 primaryToken，压过通用上下文猜测。
+const DOMINANT_PREFIX = new Set([
+  'kat', 'tvla', 'adla', 'wns', 'tns', 'whs', 'p50', 'p95', 'p99', 'p999',
+  'score', 'coverage', 'states', 'cycles', 'mutants', 'invariants', 'ndet', 'ser',
+  'fps', 'tps', 'qps', 'latency', 'throughput', 'bram', 'dsp', 'lut', 'ff'
+]);
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'of', 'and', 'or', 'in', 'for', 'with', 'is', 'are', 'was', 'were',
+  'to', 'by', 'at', 'on', 'as', 'that', 'this', 'it', 'from', 'be', 'been', 'has', 'have',
+  'see', 'seealso', 'note', 'TODO', 'total', 'all', 'up', 'down', 'per', 'over', 'under',
+  'http', 'https', 'com', 'org', 'net', 'md', 'html', 'npm', 'git',
+  '的', '了', '和', '与', '及', '在', '对', '为', '是', '其', '将', '已', '有', '个', '项',
+  '条', '次', '组', '共', '即', '中', '到', '从', '并', '也', '均', '各', '该', '被', '把'
+]);
+
+// 形如 "2026"、"1000" 这类无单位整数几乎总是噪音（年份 / 编号），除非前缀词表明是度量。
+const METRIC_HINTS = new Set([
+  'kat', 'tvla', 'score', 'coverage', 'states', 'cycles', 'count', 'total', 'files', 'deps',
+  'samples', 'runs', 'tests', 'invariants', 'traces', 'suites', 'rounds', 'bits', 'throughput'
+]);
+
+const PATTERNS = [
+  // 引用型：TSR / commit / serial —— 走「产出物是否存在」核验
+  { kind: 'ref', subtype: 'tsr', re: /\bTSR\s+([A-Za-z]{1,4}-?\d{2,4})\b/g },
+  { kind: 'ref', subtype: 'commit', re: /\bcommit\s+([0-9a-f]{7,40})\b/gi },
+  { kind: 'ref', subtype: 'serial', re: /\bserial\s+(0x[0-9a-fA-F]{4,})\b/gi },
+  // 比率型：10000/10000、5/5
+  { kind: 'ratio', re: /(\d[\d,]{0,12})\s*\/\s*(\d[\d,]{0,12})(?![/\d.])/g, dpi: true },
+  // 键值型：p95=78.5ms、score: 77.3
+  {
+    kind: 'kv',
+    re: /([A-Za-z][A-Za-z0-9_.\-]{0,39}|[\u4e00-\u9fff]{1,6})\s*[=＝:：]\s*(-?\d[\d,]*(?:\.\d+)?)\s*(ns|us|µs|μs|ms|s|sec|%|bytes|byte|b|kb|mb|gb|kib|mib|gib|states|cycles)?\b/gi,
+    keyGroup: 1, numGroup: 2, unitGroup: 3
+  },
+  // 度量型：78.5ms、9.755ns、77.3%（键来自上下文）
+  // 数字左侧不得是字母数字或连字符，否则 "SLH-DSA-128s" 会被当成 -128秒
+  { kind: 'measure', re: /(?<![\w-])(-?\d[\d,]*(?:\.\d+)?)\s*(ns|us|µs|μs|ms|s|%|cycles)\b(?![a-z])/gi, numGroup: 1, unitGroup: 2, ctx: true },
+  // 计数型：101,467 states、80 bytes、7 invariants
+  { kind: 'count', re: /(\d[\d,]{0,12})\s+(states|cycles|bytes|tests|runs|samples|suites|invariants|traces|files|deps|dimensions|bits|rounds|ciphers)\b/gi, numGroup: 1, unitGroup: 2, ctx: true },
+  // 行数型：654 行、800 行代码（「第 45 行」行号引用在提取分支里过滤）
+  { kind: 'loc', re: /(?<![\w第])(\d[\d,]{0,8})\s*行(?=[\)）\s，。、；：:]|$)/g, numGroup: 1, ctx: true }
+];
+
+const DEEP_BARE = { kind: 'bare', re: /(?:^|[|\s(])(\d[\d,]{3,})(?=[|\s.,;)\]]|$)/g, numGroup: 1, ctx: true };
+
+// 标准编号不是命中率。`FIPS 203/205` 与 `204/205` 形状相同，形状匹配器就会
+// 把两条标准编号绑成一对「文档值 vs 产物值」，于是产生一次从没发生过的漂移
+// （issue #101，lg-075-README.md:171）。这类引用要在提取阶段就排除。
+//
+// 判定必须「贴着数字」：只在数字左侧很短的前缀上找标准名，并且中间只能有空白/点号。
+// 用一个大窗口宽泛地找 `NIST` 会把「NIST 测试集通过 10/10」也误杀——那是真声明。
+const STANDARD_PREFIX_RE = /(?:FIPS|RFC|GB\s*\/?\s*T|GB|ISO\s*\/?\s*IEC|ISO|NIST|ITU-T|IEEE|PKCS\s*#?|SP\s?800-\d+|ePrint|IACR)\.?\s*$/;
+const STANDARD_SUFFIX_RE = /^\s*(?:标准|规范|standards?)\b/i;
+const STANDARD_NEAR_CHARS = 24;
+
+/** 返回排除原因，或 null 表示这确实是个比值。 */
+function standardNumberReason(line, start, end, num, den) {
+  const before = line.slice(Math.max(0, start - STANDARD_NEAR_CHARS), start);
+  if (STANDARD_PREFIX_RE.test(before)) return 'standard-prefix';
+  const after = line.slice(end, end + 12);
+  if (STANDARD_SUFFIX_RE.test(after)) return 'standard-suffix';
+  // 年份区间：两边都是 19xx/20xx，人类不会用这种比值表达通过率
+  const n = parseInt(String(num).replace(/,/g, ''), 10);
+  const d = parseInt(String(den).replace(/,/g, ''), 10);
+  if (n >= 1900 && n <= 2099 && d >= 1900 && d <= 2099) return 'year-pair';
+  return null;
+}
+
+function blank(match) {
+  return match.replace(/[^\n]/g, ' ');
+}
+
+/** 用等长空白替换噪声片段，保持行号不变。 */
+function stripNoise(text) {
+  return String(text)
+    .replace(/\r\n?/g, '\n')
+    .replace(/```[\s\S]*?```/g, blank)
+    .replace(/~~~[\s\S]*?~~~/g, blank)
+    .replace(/<!--[\s\S]*?-->/g, blank)
+    .replace(/`[^`\n]*`/g, blank)
+    .replace(/https?:\/\/[^\s)\]|>]+/g, blank)
+    .replace(/<[^>\n]+>/g, blank);
+}
+
+function lineModules(line, modules) {
+  const lower = String(line).toLowerCase().replace(/[^a-z0-9]+/g, '');
+  const hits = [];
+  for (const m of modules) {
+    if (m.dekey && lower.indexOf(m.dekey) >= 0) hits.push(m.name);
+  }
+  if (hits.length <= 1) return { module: hits[0] || null, all: hits };
+  // 同一个 §.<nospace>串里可能同时命中 "ML-KEM" 与 "ML-KEM-768"，取最长（最具体）者
+  hits.sort((a, b) => b.length - a.length);
+  return { module: hits[0], all: hits };
+}
+
+function cleanTokens(arr) {
+  const out = [];
+  for (const w of arr) {
+    if (!w) continue;
+    if (STOPWORDS.has(w)) continue;
+    if (/^\d+$/.test(w)) continue;
+    if (out.indexOf(w) >= 0) continue;
+    out.push(w);
+  }
+  return out;
+}
+
+const UNIT_TOKENS = new Set(['s', 'ms', 'us', 'µs', 'μs', 'ns']);
+
+/**
+ * 前一个单元格的数字+单位不能当前面那一格的键。
+ * 「| keygen | 48 µs | ~0.522 ms |」里 µs 会被 token 成 's'，
+ * 于是第三格得到 key `keygen-s`（而不是 `keygen`）—— 键是错的，绑定也就错。
+ * 只在「数字紧跟单位且单位就是 prefix 末尾」时剔除，不影响 “延迟(ms)” 这类表头。
+ */
+function dropForeignUnit(rawPrefix, tokensArr) {
+  if (!tokensArr.length) return tokensArr;
+  const last = tokensArr[tokensArr.length - 1];
+  if (!UNIT_TOKENS.has(String(last).toLowerCase())) return tokensArr;
+  if (!/\d(?:[.,]\d+)?\s*(?:µs|μs|us|ms|ns|s)\s*[~≈]?\s*$/i.test(rawPrefix)) return tokensArr;
+  return tokensArr.slice(0, -1);
+}
+
+function contextKey(line, startIdx, endIdx, unitToken) {
+  // 表格行的 "|" 会切断上下文，换成空格（等长，安全）
+  const rawPrefix = line.slice(Math.max(0, startIdx - 64), startIdx);
+  let prefix = rawPrefix.replace(/\|/g, ' ');
+  prefix = prefix.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
+  const before = dropForeignUnit(prefix, cleanTokens(tokens(prefix)));
+  if (!before.length) {
+    // 数字在行首时（"43/43 cross-validation tests PASS"），用后面的描述词充当键
+    let afterRaw0 = '';
+    if (endIdx != null) afterRaw0 = line.slice(endIdx, endIdx + 64).replace(/\|/g, ' ');
+    const tail = cleanTokens(tokens(afterRaw0)).filter((w) => w !== unitToken).slice(0, 3);
+    if (!tail.length) return { keyTokens: [], primaryToken: null, key: '' };
+    return { keyTokens: tail.slice(0, 2), primaryToken: tail[0], key: tail[0] };
+  }
+
+  let primary = null;
+  let keyPart = before;
+  for (let i = before.length - 1; i >= 0; i--) {
+    if (DOMINANT_PREFIX.has(before[i])) {
+      keyPart = before.slice(i);
+      primary = keyPart[keyPart.length - 1];
+      break;
+    }
+  }
+  if (!primary) {
+    primary = before[before.length - 1];
+    keyPart = before.slice(-2);
+  }
+
+  // 数字后面的描述词同样参与匹配（"43/43 cross-validation tests PASS" 的情况）
+  let afterRaw = '';
+  if (endIdx != null) afterRaw = line.slice(endIdx, endIdx + 48).replace(/\|/g, ' ');
+  const after = cleanTokens(tokens(afterRaw)).filter((w) => w !== unitToken).slice(0, 2);
+
+  const combined = cleanTokens(keyPart.concat(after)).slice(0, 4);
+  return { keyTokens: combined, primaryToken: primary, key: keyPart.join('-') };
+}
+
+function isNoiseNumber(numText, unit, primaryToken) {
+  const n = parseNum(numText);
+  if (n == null) return true;
+  if (unit) return false;
+  if (Number.isInteger(n) && n >= 1000 && n <= 2100 && !(primaryToken && METRIC_HINTS.has(primaryToken))) return true;
+  return false;
+}
+
+/**
+ * @param {string} text       原始文本（会先做等长清洗）
+ * @param {string} fileRef    展示用的文件引用
+ * @param {object} opts       { modules:[{name,dekey}], deep:boolean, headingHint:string }
+ */
+function extractClaims(text, fileRef, opts) {
+  const options = opts || {};
+  const moduleList = options.modules || [];
+  const deep = !!options.deep;
+  // 处置声明读的是原始文本：stripNoise 会把 HTML 注释抹成空格。
+  // opts.dispositions === false 时跳过，供只想看原始抽取的调用方使用。
+  const scopes = options.dispositions === false ? null : buildDispositionScopes(text, fileRef);
+  const clean = stripNoise(text);
+  const lines = clean.split('\n');
+  const baseName = String(fileRef).split('/').pop();
+  const out = [];
+  let heading = options.headingHint || '';
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const line = raw.replace(/\|/g, ' ');
+    const trimmedRaw = raw.trim();
+    if (/^#{1,6}\s+/.test(trimmedRaw)) { heading = trimmedRaw.replace(/^#{1,6}\s+/, ''); }
+
+    const spanish = lineModules(line, moduleList);
+    const modRes = lineModules(trimmedRaw, moduleList);
+    const sectionRes = lineModules(heading, moduleList);
+    const moduleOf = (r) => (r && r.module) || null;
+    const lineModule = modRes.module || moduleOf(spanish) || sectionRes.module;
+
+    const taken = [];
+    const overlaps = (s, e) => taken.some((t) => !(e <= t[0] || s >= t[1]));
+
+    const patterns = deep ? PATTERNS.concat([DEEP_BARE]) : PATTERNS;
+    for (const p of patterns) {
+      p.re.lastIndex = 0;
+      let m;
+      while ((m = p.re.exec(line)) !== null) {
+        if (m[0].length === 0) { p.re.lastIndex++; continue; }
+        const start = m.index;
+        const end = start + m[0].length;
+        if (overlaps(start, end)) continue;
+
+        let claim = null;
+        if (p.kind === 'ref') {
+          claim = {
+            kind: 'ref', subtype: p.subtype,
+            key: p.subtype, keyTokens: [p.subtype], primaryToken: p.subtype,
+            value: { type: 'ref', raw: m[0], ref: String(m[1]).toLowerCase() }
+          };
+        } else if (p.kind === 'ratio') {
+          const ctxRaw = contextKey(line, start, end, null);
+          const keyTokens = ctxRaw.keyTokens;
+          const primaryToken = ctxRaw.primaryToken;
+          const numerator = m[1], denominator = m[2];
+          const standard = standardNumberReason(line, start, end, numerator, denominator);
+          const common = {
+            kind: 'ratio',
+            key: keyTokens.length ? ctxRaw.key : 'ratio',
+            keyTokens: keyTokens.length ? keyTokens : ['ratio'],
+            primaryToken: primaryToken || 'ratio',
+            value: mkRatio(numerator, denominator)
+          };
+          if (standard) {
+            // 不静默丢掉：留成一条声明，但标上「不是度量」，由引擎单列计数——
+            // 不进判定、不进覆盖率分母。直接删掉就变成「看不见」，与假绿同宗。
+            claim = Object.assign(common, { notMeasurement: standard });
+          } else if (isNoiseNumber(numerator, null, primaryToken) && keyTokens.length === 0) {
+            continue;
+          } else {
+            claim = common;
+          }
+        } else if (p.kind === 'loc') {
+          // 行号引用（第 45 行）不是规模声明，丢弃
+          if (/第\s*$/.test(line.slice(Math.max(0, start - 4), start))) { continue; }
+          const num = parseNum(m[1]);
+          // 行数的合理区间：太小的几乎是行号，太大的几乎不是单文件
+          if (num == null || num < 10 || num > 200000) { continue; }
+          const c = contextKey(line, start, end, 'loc');
+          if (!c.keyTokens.length) { continue; }
+          claim = {
+            kind: 'loc',
+            key: c.key, keyTokens: c.keyTokens, primaryToken: c.primaryToken,
+            value: { type: 'scalar', raw: m[0], number: num, unit: '行', dim: 'loc', base: num },
+            // 数字前的 80 字符：LOC 核验只在这个窗口里找文件名主干，
+            // 防止「句子里远远提到某文件」被当成该行数声明的指向
+            locPrefix: line.slice(Math.max(0, start - 80), start)
+          };
+        } else {
+          const keyText = p.keyGroup ? m[p.keyGroup] : null;
+          const numText = m[p.numGroup];
+          const unit = p.unitGroup ? m[p.unitGroup] : null;
+          let keyTokens, primaryToken, key;
+          if (keyText) {
+            keyTokens = tokens(keyText);
+            // 单个 "\" 或 "v" 之类前缀不接受
+            primaryToken = keyTokens.length ? keyTokens[keyTokens.length - 1] : null;
+            key = keyTokens.join('-');
+          } else {
+            const unitToken = unit ? String(unit).toLowerCase() : null;
+            const c = contextKey(line, start, end, unitToken);
+            keyTokens = c.keyTokens; primaryToken = c.primaryToken; key = c.key;
+          }
+          if (!keyTokens.length) { continue; }
+          if (isNoiseNumber(numText, unit, primaryToken)) { continue; }
+          // 版本号类数字（1.2.3 / v3.3）：前一个字符是 "." 或 key 为 "v" 时丢弃
+          if (start > 0 && line[start - 1] === '.') { continue; }
+          if (keyTokens.length === 1 && keyTokens[0] === 'v') { continue; }
+          claim = {
+            kind: p.kind,
+            key, keyTokens, primaryToken,
+            value: mkValue(numText, unit)
+          };
+        }
+
+        if (!claim) continue;
+        claim.id = baseName + ':L' + (i + 1) + ':' + claim.kind + ':' + claim.key;
+        claim.file = fileRef;
+        claim.line = i + 1;
+        claim.module = lineModule;
+        claim.modulesAll = modRes.all.length ? modRes.all : (sectionRes.all || []);
+        claim.heading = heading.slice(0, 120);
+        claim.sentence = trimmedRaw.slice(0, 240);
+        if (scopes) {
+          const d = scopes.resolve(i + 1);
+          claim.disposition = d.disposition;
+          claim.dispositionSource = d.source;
+          claim.dispositionAt = d.at;
+          if (d.args && Object.keys(d.args).length) claim.dispositionArgs = Object.assign({}, d.args);
+        }
+        out.push(claim);
+        taken.push([start, end]);
+      }
+    }
+  }
+  // stableKey 必须按抽取顺序分配：同一 baseKey 的第 2 条起带 #2、#3 后缀。
+  // id 仍按行号生成，保留给人看（定位用）；身份一律用 stableKey（见 #96）。
+  assignStableKeys(out);
+  return out;
+}
+
+module.exports = { extractClaims, stripNoise, contextKey, lineModules, PATTERNS };

package/src/core/crossdoc.js

@@ -0,0 +1,97 @@
+'use strict';
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * 跨文档互证：同一个键在不同文档里给出了不同的值。
+ *
+ * 与 drift 的分工：
+ *   drift    —— 文档 vs 产出物（有证据可锚）
+ *   crossDoc —— 文档 vs 文档（没有任何产出物时，声明之间互相矛盾）
+ *
+ * 纪律：只聚类、只列值与出处，不判哪份文档错。
+ * 量级差 ≥ warnRatio（默认 10 倍）才标 warn——那种差异通常不是口径问题；
+ * 其余记 info，交人判断。
+ */
+
+const GENERIC_KEYS = new Set([
+  'max', 'min', 'total', 'sum', 'n', 'value', 'count', 'score', 'factor', 'cost',
+  'time', 'date', 'len', 'size', 'version', 'id', 'name', 'type', 'level'
+]);
+
+function shapeOf(v) {
+  if (!v) return null;
+  if (v.type === 'scalar' && v.number != null) return 'scalar:' + (v.dim || '-');
+  return null;
+}
+
+function numOf(v) {
+  if (v.type !== 'scalar' || v.number == null) return null;
+  const x = v.base != null ? v.base : v.number;
+  return Math.abs(x);
+}
+
+/**
+ * @param {Array} claims 已解析完成的声明（含 status）
+ * @param {object} opts { warnRatio }
+ * @returns {Array} 按量级差降序的不一致簇
+ */
+function crossDocCheck(claims, opts) {
+  const warnRatio = (opts && opts.warnRatio) || 10;
+  const groups = new Map();
+
+  for (const c of claims) {
+    if (c.kind === 'ref' || c.kind === 'loc' || !c.value) continue;
+    const shape = shapeOf(c.value);
+    if (!shape) continue;
+    if (!c.keyTokens || !c.keyTokens.length) continue;
+    if (c.keyTokens.length === 1 && GENERIC_KEYS.has(c.keyTokens[0])) continue;
+    // 单 token 且 ≤2 字符（q / k / n / d）：在密码学文档里几乎总是不同对象的参数名，噪音大于信号
+    if (c.keyTokens.length === 1 && c.keyTokens[0].length <= 2) continue;
+    const sig = (c.module || '-') + '|' + c.keyTokens.join('-') + '|' + shape;
+    if (!groups.has(sig)) groups.set(sig, []);
+    groups.get(sig).push(c);
+  }
+
+  const out = [];
+  for (const [sig, list] of groups) {
+    // 按值聚合：同值多处出现只占一格
+    const byVal = new Map();
+    for (const c of list) {
+      const k = String(c.value.raw);
+      if (!byVal.has(k)) byVal.set(k, []);
+      byVal.get(k).push(c);
+    }
+    if (byVal.size < 2) continue;
+    const files = new Set(list.map((c) => c.file));
+    if (files.size < 2) continue;
+
+    const nums = list.map((c) => numOf(c.value)).filter((x) => x != null && x > 0);
+    let ratio = null;
+    if (nums.length >= 2) {
+      const mx = Math.max.apply(null, nums);
+      const mn = Math.min.apply(null, nums);
+      ratio = mn > 0 ? mx / mn : null;
+    }
+    const severity = ratio != null && ratio >= warnRatio ? 'warn' : 'info';
+
+    out.push({
+      sig,
+      key: list[0].key,
+      module: list[0].module || null,
+      dim: list[0].value.dim || null,
+      distinctValues: byVal.size,
+      files: files.size,
+      claims: list.length,
+      maxMinRatio: ratio != null ? Number(ratio.toFixed(2)) : null,
+      severity,
+      values: Array.from(byVal.entries())
+        .map(([raw, cs]) => ({ raw, at: cs.slice(0, 4).map((c) => c.file + ':' + c.line), count: cs.length }))
+        .slice(0, 8)
+    });
+  }
+
+  out.sort((a, b) => (b.maxMinRatio || 0) - (a.maxMinRatio || 0));
+  return out;
+}
+
+module.exports = { crossDocCheck };