verifact 0.0.0-stage → 0.2.0

package/src/config.js

@@ -0,0 +1,198 @@
+'use strict';
+// SPDX-License-Identifier: Apache-2.0
+
+const fs = require('fs');
+const path = require('path');
+const { ConfigError } = require('./errors');
+const { dekey } = require('./core/normalize');
+const { DEFAULT_EXCLUDE } = require('./core/walk');
+
+const DEFAULT_MODULES = [
+  'ML-KEM-768', 'ML-KEM-1024', 'ML-KEM', 'ML-DSA', 'SLH-DSA',
+  'SM2', 'SM3', 'SM4', 'SM4-GCM', 'HMAC-SM3', 'P-256/ECDH',
+  'FPGA NTT', 'FPGA v5', 'NTT', 'VWZ', 'LookingGlass',
+  'TLS 1.3 Hybrid', 'Path C-2', 'C-2', 'OPK', 'TLA+', 'Double-Ratchet',
+  'Jasmin', 'liboqs', 'ADLA', 'TVLA'
+  // 注意：CARS / CBOM / SBOM 是评估框架不是模块，不要放进这张表——
+  // 否则 cars-scorecard.json 这类文件名会被当成模块，凭空制造「跨模块绑定」。
+];
+
+const DEFAULTS = {
+  docs: {
+    roots: [],
+    include: ['**/*.md'],
+    exclude: DEFAULT_EXCLUDE.concat(['**/CHANGELOG.md']),
+    maxFileBytes: 2 * 1024 * 1024,
+    maxFiles: 4000,
+    maxDepth: 12
+  },
+  artifacts: {
+    roots: [],
+    // 只登记「文件是否存在」的目录：TSR/TSQ/SHA256 这类二进制凭证不解析内容，
+    // 但文档常常引用它们的编号（TSR lg-069），存在性本身就是可核验的事实。
+    presenceRoots: [],
+    include: ['**/*.json', '**/*.md', '**/*.log', '**/*.csv', '**/*.rpt', '**/*.twr'],
+    exclude: DEFAULT_EXCLUDE.concat(['**/*.min.json']),
+    maxFileBytes: 8 * 1024 * 1024,
+    maxFiles: 6000,
+    maxDepth: 12
+  },
+  resolve: { minScore: 0.45, relTolerance: 0.005, absTolerance: 0, locTolerance: 0.05 },
+  crossDoc: { enabled: true, warnRatio: 10 },
+  lint: { enabled: true, disable: [], includeCodeBlocks: false },
+  modules: DEFAULT_MODULES,
+  bindings: [],
+  ignore: [],
+  deny: [],
+  // 哈希存证目录：文件本身被时间戳盖过，插一行注释就改变哈希、破坏存证。
+  // 这类目录不能靠 disposition（那要改文件），只能靠配置登记。
+  sealed: [],
+  gate: { failOn: 'drift' },
+  cache: { enabled: true, dir: '.verifact', maxHistory: 200 },
+  server: { host: '127.0.0.1', port: 8787 }
+};
+
+/** 去掉值为 undefined 的键：deepMerge 遇到显式 undefined 会把默认值覆盖掉。 */
+function stripUndefined(obj) {
+  const out = {};
+  for (const k of Object.keys(obj)) if (obj[k] !== undefined) out[k] = obj[k];
+  return out;
+}
+
+function isPlainObject(v) {
+  return v && typeof v === 'object' && !Array.isArray(v);
+}
+
+function deepMerge(base, over) {
+  if (!isPlainObject(over)) return over == null ? base : over;
+  const out = Object.assign({}, base);
+  for (const k of Object.keys(over)) {
+    out[k] = isPlainObject(base[k]) || Array.isArray(base[k])
+      ? (Array.isArray(over[k]) ? over[k] : deepMerge(base[k] || {}, over[k]))
+      : over[k];
+  }
+  return out;
+}
+
+function buildModules(list) {
+  return (list || []).map((name) => ({ name, dekey: dekey(name) })).filter((m) => m.dekey.length >= 2);
+}
+
+function findConfigFile(explicit, cwd) {
+  if (explicit) {
+    const p = path.resolve(cwd, explicit);
+    if (!fs.existsSync(p)) throw new ConfigError('config file not found', { path: p });
+    return p;
+  }
+  for (const name of ['verifact.json', '.verifact.json', 'verifact.config.json']) {
+    const p = path.join(cwd, name);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * 集中配置加载 + 校验。启动即失败，不让错误配置跑到半路。
+ */
+function loadConfig(opts) {
+  const options = opts || {};
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const file = findConfigFile(options.configPath, cwd);
+  let fileCfg = {};
+  if (file) {
+    try {
+      fileCfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (e) {
+      throw new ConfigError('config file is not valid JSON', { path: file, detail: e.message });
+    }
+  }
+
+  // 环境变量覆盖（服务端运行场景）
+  const envCfg = {
+    server: stripUndefined({
+      host: process.env.VERIFACT_HOST,
+      port: process.env.VERIFACT_PORT ? Number(process.env.VERIFACT_PORT) : undefined
+    })
+  };
+  if (process.env.VERIFACT_CACHE === '0') envCfg.cache = { enabled: false };
+
+  const merged = deepMerge(deepMerge(DEFAULTS, fileCfg), deepMerge(envCfg, options.overrides || {}));
+  merged.__cwd = cwd;
+  merged.__configFile = file;
+  // 配置里的相对 root 以「配置文件所在目录」为基准：换一个 cwd 跑，root 不会集体落空。
+  // root 落空会被静默跳过 → 产出物索引为空 → 声明全体退化成 unbound，drift 门禁假绿。
+  // 没有配置文件时（纯 overrides / 测试）退回 cwd，保持旧行为。
+  merged.__baseDir = file ? path.dirname(file) : cwd;
+
+  // --- 校验 ---
+  const errs = [];
+  if (!Array.isArray(merged.docs.roots) || !merged.docs.roots.length) {
+    errs.push('docs.roots 不能为空');
+  }
+  if (!Array.isArray(merged.artifacts.roots)) {
+    errs.push('artifacts.roots 必须是数组');
+  }
+  if (!Array.isArray(merged.deny)) {
+    errs.push('deny 必须是数组');
+  }
+  if (!Array.isArray(merged.ignore)) {
+    errs.push('ignore 必须是数组');
+  } else {
+    // 没有 why 的豁免就是洗白：读者看不到「为什么这条不该核」，只能选择相信。
+    // 配置层就把它当致命错——不降级、不补默认值。
+    const PLACEHOLDER = /^(todo|tbd|n\/a|na|none|-+|\.+|x+|修绑定)$/i;
+    for (const r of merged.ignore) {
+      if (!r || typeof r !== 'object' || Array.isArray(r)) {
+        errs.push('ignore 的每一项必须是规则对象，实际=' + JSON.stringify(r));
+        continue;
+      }
+      if (r.note !== undefined && r.why === undefined) {
+        errs.push('ignore 条目仍用 note 而没有 why（' + JSON.stringify(r.key || r.file) + '）：字段已改名，请写 why 说明理由');
+        continue;
+      }
+      if (typeof r.why !== 'string' || r.why.trim().length < 12) {
+        errs.push('ignore 条目缺少可读的 why（至少 12 字，说明为什么这条不该核）：' + JSON.stringify(r.key || r.file));
+        continue;
+      }
+      if (PLACEHOLDER.test(r.why.trim())) {
+        errs.push('ignore 的 why 是占位符（' + r.why.trim() + '）：' + JSON.stringify(r.key || r.file));
+      }
+    }
+  }
+  if (!Array.isArray(merged.sealed)) {
+    errs.push('sealed 必须是数组');
+  } else {
+    // sealed 只接受「路径 glob 字符串」。写成规则对象时静默不生效，
+    // 会让人以为存证目录已经受保护（假安全）——所以一律报错。
+    for (const s of merged.sealed) {
+      if (typeof s !== 'string' || !s.trim()) errs.push('sealed 的每一项必须是非空路径 glob 字符串，实际=' + JSON.stringify(s));
+    }
+  }
+  if (!(merged.resolve.minScore >= 0 && merged.resolve.minScore <= 1)) {
+    errs.push('resolve.minScore 必须在 [0,1]');
+  }
+  if (Number.isNaN(merged.server.port)) errs.push('server.port 必须是数字');
+  if (errs.length) throw new ConfigError('配置校验未通过', { problems: errs, file: merged.__configFile });
+
+  for (const r of merged.docs.roots.concat(merged.artifacts.roots)) {
+    if (typeof r !== 'string') throw new ConfigError('root 必须是字符串路径', { root: r });
+  }
+  return merged;
+}
+
+/** root 既可以是目录也可以是单个文件，这里分开处理。 */
+function partitionRoots(roots, cwd) {
+  const dirs = [];
+  const files = [];
+  const missing = [];
+  for (const r of roots) {
+    const abs = path.resolve(cwd, r);
+    let st = null;
+    try { st = fs.statSync(abs); } catch (_) { missing.push(r); continue; }
+    if (st.isDirectory()) dirs.push({ input: r, abs });
+    else if (st.isFile()) files.push({ input: r, abs, rel: path.basename(abs) });
+  }
+  return { dirs, files, missing };
+}
+
+module.exports = { loadConfig, buildModules, partitionRoots, DEFAULTS, DEFAULT_MODULES, deepMerge };

package/src/core/artifacts.js

@@ -0,0 +1,275 @@
+'use strict';
+// SPDX-License-Identifier: Apache-2.0
+
+const fs = require('fs');
+const path = require('path');
+const { iterate } = require('./walk');
+const { tokens, valueFromString, squash } = require('./normalize');
+const { extractClaims } = require('./claims');
+
+/**
+ * 产出物收集器：把 JSON / 文本报告 / 日志里的数字摊平成
+ * `{source, path, keyTokens, primaryToken, module, value}` 条目，供解析器比对。
+ *
+ * 关键设计：JSON 的字符串叶子会再走一次声明抽取器，于是
+ * `"verification": "KAT 10000/10000 Noble cross-validated, TVLA 3/3 PASS"`
+ * 会变成两条独立可比对条目 `…verification#kat` 与 `…verification#tvla`。
+ * 这样文档里写的「KAT 10,000/10,000」就能直接对上，不需要人工写绑定表。
+ */
+
+const TEXT_EXT = new Set(['.md', '.log', '.txt', '.csv', '.rpt', '.twr', '.out', '.yaml', '.yml']);
+const PRESENCE_EXT = new Set(['.tsr', '.pdf', '.json', '.md', '.bin', '.hex', '.bit']);
+// 代码文件：只数行数（供「N 行」声明核验），不抽取声明
+const CODE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.py', '.c', '.h', '.cc', '.cpp', '.rs', '.go', '.java']);
+const CODE_LINE_MAX_BYTES = 4 * 1024 * 1024;
+const MAX_LEAVES_PER_FILE = 4000;
+
+function extOf(rel) {
+  const i = rel.lastIndexOf('.');
+  return i < 0 ? '' : rel.slice(i).toLowerCase();
+}
+
+function moduleOf(str, modules) {
+  const s = squash(str);
+  let best = null;
+  for (const m of modules) {
+    if (m.dekey && s.indexOf(m.dekey) >= 0) {
+      if (!best || m.name.length > best.length) best = m.name;
+    }
+  }
+  return best;
+}
+
+function leafEntry(source, pathStr, value, raw, modules) {
+  const combo = source + ' ' + pathStr;
+  const keyTokens = tokens(pathStr.replace(/#/g, ' '));
+  return {
+    source,
+    path: pathStr,
+    keyTokens,
+    primaryToken: keyTokens.length ? keyTokens[keyTokens.length - 1] : null,
+    module: moduleOf(combo, modules),
+    value,
+    raw: raw == null ? null : String(raw).slice(0, 300)
+  };
+}
+
+function walkJson(node, basePath, sink, modules, source) {
+  const seen = [];
+
+  (function rec(val, p) {
+    if (sink.length >= MAX_LEAVES_PER_FILE) return;
+    if (val == null) { sink.push(leafEntry(source, p, null, null, modules)); return; }
+    const t = typeof val;
+    if (t === 'number' || t === 'boolean') {
+      sink.push(leafEntry(source, p, valueFromString(String(val)), val, modules));
+      return;
+    }
+    if (t === 'string') {
+      const v = valueFromString(val);
+      if (v) sink.push(leafEntry(source, p, v, val, modules));
+      // 字符串里嵌着多个度量时，逐个拆出来
+      if (/[\d]/.test(val)) {
+        const sub = extractClaims(val, source, { modules });
+        for (const c of sub) {
+          sink.push(leafEntry(source, p + '#' + c.key, c.value, c.value.raw, modules));
+        }
+      }
+      return;
+    }
+    if (Array.isArray(val)) {
+      const cap = Math.min(val.length, 200);
+      for (let i = 0; i < cap; i++) rec(val[i], p + '[' + i + ']');
+      return;
+    }
+    if (t === 'object') {
+      if (seen.indexOf(val) >= 0) return; // 环保护
+      seen.push(val);
+      for (const k of Object.keys(val)) rec(val[k], p ? p + '.' + k : k);
+    }
+  })(node, basePath);
+}
+
+function countLines(text) {
+  // 与 wc -l 一致：统计换行符数；末行无换行时补 1
+  if (!text.length) return 0;
+  let n = 0;
+  for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) n++;
+  return text.charCodeAt(text.length - 1) === 10 ? n : n + 1;
+}
+
+function collectFile(file, roots, modules, maxBytes, fileLines) {
+  const rel = roots.relLabel(file);
+  const ext = extOf(rel);
+  const out = [];
+  try {
+    if (ext === '.json') {
+      const text = fs.readFileSync(file, 'utf8');
+      if (maxBytes && Buffer.byteLength(text) > maxBytes) return out;
+      let data;
+      try { data = JSON.parse(text); } catch (_) { return out; }
+      walkJson(data, '', out, modules, rel);
+      return out;
+    }
+    if (TEXT_EXT.has(ext)) {
+      const text = fs.readFileSync(file, 'utf8');
+      if (maxBytes && Buffer.byteLength(text) > maxBytes) return out;
+      if (fileLines) fileLines.set(rel, countLines(text));
+      const claims = extractClaims(text, rel, { modules });
+      for (const c of claims) {
+        out.push({
+          source: rel,
+          path: rel + '#L' + c.line + '#' + c.key,
+          keyTokens: c.keyTokens,
+          primaryToken: c.primaryToken,
+          module: c.module || moduleOf(rel, modules),
+          value: c.value,
+          raw: c.sentence
+        });
+      }
+      return out;
+    }
+  } catch (_) {
+    return out;
+  }
+  return out;
+}
+
+/**
+ * @returns {{entries:Array, presence:Array<string>, scanned:number, skipped:number}}
+ */
+function collectArtifacts(cfg, modules) {
+  const entries = [];
+  const presence = [];
+  const fileLines = new Map();        // 文本文件 rel → 行数（供「N 行」声明核验）
+  let scanned = 0;
+  let skipped = 0;
+  const maxBytes = cfg.artifacts.maxFileBytes;
+  const seen = new Set();               // 根目录互相嵌套时去重，否则会产生「双候选→ambiguous」
+  const seenPresence = new Set();
+  const relRoot = path;
+
+  const matchInclude = (rel) => {
+    const ext = extOf(rel);
+    return ext === '.json' || TEXT_EXT.has(ext);
+  };
+
+  const handleDir = (root) => {
+    const rootLabel = path.basename(root) || root;
+    for (const f of iterate(root, {
+      exclude: cfg.artifacts.exclude,
+      matchInclude,
+      maxFileBytes: maxBytes,
+      maxFiles: cfg.artifacts.maxFiles,
+      maxDepth: cfg.artifacts.maxDepth
+    })) {
+      const key = relRoot.resolve(f.full);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const got = collectFile(f.full, { relLabel: () => rootLabel + '/' + f.rel }, modules, maxBytes, fileLines);
+      if (!got.length) skipped++; else scanned++;
+      for (const e of got) { e.abs = key; entries.push(e); }
+    }
+    // 存在性名录（供 TSR 这类引用型声明核验）：只记名字不读内容
+    for (const f of iterate(root, {
+      exclude: cfg.artifacts.exclude,
+      matchInclude: () => true,
+      maxFiles: 20000,
+      maxDepth: cfg.artifacts.maxDepth
+    })) {
+      const key = 'p:' + relRoot.resolve(f.full);
+      if (seenPresence.has(key)) continue;
+      seenPresence.add(key);
+      presence.push(rootLabel + '/' + f.rel);
+      // 代码文件顺带数行数（「N 行」声明的证据），不抽取声明
+      if (CODE_EXT.has(extOf(f.rel)) && (!f.size || f.size <= CODE_LINE_MAX_BYTES)) {
+        try {
+          const text = fs.readFileSync(f.full, 'utf8');
+          fileLines.set(rootLabel + '/' + f.rel, countLines(text));
+        } catch (_) { /* 读失败就跳过，行数证据不是必须的 */ }
+      }
+    }
+  };
+
+  for (const rootInput of cfg.artifacts.roots) {
+    const abs = path.resolve(cfg.__baseDir || cfg.__cwd || process.cwd(), rootInput);
+    let st = null;
+    try { st = fs.statSync(abs); } catch (_) { continue; }
+    if (st.isDirectory()) { handleDir(abs); continue; }
+    if (!st.isFile()) continue;
+    const base = path.basename(abs);
+    const parent = path.basename(path.dirname(abs));
+    const rel = base;
+    const label = parent ? parent + '/' + base : base;
+    const key = relRoot.resolve(abs);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    seenPresence.add('p:' + key);
+    presence.push(label);
+    const got = collectFile(abs, { relLabel: () => label }, modules, maxBytes, fileLines);
+    if (!got.length) skipped++; else scanned++;
+    for (const e of got) { e.abs = key; entries.push(e); }
+  }
+
+  // 存在性专用根：只读文件名，不读内容（TSR / TSQ / 哈希清单）
+  for (const rootInput of (cfg.artifacts.presenceRoots || [])) {
+    const abs = path.resolve(cfg.__baseDir || cfg.__cwd || process.cwd(), rootInput);
+    let st = null;
+    try { st = fs.statSync(abs); } catch (_) { continue; }
+    const rootLabel = st.isDirectory() ? (path.basename(abs) || '') : path.basename(path.dirname(abs));
+    const emit = (full, rel) => {
+      const key = 'p:' + path.resolve(full);
+      if (seenPresence.has(key)) return;
+      seenPresence.add(key);
+      presence.push(rootLabel ? rootLabel + '/' + rel : rel);
+    };
+    if (st.isFile()) { emit(abs, path.basename(abs)); continue; }
+    for (const f of iterate(abs, {
+      exclude: cfg.artifacts.exclude,
+      matchInclude: () => true,
+      maxFiles: 40000,
+      maxDepth: cfg.artifacts.maxDepth
+    })) emit(f.full, f.rel);
+  }
+
+  const denyRe = require('./walk').compilePatterns(cfg.artifacts.deny || []);
+  const denied = (e) => denyRe.some((re) => re.test(e.source + '::' + e.path) || re.test(e.source));
+  const keep = [];
+  for (const e of entries) { if (!denied(e)) keep.push(e); }
+
+  return { entries: keep, presence, scanned, skipped, denied: entries.length - keep.length, fileLines: Array.from(fileLines.entries()) };
+}
+
+// 过于通用的 token 不进倒排索引，否则候选集会爆炸（"count" 之类几乎命中一切）。
+const STOP_TOKENS = new Set([
+  'id', 'name', 'type', 'file', 'files', 'list', 'index', 'value', 'values', 'data', 'note', 'notes',
+  'title', 'version', 'status', 'state', 'path', 'source', 'key', 'keys', 'level', 'size', 'number',
+  'result', 'results', 'date', 'time', 'ts', 'msg', 'level0', 'text', 'item', 'items', 'ref', 'desc'
+]);
+
+/** primaryToken → 条目数组 + 全部 token → 条目数组。粒度放宽是为了 recall，质量由评分把关。 */
+function buildIndex(artifacts) {
+  const byToken = new Map();
+  const push = (k, e) => {
+    if (!byToken.has(k)) byToken.set(k, []);
+    byToken.get(k).push(e);
+  };
+  for (const e of artifacts.entries) {
+    const withPrimary = new Set(e.keyTokens);
+    if (e.primaryToken) withPrimary.add(e.primaryToken);
+    for (const k of withPrimary) {
+      if (STOP_TOKENS.has(k)) continue;
+      if (k.length < 2 && !/^\d+$/.test(k)) continue;
+      push(k, e);
+    }
+  }
+  const presenceSquash = new Map();
+  for (const p of artifacts.presence) {
+    const sq = squash(p);
+    if (!presenceSquash.has(sq)) presenceSquash.set(sq, []);
+    presenceSquash.get(sq).push(p);
+  }
+  return { byToken, presence: artifacts.presence, presenceSquash, entries: artifacts.entries, fileLines: new Map(artifacts.fileLines || []) };
+}
+
+module.exports = { collectArtifacts, buildIndex, collectFile, extOf, moduleOf, TEXT_EXT, PRESENCE_EXT };

package/src/core/cache.js

@@ -0,0 +1,87 @@
+'use strict';
+// SPDX-License-Identifier: Apache-2.0
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * 增量缓存：以「文件集合的 mtime+size 指纹」为 key。
+ * 命中则完全跳过产出物解析（扫描阶段最贵的一段），这是性能的主要来源。
+ */
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function fileSignature(roots, cfg) {
+  const list = [];
+  const walkDir = (dir, rootAbs, depth) => {
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const e of ents) {
+      const full = path.join(dir, e.name);
+      const rel = path.relative(rootAbs, full).split(path.sep).join('/');
+      if (e.isDirectory()) {
+        if (cfg.exclude.some((p) => new RegExp('^' + p.replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*') + '/?$').test(rel + '/'))) continue;
+        if (cfg.maxDepth && rel.split('/').length > cfg.maxDepth) continue;
+        walkDir(full, rootAbs, depth + 1);
+        continue;
+      }
+      let st = null;
+      try { st = fs.statSync(full); } catch (_) { continue; }
+      list.push([rel, st.mtimeMs, st.size]);
+    }
+  };
+  for (const r of roots) {
+    const abs = path.resolve(r);
+    let st = null;
+    try { st = fs.statSync(abs); } catch (_) { continue; }
+    if (st.isDirectory()) walkDir(abs, abs, 0);
+    else list.push([path.basename(abs), st.mtimeMs, st.size]);
+  }
+  list.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  return crypto.createHash('sha256').update(JSON.stringify(list)).digest('hex').slice(0, 32);
+}
+
+function cachePaths(cfg, cwd) {
+  const dir = path.resolve(cwd, cfg.cache.dir || '.verifact');
+  return { dir, file: path.join(dir, 'artifact-cache.json'), history: path.join(dir, 'history.jsonl') };
+}
+
+function readArtifactCache(cfg, cwd, roots) {
+  if (!cfg.cache.enabled) return { hit: false, reason: 'disabled' };
+  const p = cachePaths(cfg, cwd);
+  if (!fs.existsSync(p.file)) return { hit: false, reason: 'no_cache_file' };
+  try {
+    const raw = JSON.parse(fs.readFileSync(p.file, 'utf8'));
+    const sig = fileSignature(roots, { exclude: cfg.artifacts.exclude, maxDepth: cfg.artifacts.maxDepth });
+    if (raw.signature !== sig) return { hit: false, reason: 'stale', staged: raw };
+    return { hit: true, entries: raw.entries || [], presence: raw.presence || [], scanned: raw.scanned || 0, skipped: raw.skipped || 0, fileLines: raw.fileLines || [], signature: sig };
+  } catch (_) {
+    return { hit: false, reason: 'corrupt' };
+  }
+}
+
+function writeArtifactCache(cfg, cwd, roots, artifacts) {
+  if (!cfg.cache.enabled) return false;
+  const p = cachePaths(cfg, cwd);
+  try {
+    ensureDir(p.dir);
+    const payload = {
+      version: 1,
+      signature: fileSignature(roots, { exclude: cfg.artifacts.exclude, maxDepth: cfg.artifacts.maxDepth }),
+      entries: artifacts.entries,
+      presence: artifacts.presence,
+      scanned: artifacts.scanned,
+      skipped: artifacts.skipped,
+      fileLines: artifacts.fileLines || []
+    };
+    fs.writeFileSync(p.file, JSON.stringify(payload));
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+module.exports = { readArtifactCache, writeArtifactCache, fileSignature, cachePaths, ensureDir };