@modusensus/dsh-mneme 0.10.1 → 0.12.0

package/lib/wiki/partition.js

@@ -0,0 +1,200 @@
+// dsh-mneme/src/wiki/partition.js
+// 模块划分（spec §6 步 4）：目录为初稿，用图的内聚度做合并，超 max_files_per_page
+// 再逐级下切。全流程确定性：同输入两次划分给出逐项相同的结果（spec §9 的可重建
+// 不变量要求划分本身也稳定）。
+//
+// 启发式只有两条、都便宜到可解释（V2 要人判质量，判据必须能口述）：
+//   合并——同一父目录下的两个兄弟组，互相指向的内部边 ≥ MERGE_EDGE_MIN 且合并不超
+//   上限时并成一组（典型收益：utils/ 与它唯一的消费者；典型损失：两个互不相干的
+//   小目录被文件夹布局凑到一起，代价是页变大，不会错分语义）。
+//   下切——超上限的组按下一级目录段切开；直属文件自成一组；叶子组仍超上限时按
+//   文件名字典序切块（此时语义已无从谈起，保住「每页不超过上限」的契约）。
+import { posix } from "node:path";
+import { createHash } from "node:crypto";
+
+const MERGE_EDGE_MIN = 3;
+
+/**
+ * @param {string[]} files 仓库相对路径（已排序）
+ * @param {{edges: {from:string,to:string}[], external: Map<string,Set<string>>}} graph scan 的产物
+ * @param {number} maxFilesPerPage plan.yaml 的上限
+ * @returns {Array<{slug,title,dir,fileCount,files,parentSlug,internalEdges,externalDeps,fingerprint}>}
+ */
+export function partitionModules({ files, graph, maxFilesPerPage, repoName }) {
+  const cap = Math.max(1, Math.floor(maxFilesPerPage));
+
+  // 步 1：目录初稿——前两级目录段；根直属文件一组。
+  const groups = new Map();
+  for (const file of files) {
+    const key = groupKeyOf(file);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(file);
+  }
+
+  // 步 2：兄弟组合并（单遍、按 key 字典序，确定性）。
+  mergeSiblingGroups(groups, graph.edges, cap);
+
+  // 步 3：超限下切。
+  const finalGroups = [];
+  for (const key of [...groups.keys()].sort()) {
+    splitOversized(key, groups.get(key), cap, finalGroups);
+  }
+
+  // 步 4：slug / title / 父链 / 边聚合。
+  const modules = finalGroups
+    .map((g) => materialize(g, graph))
+    .sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : a.slug < b.slug ? -1 : 1));
+
+  assignSlugsAndParents(modules, repoName);
+  for (const mod of modules) mod.fingerprint = moduleFingerprint(mod);
+  return modules;
+}
+
+function groupKeyOf(file) {
+  const dir = posix.dirname(file);
+  if (dir === ".") return "";
+  const segments = dir.split("/");
+  return segments.slice(0, 2).join("/");
+}
+
+function mergeSiblingGroups(groups, edges, cap) {
+  // 文件级边先折算到组级（两次查找的 Map，组数 = 目录数，量级无所谓）。
+  const cross = new Map(); // "a|b" -> count（a、b 为组 key，字典序小的在前）
+  for (const e of edges) {
+    const ga = groupKeyOf(e.from);
+    const gb = groupKeyOf(e.to);
+    if (ga === gb || !groups.has(ga) || !groups.has(gb)) continue;
+    const [x, y] = ga < gb ? [ga, gb] : [gb, ga];
+    const k = `${x}|${y}`;
+    cross.set(k, (cross.get(k) ?? 0) + 1);
+  }
+
+  const keys = [...groups.keys()].sort();
+  for (const key of keys) {
+    if (!groups.has(key)) continue; // 已被并走
+    const parent = posix.dirname(key || "·");
+    for (const [pairKey, count] of [...cross.entries()].sort()) {
+      if (count < MERGE_EDGE_MIN) continue;
+      const [a, b] = pairKey.split("|");
+      if (a !== key) continue;
+      if (!groups.has(a) || !groups.has(b)) continue;
+      if (posix.dirname(a || "·") !== parent || posix.dirname(b || "·") !== parent) continue;
+      if (groups.get(a).length + groups.get(b).length > cap) continue;
+      // 并入字典序小的组；被并组从账上消失（cross 里的旧键自然失效）。
+      groups.set(a, [...groups.get(a), ...groups.get(b)].sort());
+      groups.delete(b);
+    }
+  }
+}
+
+function splitOversized(key, files, cap, out) {
+  if (files.length <= cap) {
+    out.push({ dir: key, files });
+    return;
+  }
+  // 按下一级目录段细分；直属文件（无更深层）留在本组（subKey = key）。key 为空
+  // （根直属组）时 dirname 是 "."，嵌套文件直接用完整相对目录做子键——根组没有
+  // 「前缀可剥」。
+  const sub = new Map();
+  for (const file of files) {
+    const dir = posix.dirname(file);
+    let subKey;
+    if (key === "") {
+      subKey = dir === "." ? key : dir;
+    } else {
+      const rest = dir.startsWith(key + "/") ? dir.slice(key.length + 1) : "";
+      subKey = rest === "" ? key : `${key}/${rest.split("/")[0]}`;
+    }
+    if (!sub.has(subKey)) sub.set(subKey, []);
+    sub.get(subKey).push(file);
+  }
+  if (sub.size === 1) {
+    const [onlyKey] = sub.keys();
+    if (onlyKey === key) {
+      // 已是最深层目录、没有可下的子级：按文件名切块，块名带序号（语义无可言，保契约）。
+      chunkFiles(key, files, cap, out);
+      return;
+    }
+    // 整组都在一个更深的子目录里：继续往下切。
+    splitOversized(onlyKey, sub.get(onlyKey), cap, out);
+    return;
+  }
+  for (const subKey of [...sub.keys()].sort()) {
+    splitOversized(subKey, sub.get(subKey), cap, out);
+  }
+}
+
+function chunkFiles(key, files, cap, out) {
+  for (let i = 0; i < files.length; i += cap) {
+    const slice = files.slice(i, i + cap);
+    out.push({ dir: i === 0 ? key : `${key}#${Math.floor(i / cap) + 1}`, files: slice });
+  }
+}
+
+function materialize(group, graph) {
+  const fileSet = new Set(group.files);
+  const internalEdges = graph.edges.filter((e) => fileSet.has(e.from) && fileSet.has(e.to));
+  const extCounts = new Map();
+  for (const [pkg, users] of graph.external) {
+    const n = [...users].filter((f) => fileSet.has(f)).length;
+    if (n > 0) extCounts.set(pkg, n);
+  }
+  return {
+    dir: group.dir,
+    files: group.files,
+    fileCount: group.files.length,
+    internalEdges,
+    externalDeps: [...extCounts.entries()]
+      .map(([pkg, count]) => ({ pkg, count }))
+      .sort((a, b) => (a.pkg < b.pkg ? -1 : a.pkg > b.pkg ? 1 : b.count - a.count)),
+  };
+}
+
+function assignSlugsAndParents(modules, repoName) {
+  // slug：目录段连字化；重复加序号。空目录段（根直属）用 "root"。
+  const used = new Map();
+  for (const mod of modules) {
+    const base = mod.dir === "" ? "root" : slugify(mod.dir);
+    const n = used.get(base) ?? 0;
+    used.set(base, n + 1);
+    mod.slug = n === 0 ? base : `${base}-${n + 1}`;
+    mod.title = titleOf(mod, repoName);
+  }
+  // 父链：slug 集里目录包含关系最近的祖先（重名块 #2 算同层）。
+  for (const mod of modules) {
+    mod.parentSlug = null;
+    let best = null;
+    for (const other of modules) {
+      if (other === mod) continue;
+      if (other.dir === "") continue;
+      if (mod.dir === other.dir || mod.dir === "") continue;
+      if (!mod.dir.startsWith(other.dir + "/")) continue;
+      if (best === null || other.dir.length > best.dir.length) best = other;
+    }
+    if (best) mod.parentSlug = best.slug;
+  }
+}
+
+function slugify(dir) {
+  return dir
+    .toLowerCase()
+    .replace(/[^a-z0-9/]+/g, "-")
+    .replace(/\/+/g, "-")
+    .replace(/^-+|-+$/g, "") || "root";
+}
+
+function titleOf(mod, repoName) {
+  if (mod.dir === "") return repoName ? `${repoName}（仓库根）` : "仓库根";
+  const segments = mod.dir.split("/");
+  const last = segments[segments.length - 1];
+  // 目录名直接当标题（保持原文大小写）；切块组带序号（dir 里的 # 是切块标记，
+  // slugify 之后 slug 里已无 #，所以判断要看 dir）。
+  return mod.dir.includes("#") ? `${last.replace(/#\d+$/, "")}（续 ${mod.dir.match(/#(\d+)$/)?.[1] ?? ""}）` : last;
+}
+
+function moduleFingerprint(mod) {
+  const hash = createHash("sha256");
+  for (const f of mod.files) hash.update(`f:${f}\n`);
+  for (const e of mod.internalEdges) hash.update(`e:${e.from}>${e.to}\n`);
+  return hash.digest("hex");
+}

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];
+}