@modusensus/dsh-mneme 0.10.1 → 0.11.0

package/test/wiki-inject.test.js

@@ -0,0 +1,265 @@
+// wiki/inject.js 的回归锁（M3 开局注入）。全部用例走真实 T0（fixture 仓库 apply）
+// 建数据，不手插 DB 行——这一层测的正是「DB 索引 × cwd 反查」的对账。
+// 锁的点：档位解析（含轻量档压成 off）、只注标题级、light 的 6 行上限与排序、
+// 字符预算的逐行截断（不许半行）、空串语义（不注入 = 空串而非占位）、
+// 渲染失败绝不抛、缓存随 updated_at 失效、转义只做在注入层。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { runChoroT0 } from "../src/wiki/t0.js";
+import { createStore } from "../src/store.js";
+import { createChoroQueries } from "../src/wiki/queries.js";
+import {
+  createChoroInject,
+  renderChoroBlock,
+  resolveInjectTier,
+  LIGHT_MODULE_LIMIT,
+  MAX_BLOCK_CHARS
+} from "../src/wiki/inject.js";
+import { escapePromptVars } from "../src/user-settings.js";
+
+const FIXED_NOW = () => "2026-11-05T00:00:00.000Z";
+
+/** 造仓库：files = [[相对路径, 内容], ...]，返回根目录。 */
+function makeFixture(files = null) {
+  const root = mkdtempSync(join(tmpdir(), "choro-inject-"));
+  const items = files ?? [
+    ["package.json", JSON.stringify({ name: "ifix", scripts: { test: "node --test" } }, null, 2) + "\n"],
+    ["src/a.js", 'import { b } from "./b.js";\nexport const a = () => b();\n'],
+    ["src/b.js", 'import { b2 } from "./b2.js";\nexport const b = () => b2();\n'],
+    ["src/b2.js", "export const b2 = () => 1;\n"]
+  ];
+  for (const [rel, content] of items) {
+    const abs = join(root, rel);
+    mkdirSync(join(abs, ".."), { recursive: true });
+    writeFileSync(abs, content, "utf8");
+  }
+  execFileSync("git", ["init", "-b", "main"], { cwd: root, stdio: "pipe" });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "add", "-A"], { cwd: root, stdio: "pipe" });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", "init", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+  return root;
+}
+
+function rmTempBestEffort(dir) {
+  for (let i = 0; i < 5; i++) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+      return;
+    } catch {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
+    }
+  }
+  console.warn("[wiki-inject.test] 临时目录清理未完成：" + dir);
+}
+
+function setup(config = {}, over = {}) {
+  const root = makeFixture(over.files ?? null);
+  const store = createStore(":memory:");
+  runChoroT0({ repoRoot: root, store, apply: true, now: FIXED_NOW });
+  const choro = createChoroQueries({ store });
+  return { root, store, choro };
+}
+
+const ON = { chorographyEnabled: true, chorographyInject: "light" };
+
+test("resolveInjectTier：总闸关 / 轻量档 / 非法值 / 缺省的四条口径", () => {
+  assert.equal(resolveInjectTier(null), "off");
+  assert.equal(resolveInjectTier({}), "off", "chorographyEnabled 默认关 → 不注入");
+  assert.equal(resolveInjectTier({ chorographyEnabled: false }), "off");
+  assert.equal(resolveInjectTier({ chorographyEnabled: true }), "light", "缺 chorographyInject 时按 light");
+  assert.equal(resolveInjectTier({ chorographyEnabled: true, chorographyInject: "full" }), "full");
+  assert.equal(resolveInjectTier({ chorographyEnabled: true, chorographyInject: "off" }), "off");
+  assert.equal(resolveInjectTier({ chorographyEnabled: true, chorographyInject: "bogus" }), "light", "非法值退回缺省，不静默关掉");
+  // 轻量档在消费侧压成 off：LIGHT_MODE_OFF 对平铺键赋 false，枚举键进不去（P26）
+  assert.equal(resolveInjectTier({ chorographyEnabled: true, lightMode: true }), "off");
+  assert.equal(resolveInjectTier({ chorographyEnabled: false, lightMode: false }), "off");
+});
+
+test("renderChoroBlock：只注标题级，模块名 / 文件数 / 页状态 / 页相对路径都在，正文一个字都不带", () => {
+  const { root, store, choro } = setup(ON);
+  try {
+    const repo = choro.repoByCwd(root);
+    const block = renderChoroBlock(choro.outline(repo.id), "full", "zh");
+    assert.ok(block.includes("[仓库地志]"), "有块头");
+    assert.ok(block.includes("ifix"), "仓库名");
+    assert.ok(block.includes("生成于 2026-11-05"), "生成日期：地志是快照不是真相，读者得知道它可能是旧的");
+    assert.ok(block.includes(".chorography/modules/src.md"), "页相对路径");
+    assert.ok(block.includes("（3 文件）"), "文件数");
+    // 「只注标题级」的机制锁：正文的节标题与说明行一个字都不许出现在注入块里
+    assert.equal(block.includes("## 文件清单"), false);
+    assert.equal(block.includes("确定性骨架"), false);
+    assert.equal(block.includes("| 文件 |"), false);
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("renderChoroBlock：light 只列 6 行并明说还有几个，full 列全表", () => {
+  // 9 个目录 → 9 个模块，超过 light 的 6 行上限
+  const files = [["package.json", JSON.stringify({ name: "bigfix" }) + "\n"]];
+  for (let i = 0; i < 9; i++) files.push([`p${i}/index.js`, `export const v${i} = ${i};\n`]);
+  const { root, store, choro } = setup(ON, { files });
+  try {
+    const repo = choro.repoByCwd(root);
+    const outline = choro.outline(repo.id);
+    assert.ok(outline.modules.length >= LIGHT_MODULE_LIMIT + 1, "夹具要多于上限才测得出截断");
+    const light = renderChoroBlock(outline, "light", "zh");
+    const lightLines = light.split("\n");
+    assert.equal(lightLines.length, LIGHT_MODULE_LIMIT + 2, "块头 1 + 模块 6 + 「还有 N 个」1");
+    assert.ok(light.includes("另有 " + (outline.modules.length - LIGHT_MODULE_LIMIT) + " 个模块"), "静默截断比明说更坏");
+    const full = renderChoroBlock(outline, "full", "zh");
+    assert.equal(full.includes("另有"), false, "full 不该有截断提示");
+    assert.equal(full.split("\n").length, outline.modules.length + 1);
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("renderChoroBlock：字符预算逐行截断，绝不切出半行", () => {
+  // 造足够多的模块让 full 撞 6000 字符上限
+  // 60 个「长名」模块就够撞上限：slug 取自目录名，目录名越长每条提纲行越长，
+  // 比堆 400 个短名文件快一个数量级（夹具成本不该压在 T0 的 git 扫描上）。
+  const files = [["package.json", JSON.stringify({ name: "hugefix" }) + "\n"]];
+  const longName = "very-deep-directory-name-that-keeps-going-for-quite-a-while-indeed";
+  for (let i = 0; i < 60; i++) files.push([`mod-${i}/${longName}/index.js`, `export const v = ${i};\n`]);
+  const { root, store, choro } = setup(ON, { files });
+  try {
+    const repo = choro.repoByCwd(root);
+    const block = renderChoroBlock(choro.outline(repo.id), "full", "zh");
+    assert.ok(block.length <= MAX_BLOCK_CHARS.full, "不超预算：" + block.length);
+    assert.ok(block.length > 0);
+    for (const line of block.split("\n")) {
+      assert.equal(line.startsWith("- ") || line.startsWith("["), true, "每一行都是完整的一行：" + line.slice(0, 40));
+    }
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("renderChoroBlock：空提纲 / 空模块返回空串（不注入 = 空串，宿主会过滤掉不占位）", () => {
+  assert.equal(renderChoroBlock(null, "light", "zh"), "");
+  assert.equal(renderChoroBlock({ repo: { name: "x" }, modules: [] }, "light", "zh"), "");
+  assert.equal(renderChoroBlock({ repo: { name: "x" } }, "light", "zh"), "");
+});
+
+test("createChoroInject：按 cwd 命中仓库才出块，未命中与总闸关都是空串", () => {
+  const { root, store, choro } = setup(ON);
+  try {
+    const on = createChoroInject({ choro, config: ON, language: () => "zh" });
+    assert.equal(on.tier, "light");
+    assert.ok(on.text(root).includes("[仓库地志]"));
+    assert.ok(on.text(join(root, "src")).includes("[仓库地志]"), "子目录也命中");
+    assert.equal(on.text(join(root, "no-such-dir")), "", "不存在的 cwd → 空串");
+    assert.equal(on.text(null), "", "没有 cwd → 空串");
+    const off = createChoroInject({ choro, config: { chorographyEnabled: false } });
+    assert.equal(off.text(root), "", "总闸关 → 空串");
+    const noChoro = createChoroInject({ choro: null, config: ON });
+    assert.equal(noChoro.text(root), "", "没有读侧对象也不抛");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("createChoroInject：渲染异常绝不抛，退化成空串", () => {
+  const warnings = [];
+  const boom = {
+    repoByCwd: () => ({ id: 1, updated_at: "2026-11-05T00:00:00.000Z" }),
+    outline: () => {
+      throw new Error("db is gone");
+    }
+  };
+  const inject = createChoroInject({
+    choro: boom,
+    config: ON,
+    logger: { warn: (m) => warnings.push(m) },
+    language: () => "zh"
+  });
+  assert.equal(inject.text("/whatever"), "", "附属信息块不能把整轮 systemPrompt 搞崩");
+  assert.equal(warnings.length, 1);
+  assert.ok(warnings[0].includes("db is gone"));
+});
+
+test("createChoroInject：每轮查一次库取缓存键（不 fork git），同键不重渲染，换语言换键", () => {
+  const { root, store, choro } = setup(ON);
+  try {
+    let lang = "zh";
+    let calls = 0;
+    const spy = {
+      repoByCwd: (cwd) => choro.repoByCwd(cwd),
+      outline: (id) => {
+        calls += 1;
+        return choro.outline(id);
+      }
+    };
+    const inject = createChoroInject({ choro: spy, config: ON, language: () => lang });
+    const first = inject.text(root);
+    const second = inject.text(root);
+    // 键要含页级生成时间，所以每轮必须查一次库——这是索引查询（几十微秒），
+    // 不是 P29 要避开的 fork git / stat 磁盘。这里锁的就是「查库了，但没重渲染」：
+    // 两次返回逐字节相同，说明缓存在生效而不是每次重新拼。
+    assert.equal(calls, 2, "每轮查一次库取缓存键");
+    assert.equal(second, first, "同一个键命中缓存，渲染结果一致");
+    lang = "en";
+    const en = inject.text(root);
+    assert.equal(calls, 3, "换语言换键");
+    assert.ok(en.includes("[Repo atlas]"));
+    inject.dispose();
+    assert.equal(inject.text(root).includes("[Repo atlas]"), true, "dispose 后仍能重算（只是丢了缓存）");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("createChoroInject：注入层的文本过 escapePromptVars，名字里的花括号不许崩宿主装配", () => {
+  const outline = {
+    repo: { id: 1, name: "weird{{name}}repo", updatedAt: "2026-11-05T00:00:00.000Z" },
+    generatedAt: "2026-11-05T00:00:00.000Z",
+    modules: [{ slug: "a", title: "m{{x}}", fileCount: 1, parentSlug: null, status: "skeleton", relPath: ".chorography/modules/a.md" }]
+  };
+  const fake = { repoByCwd: () => ({ id: 1, updated_at: "2026-11-05T00:00:00.000Z" }), outline: () => outline };
+  const inject = createChoroInject({ choro: fake, config: ON, language: () => "zh" });
+  const text = inject.text("/x");
+  // 契约不是「转义成某个具体形态」，而是「转义后不再留下任何成对花括号」：宿主
+  // 的 interpolate() 只认 /\{\{([^{}]*)\}\}/，只要 {{ 与 }} 都不成对出现，
+  // 就永远不会被当成变量引用。所以锁这两个子串，不锁反斜杠落在哪一格。
+  assert.equal(text.includes("{{"), false, "残留 {{ 会让宿主 interpolate 抛错崩整轮装配");
+  assert.equal(text.includes("}}"), false, "残留 }} 同上");
+  // 与转义函数逐字节一致：注入层是唯一做转义的地方，别的层不许再包一层。
+  assert.equal(text, escapePromptVars(ON, renderChoroBlock(outline, "light", "zh")));
+  // 未转义的渲染函数本身保持原样——/choro 的 UI 回执不进宿主模板，转义了反而难看
+  assert.ok(renderChoroBlock(outline, "light", "zh").includes("{{name}}"));
+});
+
+// T1 富化只推 choro_pages.generated_at，不动 choro_repos.updated_at（store.js:
+// markChoroPageEnriched 的注释写明「T0 整仓替换与 T1 页级富化并存」）。缓存键若挂
+// 在仓库行上，用户刚跑完 `--t1 --apply`，注入块还会写着「骨架」而 /choro（无缓存）
+// 已经报「已有语义段」——两个面说同一件事却给出不同答案。所以锁这条：页级状态一变，
+// 下一轮的注入块必须跟着变，且不是靠 dispose / 重启。
+test("createChoroInject：T1 富化只推页级 generated_at，缓存也必须失效（不能停在「骨架」）", () => {
+  const { root, store, choro } = setup(ON);
+  try {
+    const inject = createChoroInject({ choro, config: ON, language: () => "zh" });
+    const before = inject.text(root);
+    assert.equal(before.includes("已有语义段"), false, "富化前不该出现 enriched 标签");
+    const repo = choro.repoByCwd(root);
+    const repoRowBefore = store.choroRepoByRoot(root);
+    const page = store.choroPageBySlug(repo.id, "src");
+    assert.ok(page, "夹具必须切出 src 模块，否则这条用例测的是空气");
+    store.markChoroPageEnriched(page.id, "2026-11-06T09:00:00.000Z");
+    // 前提断言：富化确实没有碰仓库行——不然这条用例会假绿（更新的是 updated_at 也就命中）
+    assert.equal(store.choroRepoByRoot(root).updated_at, repoRowBefore.updated_at, "T1 富化不该动 choro_repos.updated_at");
+    const after = inject.text(root);
+    assert.equal(after.includes("已有语义段"), true, "页级生成时间变了，注入块必须重算");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});

package/test/wiki-partition.test.js

@@ -0,0 +1,112 @@
+// partition.js 的回归锁：划分确定性（同输入两次逐项相同——spec §9 可重建不变量的
+// 前半段）、兄弟组内聚合并、超限逐级下切、slug 稳定、父子链按目录包含。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { partitionModules } from "../src/wiki/partition.js";
+
+function graph(edges) {
+  const files = [...new Set(edges.flatMap((e) => [e.from, e.to]))].sort();
+  return { files, graph: { edges, external: new Map() } };
+}
+
+test("划分是确定性的：同输入两次结果逐项相同", () => {
+  const input = graph([
+    { from: "src/a.js", to: "src/b.js" },
+    { from: "lib/c.js", to: "src/a.js" },
+  ]);
+  const one = partitionModules({ ...input, maxFilesPerPage: 40, repoName: "demo" });
+  const two = partitionModules({ ...input, maxFilesPerPage: 40, repoName: "demo" });
+  assert.deepEqual(one, two);
+});
+
+test("根直属文件成 root 模块；目录组各自成页；互不相干的组不合并", () => {
+  // 显式给根直属文件（graph() 只从边推文件，不含根组）。
+  const files = ["README.md", "package.json", "src/a.js", "src/b.js", "tools/x.js", "tools/y.js"];
+  const g = {
+    edges: [
+      { from: "src/a.js", to: "src/b.js" },
+      { from: "tools/x.js", to: "tools/y.js" },
+    ],
+    external: new Map(),
+  };
+  const mods = partitionModules({ files, graph: g, maxFilesPerPage: 40, repoName: "demo" });
+  const slugs = mods.map((m) => m.slug).sort();
+  assert.deepEqual(slugs, ["root", "src", "tools"]);
+  const root = mods.find((m) => m.slug === "root");
+  assert.deepEqual(root.files.sort(), ["README.md", "package.json"]);
+  assert.equal(root.title, "demo（仓库根）");
+  const src = mods.find((m) => m.slug === "src");
+  assert.deepEqual(src.files.sort(), ["src/a.js", "src/b.js"]);
+});
+
+test("兄弟组交叉边 ≥3 才合并（内聚判据要能口述，V2 人判用）", () => {
+  // utils 与 src 之间 3 条边 → 合并成一个模块
+  const strong = graph([
+    { from: "src/a.js", to: "utils/u1.js" },
+    { from: "src/b.js", to: "utils/u1.js" },
+    { from: "src/a.js", to: "utils/u2.js" },
+  ]);
+  const merged = partitionModules({ ...strong, maxFilesPerPage: 40, repoName: "demo" });
+  assert.equal(merged.length, 1, "3 条交叉边触发合并");
+  // 只有 2 条边 → 各自独立
+  const weak = graph([
+    { from: "src/a.js", to: "utils/u1.js" },
+    { from: "src/b.js", to: "utils/u1.js" },
+  ]);
+  const separate = partitionModules({ ...weak, maxFilesPerPage: 40, repoName: "demo" });
+  assert.equal(separate.length, 2, "2 条边不合并");
+});
+
+test("超 max_files_per_page 的组逐级下切，叶子组仍超限按字典序切块", () => {
+  const files = [];
+  const edges = [];
+  for (let i = 0; i < 7; i++) {
+    files.push(`big/f${i}.js`);
+    if (i > 0) edges.push({ from: "big/f0.js", to: `big/f${i}.js` });
+  }
+  const mods = partitionModules({ files, graph: { edges, external: new Map() }, maxFilesPerPage: 3, repoName: "demo" });
+  const total = mods.reduce((sum, m) => sum + m.fileCount, 0);
+  assert.equal(total, 7, "切分不丢文件");
+  assert.ok(mods.every((m) => m.fileCount <= 3), "每块都不超上限");
+  assert.ok(mods.length >= 3, "7 个文件、上限 3 → 至少 3 块");
+  // slug 唯一（切块组的 #2 序号后缀避免撞名）
+  const slugs = mods.map((m) => m.slug);
+  assert.equal(new Set(slugs).size, slugs.length, "slug 无重复");
+});
+
+test("父链按目录包含取最近祖先（spec frontmatter.parents / DB parent_id 同源）", () => {
+  const { files, graph: g } = graph([
+    { from: "src/store/index.js", to: "src/store/util.js" },
+    { from: "src/wiki/t0.js", to: "src/store/index.js" },
+  ]);
+  const mods = partitionModules({ files, graph: g, maxFilesPerPage: 40, repoName: "demo" });
+  // 初稿是两级目录段：src/store、src/wiki；「src」本身不是组 → 无父链也合法，
+  // 但 src/store 与 src/wiki 之间没有包含关系（同层），互不为父。
+  const store = mods.find((m) => m.dir === "src/store");
+  const wiki = mods.find((m) => m.dir === "src/wiki");
+  assert.ok(store && wiki);
+  assert.equal(store.parentSlug, null, "同级目录不是父子");
+});
+
+test("模块指纹随文件集/边集变化（DB 记账与过期检测的输入）", () => {
+  const a = partitionModules({ ...graph([{ from: "src/a.js", to: "src/b.js" }]), maxFilesPerPage: 40, repoName: "d" });
+  const b = partitionModules({
+    files: ["src/a.js", "src/b.js", "src/c.js"],
+    graph: { edges: [{ from: "src/a.js", to: "src/b.js" }], external: new Map() },
+    maxFilesPerPage: 40,
+    repoName: "d",
+  });
+  const fa = a.find((m) => m.slug === "src").fingerprint;
+  const fb = b.find((m) => m.slug === "src").fingerprint;
+  assert.notEqual(fa, fb, "文件集变了指纹必须变");
+});
+
+test("外部依赖按模块聚合（骨架页「外部依赖」一节的数据源）", () => {
+  const files = ["src/a.js", "src/b.js", "lib/c.js"];
+  const external = new Map([["left-pad", new Set(["src/a.js", "src/b.js"])]]);
+  const mods = partitionModules({ files, graph: { edges: [], external }, maxFilesPerPage: 40, repoName: "d" });
+  const src = mods.find((m) => m.dir === "src");
+  assert.deepEqual(src.externalDeps, [{ pkg: "left-pad", count: 2 }]);
+  const lib = mods.find((m) => m.dir === "lib");
+  assert.deepEqual(lib.externalDeps, []);
+});

package/test/wiki-plan.test.js

@@ -0,0 +1,80 @@
+// plan.yaml 校验的回归锁（spec §4 / §9；实现计划 P1）。
+// 锁三类回归：未知键必须整轮拒绝（拼错的键等于失效的控制，不能静默忽略）、
+// 类型错误逐条收集一次报完（人一次改完，不逐个试错）、无 plan.yaml 走默认启发式。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { loadPlan, planFingerprint, PLAN_ALLOWED_KEYS, PlanInvalidError } from "../src/wiki/plan.js";
+
+test("无 plan.yaml / 空文件走默认启发式", () => {
+  const a = loadPlan(null);
+  assert.equal(a.plan.maxFilesPerPage, 40);
+  assert.deepEqual(a.plan.exclude, []);
+  assert.equal(a.plan.pages, null);
+  assert.deepEqual(a.plan.templates, {});
+  // 「没带 plan」也是可记账状态：指纹 = 空串 sha256
+  assert.equal(a.fingerprint, planFingerprint(""));
+  const b = loadPlan("   \n");
+  assert.equal(b.plan.maxFilesPerPage, 40);
+});
+
+test("未知键整轮拒绝，报出键名与允许列表（spec 降级表第一行）", () => {
+  assert.throws(
+    () => loadPlan("includes:\n  - src\n"),
+    (err) => {
+      assert.ok(err instanceof PlanInvalidError);
+      assert.ok(err.message.includes("includes"), "报错要点名拼错的键");
+      assert.ok(err.message.includes("include"), "有相近键时给改正提示");
+      assert.ok(err.message.includes("允许的顶层键"));
+      for (const k of PLAN_ALLOWED_KEYS) assert.ok(err.message.includes(k));
+      return true;
+    }
+  );
+});
+
+test("完全不相干的未知键不给误导性提示", () => {
+  assert.throws(
+    () => loadPlan("zzzzqqqq: 1\n"),
+    (err) => err.message.includes("zzzzqqqq")
+  );
+});
+
+test("类型错误逐条收集、一次报完（不 fail-fast）", () => {
+  try {
+    loadPlan("exclude: not-an-array\nmax_files_per_page: zero\npages:\n  - path: \"\"\n");
+    assert.fail("应该抛 PlanInvalidError");
+  } catch (err) {
+    assert.ok(err instanceof PlanInvalidError);
+    assert.ok(err.issues.length >= 3, `至少三条 issue，实际 ${err.issues.length}`);
+    assert.ok(err.issues.some((i) => i.includes("exclude")));
+    assert.ok(err.issues.some((i) => i.includes("max_files_per_page")));
+    assert.ok(err.issues.some((i) => i.includes("pages[0]")));
+  }
+});
+
+test("YAML 语法错误也走同一条拒绝路径", () => {
+  assert.throws(() => loadPlan("a: [1, 2\nb: }\n"), PlanInvalidError);
+});
+
+test("pages 白名单形状合法时被接受，模板/笔记被保留", () => {
+  const { plan } = loadPlan(
+    "pages:\n  - path: src\n    title: 源码主区\n    template: arch\n    notes: 关注导出面\n" +
+    "templates:\n  arch: |\n    自定义正文行\n"
+  );
+  assert.deepEqual(plan.pages, [{ path: "src", title: "源码主区", template: "arch", notes: "关注导出面" }]);
+  assert.equal(plan.templates.arch, "自定义正文行\n");
+});
+
+test("pages 重复 path / 未知页级键 / 非 mapping 都被点名", () => {
+  try {
+    loadPlan("pages:\n  - path: src\n  - path: src\n  - bogus: 1\n  - 42\n");
+    assert.fail("应该抛");
+  } catch (err) {
+    assert.ok(err.issues.some((i) => i.includes("重复")));
+    assert.ok(err.issues.some((i) => i.includes("bogus")));
+    assert.ok(err.issues.some((i) => i.includes("pages[3]")));
+  }
+});
+
+test("指纹随内容变化（plan.yaml 改了就要重划边界）", () => {
+  assert.notEqual(planFingerprint("a: 1\n"), planFingerprint("a: 2\n"));
+});

package/test/wiki-queries.test.js

@@ -0,0 +1,187 @@
+// queries.js 的回归锁（M1 读侧）。全部用例走真实 T0（fixture 仓库 apply）建数据，
+// 不手插 DB 行——读侧的契约是「DB 索引 × 磁盘真源」的对账，手插行测不出盘上缺页
+// 这类真实故障。锁的点：slug 白名单解析（查不到返回 null，绝不拿用户输入拼路径）、
+// 盘上缺页如实报 page-missing、检索分节与行号、repo 解析的歧义处理。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { runChoroT0 } from "../src/wiki/t0.js";
+import { createStore } from "../src/store.js";
+import { createChoroQueries } from "../src/wiki/queries.js";
+
+const FIXED_NOW = () => "2026-11-05T00:00:00.000Z";
+
+function makeFixture() {
+  const root = mkdtempSync(join(tmpdir(), "choro-queries-"));
+  writeFileSync(join(root, "package.json"), JSON.stringify({ name: "qfix", scripts: { test: "node --test" } }, null, 2) + "\n", "utf8");
+  mkdirSync(join(root, "src"), { recursive: true });
+  writeFileSync(join(root, "src", "a.js"), 'import { b } from "./b.js";\nimport h from "left-pad";\nexport const a = () => b();\n', "utf8");
+  writeFileSync(join(root, "src", "b.js"), 'import { b2 } from "./b2.js";\nexport const b = () => b2();\n', "utf8");
+  writeFileSync(join(root, "src", "b2.js"), "export const b2 = () => 1;\n", "utf8");
+  execFileSync("git", ["init", "-b", "main"], { cwd: root, stdio: "pipe" });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "add", "-A"], { cwd: root, stdio: "pipe" });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", "init", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+  return root;
+}
+
+function rmTempBestEffort(dir) {
+  for (let i = 0; i < 5; i++) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+      return;
+    } catch {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
+    }
+  }
+  console.warn(`[wiki-queries.test] 临时目录清理未完成：${dir}`);
+}
+
+function setup() {
+  const root = makeFixture();
+  const store = createStore(":memory:");
+  runChoroT0({ repoRoot: root, store, apply: true, now: FIXED_NOW });
+  return { root, store, q: createChoroQueries({ store }) };
+}
+
+test("listRepos / resolveRepo：单仓自动收敛，多仓歧义要显式给键", () => {
+  const { root, store, q } = setup();
+  try {
+    const repos = q.listRepos();
+    assert.equal(repos.length, 1);
+    assert.equal(repos[0].module_count, 2, "src 与 root 两个模块（1 条跨模块边不触发合并）");
+    assert.equal(repos[0].page_count, 2);
+    const auto = q.resolveRepo(undefined);
+    assert.equal(auto.id, repos[0].id, "只有一个仓库时不带键也能解析");
+    assert.ok(q.resolveRepo("qfix").id, "按显示名解析");
+    assert.equal(q.resolveRepo("no-such-repo"), null);
+    // 造第二个仓库让解析变歧义
+    const root2 = makeFixture();
+    try {
+      runChoroT0({ repoRoot: root2, store, apply: true, now: FIXED_NOW });
+      const amb = q.resolveRepo(undefined);
+      assert.ok(amb.ambiguous, "多仓无键 → 歧义清单而不是猜一个");
+      assert.equal(amb.ambiguous.length, 2);
+    } finally {
+      rmTempBestEffort(root2);
+    }
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("moduleMap：模块、页面状态与跨模块边同源返回", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    const { modules, edges } = q.moduleMap(repo.id);
+    const slugs = modules.map((m) => m.slug).sort();
+    assert.deepEqual(slugs, ["root", "src"]);
+    const src = modules.find((m) => m.slug === "src");
+    assert.equal(src.page_status, "skeleton");
+    // fixture 的引用全在 src 模块内部（a→b→b2），left-pad 是外部依赖，root 只有
+    // package.json 没有代码——跨模块边应为空集。跨模块聚erge本身由 wiki-store 的
+    // 整仓替换用例与 t0 的 moduleEdges 排序覆盖。
+    assert.deepEqual(edges, []);
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("readPage：正文来自磁盘真源；盘上缺页如实报 page-missing；未知 slug 返回 null", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    const page = q.readPage(repo.id, "src");
+    assert.equal(page.slug, "src");
+    assert.ok(page.content.includes("## 文件清单"), "正文是骨架页");
+    assert.equal(page.content.split("\n").length > 10, true);
+    assert.equal(q.readPage(repo.id, "../../etc/passwd"), null, "未知 slug 一律 null（路径零用户输入）");
+    // 盘上删页：索引还在、读侧如实报缺
+    unlinkSync(join(root, ".chorography", "modules", "src.md"));
+    const missing = q.readPage(repo.id, "src");
+    assert.equal(missing.error, "page-missing");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("search：按节返回命中与行号，空 q 返回空数组，module 过滤生效", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    // 骨架页里必有「文件清单」节标题与 b2.js 文件名
+    const hits = q.search(repo.id, "文件清单");
+    assert.ok(hits.length >= 2, "两页都有文件清单节");
+    assert.ok(hits.every((h) => h.line >= 1 && typeof h.section === "string"));
+    const byFile = q.search(repo.id, "b2.js");
+    // 命中两处是契约而非巧合：frontmatter 的 sourceFiles（节=页首）+ 正文「文件
+    // 清单」表。分节让调用方能区分这两层。
+    assert.equal(byFile.length, 2);
+    assert.ok(byFile.every((h) => h.slug === "src"), "b2.js 只属于 src 页");
+    assert.equal(byFile.filter((h) => h.section.startsWith("文件清单")).length, 1, "节名带数量后缀（文件清单（N 个）），按前缀匹配");
+    assert.deepEqual(q.search(repo.id, "  "), [], "空 q 不报错返回空");
+    const inRoot = q.search(repo.id, "package.json", { moduleSlug: "root" });
+    assert.equal(inRoot.length, 2, "与 b2.js 同款两层命中：frontmatter（页首）+ 文件清单表");
+    assert.equal(inRoot[0].slug, "root");
+    assert.deepEqual(q.search(repo.id, "package.json", { moduleSlug: "src" }), [], "模块过滤真生效");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+test("repoByCwd：祖先前缀命中、最长 root 胜出、cwd 不存在返回 null", () => {
+  const { root, store, q } = setup();
+  let nested = null;
+  try {
+    // 精确根目录
+    const exact = q.repoByCwd(root);
+    assert.ok(exact, "仓库根命中");
+    // 子目录也要命中——真实会话的 cwd 常常是 D:/repo/src 这种
+    const sub = q.repoByCwd(join(root, "src"));
+    assert.equal(sub.id, exact.id, "子目录按祖先前缀命中同一个仓库");
+    assert.equal(q.repoByCwd(join(root, "no-such-dir")), null, "cwd 不存在 → null（不是抛错，注入在热路径上）");
+    assert.equal(q.repoByCwd(""), null);
+    assert.equal(q.repoByCwd(null), null);
+    // 嵌套仓库：外层先登记，内层后登记 → 内层会话必须被内层抢走（最长前缀）
+    nested = makeFixture();
+    runChoroT0({ repoRoot: nested, store, apply: true, now: FIXED_NOW });
+    const inner = q.repoByCwd(join(nested, "src"));
+    assert.equal(inner.root_path, nested, "嵌套时取最深那层，否则内层会话被外层仓库抢走");
+    assert.equal(q.repoByCwd(root).root_path, root, "外层 cwd 仍落外层");
+  } finally {
+    store.close();
+    if (nested) rmTempBestEffort(nested);
+    rmTempBestEffort(root);
+  }
+});
+
+test("outline：模块名 + 文件数 + 页状态 + 页相对路径，不读正文", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    const out = q.outline(repo.id);
+    assert.equal(out.repo.id, repo.id);
+    assert.equal(out.repo.name, "qfix");
+    assert.equal(out.modules.length, 2);
+    const srcMod = out.modules.find((m) => m.slug === "src");
+    assert.equal(srcMod.status, "skeleton");
+    assert.equal(srcMod.relPath, ".chorography/modules/src.md");
+    assert.ok(srcMod.fileCount >= 3);
+    assert.equal(srcMod.parentSlug, null);
+    assert.ok(out.generatedAt, "生成时间由页行的 generated_at 汇总");
+    // 「只注标题级」的机制锁：提纲里不许出现页正文片段（骨架页的节标题/说明行）
+    const serialized = JSON.stringify(out);
+    assert.equal(serialized.includes("## 文件清单"), false, "提纲不含正文节标题");
+    assert.equal(serialized.includes("确定性骨架"), false, "提纲不含页内说明行");
+    assert.equal(q.outline(9999), null, "未知 repo → null");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});