@modusensus/dsh-mneme 0.10.1 → 0.11.0

package/lib/wiki/plan.js

@@ -0,0 +1,214 @@
+// dsh-mneme/src/wiki/plan.js
+// chorography 的 plan.yaml 正面控制（spec §4 / 决策 D7）：白黑名单、每页模板、
+// 作图笔记。这是用户手写的文件，机器只读不写。
+//
+// 为什么校验是「未知键整轮不跑」而不是「忽略并继续」（spec 降级表第一行）：拼错
+// 一个键名（include 写成 includes）等于那条控制整段失效，而用户以为它在生效——
+// 静默忽略的代价是生成结果和用户意图悄悄分叉，正是 D7 要防的事。整轮拒绝 + 报出
+// 键名与允许列表，把拼错变成一次可修正的显式失败。
+//
+// 校验收全部 issue 后一次报出，不 fail-fast：人改配置通常一次错多处，逐个试错
+// 只会多跑几轮生成。
+//
+// 依赖 `yaml`（实现计划 P1）：plan.yaml 是用户配置，手写子集解析器会在注释 /
+// 锚点 / 多行字符串上静默错解，错解配置比拒绝配置更伤。
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { parseDocument } from "yaml";
+
+export const PLAN_ALLOWED_KEYS = Object.freeze([
+  "include", "exclude", "pages", "templates", "max_files_per_page",
+]);
+export const PLAN_PAGE_ALLOWED_KEYS = Object.freeze(["path", "title", "template", "notes"]);
+export const DEFAULT_MAX_FILES_PER_PAGE = 40;
+
+// plan.yaml 不存在时的启发式默认（spec §6 步 1）：全量 include、零 exclude 追加
+// （目录级排除由 scan.js 的默认排除表承担：node_modules/构建产物 + 一切点开头目录，
+// 见 DEFAULT_EXCLUDE_DIRS 上方注释——所以空 plan 也不是「什么都读」）、
+// 无页面白名单（划分结果全建页）。
+export function defaultPlan() {
+  return {
+    include: null,
+    exclude: [],
+    pages: null,
+    templates: {},
+    maxFilesPerPage: DEFAULT_MAX_FILES_PER_PAGE,
+  };
+}
+
+/** plan.yaml 的内容指纹（无文件时对空串取 hash，保证「没带 plan」也是一个可记账状态）。 */
+export function planFingerprint(rawText) {
+  return createHash("sha256").update(rawText ?? "", "utf8").digest("hex");
+}
+
+/** 校验拒绝：issues 是人可读的中文清单，CLI 原样透出（spec 降级表：报出键名与允许列表）。 */
+export class PlanInvalidError extends Error {
+  constructor(issues, { planPath } = {}) {
+    const lines = issues.map((it) => `  - ${it}`);
+    super(
+      `plan.yaml 校验不通过，本轮未运行${planPath ? `（${planPath}）` : ""}：\n${lines.join("\n")}\n` +
+      `允许的顶层键：${PLAN_ALLOWED_KEYS.join(" / ")}`
+    );
+    this.name = "PlanInvalidError";
+    this.issues = issues;
+  }
+}
+
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function expectType(value, want, label, issues) {
+  const got = typeOf(value);
+  if (got !== want) {
+    issues.push(`${label} 需要 ${want === "array" ? "数组" : want === "string" ? "字符串" : want}，实际是 ${got}`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * 解析并校验 plan.yaml。rawText 为空（文件不存在）时返回默认启发式。
+ * 任何校验失败抛 PlanInvalidError（收集全部 issue）。
+ */
+export function loadPlan(rawText, { planPath } = {}) {
+  if (rawText == null || String(rawText).trim() === "") return { plan: defaultPlan(), fingerprint: planFingerprint("") };
+
+  const doc = parseDocument(rawText);
+  const issues = [];
+  if (doc.errors.length > 0) {
+    for (const err of doc.errors) issues.push(`YAML 语法错误：${String(err.message ?? err)}`);
+    throw new PlanInvalidError(issues, { planPath });
+  }
+  const root = doc.toJS({ maxAliasCount: 200 });
+
+  if (root === null || root === undefined) {
+    throw new PlanInvalidError(["文件是空的：要么删掉 plan.yaml 走默认启发式，要么写一条配置"], { planPath });
+  }
+  if (typeof root !== "object" || Array.isArray(root)) {
+    throw new PlanInvalidError([`顶层必须是键值映射（mapping），实际是 ${Array.isArray(root) ? "数组" : typeof root}`], { planPath });
+  }
+
+  const known = new Set(PLAN_ALLOWED_KEYS);
+  for (const key of Object.keys(root)) {
+    if (!known.has(key)) {
+      const near = nearestKey(key);
+      issues.push(
+        `未知键 "${key}"（本轮拒绝运行：拼错的键等于失效的控制，不能静默忽略）` +
+        (near ? `；如果你要写的是 "${near}"，请改正键名` : "")
+      );
+    }
+  }
+
+  const plan = defaultPlan();
+
+  if (root.include !== undefined) {
+    if (expectType(root.include, "array", "include", issues)) plan.include = root.include.map(String);
+  }
+  if (root.exclude !== undefined) {
+    if (expectType(root.exclude, "array", "exclude", issues)) plan.exclude = root.exclude.map(String);
+  }
+  if (root.max_files_per_page !== undefined) {
+    const v = root.max_files_per_page;
+    if (!Number.isInteger(v) || v <= 0) {
+      issues.push(`max_files_per_page 需要正整数，实际是 ${JSON.stringify(v)}`);
+    } else {
+      plan.maxFilesPerPage = v;
+    }
+  }
+  if (root.templates !== undefined) {
+    if (expectType(root.templates, "object", "templates", issues) && !Array.isArray(root.templates)) {
+      for (const [name, body] of Object.entries(root.templates)) {
+        if (typeof body !== "string") {
+          issues.push(`templates.${name} 的值需要字符串（模板正文），实际是 ${typeOf(body)}`);
+        } else {
+          plan.templates[name] = body;
+        }
+      }
+    } else if (Array.isArray(root.templates)) {
+      issues.push("templates 需要键值映射（模板名 → 正文），实际是数组");
+    }
+  }
+  if (root.pages !== undefined) {
+    if (expectType(root.pages, "array", "pages", issues)) {
+      const seen = new Set();
+      plan.pages = [];
+      root.pages.forEach((entry, i) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+          issues.push(`pages[${i}] 需要键值映射（path/title/template/notes），实际是 ${typeOf(entry)}`);
+          return;
+        }
+        for (const key of Object.keys(entry)) {
+          if (!PLAN_PAGE_ALLOWED_KEYS.includes(key)) {
+            issues.push(`pages[${i}] 有未知键 "${key}"；页级允许：${PLAN_PAGE_ALLOWED_KEYS.join(" / ")}`);
+          }
+        }
+        const path = typeof entry.path === "string" ? entry.path.trim() : "";
+        if (path === "") {
+          issues.push(`pages[${i}] 缺 path（页面标识，对应模块 slug）`);
+          return;
+        }
+        if (seen.has(path)) issues.push(`pages 里 path "${path}" 重复出现`);
+        seen.add(path);
+        if (entry.title !== undefined && typeof entry.title !== "string") {
+          issues.push(`pages["${path}"].title 需要字符串，实际是 ${typeOf(entry.title)}`);
+        }
+        if (entry.template !== undefined && typeof entry.template !== "string") {
+          issues.push(`pages["${path}"].template 需要字符串（模板名），实际是 ${typeOf(entry.template)}`);
+        }
+        if (entry.notes !== undefined && typeof entry.notes !== "string") {
+          issues.push(`pages["${path}"].notes 需要字符串，实际是 ${typeOf(entry.notes)}`);
+        }
+        plan.pages.push({
+          path,
+          title: typeof entry.title === "string" ? entry.title : undefined,
+          template: typeof entry.template === "string" ? entry.template : undefined,
+          notes: typeof entry.notes === "string" ? entry.notes : undefined,
+        });
+      });
+    }
+  }
+
+  if (issues.length > 0) throw new PlanInvalidError(issues, { planPath });
+  return { plan, fingerprint: planFingerprint(rawText) };
+}
+
+/** 从磁盘读 plan.yaml。<repoRoot>/.chorography/plan.yaml 是唯一位置（spec §4）。 */
+export function loadPlanFromRepo(repoRoot) {
+  const planPath = join(repoRoot, ".chorography", "plan.yaml");
+  if (!existsSync(planPath)) return { plan: defaultPlan(), fingerprint: planFingerprint(""), planPath: null, raw: "" };
+  const raw = readFileSync(planPath, "utf8");
+  return { ...loadPlan(raw, { planPath }), planPath, raw };
+}
+
+// 编辑距离只用来给「未知键」提示一个最近候选；实现取经典 DP，规模只有几个键，
+// 不值得引库。距离不够近（超过键长一半或大于 2）就不猜，猜错提示比没有提示更吵。
+function nearestKey(key) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const candidate of PLAN_ALLOWED_KEYS) {
+    const dist = editDistance(key.toLowerCase(), candidate.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = candidate;
+    }
+  }
+  return bestDist <= Math.max(2, Math.floor(key.length / 2)) ? best : null;
+}
+
+function editDistance(a, b) {
+  const prev = new Array(b.length + 1).fill(0).map((_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let carry = prev[0];
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = prev[j];
+      prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, carry + (a[i - 1] === b[j - 1] ? 0 : 1));
+      carry = tmp;
+    }
+  }
+  return prev[b.length];
+}

package/lib/wiki/queries.js

@@ -0,0 +1,220 @@
+// dsh-mneme/src/wiki/queries.js
+// chorography 的读侧（M1）：仓库列表 / 模块图 / 页面正文 / 关键词检索。
+// 只读，零写路径——写入口只有 M0 的 t0.js（红线 3：模型侧一个写工具都不注册）。
+//
+// 真源纪律（spec §4 / P12）：页面正文永远读仓库磁盘的 MD（root_path + DB 里的
+// rel_path），库里的表只是索引与状态账。slug 只从 DB 白名单解析，路径拼装零用户
+// 输入——面板与工具传进来的 slug 查不到模块行就返回 null，绝不用它拼路径。
+import { readFileSync, existsSync, realpathSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+
+export function createChoroQueries({ store }) {
+  const db = store.db;
+
+  /** 已登记仓库（含模块/页面计数，面板仓库选择器与工具的 repo 解析共用）。 */
+  function listRepos() {
+    const rows = db.prepare(
+      `SELECT r.id, r.root_path, r.name, r.plan_fingerprint, r.git_baseline, r.updated_at,
+              (SELECT COUNT(*) FROM choro_modules m WHERE m.repo_id = r.id) AS module_count,
+              (SELECT COUNT(*) FROM choro_pages p JOIN choro_modules m2 ON p.module_id = m2.id
+                 WHERE m2.repo_id = r.id) AS page_count
+         FROM choro_repos r ORDER BY r.id`
+    ).all();
+    return rows;
+  }
+
+  /** repo 解析：数字 id 或显示名（root_path 是本机私有路径，不作为对外键）。 */
+  function resolveRepo(ref) {
+    if (ref === undefined || ref === null || ref === "") {
+      const rows = listRepos();
+      if (rows.length === 1) return rows[0];
+      if (rows.length === 0) return null;
+      return { ambiguous: rows.map((r) => ({ id: r.id, name: r.name })) };
+    }
+    const byId = db.prepare("SELECT * FROM choro_repos WHERE id = ?").get(Number(ref));
+    if (byId) return byId;
+    const byName = db.prepare("SELECT * FROM choro_repos WHERE name = ?").get(String(ref));
+    return byName ?? null;
+  }
+
+  /** 模块表 + 跨模块边（choro_module_map 与面板左侧树共用同一份数据）。 */
+  function moduleMap(repoId) {
+    const modules = db.prepare(
+      `SELECT m.id, m.slug, m.title, m.parent_id, m.file_count, m.fingerprint, m.updated_at,
+              p.status AS page_status, p.rel_path AS page_rel_path
+         FROM choro_modules m
+         LEFT JOIN choro_pages p ON p.module_id = m.id
+        WHERE m.repo_id = ? ORDER BY m.slug`
+    ).all(repoId);
+    const edges = db.prepare(
+      `SELECT from_slug, to_slug, weight FROM choro_edges WHERE repo_id = ?
+        ORDER BY from_slug, to_slug`
+    ).all(repoId);
+    return { modules, edges };
+  }
+
+  /**
+   * 读一页正文。slug 必须命中 DB 的模块行（P12：路径零用户输入）；磁盘文件被手删
+   * 时返回 { error: "page-missing" }（索引还没重算，读侧如实报缺，不伪造内容）。
+   */
+  function readPage(repoId, slug) {
+    const row = db.prepare(
+      `SELECT m.slug, m.title, m.file_count, m.parent_id, p.rel_path, p.status,
+              p.git_baseline, p.template_version, p.generated_at, p.human_block_count
+         FROM choro_modules m JOIN choro_pages p ON p.module_id = m.id
+        WHERE m.repo_id = ? AND m.slug = ?`
+    ).get(repoId, String(slug));
+    if (!row) return null;
+    const repo = db.prepare("SELECT root_path, name FROM choro_repos WHERE id = ?").get(repoId);
+    const abs = join(repo.root_path, row.rel_path);
+    if (!existsSync(abs)) return { error: "page-missing", slug: row.slug, relPath: row.rel_path };
+    return {
+      slug: row.slug,
+      title: row.title,
+      fileCount: row.file_count,
+      status: row.status,
+      gitBaseline: row.git_baseline,
+      templateVersion: row.template_version,
+      generatedAt: row.generated_at,
+      humanBlockCount: row.human_block_count,
+      repoName: repo.name,
+      relPath: row.rel_path,
+      content: readFileSync(abs, "utf8"),
+    };
+  }
+
+  /**
+   * 关键词检索（P10）：按 `## ` 分节做大小写不敏感子串匹配，命中返回页 slug、
+   * 节标题、起始行号与摘录。只扫 DB 里登记过的页面文件（不是全目录 glob——
+   * 划分变更后未重算的孤儿文件不该被搜出来）。q 为空返回空数组不报错。
+   */
+  function search(repoId, q, { moduleSlug = null, limit = 20 } = {}) {
+    const needle = String(q ?? "").trim().toLowerCase();
+    if (needle === "") return [];
+    const cap = Math.max(1, Math.min(100, Number(limit) || 20));
+    const pages = db.prepare(
+      `SELECT m.slug, m.title AS module_title, p.rel_path
+         FROM choro_modules m JOIN choro_pages p ON p.module_id = m.id
+        WHERE m.repo_id = ? AND (? IS NULL OR m.slug = ?)
+        ORDER BY m.slug`
+    ).all(repoId, moduleSlug, moduleSlug);
+    const repo = db.prepare("SELECT root_path FROM choro_repos WHERE id = ?").get(repoId);
+    const hits = [];
+    for (const page of pages) {
+      const abs = join(repo.root_path, page.rel_path);
+      if (!existsSync(abs)) continue;
+      let text;
+      try {
+        text = readFileSync(abs, "utf8");
+      } catch {
+        continue;
+      }
+      const lines = text.split("\n");
+      // 分节：每个 `## ` 标题开启一节，节内所有行都属于该节；文件头（frontmatter
+      // 之后到第一个 `## `）算 "（页首）" 一节，保证对 title/摘要的命中也有落点。
+      let section = "（页首）";
+      let sectionStart = 1;
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (i > 0 && /^## /.test(line)) {
+          section = line.replace(/^## /, "").trim();
+          sectionStart = i + 1;
+        }
+        if (line.toLowerCase().includes(needle)) {
+          hits.push({
+            slug: page.slug,
+            moduleTitle: page.module_title,
+            section,
+            line: i + 1,
+            sectionStart,
+            excerpt: line.trim().slice(0, 200),
+          });
+          if (hits.length >= cap) return hits;
+        }
+      }
+    }
+    return hits;
+  }
+
+  /**
+   * 按会话工作目录找已登记仓库（M3 开局注入的唯一入口）。
+   *
+   * 三个刻意的取舍：
+   * 1. **祖先前缀匹配**而不是精确相等——真实会话的 cwd 常常是仓库子目录
+   *    （`D:/repo/src`），精确相等会让绝大部分会话匹配不到，等于逼用户
+   *    「必须在仓库根开会话」这条暗规则。
+   * 2. 两侧都做 realpath 归一：Windows 上盘符大小写、8.3 短名、符号链接
+   *    会让同一个目录写出不同字符串；t0 落库时存的就是 realpath。
+   * 3. **最长前缀胜出**——仓库嵌套（子模块、`.worktrees/`）时取最深那层，
+   *    否则内层会话会被外层仓库抢走。
+   * cwd 不存在或不是目录时返回 null（不是抛错）：注入在热路径上，失败只
+   * 意味着「本帧不注入」。
+   */
+  function repoByCwd(cwd) {
+    const raw = String(cwd ?? "").trim();
+    if (raw === "") return null;
+    let normalized;
+    try {
+      normalized = realpathSync(resolve(raw));
+    } catch {
+      return null;
+    }
+    const cmp = (p) => (process.platform === "win32" ? p.toLowerCase() : p);
+    const target = cmp(normalized);
+    const rows = db.prepare("SELECT * FROM choro_repos ORDER BY id").all();
+    let best = null;
+    for (const row of rows) {
+      const root = cmp(String(row.root_path ?? ""));
+      if (root === "") continue;
+      const hit = target === root || target.startsWith(root.endsWith(sep) ? root : root + sep);
+      if (!hit) continue;
+      if (!best || root.length > cmp(String(best.root_path)).length) best = row;
+    }
+    return best ?? null;
+  }
+
+  /**
+   * 注入与 /choro 共用的最小提纲（M3）：模块名 + 文件数 + 页状态 + 页相对路径。
+   * **不读页正文**——spec §7 要求「只注标题级不注正文」，正文走 readPage。
+   * parentSlug 单独解出来给渲染层做层级缩进（DB 里存的是 parent_id）。
+   */
+  function outline(repoId) {
+    const repo = db.prepare(
+      "SELECT id, root_path, name, git_baseline, plan_fingerprint, updated_at FROM choro_repos WHERE id = ?"
+    ).get(repoId);
+    if (!repo) return null;
+    const rows = db.prepare(
+      `SELECT m.id, m.slug, m.title, m.parent_id, m.file_count,
+              p.status AS page_status, p.rel_path AS page_rel_path, p.generated_at
+         FROM choro_modules m
+         LEFT JOIN choro_pages p ON p.module_id = m.id
+        WHERE m.repo_id = ? ORDER BY m.slug`
+    ).all(repoId);
+    const slugById = new Map(rows.map((r) => [r.id, r.slug]));
+    let generatedAt = null;
+    const modules = rows.map((r) => {
+      if (r.generated_at && (generatedAt === null || r.generated_at > generatedAt)) generatedAt = r.generated_at;
+      return {
+        slug: r.slug,
+        title: r.title,
+        fileCount: r.file_count,
+        parentSlug: r.parent_id === null || r.parent_id === undefined ? null : slugById.get(r.parent_id) ?? null,
+        status: r.page_status ?? null,
+        relPath: r.page_rel_path ?? null,
+      };
+    });
+    return {
+      repo: {
+        id: repo.id,
+        name: repo.name,
+        rootPath: repo.root_path,
+        gitBaseline: repo.git_baseline,
+        updatedAt: repo.updated_at,
+      },
+      generatedAt: generatedAt ?? repo.updated_at ?? null,
+      modules,
+    };
+  }
+
+  return { listRepos, resolveRepo, moduleMap, readPage, search, repoByCwd, outline };
+}

package/lib/wiki/render.js

@@ -0,0 +1,187 @@
+// dsh-mneme/src/wiki/render.js
+// T0 骨架页与 index.md 的确定性渲染（spec §6 步 6），以及混合所有权的保留区机制
+// （spec §4：`<!-- CHORO:HUMAN -->` 标记块重生成时逐字节保留）。
+//
+// 确定性纪律（spec §9 可重建不变量）：正文零时间戳、零随机——所有列表先排序再拼；
+// 页面唯一的时刻 frontmatter.generatedAt 由 t0.js 从 state.json 沿用（实现计划
+// P3：时刻收进 state.json，失败不推进，页面字节才可能跨 run 稳定）。
+//
+// 保留区规则（写死、可测）：
+//   1. 抽取：START…END 之间连同两行标记整体抽出，一个字节不动；
+//   2. 回填：新正文之后按原相对顺序接回全部块；
+//   3. 重生成永不删块、永不改写块内内容（包括缩进与格式）——红线 6；
+//   4. 没有块时整页覆盖（spec：人在块外的手改不保证存活，是明说语义不是事故）。
+
+export const TEMPLATE_VERSION = "1";
+
+export const HUMAN_START = "<!-- CHORO:HUMAN:START -->";
+export const HUMAN_END = "<!-- CHORO:HUMAN:END -->";
+
+// T1 语义段的包装标记。写的人是 t1.js，读的人还有 t0.js——重跑 T0 时它要能认出
+// 「这页已经被富化过」，否则 enriched → skeleton 的退回是静默的。标记随页面格式
+// 走，所以与 HUMAN 标记同住这里，t1.js 转出给调用方。
+export const T1_SECTION_START = "<!-- CHORO:T1:START -->";
+export const T1_SECTION_END = "<!-- CHORO:T1:END -->";
+
+/** 抽出全部保留区。返回 { blocks: string[]（含标记本身，原样）, count }。 */
+export function extractHumanBlocks(pageText) {
+  if (typeof pageText !== "string") return { blocks: [], count: 0 };
+  const blocks = [];
+  const re = new RegExp(`${escapeRegExp(HUMAN_START)}[\\s\\S]*?${escapeRegExp(HUMAN_END)}`, "g");
+  let m;
+  while ((m = re.exec(pageText)) !== null) blocks.push(m[0]);
+  return { blocks, count: blocks.length };
+}
+
+/** 新正文 + 保留区（按原顺序接在页尾，各隔一个空行）。 */
+export function injectHumanBlocks(newContent, blocks) {
+  if (!blocks || blocks.length === 0) return newContent;
+  return `${newContent.replace(/\n*$/, "\n")}\n${blocks.join("\n\n")}\n`;
+}
+
+/**
+ * 渲染一页骨架。meta: { slug, title, parents[], sourceFiles[], gitBaseline,
+ * generatedAt, status }；mod 是 partition 的产物。
+ */
+export function renderSkeletonPage(mod, meta) {
+  const lines = [];
+  lines.push("---");
+  lines.push("choro: v1");
+  lines.push(`slug: ${meta.slug}`);
+  lines.push(`title: ${yamlScalar(meta.title)}`);
+  if (meta.parents && meta.parents.length > 0) {
+    lines.push("parents:");
+    for (const p of meta.parents) lines.push(`  - ${p}`);
+  } else {
+    lines.push("parents: []");
+  }
+  lines.push("sourceFiles:");
+  for (const f of meta.sourceFiles) lines.push(`  - ${f}`);
+  lines.push(`gitBaseline: ${meta.gitBaseline}`);
+  lines.push(`templateVersion: ${TEMPLATE_VERSION}`);
+  lines.push(`language: ${meta.language ?? "zh"}`);
+  lines.push(`status: ${meta.status}`);
+  lines.push(`generatedAt: ${meta.generatedAt}`);
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${meta.title}`);
+  lines.push("");
+  // 注意：这行说明里**不得出现成对的标记字面量**——抽取用的是全局正则，说明行
+  // 里一旦同时含 START 与 END，下一轮重生成就会把它当成一块保留区接在页尾
+  // （实测：第二轮页面凭空多两行）。所以说标记时用名字，不用原文。
+  lines.push(
+    `> 确定性骨架（T0，零模型）：由文件树与 import 图生成。` +
+    `CHORO:HUMAN 标记对（START/END 两个 HTML 注释）包住的内容在重生成时逐字节保留；` +
+    `标记对之外的手改不保留（想保住一段就把它挪进标记对里）。`
+  );
+  lines.push("");
+  lines.push(`## 文件清单（${mod.fileCount} 个）`);
+  lines.push("");
+  lines.push("| 文件 | 行数 |");
+  lines.push("| --- | ---: |");
+  for (const [file, lines2] of mod.fileLines) lines.push(`| ${file} | ${lines2} |`);
+  lines.push("");
+  lines.push("## 入口");
+  lines.push("");
+  if (mod.entries.length > 0) {
+    for (const e of mod.entries) lines.push(`- \`${e}\``);
+  } else {
+    lines.push("- 无（没有 index/main 命名的文件，也不是包入口）");
+  }
+  lines.push("");
+  lines.push("## 内部依赖");
+  lines.push("");
+  if (mod.upstream.length > 0) {
+    lines.push(`- 上游依赖（本模块引用的模块）：${mod.upstream.map((s) => `\`${s}\``).join("、")}`);
+  }
+  if (mod.downstream.length > 0) {
+    lines.push(`- 下游（引用本模块的模块）：${mod.downstream.map((s) => `\`${s}\``).join("、")}`);
+  }
+  if (mod.upstream.length === 0 && mod.downstream.length === 0) {
+    lines.push("- 无内部依赖边（孤立模块）");
+  }
+  lines.push("");
+  lines.push("## 外部依赖");
+  lines.push("");
+  if (mod.externalDeps.length > 0) {
+    for (const d of mod.externalDeps) lines.push(`- \`${d.pkg}\` ×${d.count}`);
+  } else {
+    lines.push("- 无外部 npm 依赖");
+  }
+  lines.push("");
+  lines.push("## 生成说明");
+  lines.push("");
+  lines.push(
+    `- 模块划分：目录初稿 + 兄弟组内聚合并（内部边 ≥3），超上限逐级下切；` +
+    `本组 ${mod.fileCount} 个文件。`
+  );
+  if (mod.unresolvedCount > 0) {
+    lines.push(`- ${mod.unresolvedCount} 条相对引用没有解析到仓库内文件（别名/动态路径），未计入依赖图。`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/** index.md：模块目录 + 仓库级信息。同样零时间戳（时刻在 state.json）。 */
+export function renderIndex(modules, repoMeta) {
+  const lines = [];
+  lines.push("---");
+  lines.push("choro: v1");
+  lines.push(`repo: ${yamlScalar(repoMeta.name)}`);
+  lines.push(`gitBaseline: ${repoMeta.gitBaseline}`);
+  lines.push(`templateVersion: ${TEMPLATE_VERSION}`);
+  lines.push(`generatedAt: ${repoMeta.generatedAt}`);
+  lines.push("language: zh");
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${repoMeta.name} · 仓库地志`);
+  lines.push("");
+  lines.push(
+    `T0 确定性骨架（零模型）。页面在 \`modules/\` 下，真源是本目录的 Markdown；` +
+    `本文件整页机器所有、可随时重算（spec §4）。`
+  );
+  lines.push("");
+  lines.push(`- 扫描 ${repoMeta.fileCount} 个文件，划出 ${modules.length} 个模块。`);
+  if (repoMeta.skipped > 0) lines.push(`- ${repoMeta.skipped} 个文件读取失败，已跳过（页脚与 receipt 都有记）。`);
+  if (repoMeta.unresolved > 0) lines.push(`- ${repoMeta.unresolved} 条相对引用未解析（别名/动态路径），未计入依赖图。`);
+  lines.push("");
+  lines.push("## 模块目录");
+  lines.push("");
+  lines.push("| 模块 | 页面 | 文件数 | 内部边 | 外部依赖 |");
+  lines.push("| --- | --- | ---: | ---: | ---: |");
+  for (const mod of modules) {
+    const pageRel = `modules/${mod.slug}.md`;
+    lines.push(
+      `| ${mod.title} | [${mod.slug}](${pageRel}) | ${mod.fileCount} | ` +
+      `${mod.internalEdges.length} | ${mod.externalDeps.length} |`
+    );
+  }
+  lines.push("");
+  lines.push("## 脚本命令（根 package.json）");
+  lines.push("");
+  const scriptNames = Object.keys(repoMeta.scripts ?? {}).sort();
+  if (scriptNames.length > 0) {
+    lines.push("| 命令 | 内容 |");
+    lines.push("| --- | --- |");
+    for (const name of scriptNames) lines.push(`| \`${name}\` | ${escapeCell(String(repoMeta.scripts[name]))} |`);
+  } else {
+    lines.push("- 无 scripts 字段或没有根 package.json。");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+// YAML 标量：含冒号/引号等特殊字符时加引号（frontmatter 里的 title/repo 是人名或
+// 目录名，通常无害，但这层便宜且省掉转义 bug）。
+function yamlScalar(text) {
+  const s = String(text ?? "");
+  return /[:#'\"[\]{},&*?|>%@`]/.test(s) || s.trim() !== s ? JSON.stringify(s) : s;
+}
+
+function escapeCell(text) {
+  return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}