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

package/scripts/build-runtime-manifest.mjs

@@ -1,224 +1,224 @@
-// 生成 runtime-manifest.json（issue #131 / PR-C）
-//
-// **平台无关**是这份清单的核心设计：数据源是 `package-lock.json` 而不是「本机装好的那棵树」。
-// npm 的 lockfile 里包含**所有平台**的包条目（各自的 os / cpu 与 integrity），所以一份清单就能
-// 覆盖 win32 / darwin / linux × x64 / arm64 —— 下载时再按平台过滤（`matchesPlatform`）。
-//
-// 为什么不做成「按平台各存一份、谁在哪个系统上生成」：那样 macOS 用户在一台没人跑过脚本的机器上
-// 会看到「清单里没有 darwin-arm64 的条目」而直接卡住。清单是随包发布的静态数据，它必须一次覆盖
-// 所有平台，而不是依赖某个贡献者手上有对应的机器。
-//
-// 哈希取自 lockfile 的 integrity（npm 自己算的），所以维护成本是「改依赖后重跑一次脚本」。
-//
-// 用法：
-//   node scripts/build-runtime-manifest.mjs            # 生成/更新
-//   node scripts/build-runtime-manifest.mjs --check     # 只校验现有文件与 lockfile 一致（CI 用）
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { matchesPlatform } from "../src/runtime/closure.js";
-
-const ROOT = fileURLToPath(new URL("..", import.meta.url));
-const MANIFEST = join(ROOT, "runtime-manifest.json");
-const MANIFEST_VERSION = 2;
-const ENTRY = "@huggingface/transformers";
-
-/**
- * 证据：`@huggingface/transformers` 的 Node 构建（dist/transformers.node.mjs）顶层只 import
- * onnxruntime-node 与 sharp，从不 import onnxruntime-web（把一个空的 onnxruntime-web 打桩进去，
- * 嵌入结果逐字节相同：dims=[2,512]、L2 范数 1.0000、cos 0.3053）。而它解包后 127.7MB，占整个
- * 闭包约三分之一。所以清单里剔除它，风险由 verify 的真实推理兜底。
- */
-const EXCLUDED = {
-  "onnxruntime-web": "Node 构建从不 import 它（打桩验证：嵌入结果逐字节相同）",
-  // sharp 0.35 起把 WASM 回退包装进 optionalDependencies（freebsd/webcontainers 场景），
-  // 六个覆盖平台在 Node 里从不 import；wasm32 无 os 约束，会混进每个平台的 natives 断言。
-  "@img/sharp-freebsd-wasm32": "FreeBSD 专用 WASM 回退，覆盖平台之外",
-  "@img/sharp-webcontainers-wasm32": "WebContainers 专用 WASM 回退，覆盖平台之外",
-  "@img/sharp-wasm32": "无 os 约束的 WASM 回退，Node 构建从不 import",
-};
-
-/**
- * 被剔除的包，以及**它子树下的一切**。
- *
- * 只按包名过滤会漏掉嵌套条目：闭包是按源布局镜像的，所以存在
- * `onnxruntime-web/node_modules/onnxruntime-common` 这种位于被剔除包内部的包 ——
- * 那个位置根本不会被取回来，留在清单里就是让下载器去填一个不存在的坑。
- * 同名但位于别处（例如顶层 onnxruntime-common）不受影响。
- */
-export function isExcluded(pkg) {
-  return Object.keys(EXCLUDED).some(
-    (name) => pkg.name === name || pkg.rel === name || pkg.rel.startsWith(`${name}/`)
-  );
-}
-
-/** lockfile 的路径 → 包名（最后一段 `node_modules/` 之后的部分）。 */
-export function nameOfPath(path) {
-  const marker = path.lastIndexOf("node_modules/");
-  return marker === -1 ? path : path.slice(marker + "node_modules/".length);
-}
-
-/** lockfile 的路径 → payload 里的相对路径（去掉开头的 `node_modules/`）。 */
-export function relOfPath(path) {
-  return path.startsWith("node_modules/") ? path.slice("node_modules/".length) : path;
-}
-
-/**
- * 按 Node 的解析语义列出候选路径：从引用者自身的 `node_modules` 逐级向上，最后兜底到根部。
- *
- * 例：引用者在 `node_modules/a/node_modules/b`、依赖 `x` →
- *   `…/b/node_modules/x` → `node_modules/a/node_modules/x` → `node_modules/x`
- * @param {string} fromPath - 引用者的 lockfile 路径。
- * @param {string} name - 依赖名。
- * @returns {string[]} 候选路径，由近到远。
- */
-export function resolveCandidates(fromPath, name) {
-  const out = [`${fromPath}/node_modules/${name}`];
-  let cursor = fromPath;
-  while (cursor.includes("/node_modules/")) {
-    cursor = cursor.slice(0, cursor.lastIndexOf("/node_modules/"));
-    out.push(cursor === "" ? `node_modules/${name}` : `${cursor}/node_modules/${name}`);
-  }
-  if (!out.includes(`node_modules/${name}`)) out.push(`node_modules/${name}`);
-  return out;
-}
-
-/** registry 的 tarball 地址：lockfile 记了 resolved 就用它（与 integrity 同源），否则按 npm 约定推。 */
-function tarballUrl(name, version, resolved) {
-  if (typeof resolved === "string" && resolved.startsWith("http")) return resolved;
-  const base = name.startsWith("@") ? name.slice(name.indexOf("/") + 1) : name;
-  return `https://registry.npmjs.org/${name}/-/${base}-${version}.tgz`;
-}
-
-/**
- * 从 lockfile 走一遍闭包。
- * @param {object} lock - package-lock.json 的内容。
- * @returns {{packages: object[], missing: string[]}} 包列表（按 rel 排序）与解析不到的依赖。
- */
-export function closureFromLockfile(lock) {
-  const all = lock.packages ?? {};
-  const known = new Set(
-    Object.entries(all)
-      .filter(([path, meta]) => path.includes("node_modules/") && meta?.version !== undefined)
-      .map(([path]) => path)
-  );
-  const seen = new Map();
-  const missing = [];
-  const queue = [`node_modules/${ENTRY}`];
-
-  while (queue.length > 0) {
-    const path = queue.shift();
-    if (seen.has(path)) continue;
-    const meta = all[path];
-    if (meta?.version === undefined) {
-      missing.push(path);
-      continue;
-    }
-    if (isExcluded({ name: nameOfPath(path), rel: relOfPath(path) })) continue;
-    seen.set(path, meta);
-
-    const deps = { ...(meta.dependencies ?? {}), ...(meta.optionalDependencies ?? {}) };
-    for (const name of Object.keys(deps)) {
-      const resolved = resolveCandidates(path, name).find((option) => known.has(option));
-      if (resolved === undefined) missing.push(`${name}（被 ${relOfPath(path)} 需要）`);
-      else queue.push(resolved);
-    }
-  }
-
-  const packages = [...seen.entries()]
-    .map(([path, meta]) => ({
-      name: nameOfPath(path),
-      version: meta.version,
-      rel: relOfPath(path),
-      integrity: meta.integrity ?? null,
-      tarball: tarballUrl(nameOfPath(path), meta.version, meta.resolved),
-      // 平台约束照抄 lockfile：下载器按它过滤。没有这三个字段 = 与平台无关。
-      ...(Array.isArray(meta.os) ? { os: meta.os } : {}),
-      ...(Array.isArray(meta.cpu) ? { cpu: meta.cpu } : {}),
-      // libc 也带上：linux-x64 的 glibc 机器靠它剔掉两套 musl 变体（十几 MB）。
-      // 下载器只在**确认**了本机 libc 时才据此过滤，拿不到证据就不看这个字段。
-      ...(Array.isArray(meta.libc) ? { libc: meta.libc } : {})
-    }))
-    .sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
-
-  return { packages, missing };
-}
-
-/** 某个平台实际需要取哪些包（与下载器用同一条判据）。 */
-export function packagesForPlatform(manifest, platform, arch, libc = null) {
-  return manifest.packages.filter((pkg) => matchesPlatform(pkg, platform, arch, libc));
-}
-
-/** 生成一份**平台无关**的清单。 */
-export function build() {
-  const lock = JSON.parse(readFileSync(join(ROOT, "package-lock.json"), "utf8"));
-  const { packages, missing } = closureFromLockfile(lock);
-  // 解析不到的依赖必须让生成**失败**：带缺口的清单会让用户在下载时才失败，而且「少了一个包」
-  // 这种缺口结构检查看不出来（它只点三个必需包）。生成期的数据问题就该在生成期炸掉 ——
-  // 这也是我第一版真正踩过的：被剔除包的孤儿依赖留在了清单里，而生成器一声不吭。
-  if (missing.length > 0) {
-    throw new Error(`这些依赖在 package-lock.json 里解析不到：${missing.slice(0, 10).join("、")}`);
-  }
-
-  const entry = packages.find((pkg) => pkg.rel === ENTRY);
-  if (entry === undefined) throw new Error(`闭包入口没解析出来：${missing.join("; ") || "lockfile 里没有它"}`);
-  // 查不到 sha512 就不能写进清单：那等于让下载器「先信任再校验」，是假校验。
-  const withoutIntegrity = packages.filter(
-    (pkg) => typeof pkg.integrity !== "string" || !pkg.integrity.startsWith("sha512-")
-  );
-  if (withoutIntegrity.length > 0) {
-    throw new Error(`这些包在 package-lock.json 里没有 sha512 integrity：${withoutIntegrity.map((p) => p.rel).join("、")}`);
-  }
-
-  return {
-    manifestVersion: MANIFEST_VERSION,
-    entry: ENTRY,
-    transformersVersion: entry.version,
-    excluded: EXCLUDED,
-    // 平台无关：下载时按 os/cpu/libc 过滤（payloadId 也由下载器按本机平台算）。
-    packages
-  };
-}
-
-/** 应当被覆盖的平台（自检与 CI 断言用）。 */
-export const COVERED_PLATFORMS = [
-  ["win32", "x64"],
-  ["win32", "arm64"],
-  ["darwin", "x64"],
-  ["darwin", "arm64"],
-  ["linux", "x64"],
-  ["linux", "arm64"]
-];
-
-/** 命令行入口。`--check` 只校验，不写文件。 */
-export function main(args = process.argv.slice(2)) {
-  const check = args.includes("--check");
-  const built = build();
-  const coverage = COVERED_PLATFORMS.map(([platform, arch]) => {
-    const set = packagesForPlatform(built, platform, arch);
-    const hasEntry = set.some((pkg) => pkg.rel === ENTRY);
-    const hasNative = set.some((pkg) => pkg.rel === "onnxruntime-node");
-    // linux 再报一次「确认 glibc 时」的包数：下载器会剔掉另一套 libc 的变体，这行让
-    // 「剔掉了多少」在 --check 里看得见，而不是只能翻清单。
-    const glibc = platform === "linux" ? `；确认 glibc 时 ${packagesForPlatform(built, platform, arch, "glibc").length} 个` : "";
-    return `${platform}-${arch}: ${set.length} 个包${glibc}${hasEntry && hasNative ? "" : "（缺入口或原生依赖！）"}`;
-  });
-
-  if (check) {
-    const existing = existsSync(MANIFEST) ? readFileSync(MANIFEST, "utf8") : "";
-    const same = existing === `${JSON.stringify(built, null, 2)}\n`;
-    process.stdout.write(`${same ? "✓" : "✗"} 清单与 package-lock.json ${same ? "一致" : "不一致，请重跑生成"}\n`);
-    for (const line of coverage) process.stdout.write(`   ${line}\n`);
-    return same ? 0 : 1;
-  }
-
-  writeFileSync(MANIFEST, `${JSON.stringify(built, null, 2)}\n`, "utf8");
-  process.stdout.write(`写入 ${MANIFEST}\n共 ${built.packages.length} 个包（已剔除 ${Object.keys(EXCLUDED).join("、")} 及其子树）\n`);
-  for (const line of coverage) process.stdout.write(`   ${line}\n`);
-  return 0;
-}
-
-// 只有被直接执行时才干活：被 import 时（测试里）不该顺手改写清单文件。
-const invokedDirectly =
-  process.argv[1] != null && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/").split("/").pop() ?? "");
-if (invokedDirectly) process.exitCode = main();
+// 生成 runtime-manifest.json（issue #131 / PR-C）
+//
+// **平台无关**是这份清单的核心设计：数据源是 `package-lock.json` 而不是「本机装好的那棵树」。
+// npm 的 lockfile 里包含**所有平台**的包条目（各自的 os / cpu 与 integrity），所以一份清单就能
+// 覆盖 win32 / darwin / linux × x64 / arm64 —— 下载时再按平台过滤（`matchesPlatform`）。
+//
+// 为什么不做成「按平台各存一份、谁在哪个系统上生成」：那样 macOS 用户在一台没人跑过脚本的机器上
+// 会看到「清单里没有 darwin-arm64 的条目」而直接卡住。清单是随包发布的静态数据，它必须一次覆盖
+// 所有平台，而不是依赖某个贡献者手上有对应的机器。
+//
+// 哈希取自 lockfile 的 integrity（npm 自己算的），所以维护成本是「改依赖后重跑一次脚本」。
+//
+// 用法：
+//   node scripts/build-runtime-manifest.mjs            # 生成/更新
+//   node scripts/build-runtime-manifest.mjs --check     # 只校验现有文件与 lockfile 一致（CI 用）
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { matchesPlatform } from "../src/runtime/closure.js";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+const MANIFEST = join(ROOT, "runtime-manifest.json");
+const MANIFEST_VERSION = 2;
+const ENTRY = "@huggingface/transformers";
+
+/**
+ * 证据：`@huggingface/transformers` 的 Node 构建（dist/transformers.node.mjs）顶层只 import
+ * onnxruntime-node 与 sharp，从不 import onnxruntime-web（把一个空的 onnxruntime-web 打桩进去，
+ * 嵌入结果逐字节相同：dims=[2,512]、L2 范数 1.0000、cos 0.3053）。而它解包后 127.7MB，占整个
+ * 闭包约三分之一。所以清单里剔除它，风险由 verify 的真实推理兜底。
+ */
+const EXCLUDED = {
+  "onnxruntime-web": "Node 构建从不 import 它（打桩验证：嵌入结果逐字节相同）",
+  // sharp 0.35 起把 WASM 回退包装进 optionalDependencies（freebsd/webcontainers 场景），
+  // 六个覆盖平台在 Node 里从不 import；wasm32 无 os 约束，会混进每个平台的 natives 断言。
+  "@img/sharp-freebsd-wasm32": "FreeBSD 专用 WASM 回退，覆盖平台之外",
+  "@img/sharp-webcontainers-wasm32": "WebContainers 专用 WASM 回退，覆盖平台之外",
+  "@img/sharp-wasm32": "无 os 约束的 WASM 回退，Node 构建从不 import",
+};
+
+/**
+ * 被剔除的包，以及**它子树下的一切**。
+ *
+ * 只按包名过滤会漏掉嵌套条目：闭包是按源布局镜像的，所以存在
+ * `onnxruntime-web/node_modules/onnxruntime-common` 这种位于被剔除包内部的包 ——
+ * 那个位置根本不会被取回来，留在清单里就是让下载器去填一个不存在的坑。
+ * 同名但位于别处（例如顶层 onnxruntime-common）不受影响。
+ */
+export function isExcluded(pkg) {
+  return Object.keys(EXCLUDED).some(
+    (name) => pkg.name === name || pkg.rel === name || pkg.rel.startsWith(`${name}/`)
+  );
+}
+
+/** lockfile 的路径 → 包名（最后一段 `node_modules/` 之后的部分）。 */
+export function nameOfPath(path) {
+  const marker = path.lastIndexOf("node_modules/");
+  return marker === -1 ? path : path.slice(marker + "node_modules/".length);
+}
+
+/** lockfile 的路径 → payload 里的相对路径（去掉开头的 `node_modules/`）。 */
+export function relOfPath(path) {
+  return path.startsWith("node_modules/") ? path.slice("node_modules/".length) : path;
+}
+
+/**
+ * 按 Node 的解析语义列出候选路径：从引用者自身的 `node_modules` 逐级向上，最后兜底到根部。
+ *
+ * 例：引用者在 `node_modules/a/node_modules/b`、依赖 `x` →
+ *   `…/b/node_modules/x` → `node_modules/a/node_modules/x` → `node_modules/x`
+ * @param {string} fromPath - 引用者的 lockfile 路径。
+ * @param {string} name - 依赖名。
+ * @returns {string[]} 候选路径，由近到远。
+ */
+export function resolveCandidates(fromPath, name) {
+  const out = [`${fromPath}/node_modules/${name}`];
+  let cursor = fromPath;
+  while (cursor.includes("/node_modules/")) {
+    cursor = cursor.slice(0, cursor.lastIndexOf("/node_modules/"));
+    out.push(cursor === "" ? `node_modules/${name}` : `${cursor}/node_modules/${name}`);
+  }
+  if (!out.includes(`node_modules/${name}`)) out.push(`node_modules/${name}`);
+  return out;
+}
+
+/** registry 的 tarball 地址：lockfile 记了 resolved 就用它（与 integrity 同源），否则按 npm 约定推。 */
+function tarballUrl(name, version, resolved) {
+  if (typeof resolved === "string" && resolved.startsWith("http")) return resolved;
+  const base = name.startsWith("@") ? name.slice(name.indexOf("/") + 1) : name;
+  return `https://registry.npmjs.org/${name}/-/${base}-${version}.tgz`;
+}
+
+/**
+ * 从 lockfile 走一遍闭包。
+ * @param {object} lock - package-lock.json 的内容。
+ * @returns {{packages: object[], missing: string[]}} 包列表（按 rel 排序）与解析不到的依赖。
+ */
+export function closureFromLockfile(lock) {
+  const all = lock.packages ?? {};
+  const known = new Set(
+    Object.entries(all)
+      .filter(([path, meta]) => path.includes("node_modules/") && meta?.version !== undefined)
+      .map(([path]) => path)
+  );
+  const seen = new Map();
+  const missing = [];
+  const queue = [`node_modules/${ENTRY}`];
+
+  while (queue.length > 0) {
+    const path = queue.shift();
+    if (seen.has(path)) continue;
+    const meta = all[path];
+    if (meta?.version === undefined) {
+      missing.push(path);
+      continue;
+    }
+    if (isExcluded({ name: nameOfPath(path), rel: relOfPath(path) })) continue;
+    seen.set(path, meta);
+
+    const deps = { ...(meta.dependencies ?? {}), ...(meta.optionalDependencies ?? {}) };
+    for (const name of Object.keys(deps)) {
+      const resolved = resolveCandidates(path, name).find((option) => known.has(option));
+      if (resolved === undefined) missing.push(`${name}（被 ${relOfPath(path)} 需要）`);
+      else queue.push(resolved);
+    }
+  }
+
+  const packages = [...seen.entries()]
+    .map(([path, meta]) => ({
+      name: nameOfPath(path),
+      version: meta.version,
+      rel: relOfPath(path),
+      integrity: meta.integrity ?? null,
+      tarball: tarballUrl(nameOfPath(path), meta.version, meta.resolved),
+      // 平台约束照抄 lockfile：下载器按它过滤。没有这三个字段 = 与平台无关。
+      ...(Array.isArray(meta.os) ? { os: meta.os } : {}),
+      ...(Array.isArray(meta.cpu) ? { cpu: meta.cpu } : {}),
+      // libc 也带上：linux-x64 的 glibc 机器靠它剔掉两套 musl 变体（十几 MB）。
+      // 下载器只在**确认**了本机 libc 时才据此过滤，拿不到证据就不看这个字段。
+      ...(Array.isArray(meta.libc) ? { libc: meta.libc } : {})
+    }))
+    .sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+
+  return { packages, missing };
+}
+
+/** 某个平台实际需要取哪些包（与下载器用同一条判据）。 */
+export function packagesForPlatform(manifest, platform, arch, libc = null) {
+  return manifest.packages.filter((pkg) => matchesPlatform(pkg, platform, arch, libc));
+}
+
+/** 生成一份**平台无关**的清单。 */
+export function build() {
+  const lock = JSON.parse(readFileSync(join(ROOT, "package-lock.json"), "utf8"));
+  const { packages, missing } = closureFromLockfile(lock);
+  // 解析不到的依赖必须让生成**失败**：带缺口的清单会让用户在下载时才失败，而且「少了一个包」
+  // 这种缺口结构检查看不出来（它只点三个必需包）。生成期的数据问题就该在生成期炸掉 ——
+  // 这也是我第一版真正踩过的：被剔除包的孤儿依赖留在了清单里，而生成器一声不吭。
+  if (missing.length > 0) {
+    throw new Error(`这些依赖在 package-lock.json 里解析不到：${missing.slice(0, 10).join("、")}`);
+  }
+
+  const entry = packages.find((pkg) => pkg.rel === ENTRY);
+  if (entry === undefined) throw new Error(`闭包入口没解析出来：${missing.join("; ") || "lockfile 里没有它"}`);
+  // 查不到 sha512 就不能写进清单：那等于让下载器「先信任再校验」，是假校验。
+  const withoutIntegrity = packages.filter(
+    (pkg) => typeof pkg.integrity !== "string" || !pkg.integrity.startsWith("sha512-")
+  );
+  if (withoutIntegrity.length > 0) {
+    throw new Error(`这些包在 package-lock.json 里没有 sha512 integrity：${withoutIntegrity.map((p) => p.rel).join("、")}`);
+  }
+
+  return {
+    manifestVersion: MANIFEST_VERSION,
+    entry: ENTRY,
+    transformersVersion: entry.version,
+    excluded: EXCLUDED,
+    // 平台无关：下载时按 os/cpu/libc 过滤（payloadId 也由下载器按本机平台算）。
+    packages
+  };
+}
+
+/** 应当被覆盖的平台（自检与 CI 断言用）。 */
+export const COVERED_PLATFORMS = [
+  ["win32", "x64"],
+  ["win32", "arm64"],
+  ["darwin", "x64"],
+  ["darwin", "arm64"],
+  ["linux", "x64"],
+  ["linux", "arm64"]
+];
+
+/** 命令行入口。`--check` 只校验，不写文件。 */
+export function main(args = process.argv.slice(2)) {
+  const check = args.includes("--check");
+  const built = build();
+  const coverage = COVERED_PLATFORMS.map(([platform, arch]) => {
+    const set = packagesForPlatform(built, platform, arch);
+    const hasEntry = set.some((pkg) => pkg.rel === ENTRY);
+    const hasNative = set.some((pkg) => pkg.rel === "onnxruntime-node");
+    // linux 再报一次「确认 glibc 时」的包数：下载器会剔掉另一套 libc 的变体，这行让
+    // 「剔掉了多少」在 --check 里看得见，而不是只能翻清单。
+    const glibc = platform === "linux" ? `；确认 glibc 时 ${packagesForPlatform(built, platform, arch, "glibc").length} 个` : "";
+    return `${platform}-${arch}: ${set.length} 个包${glibc}${hasEntry && hasNative ? "" : "（缺入口或原生依赖！）"}`;
+  });
+
+  if (check) {
+    const existing = existsSync(MANIFEST) ? readFileSync(MANIFEST, "utf8") : "";
+    const same = existing === `${JSON.stringify(built, null, 2)}\n`;
+    process.stdout.write(`${same ? "✓" : "✗"} 清单与 package-lock.json ${same ? "一致" : "不一致，请重跑生成"}\n`);
+    for (const line of coverage) process.stdout.write(`   ${line}\n`);
+    return same ? 0 : 1;
+  }
+
+  writeFileSync(MANIFEST, `${JSON.stringify(built, null, 2)}\n`, "utf8");
+  process.stdout.write(`写入 ${MANIFEST}\n共 ${built.packages.length} 个包（已剔除 ${Object.keys(EXCLUDED).join("、")} 及其子树）\n`);
+  for (const line of coverage) process.stdout.write(`   ${line}\n`);
+  return 0;
+}
+
+// 只有被直接执行时才干活：被 import 时（测试里）不该顺手改写清单文件。
+const invokedDirectly =
+  process.argv[1] != null && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/").split("/").pop() ?? "");
+if (invokedDirectly) process.exitCode = main();

package/scripts/changelog-prep.mjs

@@ -1,91 +1,91 @@
-// 发布准备里「在 CHANGELOG 顶部插版本占位节」这一步的单一实现。
-//
-// 为什么抽成模块而不是留在入口里：入口 scripts/release-prep.mjs 在仓库根、import 即
-// 执行，测不了；而这一步恰恰踩过坑——原先的实现在 **CRLF 检出**上用 /^(# Changelog\n\n)/
-// 匹配文件头，命中不了于是 replace 退化成 no-op，**脚本却照样打印 ✓**，git status 里
-// 什么也看不见。发版时最怕的就是这种假成功（CI 跑在 ubuntu 上是 LF，所以只有本机会中招）。
-// 抽出来之后：行尾两种都能吃，匹配不上则**如实回报**，由入口报错退出。
-//
-// 与 scripts/test-count-sync.mjs 同一个理由：规则收在共用模块里才测得到、也才不会两处各写一份。
-
-/** 取出文本的行尾风格：插入的内容跟着它走，避免把 CRLF 文件混成一半 CRLF 一半 LF。 */
-export function detectEol(text) {
-  return text.includes("\r\n") ? "\r\n" : "\n";
-}
-
-/**
- * 只剥掉整段两端的空行，保留每行自己的缩进（正文原样搬走的前提）。
- * 重新拼回时用原文的行尾：CRLF 的 CHANGELOG 若在这里退化成 LF，整份文件就成了混合行尾。
- */
-function stripBlankEdges(text, eol) {
-  const lines = text.split(/\r?\n/);
-  let from = 0;
-  let to = lines.length;
-  while (from < to && lines[from].trim() === "") from += 1;
-  while (to > from && lines[to - 1].trim() === "") to -= 1;
-  return lines.slice(from, to).join(eol);
-}
-
-/**
- * 插入 `## [version] - date` 节（幂等：已含该版本则不改）。
- *
- * **两个位置约定，都是被真实发版逼出来的**：
- *
- * 1. 新版本节排在 `## [Unreleased]` **下面**，不是 `# Changelog` 下面。Keep a Changelog
- *    的约定是未发布区永远在最上；插反了会写出「[0.9.1] 在 [Unreleased] 之上」的顺序颠倒。
- *    v0.9.0 那次就是靠事后一笔人工提交（77df0fb）掰回来的——机器算得对的事不该留给人补。
- *
- * 2. `[Unreleased]` 里攒着的条目**整段搬进新版本节**，Unreleased 留空。原先只插一个
- *    「🐛 修复 / （待填）」空占位，攒着的条目原地不动，于是发版后文件里同时存在
- *    「新版本节是空的」和「旧条目还挂在 Unreleased 名下」——搬运这一步照样是人工补的
- *    （同一个 77df0fb）。搬的是位置不是内容：原样移动、一个字不改，所以「新版本节里
- *    该写什么」这个判断仍然只由往 Unreleased 里写条目的人做。
- *
- * 返回 `{ok:false, reason}` 而不是静默返回原文——调用方必须能区分「没什么可做」与
- * 「该做但没做成」，后者要报错退出。`reason` 取值：`already-present` / `header-not-found`。
- * 成功时带两个字段，**必须分开用**：
- * - `movedContent`：是否真的从 [Unreleased] 搬了非空正文（决定「搬了」还是「插了空占位」）；
- * - `moved`：其中以 `- ` 开头的条目数，只用于把日志说得更具体。
- * 用 `moved` 当「有没有搬」的判据是错的：正文非空但一条 `-` 都没有（例如全是正文段落或
- * 缩进代码块）时 `moved` 是 0，日志会说「[Unreleased] 本来是空的」——而它是非空的。
- *
- * @param {string} text CHANGELOG 全文
- * @param {string} version 如 "0.8.13"
- * @param {string} date 如 "2026-10-03"
- * @returns {{ok: true, text: string, moved: number, movedContent: boolean} | {ok: false, reason: "already-present" | "header-not-found"}}
- */
-export function insertReleaseSection(text, version, date) {
-  if (text.includes(`## [${version}]`)) return { ok: false, reason: "already-present" };
-  const eol = detectEol(text);
-  const placeholder = `## 🐛 修复${eol}${eol}- （待填）${eol}`;
-
-  const m = /^## \[Unreleased\][^\r\n]*\r?\n/m.exec(text);
-  if (m) {
-    const start = m.index + m[0].length;
-    const rest = text.slice(start);
-    const nextRel = rest.search(/^## \[/m);
-    const body = nextRel === -1 ? rest : rest.slice(0, nextRel);
-    const tail = nextRel === -1 ? "" : rest.slice(nextRel);
-    // 只剥节边界上的空行，**不 trim 正文**：正文首行若是缩进代码块（Markdown 的四空格），
-    // trim 会把前导空格吃掉，代码块降级成普通段落——那就不是「原样搬」了。
-    const pending = stripBlankEdges(body, eol);
-    const head = `## [${version}] - ${date}${eol}${eol}`;
-
-    // Unreleased 里攒着东西：整段搬进新版本节，Unreleased 留空。
-    // 搬的是位置不是内容——原样移动，一个字不改。这样「新版本节里有什么」这个判断
-    // 仍然只由往 Unreleased 里写条目的人做，脚本只负责把攒好的东西挪对地方。
-    if (pending) {
-      const moved = pending.split(/\r?\n/).filter((l) => l.startsWith("- ")).length;
-      return { ok: true, moved, movedContent: true, text: text.slice(0, start) + eol + head + pending + eol + eol + tail };
-    }
-
-    // Unreleased 是空的：插占位节，等人写内容。
-    return { ok: true, moved: 0, movedContent: false, text: text.slice(0, start) + eol + head + placeholder + eol + tail };
-  }
-
-  // 没有 [Unreleased] 的旧文件：退回标题之后。BOM 可选——带 BOM 的检出上 `^#` 同样匹配不到。
-  const section = `## [${version}] - ${date}${eol}${eol}${placeholder}${eol}`;
-  const out = text.replace(/^(\uFEFF?# Changelog\r?\n\r?\n)/, "$1" + section);
-  if (out === text) return { ok: false, reason: "header-not-found" };
-  return { ok: true, moved: 0, movedContent: false, text: out };
-}
+// 发布准备里「在 CHANGELOG 顶部插版本占位节」这一步的单一实现。
+//
+// 为什么抽成模块而不是留在入口里：入口 scripts/release-prep.mjs 在仓库根、import 即
+// 执行，测不了；而这一步恰恰踩过坑——原先的实现在 **CRLF 检出**上用 /^(# Changelog\n\n)/
+// 匹配文件头，命中不了于是 replace 退化成 no-op，**脚本却照样打印 ✓**，git status 里
+// 什么也看不见。发版时最怕的就是这种假成功（CI 跑在 ubuntu 上是 LF，所以只有本机会中招）。
+// 抽出来之后：行尾两种都能吃，匹配不上则**如实回报**，由入口报错退出。
+//
+// 与 scripts/test-count-sync.mjs 同一个理由：规则收在共用模块里才测得到、也才不会两处各写一份。
+
+/** 取出文本的行尾风格：插入的内容跟着它走，避免把 CRLF 文件混成一半 CRLF 一半 LF。 */
+export function detectEol(text) {
+  return text.includes("\r\n") ? "\r\n" : "\n";
+}
+
+/**
+ * 只剥掉整段两端的空行，保留每行自己的缩进（正文原样搬走的前提）。
+ * 重新拼回时用原文的行尾：CRLF 的 CHANGELOG 若在这里退化成 LF，整份文件就成了混合行尾。
+ */
+function stripBlankEdges(text, eol) {
+  const lines = text.split(/\r?\n/);
+  let from = 0;
+  let to = lines.length;
+  while (from < to && lines[from].trim() === "") from += 1;
+  while (to > from && lines[to - 1].trim() === "") to -= 1;
+  return lines.slice(from, to).join(eol);
+}
+
+/**
+ * 插入 `## [version] - date` 节（幂等：已含该版本则不改）。
+ *
+ * **两个位置约定，都是被真实发版逼出来的**：
+ *
+ * 1. 新版本节排在 `## [Unreleased]` **下面**，不是 `# Changelog` 下面。Keep a Changelog
+ *    的约定是未发布区永远在最上；插反了会写出「[0.9.1] 在 [Unreleased] 之上」的顺序颠倒。
+ *    v0.9.0 那次就是靠事后一笔人工提交（77df0fb）掰回来的——机器算得对的事不该留给人补。
+ *
+ * 2. `[Unreleased]` 里攒着的条目**整段搬进新版本节**，Unreleased 留空。原先只插一个
+ *    「🐛 修复 / （待填）」空占位，攒着的条目原地不动，于是发版后文件里同时存在
+ *    「新版本节是空的」和「旧条目还挂在 Unreleased 名下」——搬运这一步照样是人工补的
+ *    （同一个 77df0fb）。搬的是位置不是内容：原样移动、一个字不改，所以「新版本节里
+ *    该写什么」这个判断仍然只由往 Unreleased 里写条目的人做。
+ *
+ * 返回 `{ok:false, reason}` 而不是静默返回原文——调用方必须能区分「没什么可做」与
+ * 「该做但没做成」，后者要报错退出。`reason` 取值：`already-present` / `header-not-found`。
+ * 成功时带两个字段，**必须分开用**：
+ * - `movedContent`：是否真的从 [Unreleased] 搬了非空正文（决定「搬了」还是「插了空占位」）；
+ * - `moved`：其中以 `- ` 开头的条目数，只用于把日志说得更具体。
+ * 用 `moved` 当「有没有搬」的判据是错的：正文非空但一条 `-` 都没有（例如全是正文段落或
+ * 缩进代码块）时 `moved` 是 0，日志会说「[Unreleased] 本来是空的」——而它是非空的。
+ *
+ * @param {string} text CHANGELOG 全文
+ * @param {string} version 如 "0.8.13"
+ * @param {string} date 如 "2026-10-03"
+ * @returns {{ok: true, text: string, moved: number, movedContent: boolean} | {ok: false, reason: "already-present" | "header-not-found"}}
+ */
+export function insertReleaseSection(text, version, date) {
+  if (text.includes(`## [${version}]`)) return { ok: false, reason: "already-present" };
+  const eol = detectEol(text);
+  const placeholder = `## 🐛 修复${eol}${eol}- （待填）${eol}`;
+
+  const m = /^## \[Unreleased\][^\r\n]*\r?\n/m.exec(text);
+  if (m) {
+    const start = m.index + m[0].length;
+    const rest = text.slice(start);
+    const nextRel = rest.search(/^## \[/m);
+    const body = nextRel === -1 ? rest : rest.slice(0, nextRel);
+    const tail = nextRel === -1 ? "" : rest.slice(nextRel);
+    // 只剥节边界上的空行，**不 trim 正文**：正文首行若是缩进代码块（Markdown 的四空格），
+    // trim 会把前导空格吃掉，代码块降级成普通段落——那就不是「原样搬」了。
+    const pending = stripBlankEdges(body, eol);
+    const head = `## [${version}] - ${date}${eol}${eol}`;
+
+    // Unreleased 里攒着东西：整段搬进新版本节，Unreleased 留空。
+    // 搬的是位置不是内容——原样移动，一个字不改。这样「新版本节里有什么」这个判断
+    // 仍然只由往 Unreleased 里写条目的人做，脚本只负责把攒好的东西挪对地方。
+    if (pending) {
+      const moved = pending.split(/\r?\n/).filter((l) => l.startsWith("- ")).length;
+      return { ok: true, moved, movedContent: true, text: text.slice(0, start) + eol + head + pending + eol + eol + tail };
+    }
+
+    // Unreleased 是空的：插占位节，等人写内容。
+    return { ok: true, moved: 0, movedContent: false, text: text.slice(0, start) + eol + head + placeholder + eol + tail };
+  }
+
+  // 没有 [Unreleased] 的旧文件：退回标题之后。BOM 可选——带 BOM 的检出上 `^#` 同样匹配不到。
+  const section = `## [${version}] - ${date}${eol}${eol}${placeholder}${eol}`;
+  const out = text.replace(/^(\uFEFF?# Changelog\r?\n\r?\n)/, "$1" + section);
+  if (out === text) return { ok: false, reason: "header-not-found" };
+  return { ok: true, moved: 0, movedContent: false, text: out };
+}