@modusensus/dsh-mneme 0.12.0 → 0.14.0-beta.1

package/lib/wiki/claims.js

@@ -0,0 +1,267 @@
+// dsh-mneme/src/wiki/claims.js
+// Claim 粒度的失效判定——借自 openwiki 的 Grounded Claims 设计：每条结论挂着「哪个
+// 文件、哪几行」的证据，代码一动就先算出「哪几条结论失准」，而不是把整个仓库判成
+// 过期、把全部语义段重跑一遍。
+//
+// 为什么值得做：choro_claims 早就存了 source_path / start_line / end_line（见 store.js
+// 的 choro_claims 表定义），三列本来就是为这件事准备的；可 t0.js 重跑时整页 claims 会被
+// 清空（replaceChoroGraph 的 pages[].claims = []），于是改一行代码就让所有页的语义段
+// 变成无主孤儿。本模块把「整仓过期」降成「哪页哪条」，代价是一次 git diff 加几十行
+// 纯计算：零模型、零网络、零写入。
+//
+// 只算「相对上次生成基线改了什么」，不判断代码本体——结论要留给读它的人。
+import { execFileSync } from "node:child_process";
+
+// git 对「含非 ASCII / 控制字符」的路径会加双引号并按 C 风格转义（core.quotepath 默认
+// 就是开的），例如中文名会写成 "a/\344\270\255\346\226\207.js"。只脱引号不解转义的话，
+// 归一出来的字符串永远对不上 choro_claims.source_path，这些文件上的结论就再也判不成
+// touched —— **漏判**比误判更难发现，因为它看起来一切正常。
+const GIT_PATH_ESCAPES = { a: "\x07", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t", v: "\v", '"': '"', "\\": "\\" };
+
+function unescapeQuotedGitPath(s) {
+  if (!s.includes("\\")) return s;
+  const bytes = [];
+  const pushStr = (str) => { for (const b of Buffer.from(str, "utf8")) bytes.push(b); };
+  for (let i = 0; i < s.length; i += 1) {
+    const ch = s[i];
+    if (ch !== "\\" || i === s.length - 1) { pushStr(ch); continue; }
+    const octal = /^[0-7]{3}/.exec(s.slice(i + 1));
+    if (octal) { bytes.push(parseInt(octal[0], 8) & 0xff); i += 3; continue; }
+    const escaped = GIT_PATH_ESCAPES[s[i + 1]];
+    if (escaped !== undefined) { pushStr(escaped); i += 1; continue; }
+    pushStr(ch);
+  }
+  return Buffer.from(bytes).toString("utf8");
+}
+
+// 路径归一：choro_claims.source_path 存的是仓库相对路径（正斜杠）；git 侧也是正斜杠，
+// 但 `--- a/x` `+++ b/x` 带前缀，可能需要去掉。转义只出现在被引号包起来的那种写法里，
+// 所以解转义严格跟着「这次是否脱过引号」走——不能对未加引号的路径无条件解，
+// 否则 Windows 风格的反斜杠会被当成转义序列吃掉。
+function normDiffPath(p) {
+  let s = String(p ?? "").trim();
+  const quoted = s.length >= 2 && s.startsWith('"') && s.endsWith('"');
+  if (quoted) s = unescapeQuotedGitPath(s.slice(1, -1));
+  if (s.startsWith("a/") || s.startsWith("b/")) s = s.slice(2);
+  return s.replace(/\\/g, "/");
+}
+
+/**
+ * 解析 `git diff --unified=0 <baseline> HEAD` 的文本。
+ *
+ * 只认 hunk 头 `@@ -a,b +c,d @@`：不解析正文，正文里带 `@@` 的代码行不会干扰，
+ * 因为 hunk 头必须匹配完整形状。两个计数都要——旧侧计数是新旧行坐标的唯一来源，
+ * claims 的行号记在**旧侧**（写 claim 时那一版就是 HEAD）。
+ *
+ * 不传 -M 还不够：git 在 `--unified=0` 下**仍会**自动开重命名检测（实测输出
+ * `similarity index 100% / rename from / rename to`，既不出 hunk 也不进 /dev/null），
+ * 于是重命名后旧路径上的 claim 会被判成「没事」。必须显式 `--no-renames`，让重命名
+ * 按「删旧 + 增新」处理：旧路径上的 claim 落进 deleted 是对的（锚点跟着文件走了，得
+ * 重新指），新路径没有 claim 自然也不会误报。
+ *
+ * 返回 { files: Map<path, [{oldStart, oldCount, newStart, newCount}]>, deleted: string[] }。
+ */
+export function parseDiffRanges(diffText) {
+  const files = new Map();
+  const deleted = [];
+  let livePath = null;
+  let oldPath = null;
+  for (const line of String(diffText ?? "").split("\n")) {
+    if (line.startsWith("diff --git ")) { livePath = null; oldPath = null; continue; }
+    if (line.startsWith("--- ")) { oldPath = normDiffPath(line.slice(4)); continue; }
+    if (line.startsWith("+++ ")) {
+      const raw = line.slice(4).trim();
+      if (raw === "/dev/null") {
+        // 整文件删除：claims 指向它的全部作废（没有出处就没有可校验的结论）。
+        if (oldPath) deleted.push(oldPath);
+        livePath = null;
+      } else {
+        livePath = normDiffPath(raw);
+        if (!files.has(livePath)) files.set(livePath, []);
+      }
+      continue;
+    }
+    const m = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
+    if (!m || livePath === null) continue;
+    files.get(livePath).push({
+      oldStart: Number(m[1]),
+      oldCount: m[2] === undefined ? 1 : Number(m[2]),
+      newStart: Number(m[3]),
+      newCount: m[4] === undefined ? 1 : Number(m[4]),
+    });
+  }
+  return { files, deleted };
+}
+
+/**
+ * 取基线到当前 HEAD 的 diff。基线不在仓库里（force-push / 浅克隆 / 换机重拉）时
+ * 不猜：回 { ok: false, reason }，调用方据此说「基线认不出了，建议重建」而不是
+ * 拿空 diff 报「全部结论都还准」——空 diff 与「算不出来」在页面上是两句话。
+ */
+export function diffSince(repoRoot, baseline, head) {
+  const clean = (v) => /^[0-9a-f]{7,40}$/i.test(String(v ?? "").trim());
+  if (!clean(baseline) || !clean(head)) return { ok: false, reason: "baseline-unreadable" };
+  try {
+    const text = execFileSync(
+      "git",
+      ["diff", "--unified=0", "--no-color", "--no-ext-diff", "--no-renames", `${baseline}..${head}`],
+      // --no-renames 是必需的，不是保险：git 会按配置自动开重命名检测（实测在
+      // --unified=0 下也开），一旦识别成 rename 就既不产生 hunk、也不产生 /dev/null，
+      // 旧路径上的 claim 会被静默判成 untouched。见本函数上方 parseDiffRanges 的说明。
+      // stdio 显式接管 stderr：execFileSync 默认把子进程 stderr 直接漏到父进程，
+      // 「不是 git 仓库」那条几十行的 usage 会污染面板日志，也会在测试输出里刷屏。
+      { cwd: repoRoot, encoding: "utf8", maxBuffer: 32 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }
+    );
+    return { ok: true, ...parseDiffRanges(text) };
+  } catch (err) {
+    // 两种情况在这里合流：`<基线>..HEAD` 里有 git 认不出的 rev（force-push 后
+    // 旧基线消失、浅克隆截断历史），或这个目录根本不是 git 仓库。对调用方是同一件
+    // 事：**算不出来**。别把 exit code 当 reason 抛给面板——面板要说的是人话。
+    return { ok: false, reason: "diff-failed", detail: String(err?.stderr ?? err?.message ?? err).trim().slice(0, 200) };
+  }
+}
+
+function normPath(p) {
+  return String(p ?? "").replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+/**
+ * 逐条 claim 判「还准不准」。
+ *
+ * 四档理由，全部能从 diff 与三列证据机械算出：
+ *   - deleted      证据文件在基线之后被删了，这条结论没有出处了。
+ *   - touched      改动的行与 claim 的行区间相交，结论本身可能已经不对。
+ *   - shifted      claim 区间没被碰，但它上方有增删，行号整体偏移——内容还在，
+ *                  锚点要重新指。刻意与 touched 分开：混成一个「失效」，面板就会
+ *                  对着一堆只是行号错位的结论喊「要重写」，喊几次就没人信了。
+ *   - unverifiable 所属文件改过，可这条 claim 当初就没记行号，无法定位到具体一行。
+ *
+ * 输入 diff 为 { files: Map, deleted: string[] }；输出与输入等长，未受影响的
+ * reason 为 null（调用方自行过滤）。
+ */
+export function assessClaims(claims, diff) {
+  const files = diff?.files ?? new Map();
+  const deleted = new Set(diff?.deleted ?? []);
+  return (claims ?? []).map((claim) => {
+    const path = normPath(claim.sourcePath);
+    if (path === "") return { ...claim, reason: null };
+    if (deleted.has(path)) return { ...claim, reason: "deleted" };
+    const hunks = files.get(path);
+    if (!hunks || hunks.length === 0) return { ...claim, reason: null };
+    const start = Number.isInteger(claim.startLine) ? claim.startLine : null;
+    const end = Number.isInteger(claim.endLine) ? claim.endLine : start;
+    if (start === null || start < 1) return { ...claim, reason: "unverifiable" };
+    const sorted = [...hunks].sort((a, b) => a.oldStart - b.oldStart);
+    let shift = 0;
+    for (const h of sorted) {
+      const hOldEnd = h.oldCount === 0 ? h.oldStart : h.oldStart + h.oldCount - 1;
+      // 纯插入（`@@ -a,0 +c,d @@`，oldCount === 0）没有「旧行区间」，但它插在旧第 a 行
+      // 之后、第 a+1 行之前。落进 claim 区间内部（a >= start 且 a < end）就是真碰到了，
+      // 与「删除/替换」一样算 touched；插在 claim 首行之前只是把它推下去，仍算 shifted。
+      // 老写法 `h.oldCount > 0 && ...` 让纯插入永远不算相交——多行结论被插进新行时，
+      // 结论原文已被改变却报「没事」。
+      const overlaps = h.oldCount > 0
+        ? start <= hOldEnd && end >= h.oldStart
+        : h.oldStart >= start && h.oldStart < end;
+      if (overlaps) return { ...claim, reason: "touched", shift };
+      if (hOldEnd < start) shift += h.newCount - h.oldCount;
+    }
+    return shift === 0 ? { ...claim, reason: null } : { ...claim, reason: "shifted", shift };
+  });
+}
+
+/**
+ * 仓库级汇总：逐条判定 → 「哪几页、几条、因为什么」。
+ *
+ * claims 每项需带 pageSlug；pages 每项 { slug, title, hasT1, verifiedBaseline,
+ * verifiedAt, diffBaseline, baselineApprox, baselineUnknown, anchorStale }。
+ *
+ * 为什么 pages 要带验证基线、为什么还要 diffByPage：claims 的行号是**各自那页被
+ * 富化的那一刻**记下的。全仓只有一个 git_baseline（T0 的时点），拿它当所有 claims
+ * 的比对起点，会把「T1 之前就发生、claim 早已算进去」的改动误报成 touched——页越晚
+ * 富化越容易误报。所以每页按自己的 verifiedBaseline 分组各算一次 diff。
+ *
+ * hasT1 是页面正文里有 T1 段标记的页——这类页「正文有语义段、库里零条 claims」是
+ * t1.js 落盘非原子留下的残局（文件先落盘、DB 后写，中途崩了就成这样）。单独记进
+ * inconsistent：不修它的话这页永远「看起来没有可校验的证据」，一次都不会被标成需要复核。
+ *
+ * diffByPage(slug) 三态：diff 对象 = 算过了；null = 这一页没有可用的起点（判不了）。
+ * 「判不了」的结论一条都不标，页面用 baselineUnknown / anchorStale 两种不同的说法交代。
+ */
+export function summarizeClaims(claims, diff, { pages = [], diffByPage = null } = {}) {
+  const assessed = diffByPage
+    ? (claims ?? []).flatMap((claim) => assessClaims([claim], diffByPage(claim.pageSlug)))
+    : assessClaims(claims, diff);
+  const bySlug = new Map();
+  for (const page of pages) {
+    bySlug.set(page.slug, {
+      slug: page.slug,
+      title: page.title ?? page.slug,
+      hasT1: Boolean(page.hasT1),
+      verifiedBaseline: page.verifiedBaseline ?? null,
+      verifiedAt: page.verifiedAt ?? null,
+      // 实际拿来跑 diff 的起点：新数据就是 verifiedBaseline；老数据（本功能之前富化）
+      // 退到全仓基线，baselineApprox 标记「这不是当真的验证点，是保底起点」。
+      diffBaseline: page.diffBaseline ?? page.verifiedBaseline ?? null,
+      baselineApprox: Boolean(page.baselineApprox),
+      baselineUnknown: Boolean(page.baselineUnknown),
+      anchorStale: Boolean(page.anchorStale),
+      claims: 0,
+      atRisk: [],
+      inconsistent: false,
+    });
+  }
+  for (const claim of assessed) {
+    const slug = claim.pageSlug;
+    if (!bySlug.has(slug)) {
+      bySlug.set(slug, { slug, title: claim.pageTitle ?? slug, hasT1: false, claims: 0, atRisk: [], inconsistent: false });
+    }
+    const bucket = bySlug.get(slug);
+    bucket.claims += 1;
+    if (!claim.reason) continue;
+    bucket.atRisk.push({
+      claimId: claim.id ?? null,
+      statement: claim.statement,
+      kind: claim.kind ?? null,
+      sourcePath: claim.sourcePath,
+      startLine: claim.startLine ?? null,
+      endLine: claim.endLine ?? null,
+      reason: claim.reason,
+      shift: claim.shift ?? 0,
+    });
+  }
+  for (const bucket of bySlug.values()) {
+    bucket.inconsistent = bucket.hasT1 && bucket.claims === 0;
+    // 零条结论的页谈不上「哪次验证的」——骨架页不该因为没富化过就被标成「判不了」。
+    if (bucket.claims === 0) bucket.baselineUnknown = false;
+  }
+  const list = [...bySlug.values()].sort((a, b) => {
+    // 有风险的排前面，然后依次是：锚点对不上账的、起点认不出的、本来就是空的、
+    // 干净的。依次递减的严重度，是为了让「要动手」的永远在第一屏。
+    const rank = (p) =>
+      p.atRisk.length > 0 ? 0
+        : p.inconsistent ? 1
+          : p.anchorStale ? 2
+            : p.baselineUnknown ? 3
+              : 4;
+    return rank(a) - rank(b) || a.slug.localeCompare(b.slug);
+  });
+  const flat = list.flatMap((p) => p.atRisk);
+  const count = (reason) => flat.filter((c) => c.reason === reason).length;
+  return {
+    pages: list,
+    totals: {
+      pages: list.length,
+      claims: assessed.length,
+      atRiskClaims: flat.length,
+      atRiskPages: list.filter((p) => p.atRisk.length > 0).length,
+      touched: count("touched"),
+      shifted: count("shifted"),
+      deleted: count("deleted"),
+      unverifiable: count("unverifiable"),
+      inconsistentPages: list.filter((p) => p.inconsistent).length,
+      baselineUnknownPages: list.filter((p) => p.baselineUnknown).length,
+      anchorStalePages: list.filter((p) => p.anchorStale).length,
+    },
+  };
+}

package/lib/wiki/cli-hint.js

@@ -0,0 +1,90 @@
+// dsh-mneme/src/wiki/cli-hint.js
+// issue #607：面板空态让用户「在仓库目录里跑 `dsh-mneme-choro <仓库路径> --apply`」，
+// 但插件是装在 profile 依赖里的，npm 只为**全局**安装把 shim 放进 PATH。profile 的
+// shim 落在 `<profile>/node_modules/.bin`，那里不在 PATH 上 —— 用户照着抄必然
+// command not found。issue 作者实测后的原话是「完全就是 AI 自己编的」。
+//
+// 所以提示里的命令必须**能直接粘贴就跑**：给绝对路径的入口，而不是一个只对全局
+// 安装成立的光名字。入口从插件自身位置推导（不信 PATH、不信 cwd）。
+//
+// 做法是逐级向上找「同时存在 bin/dsh-mneme-choro.mjs 与 package.json」的目录，
+// 而不是固定 dirname 几次：本仓库的 src 与 lib 是同一层，但 wiki/ 是第二层，
+// bin/ 里的脚本又在第一层 —— 写死层数的推导只要有一处调用方挪个位置就悄悄算错，
+// 而算错的表现正是「又给出一条跑不起来的命令」，与这条 issue 的病因同源。
+//
+// 这条对 hoisted 与 pnpm isolated 两种 linker 都成立：后者的真实路径在
+// `.pnpm/<pkg>/node_modules/@modusensus/dsh-mneme/`，包根照样是它的父目录。
+//
+// 刻意**只给 `node <entry>` 这一种形态**：`.bin` 的 shim 在 hoisted 布局下位于
+// 包根的 `../../../node_modules/.bin`，isolated 布局下却在 profile 根 —— 猜错就是
+// 再给一条跑不起来的命令。宁可只给一条一定对的，也不并列两条一条错的。
+//
+// 找不到入口就返回 null（源码树被裁剪、或调用方在包外），调用方退回通用说法，
+// 不硬编一个假路径。
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ENTRY_BASENAME = "dsh-mneme-choro.mjs";
+// 从 `src/wiki/` 到包根是 2 层，从 `bin/` 是 1 层；留到 6 层是为了 pnpm 的
+// `.pnpm/<pkg>/node_modules/@modusensus/<name>/` 这种深路径，同时不至于一路走到盘符。
+const MAX_LEVELS = 6;
+
+/**
+ * choro CLI 入口的绝对路径；找不到（源码树被裁剪、调用方在包外）返回 null。
+ *
+ * @param {string} fromModuleUrl - 调用方自己的 `import.meta.url`。
+ * @returns {string|null}
+ */
+export function choroCliEntry(fromModuleUrl) {
+  let dir;
+  try {
+    dir = dirname(fileURLToPath(fromModuleUrl));
+  } catch {
+    return null;
+  }
+  for (let level = 0; level <= MAX_LEVELS; level += 1) {
+    const entry = join(dir, "bin", ENTRY_BASENAME);
+    // 两个条件都要：只有 bin/ 没有 package.json 的目录可能是别人的同名 bin；
+    // 只有 package.json 没有 bin/ 的是源码树被裁剪（`files` 少了 bin）。
+    if (existsSync(entry) && existsSync(join(dir, "package.json"))) return entry;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+/**
+ * 给一句可直接粘贴的命令。只负责引号与形态，仓库路径由调用方给（面板给
+ * `<仓库路径>` 占位符，工具报错给 `<repo>`）。
+ *
+ * 引号按平台分：Windows 的 cmd / PowerShell 用双引号；POSIX 用单引号并把内嵌
+ * 单引号转成 `'\''` —— 安装路径里带空格是常态（`C:\Program Files\`），不带引号的
+ * 示例等于又给人一条跑不起来的命令。
+ *
+ * @param {string|null} entry - `choroCliEntry()` 的产物。
+ * @param {string} repoPlaceholder - 仓库路径占位符的展示形态。
+ * @param {string} [platform] - 覆盖 `process.platform`（测试用）。
+ * @returns {string|null}
+ */
+export function choroCliCommand(entry, repoPlaceholder, platform = process.platform) {
+  if (!entry) return null;
+  const quoted = platform === "win32"
+    ? `"${entry}"`
+    : `'${entry.replace(/'/g, "'\\''")}'`;
+  return `node ${quoted} ${repoPlaceholder} --apply`;
+}
+
+/**
+ * 一站式的便捷口：从调用方的 `import.meta.url` 直接拿到命令串。
+ * 找不到入口返回 null，调用方据此选通用说法。
+ *
+ * @param {string} fromModuleUrl
+ * @param {string} repoPlaceholder
+ * @param {string} [platform]
+ * @returns {string|null}
+ */
+export function choroCliCommandFrom(fromModuleUrl, repoPlaceholder, platform = process.platform) {
+  return choroCliCommand(choroCliEntry(fromModuleUrl), repoPlaceholder, platform);
+}