@modusensus/dsh-mneme 0.10.0 → 0.11.0

package/lib/wiki/t0.js

@@ -0,0 +1,463 @@
+// dsh-mneme/src/wiki/t0.js
+// T0 编排（spec §6 步 1–8）：读 plan → 列文件 → 解析 import 图 → 划分模块 →
+// 渲染骨架 → dry-run 报告或 apply 写盘 + 落库 + state.json 收尾。
+//
+// 全程零模型、零网络、可离线（spec：T0「秒级、可离线、必有产出」）。所有磁盘写入
+// 被限定在 `<repo>/.chorography/` 之内（红线 1 的机械面：写路径断言 + 不碰
+// .github/.gitignore/AGENTS.md，契约测试对整个仓库做树快照比对）。
+//
+// 失败语义（红线 5）：中途任何一步失败，state.json 不写（保持上一次成功 run 的
+// 内容），库侧 replaceChoroGraph 是单事务——半截失败整体回滚到上一次成功 run。
+// 重跑幂等：同样的输入得到同样的划分、同样的页面字节、同样的行数。
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, realpathSync, readdirSync } from "node:fs";
+import { join, posix, sep, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { loadPlanFromRepo } from "./plan.js";
+import {
+  listFiles, parseImportGraph, repoFingerprint, countLines,
+  readRootPackage, workspacePrefixes, compileInclude,
+} from "./scan.js";
+import { partitionModules } from "./partition.js";
+import {
+  renderSkeletonPage, renderIndex, extractHumanBlocks, injectHumanBlocks,
+  TEMPLATE_VERSION, T1_SECTION_START,
+} from "./render.js";
+
+export const CHORO_DIR = ".chorography";
+
+/** 拒绝类：CLI 据此透出人话并 exit 1（不写任何东西就退）。 */
+export class ChoroRefusal extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "ChoroRefusal";
+    this.code = code;
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.repoRoot 仓库路径（内部 realpath）
+ * @param {object|null} opts.store createStore 产物（apply 时必传；dry-run 可为 null）
+ * @param {boolean} [opts.apply=false] false = dry-run（零写入）
+ * @param {() => string} [opts.now] ISO 时刻（测试注入假时钟）
+ */
+export function runChoroT0({ repoRoot, store = null, apply = false, now = () => new Date().toISOString() }) {
+  let rootPath;
+  try {
+    rootPath = realpathSync(resolve(repoRoot));
+  } catch (err) {
+    throw new ChoroRefusal("no-such-dir", `仓库路径不存在或不可达：${repoRoot}（${String(err?.message ?? err)}）`);
+  }
+  if (!statDir(rootPath)) {
+    throw new ChoroRefusal("no-such-dir", `仓库路径不是目录：${rootPath}`);
+  }
+
+  // git 基线（spec 降级表第一行：不是 git 仓库 → 拒绝并说明原因，锚点无法核验）。
+  const gitBaseline = gitHead(rootPath);
+  if (!gitBaseline) {
+    throw new ChoroRefusal(
+      "not-git",
+      `${rootPath} 不是 git 仓库（git rev-parse HEAD 失败）。chorography 的每条出处锚点都要能对着提交核验，非 git 目录拒绝生成。`
+    );
+  }
+
+  // plan.yaml（用户所有，机器只读）：有 → 严格校验（未知键整轮拒绝）；无 → 默认启发式。
+  const loaded = loadPlanFromRepo(rootPath);
+  const plan = loaded.plan;
+
+  // 扫描（spec 步 2–3）。include 白名单非空时文件还须命中任意一条。
+  const includeMatcher = compileInclude(plan.include ?? []);
+  let files = listFiles(rootPath, { exclude: plan.exclude ?? [] });
+  if ((plan.include ?? []).length > 0) files = files.filter((f) => includeMatcher.matchesFile(f));
+  const graph = parseImportGraph(rootPath, files);
+
+  // 划分（spec 步 4）。workspace 前缀目前只作登记，不参与合并启发式（v1 保守）。
+  const pkg = readRootPackage(rootPath);
+  workspacePrefixes(pkg?.workspaces ?? []);
+  const repoName = pkg?.name ?? rootPath.split(/[\\/]/).pop() ?? "repo";
+  const modules = partitionModules({ files, graph, maxFilesPerPage: plan.maxFilesPerPage, repoName });
+
+  // 模块级依赖边（M1 补口 P8）：文件级边按所属模块聚合，只留跨模块方向；排序
+  // 进快照，库里的边集与页面字节一样可重建。
+  const slugByFile = new Map();
+  for (const mod of modules) {
+    for (const f of mod.files) slugByFile.set(f, mod.slug);
+  }
+  const edgeAgg = new Map();
+  for (const e of graph.edges) {
+    const from = slugByFile.get(e.from);
+    const to = slugByFile.get(e.to);
+    if (!from || !to || from === to) continue;
+    const key = `${from}|${to}`;
+    edgeAgg.set(key, (edgeAgg.get(key) ?? 0) + 1);
+  }
+  const moduleEdges = [...edgeAgg.entries()]
+    .map(([key, weight]) => {
+      const [fromSlug, toSlug] = key.split("|");
+      return { fromSlug, toSlug, weight };
+    })
+    .sort((a, b) =>
+      a.fromSlug < b.fromSlug ? -1 : a.fromSlug > b.fromSlug ? 1 : a.toSlug < b.toSlug ? -1 : 1
+    );
+
+  // 页面白名单（D7 正面控制）：plan.pages 非空时只给列出的 slug 建页。
+  const whitelist = plan.pages && plan.pages.length > 0 ? new Map(plan.pages.map((p) => [p.path, p])) : null;
+  const warnings = [];
+  if (whitelist) {
+    for (const [path] of whitelist) {
+      if (!modules.some((m) => m.slug === path)) {
+        warnings.push(`plan.yaml pages 里的 "${path}" 没有对应的模块划分结果（划分会随代码漂移，这不是错误，只提示）。`);
+      }
+    }
+  }
+
+  // state.json：沿用上次成功 run 的 generatedAt（实现计划 P3）——只有当
+  // plan 与仓库状态都没变时沿用，页面字节才逐字稳定（spec §9 可重建不变量）。
+  const fingerprint = repoFingerprint(files, graph.edges);
+  const prevState = readState(rootPath);
+  const stateStable =
+    prevState !== null &&
+    prevState.planFingerprint === loaded.fingerprint &&
+    prevState.repoFingerprint === fingerprint;
+  const generatedAt = stateStable && prevState.generatedAt ? prevState.generatedAt : now();
+
+  const unresolvedTotal = graph.unresolved.length;
+
+  // 页面组装（spec 步 6）。
+  const pageTargets = [];
+  for (const mod of modules) {
+    if (whitelist && !whitelist.has(mod.slug)) continue;
+    const entry = assembleModuleView(mod, modules, graph, rootPath);
+    const custom = whitelist?.get(mod.slug);
+    let content = renderSkeletonPage(entry, {
+      slug: mod.slug,
+      title: custom?.title ?? mod.title,
+      parents: parentChain(mod, modules),
+      sourceFiles: mod.files,
+      gitBaseline,
+      generatedAt,
+      status: "skeleton",
+      language: "zh",
+    });
+    const extra = renderPlanExtras(custom, plan, warnings);
+    if (extra) content = `${content.replace(/\n*$/, "\n")}\n${extra}`;
+    pageTargets.push({ moduleSlug: mod.slug, relPath: `${CHORO_DIR}/modules/${mod.slug}.md`, content });
+  }
+
+  const indexRelPath = `${CHORO_DIR}/index.md`;
+  // index 是「页面目录」：白名单挡掉的模块没有页，目录里也不列（列出会指向不存在的文件）。
+  const indexedModules = modules.filter((m) => !whitelist || whitelist.has(m.slug));
+  const indexContent = renderIndex(
+    indexedModules.map((m) => ({
+      ...m,
+      fileLines: [],
+    })),
+    {
+      name: repoName,
+      gitBaseline,
+      generatedAt,
+      fileCount: files.length,
+      skipped: graph.skipped.length,
+      unresolved: unresolvedTotal,
+      scripts: pkg?.scripts ?? {},
+    }
+  );
+
+  // T0 重跑会把已富化的页退回骨架（P19：富化层不参与字节稳定不变量，重建整页丢弃
+  // 重来）。丢弃本身是设计意图，静默不是：不清点的话，人看到的只是「跑完 T0，语义
+  // 段落没了」，而 .chorography/evidence/*.json 还会变成没人引用的孤儿。这里只报，
+  // 不改字节、不删 evidence——一条只读的清点，dry-run 与 apply 共用。
+  const t1Loss = collectT1Loss(rootPath, pageTargets);
+  if (t1Loss.pages.length > 0) {
+    const names = t1Loss.pages.slice(0, 3).join("、");
+    warnings.push(
+      `${t1Loss.pages.length} 页含 T1 语义段（${names}${t1Loss.pages.length > 3 ? " 等" : ""}）：`
+      + `本次会退回骨架、清空 choro_claims`
+      + `${t1Loss.orphanEvidence > 0 ? `，${t1Loss.orphanEvidence} 份 evidence 文件会变成孤儿（不删）` : ""}。`
+      + "要留住语义段就别在这里重跑 T0；需要时再用 --t1 重新富化。"
+    );
+  }
+
+  if (!apply) {
+    return {
+      dryRun: true,
+      repoPath: rootPath,
+      repoName,
+      gitBaseline,
+      planPath: loaded.planPath,
+      planFingerprint: loaded.fingerprint,
+      repoFingerprint: fingerprint,
+      generatedAt,
+      reusedGeneratedAt: stateStable,
+      fileCount: files.length,
+      moduleCount: modules.length,
+      pageCount: pageTargets.length,
+      skippedByWhitelist: whitelist ? modules.length - pageTargets.length : 0,
+      skippedFiles: graph.skipped,
+      unresolvedCount: unresolvedTotal,
+      humanBlocksSeen: countExistingHumanBlocks(rootPath, pageTargets),
+      t1Loss: { pages: t1Loss.pages, orphanEvidence: t1Loss.orphanEvidence },
+      wouldWrite: [...pageTargets.map((p) => ({ path: p.relPath, bytes: Buffer.byteLength(p.content, "utf8") })),
+        { path: indexRelPath, bytes: Buffer.byteLength(indexContent, "utf8") },
+        { path: `${CHORO_DIR}/state.json`, bytes: 0 }],
+      warnings,
+      moduleSummary: modules.map((m) => ({
+        slug: m.slug, title: m.title, fileCount: m.fileCount,
+        internalEdges: m.internalEdges.length, externalDeps: m.externalDeps.length,
+      })),
+    };
+  }
+
+  if (!store) throw new ChoroRefusal("store-required", "apply 模式需要打开的 store（memory.db）。");
+
+  // apply：写盘 → 落库 → state.json 收尾（红线 5：失败不推进 state）。
+  const choroDir = join(rootPath, CHORO_DIR);
+  mkdirSync(join(choroDir, "modules"), { recursive: true });
+
+  let humanBlocksPreserved = 0;
+  let bytes = 0;
+  for (const target of pageTargets) {
+    const abs = assertInsideChoro(rootPath, target.relPath);
+    const finalContent = preserveHumanBlocks(abs, target.content);
+    if (finalContent.humanBlocks > 0) humanBlocksPreserved += finalContent.humanBlocks;
+    writeFileSync(abs, finalContent.content, "utf8");
+    bytes += Buffer.byteLength(finalContent.content, "utf8");
+  }
+  const indexAbs = assertInsideChoro(rootPath, indexRelPath);
+  writeFileSync(indexAbs, indexContent, "utf8");
+  bytes += Buffer.byteLength(indexContent, "utf8");
+
+  const repoRow = store.upsertChoroRepo(rootPath, repoName, loaded.fingerprint, gitBaseline, generatedAt);
+  store.replaceChoroGraph(repoRow.id, {
+    edges: moduleEdges,
+    modules: modules.map((m) => ({
+      slug: m.slug,
+      title: (whitelist?.get(m.slug)?.title) ?? m.title,
+      parentSlug: m.parentSlug,
+      fileCount: m.fileCount,
+      fingerprint: m.fingerprint,
+    })),
+    pages: pageTargets.map((p) => ({
+      moduleSlug: p.moduleSlug,
+      relPath: p.relPath,
+      status: "skeleton",
+      gitBaseline,
+      templateVersion: TEMPLATE_VERSION,
+      generatedAt,
+      humanBlockCount: existingHumanBlockCount(join(rootPath, p.relPath)),
+      claims: [],
+    })),
+    updatedAt: generatedAt,
+  });
+
+  const state = {
+    choro: "v1",
+    gitBaseline,
+    templateVersion: TEMPLATE_VERSION,
+    planFingerprint: loaded.fingerprint,
+    repoFingerprint: fingerprint,
+    generatedAt,
+    moduleCount: modules.length,
+    pageCount: pageTargets.length,
+    fileCount: files.length,
+  };
+  const stateAbs = assertInsideChoro(rootPath, `${CHORO_DIR}/state.json`);
+  writeFileSync(stateAbs, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+
+  return {
+    dryRun: false,
+    repoPath: rootPath,
+    repoName,
+    gitBaseline,
+    planPath: loaded.planPath,
+    planFingerprint: loaded.fingerprint,
+    repoFingerprint: fingerprint,
+    generatedAt,
+    reusedGeneratedAt: stateStable,
+    fileCount: files.length,
+    moduleCount: modules.length,
+    pageCount: pageTargets.length,
+    skippedByWhitelist: whitelist ? modules.length - pageTargets.length : 0,
+    skippedFiles: graph.skipped,
+    unresolvedCount: unresolvedTotal,
+    humanBlocksPreserved,
+    bytes,
+    t1Loss: { pages: t1Loss.pages, orphanEvidence: t1Loss.orphanEvidence },
+    warnings,
+    moduleSummary: modules.map((m) => ({
+      slug: m.slug, title: m.title, fileCount: m.fileCount,
+      internalEdges: m.internalEdges.length, externalDeps: m.externalDeps.length,
+    })),
+  };
+}
+
+/* ------------------------------ 内部件 ------------------------------ */
+
+function statDir(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function gitHead(repoRoot) {
+  try {
+    const out = execFileSync("git", ["rev-parse", "HEAD"], { cwd: repoRoot, encoding: "utf8" });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function readState(repoRoot) {
+  try {
+    const raw = readFileSync(join(repoRoot, CHORO_DIR, "state.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// 组装渲染视图：行数、入口、模块级上/下游、逐模块 unresolved 计数。
+function assembleModuleView(mod, modules, graph, rootPath) {
+  const fileSet = new Set(mod.files);
+  const fileLines = mod.files.map((f) => [f, countLines(rootPath, f)]);
+  const entries = mod.files.filter((f) => /^(index|main)\.(js|mjs|cjs|ts|tsx|jsx|vue)$/.test(posix.basename(f)));
+  const slugByFile = new Map();
+  for (const other of modules) {
+    for (const f of other.files) slugByFile.set(f, other.slug);
+  }
+  const upstream = new Set();
+  const downstream = new Set();
+  // 跨模块方向查全图：本模块文件引用别的模块 → upstream（本模块的依赖）；
+  // 别的模块引用本模块文件 → downstream（谁依赖它）。模块内部边不计方向。
+  for (const e of graph.edges) {
+    if (slugByFile.get(e.from) === mod.slug && slugByFile.get(e.to) !== mod.slug) upstream.add(slugByFile.get(e.to));
+    if (slugByFile.get(e.from) !== mod.slug && slugByFile.get(e.to) === mod.slug) downstream.add(slugByFile.get(e.from));
+  }
+  const unresolvedCount = graph.unresolved.filter((u) => fileSet.has(u.from)).length;
+  return {
+    ...mod,
+    fileLines,
+    entries: entries.sort(),
+    upstream: [...upstream].filter((s) => s && s !== mod.slug).sort(),
+    downstream: [...downstream].filter((s) => s && s !== mod.slug).sort(),
+    unresolvedCount,
+  };
+}
+
+function parentChain(mod, modules) {
+  const chain = [];
+  let current = mod;
+  const bySlug = new Map(modules.map((m) => [m.slug, m]));
+  while (current?.parentSlug) {
+    const parent = bySlug.get(current.parentSlug);
+    if (!parent) break;
+    chain.push(parent.slug);
+    current = parent;
+  }
+  return chain.reverse();
+}
+
+// plan.pages 的 template / notes 的 M0 确定性处理：模板正文与作图笔记原文追加为
+// 页尾小节（零模型语义下「每页模板」能做到的就是把人写的话原样放进页里）。模板名
+// 查不到时页里放占位、warnings 里也记一条——两头都看得见，不静默吞。
+function renderPlanExtras(custom, plan, warnings) {
+  if (!custom) return null;
+  const parts = [];
+  if (custom.template) {
+    const body = plan.templates?.[custom.template];
+    if (typeof body === "string") {
+      parts.push(`## 模板：${custom.template}`);
+      parts.push("");
+      parts.push(body.replace(/\n*$/, ""));
+      parts.push("");
+    } else {
+      warnings.push(`plan.yaml pages["${custom.path}"] 引用的模板 "${custom.template}" 在 templates 里没有定义，页里先放了占位。`);
+      parts.push(`## 模板：${custom.template}`);
+      parts.push("");
+      parts.push(`> plan.yaml 引用的模板 "${custom.template}" 在 templates 里没有定义；这段先占位，模板补上后重跑即得正文。`);
+      parts.push("");
+    }
+  }
+  if (custom.notes) {
+    parts.push("## 作图笔记（plan.yaml notes）");
+    parts.push("");
+    parts.push(custom.notes.replace(/\n*$/, ""));
+    parts.push("");
+  }
+  return parts.length > 0 ? parts.join("\n") : null;
+}
+
+// 写盘前的保留区保留：已有页面文件里的 CHORO:HUMAN 块整体抽出，逐字节接回新正文
+// 页尾（实现计划 P6）。文件不存在（首轮）就当无块，直接用新正文。
+function preserveHumanBlocks(absPath, newContent) {
+  let blocks = [];
+  if (existsSync(absPath)) {
+    try {
+      blocks = extractHumanBlocks(readFileSync(absPath, "utf8")).blocks;
+    } catch {
+      blocks = [];
+    }
+  }
+  const content = blocks.length > 0 ? injectHumanBlocks(newContent, blocks) : newContent;
+  return { content, humanBlocks: blocks.length };
+}
+
+function existingHumanBlockCount(absPath) {
+  if (!existsSync(absPath)) return 0;
+  try {
+    return extractHumanBlocks(readFileSync(absPath, "utf8")).count;
+  } catch {
+    return 0;
+  }
+}
+
+// 重跑 T0 会丢掉的东西：页面里已有的 T1 语义段，以及只被它引用的 evidence 文件。
+// 返回值里的 pages 是相对路径（receipt 里人读），orphanEvidence 是 .chorography/
+// evidence/ 下现有的 .json 个数——T0 apply 会清空 choro_claims，这些文件从此没有
+// 引用者。两者都是「会失去什么」的清点，不构成阻止：丢弃是设计意图，静默才是 bug。
+function collectT1Loss(rootPath, pageTargets) {
+  const pages = [];
+  for (const target of pageTargets) {
+    const abs = join(rootPath, target.relPath);
+    if (!existsSync(abs)) continue;
+    try {
+      if (readFileSync(abs, "utf8").includes(T1_SECTION_START)) pages.push(target.relPath);
+    } catch {
+      /* 读不了就当没有：清点不该让 T0 失败 */
+    }
+  }
+  let orphanEvidence = 0;
+  const evidenceDir = join(rootPath, CHORO_DIR, "evidence");
+  try {
+    orphanEvidence = readdirSync(evidenceDir).filter((name) => name.endsWith(".json")).length;
+  } catch {
+    orphanEvidence = 0;
+  }
+  return { pages, orphanEvidence };
+}
+
+function countExistingHumanBlocks(rootPath, pageTargets) {
+  let n = 0;
+  for (const target of pageTargets) {
+    n += existingHumanBlockCount(join(rootPath, target.relPath));
+  }
+  return n;
+}
+
+// 红线 1 的机械面：所有写路径必须落在 <root>/.chorography/ 内。slug 由 slugify
+// 生成（[a-z0-9-]），这条断言是保险层不是唯一防线——划分器改动时先撞这里。
+function assertInsideChoro(rootPath, relPath) {
+  const abs = resolve(rootPath, relPath.split("/").join(sep));
+  const choroRoot = resolve(rootPath, CHORO_DIR);
+  if (!(abs === choroRoot || abs.startsWith(choroRoot + sep))) {
+    throw new ChoroRefusal(
+      "write-outside-chorography",
+      `写路径越出 ${CHORO_DIR}/：${relPath}（红线 1：chorography 绝不写仓库里任何别的位置）`
+    );
+  }
+  return abs;
+}