@modusensus/dsh-mneme 0.7.31 → 0.7.32

package/test/runtime-adopt.test.js

@@ -0,0 +1,206 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { adoptRuntime, materializePackage, RUNTIME_MANIFEST_VERSION } from "../src/runtime/adopt.js";
+import { describePayload, nodeModulesDir, payloadDir, payloadId, runtimeManifestPath } from "../src/runtime/layout.js";
+import { readJsonSafe } from "../src/runtime/layout.js";
+
+// 收编（issue #131 / PR-A）：守住「老用户升级后本地嵌入不断」这条底线。
+// 关键判据是——源布局被如实镜像（含嵌套层）、同卷走硬链接、符号链接不跟随、
+// 产出的目录能通过结构检查。
+
+/** 造一份「像真的」源 node_modules：入口 + 三平台单包 + 平台分片 + 嵌套版本冲突。 */
+function makeSource({ withSymlink = false } = {}) {
+  const base = mkdtempSync(join(tmpdir(), "mneme-adopt-src-"));
+  const nm = join(base, "node_modules");
+  const write = (rel, body) => {
+    const full = join(nm, rel);
+    mkdirSync(join(full, ".."), { recursive: true });
+    writeFileSync(full, body);
+  };
+  const pkg = (rel, manifest) => write(join(rel, "package.json"), JSON.stringify(manifest));
+
+  pkg("@huggingface/transformers", {
+    name: "@huggingface/transformers",
+    version: "4.2.0",
+    dependencies: { "onnxruntime-node": "1.24.3", sharp: "^0.34.5" }
+  });
+  write("@huggingface/transformers/dist/transformers.node.mjs", "export const real = true;\n");
+
+  pkg("onnxruntime-node", { name: "onnxruntime-node", version: "1.24.3", dependencies: { "onnxruntime-common": "1.24.3" } });
+  write("onnxruntime-node/bin/napi-v6/win32/x64/onnxruntime.dll", "dll-bytes\n");
+  write("onnxruntime-node/bin/napi-v6/darwin/arm64/libonnxruntime.dylib", "dylib-bytes\n");
+
+  pkg("onnxruntime-common", { name: "onnxruntime-common", version: "1.24.3" });
+  write("onnxruntime-common/index.js", "export default 1;\n");
+
+  pkg("sharp", { name: "sharp", version: "0.34.5" });
+  write("sharp/index.js", "export default 2;\n");
+
+  if (withSymlink) write("sharp/linked.js", "export default 3;\n");
+
+  return { base, nm, write };
+}
+
+test("收编：镜像源布局（含嵌套层），并写出清单", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+
+  assert.equal(result.ok, true, result.reason);
+  assert.equal(result.payloadId, "transformers-4.2.0-node-win32-x64");
+  assert.equal(result.payloadDir, payloadDir(runtimeDir, payloadId({ version: "4.2.0", platform: "win32", arch: "x64" })));
+
+  const manifest = readJsonSafe(runtimeManifestPath(result.payloadDir));
+  assert.equal(manifest.manifestVersion, RUNTIME_MANIFEST_VERSION);
+  assert.equal(manifest.procedure, "adopted");
+  assert.equal(manifest.version, "4.2.0");
+  assert.ok(manifest.packages.some((p) => p.rel === "onnxruntime-node"));
+
+  // 收编产物必须能通过结构检查——这是「adopt 与 layout 契约一致」的整合判据。
+  const report = describePayload(result.payloadDir, { platform: "win32", arch: "x64" });
+  assert.equal(report.ok, true, `missing=${report.missing} reasons=${report.reasons}`);
+  assert.equal(report.manifest?.procedure, "adopted");
+});
+
+test("收编：同卷走硬链接（不额外占盘），且文件内容一致", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+
+  assert.equal(result.totals.files, result.totals.linked + result.totals.copied, "每个文件要么链接要么复制");
+  assert.ok(result.totals.linked > 0, `同卷应当走硬链接，实际 linked=${result.totals.linked} copied=${result.totals.copied}`);
+  assert.ok(result.totals.bytes > 0);
+  assert.equal(result.manifest.materialize.mode, "hardlink");
+  assert.equal(result.manifest.materialize.linkError, null, "没回退就不该有 linkError");
+
+  const copied = join(nodeModulesDir(result.payloadDir), "onnxruntime-node", "bin", "napi-v6", "win32", "x64", "onnxruntime.dll");
+  assert.equal(readJsonSafe(copied), undefined, "非 JSON 内容应当原样搬过来");
+});
+
+test("收编：硬链接不可用时回退复制，并把原因如实记进清单与 warnings", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  // 注入一个必定失败的 linkSync，覆盖「跨卷 / 权限不足」这类本机不可复现的环境差异。
+  const denyLink = () => {
+    const error = new Error("operation not permitted, link");
+    error.code = "EPERM";
+    throw error;
+  };
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", link: denyLink });
+
+  assert.equal(result.ok, true, result.reason);
+  assert.equal(result.totals.linked, 0);
+  assert.equal(result.totals.copied, result.totals.files);
+  assert.equal(result.manifest.materialize.mode, "copy");
+  assert.match(result.manifest.materialize.linkError, /EPERM/);
+  assert.equal(
+    result.manifest.warnings.filter((w) => w.includes("硬链接不可用")).length,
+    1,
+    "同一次收编只该记一条回退原因，不是每个文件记一条"
+  );
+  // 回退之后产物依然必须能通过结构检查——回退不能以正确性为代价。
+  assert.equal(describePayload(result.payloadDir, { platform: "win32", arch: "x64" }).ok, true);
+});
+
+test("收编：跳过嵌套 node_modules，避免把同一份包搬两遍", () => {
+  const { nm, write } = makeSource();
+  // 给入口包塞一个嵌套副本：闭包不会把它当作依赖，因此不该被搬进产物。
+  write("@huggingface/transformers/node_modules/orphan/index.js", "orphan\n");
+  write("@huggingface/transformers/node_modules/orphan/package.json", JSON.stringify({ name: "orphan", version: "1.0.0" }));
+
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(result.ok, true, result.reason);
+
+  const orphan = join(nodeModulesDir(result.payloadDir), "@huggingface", "transformers", "node_modules", "orphan");
+  assert.equal(describePayload(result.payloadDir, { platform: "win32", arch: "x64" }).ok, true);
+  assert.equal(readJsonSafe(join(orphan, "package.json")), undefined, "不可达的嵌套包不该被搬进来");
+});
+
+test("收编：符号链接不跟随，记进 warnings（isolated 布局的来源会被如实暴露）", (t) => {
+  const { nm, write } = makeSource();
+  const real = join(nm, "sharp", "index.js");
+  const link = join(nm, "sharp", "linked.js");
+  try {
+    symlinkSync(real, link, "file");
+  } catch {
+    t.skip("当前环境不允许创建符号链接（Windows 需要开发者模式），跳过该断言");
+    return;
+  }
+  assert.ok(write);
+
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(result.totals.symlinks, 1);
+  assert.ok(result.manifest.warnings.some((w) => w.includes("符号链接")));
+});
+
+test("收编：目标已存在时默认拒绝，overwrite 才覆盖", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const first = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(first.ok, true);
+
+  const again = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(again.ok, false);
+  assert.match(again.reason, /目标已存在/);
+
+  const forced = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", overwrite: true });
+  assert.equal(forced.ok, true);
+});
+
+test("收编：源里没有入口包时给出可读原因，不抛异常", () => {
+  const empty = mkdtempSync(join(tmpdir(), "mneme-adopt-empty-"));
+  mkdirSync(join(empty, "node_modules"), { recursive: true });
+  const result = adoptRuntime({ fromModulesDir: join(empty, "node_modules") });
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /入口包不存在|入口包未解析到/);
+});
+
+test("materializePackage：统计文件与字节数，返回自身可测", () => {
+  const { base } = makeSource();
+  const src = join(base, "node_modules", "onnxruntime-common");
+  const dest = mkdtempSync(join(tmpdir(), "mneme-materialize-"));
+  const stats = materializePackage({ srcDir: src, destDir: join(dest, "pkg") });
+  assert.equal(stats.files, 2, "package.json + index.js");
+  assert.ok(stats.bytes > 0);
+  assert.equal(stats.symlinks, 0);
+});
+
+test("覆盖收编：先清空目标目录，否则硬链接全部退化成复制、残留文件也清不掉", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  const first = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64" });
+  assert.equal(first.ok, true, first.reason);
+  assert.equal(first.manifest.materialize.mode, "hardlink");
+
+  // 只可能来自上一次收编的残留文件：覆盖时必须被清掉。
+  const stale = join(first.payloadDir, "stale-from-previous-run");
+  writeFileSync(stale, "stale\n");
+
+  const second = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", overwrite: true });
+  assert.equal(second.ok, true, second.reason);
+  // 不清空目标目录的话，linkSync 对已存在的目标路径抛 EEXIST，每个文件都掉进复制分支：
+  // 物化方式会假报成 copy，warnings 会错说「硬链接不可用」，整份闭包真实占盘。
+  assert.equal(second.manifest.materialize.mode, "hardlink", "覆盖不该把硬链接降级成复制");
+  assert.equal(second.manifest.materialize.linkError, null);
+  assert.equal(existsSync(stale), false, "上一次收编的残留文件必须被清掉");
+});
+
+test("截断的闭包必须拒绝：宁可明确失败，也不要产出一份看起来可用的运行时", () => {
+  const { nm } = makeSource();
+  const runtimeDir = mkdtempSync(join(tmpdir(), "mneme-adopt-dst-"));
+  // 上限 1 个包，必然截断传递依赖。结构检查只看必需包/版本/入口，所以这种残缺 payload
+  // 本来会被判为可用、被 loader 选中，然后在 import 原生模块时才炸。
+  const result = adoptRuntime({ fromModulesDir: nm, runtimeDir, platform: "win32", arch: "x64", maxPackages: 1 });
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /截断/);
+  assert.equal(
+    existsSync(payloadDir(runtimeDir, payloadId({ version: "4.2.0", platform: "win32", arch: "x64" }))),
+    false,
+    "拒绝时不该留下半份 payload"
+  );
+});

package/test/runtime-cli.test.js

@@ -0,0 +1,89 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { makeEmptyModules, makeSourceModules } from "./helpers/runtime-source.js";
+
+// 这个 CLI 脚本原先不在任何测试覆盖里：USAGE 模板字面量里多一个反引号就能让它整体语法错误，
+// 而 CI 依然全绿 —— package.json 的 `test` 只跑 test/*.test.js，从不碰 scripts/。踩过一次。
+//
+// 这里动态 import 它：解析与求值都会真的发生，任何语法错都会让下面的测试直接炸。
+// 脚本侧有 invokedDirectly 守卫，所以 import 不会顺带跑起 CLI。
+const cli = await import("../scripts/mneme-runtime.mjs");
+
+test("CLI 脚本能被解析并求值（语法错必须在这里现形，而不是发布出去）", () => {
+  assert.equal(typeof cli.main, "function");
+  assert.equal(typeof cli.parseArgs, "function");
+  assert.equal(typeof cli.UsageError, "function");
+});
+
+test("CLI：--key value 与 --flag 各自解析正确", () => {
+  assert.deepEqual(cli.parseArgs(["--runtime", "/rt", "--from", "/nm", "--json"]), {
+    runtime: "/rt",
+    from: "/nm",
+    json: true
+  });
+  assert.deepEqual(cli.parseArgs(["--overwrite"]), { overwrite: true });
+  assert.deepEqual(cli.parseArgs([]), {});
+});
+
+test("CLI：带值选项缺值必须是用法错误 —— 不能把 \"true\" 当路径用下去", () => {
+  for (const key of ["runtime", "from", "cache-dir"]) {
+    assert.throws(() => cli.parseArgs([`--${key}`]), cli.UsageError, `--${key} 缺值应当报用法错误`);
+    // 后面紧跟另一个选项同样算缺值：不能把这个选项吞成上一个选项的值。
+    assert.throws(() => cli.parseArgs([`--${key}`, "--json"]), cli.UsageError, `--${key} 后接选项也算缺值`);
+  }
+});
+
+test("CLI：未知选项立刻报错，而不是静默忽略（打错字要立刻可见）", () => {
+  assert.throws(() => cli.parseArgs(["--runtim", "/rt"]), cli.UsageError);
+  assert.throws(() => cli.parseArgs(["-h"]), cli.UsageError);
+  assert.throws(() => cli.parseArgs(["/rt"]), cli.UsageError);
+});
+
+/** 捕获 console.log，用来断言 CLI 打印给用户的那几行。 */
+async function captureLog(fn) {
+  const original = console.log;
+  const lines = [];
+  console.log = (...args) => lines.push(args.join(" "));
+  try {
+    return { value: await fn(), text: lines.join("\n") };
+  } finally {
+    console.log = original;
+  }
+}
+
+/**
+ * 可收编源的夹具有两处要用（这里与 test/runtime-adopt-service.test.js），
+ * 所以放在 test/helpers/runtime-source.js —— 两份漂移过一次就会有两种结论。
+ */
+
+test("CLI adopt：源里没有入口包时给出干净原因，不能抛 TypeError（评审阻塞项）", async () => {
+  const src = makeEmptyModules();
+  // 修之前这里会抛：adoptRuntime 失败时不带 payloadDir，却被当成路径喂给 describePayload。
+  const { value, text } = await captureLog(() =>
+    cli.runAdopt({ runtimeDir: src.runtimeDir, asJson: false, options: { from: src.nm } })
+  );
+  assert.equal(value, 1);
+  assert.match(text, /收编失败：/, `应当打印干净原因，实际输出：${text}`);
+  assert.match(text, /入口包/);
+});
+
+test("CLI adopt：必需传递依赖缺口必须让退出码变红（评审阻塞项）", async () => {
+  const src = makeSourceModules({ withMissingDep: true });
+  const { value, text } = await captureLog(() =>
+    cli.runAdopt({ runtimeDir: src.runtimeDir, asJson: false, options: { from: src.nm } })
+  );
+  // 结构检查会「通过」——它只看三个必需包；缺口只有闭包计划知道。
+  assert.match(text, /结构检查：通过/);
+  assert.match(text, /缺失依赖：definitely-not-installed-pkg/);
+  assert.match(text, /闭包完整性：未通过/);
+  assert.equal(value, 1, "闭包缺件时退出码必须是 1，否则脚本化 gate 会在最需要它的时候误报健康");
+});
+
+test("CLI adopt：闭包完整时仍然报 0（防止上面那条修复过度触发）", async () => {
+  const src = makeSourceModules();
+  const { value, text } = await captureLog(() =>
+    cli.runAdopt({ runtimeDir: src.runtimeDir, asJson: false, options: { from: src.nm } })
+  );
+  assert.match(text, /结构检查：通过/);
+  assert.equal(value, 0, text);
+});

package/test/runtime-closure.test.js

@@ -0,0 +1,193 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { DEFAULT_MAX_PACKAGES, matchesPlatform, planClosure, resolvePackageDir } from "../src/runtime/closure.js";
+
+// 依赖闭包遍历（issue #131 / PR-A）：守住四条判据——按源布局镜像、平台过滤、
+// 可选依赖缺失不算错、peer 不进闭包。它是 adopt / export 的共同地基，
+// 走错一步就会把宿主整棵树拖进来（或漏带一个真需要的包）。
+
+/** 从 rel 路径推导包名（处理 scope 与嵌套 node_modules）。 */
+function nameFromRel(rel) {
+  const parts = rel.split("/");
+  const i = parts.lastIndexOf("node_modules");
+  return (i === -1 ? parts : parts.slice(i + 1)).join("/");
+}
+
+/** 按紧凑的 spec 造一棵假的 node_modules 树。 */
+function makeTree(spec) {
+  const base = mkdtempSync(join(tmpdir(), "mneme-closure-"));
+  // 刻意多套一层 proj/：这样「不允许解析越出源树」这条判据才测得出来
+  // （源树的上一级就是 base，base/node_modules 里的包必须解析不到）。
+  const nm = join(base, "proj", "node_modules");
+  mkdirSync(nm, { recursive: true });
+  for (const [rel, def = {}] of Object.entries(spec)) {
+    const dir = join(nm, rel);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, "package.json"),
+      JSON.stringify({
+        name: def.name ?? nameFromRel(rel),
+        version: def.version ?? "1.0.0",
+        ...(def.deps ? { dependencies: def.deps } : {}),
+        ...(def.optional ? { optionalDependencies: def.optional } : {}),
+        ...(def.peers ? { peerDependencies: def.peers } : {}),
+        ...(def.os ? { os: def.os } : {}),
+        ...(def.cpu ? { cpu: def.cpu } : {})
+      })
+    );
+  }
+  return { base, nm };
+}
+
+/**
+ * 一份贴近真实的树：transformers 是入口，它同时带 onnxruntime-node（多平台单包）、
+ * onnxruntime-web（自带一份不同版本的 onnxruntime-common）、sharp（平台分片走
+ * optionalDependencies），外加 peer、环、缺件四种边界。
+ */
+function realisticTree() {
+  return makeTree({
+    "@huggingface/transformers": {
+      version: "4.2.0",
+      deps: {
+        "onnxruntime-node": "1.24.3",
+        "onnxruntime-web": "1.26.0-dev",
+        sharp: "^0.34.5",
+        "@huggingface/tokenizers": "^0.1.3",
+        "@huggingface/jinja": "^0.5.6",
+        "darwin-only-pkg": "1.0.0"
+      },
+      peers: { "@deepseek-ai/cordis": "^4.0.1" }
+    },
+    "onnxruntime-node": { version: "1.24.3", deps: { "onnxruntime-common": "1.24.3", "adm-zip": "^0.5.16" } },
+    "onnxruntime-web": {
+      version: "1.26.0-dev",
+      deps: { "onnxruntime-common": "1.24.0-dev" }
+    },
+    "onnxruntime-web/node_modules/onnxruntime-common": { version: "1.24.0-dev" },
+    "onnxruntime-common": { version: "1.24.3" },
+    "adm-zip": { deps: { "global-agent": "^3.0.0" } },
+    "global-agent": { deps: { "adm-zip": "^0.5.16" } },
+    sharp: { version: "0.34.5", optional: { "@img/sharp-win32-x64": "0.34.5", "@img/sharp-darwin-arm64": "0.34.5" } },
+    "@img/sharp-win32-x64": { version: "0.34.5", os: ["win32"], cpu: ["x64"] },
+    "@img/sharp-darwin-arm64": { version: "0.34.5", os: ["darwin"], cpu: ["arm64"] },
+    "@huggingface/tokenizers": { version: "0.1.3", optional: { "not-installed-optional": "^1.0.0" } },
+    "@huggingface/jinja": { version: "0.5.6", deps: { "missing-required-thing": "^1.0.0" } },
+    "darwin-only-pkg": { os: ["darwin"] },
+    // 只在 root 之外存在，用来验证解析不会越出源树
+    "@deepseek-ai/cordis": { version: "4.0.2" }
+  });
+}
+
+test("按源布局镜像：嵌套的那份依赖与原位版本都被保留", () => {
+  const { nm } = realisticTree();
+  const plan = planClosure({ rootModulesDir: nm, platform: "win32", arch: "x64" });
+  const byRel = new Map(plan.packages.map((p) => [p.rel, p]));
+
+  assert.equal(byRel.get("@huggingface/transformers")?.version, "4.2.0");
+  assert.equal(byRel.get("onnxruntime-common")?.version, "1.24.3", "顶层那份");
+  assert.equal(
+    byRel.get("onnxruntime-web/node_modules/onnxruntime-common")?.version,
+    "1.24.0-dev",
+    "嵌套那份必须按原层级保留，否则解析结果会被悄悄改掉"
+  );
+  assert.equal(plan.gaps.filter((g) => g.reason === "必需依赖未找到").length, 1);
+  assert.deepEqual(plan.gaps[0], { name: "missing-required-thing", from: "@huggingface/jinja", reason: "必需依赖未找到" });
+});
+
+test("平台分片包：只带当前平台的，另一个记进 skipped", () => {
+  const { nm } = realisticTree();
+  const plan = planClosure({ rootModulesDir: nm, platform: "win32", arch: "x64" });
+  const rels = plan.packages.map((p) => p.rel);
+  assert.ok(rels.includes("@img/sharp-win32-x64"));
+  assert.equal(rels.includes("@img/sharp-darwin-arm64"), false, "darwin 分片不该进闭包");
+  assert.deepEqual(
+    plan.skipped.map((s) => s.rel).sort(),
+    ["@img/sharp-darwin-arm64", "darwin-only-pkg"].sort(),
+    "两个平台不匹配的包都该被记下来"
+  );
+  // 交叉验证：换成 darwin/arm64 时，该带的是另外那个。
+  const darwin = planClosure({ rootModulesDir: nm, platform: "darwin", arch: "arm64" });
+  const darwinRels = darwin.packages.map((p) => p.rel);
+  assert.ok(darwinRels.includes("@img/sharp-darwin-arm64"));
+  assert.equal(darwinRels.includes("@img/sharp-win32-x64"), false);
+});
+
+test("peerDependencies 不进闭包（宿主提供的东西不该被复制进来）", () => {
+  const { nm } = realisticTree();
+  const plan = planClosure({ rootModulesDir: nm, platform: "win32", arch: "x64" });
+  assert.equal(plan.packages.some((p) => p.rel === "@deepseek-ai/cordis"), false);
+});
+
+test("可选依赖缺失不算错，必需依赖缺失才记 gap", () => {
+  const { nm } = realisticTree();
+  const plan = planClosure({ rootModulesDir: nm, platform: "win32", arch: "x64" });
+  assert.equal(plan.gaps.some((g) => g.name === "not-installed-optional"), false);
+  assert.equal(plan.gaps.filter((g) => g.name === "missing-required-thing").length, 1);
+  // 平台分片包在别的平台上缺席，同样不算 gap
+  assert.equal(plan.gaps.some((g) => g.name === "@img/sharp-darwin-arm64"), false);
+});
+
+test("依赖成环也能终止，且每个包只出现一次", () => {
+  const { nm } = realisticTree();
+  const plan = planClosure({ rootModulesDir: nm, platform: "win32", arch: "x64" });
+  const rels = plan.packages.map((p) => p.rel);
+  assert.equal(rels.filter((r) => r === "adm-zip").length, 1);
+  assert.equal(rels.filter((r) => r === "global-agent").length, 1);
+});
+
+test("条目上限命中时截断并如实上报，不静默丢包", () => {
+  const { nm } = realisticTree();
+  const plan = planClosure({ rootModulesDir: nm, platform: "win32", arch: "x64", maxPackages: 3 });
+  assert.equal(plan.truncated, true);
+  assert.equal(plan.packages.length, 3);
+  assert.ok(DEFAULT_MAX_PACKAGES >= 100, "默认上限应当足够容纳真实闭包");
+});
+
+test("入口包不存在：只记一条 gap，不抛异常", () => {
+  const { nm } = makeTree({});
+  const plan = planClosure({ rootModulesDir: nm, entry: "@huggingface/transformers" });
+  assert.deepEqual(plan.packages, []);
+  assert.equal(plan.gaps.length, 1);
+  assert.match(plan.gaps[0].reason, /入口包不存在/);
+});
+
+test("resolvePackageDir：优先取最近的一层，且绝不越出源树", () => {
+  const { nm } = realisticTree();
+  const web = join(nm, "onnxruntime-web");
+  const nested = resolvePackageDir(web, "onnxruntime-common", nm);
+  assert.equal(nested, join(nm, "onnxruntime-web", "node_modules", "onnxruntime-common"), "就近优先");
+  assert.equal(resolvePackageDir(web, "adm-zip", nm), join(nm, "adm-zip"), "回退到顶层");
+  assert.equal(resolvePackageDir(nm, "definitely-not-there", nm), null);
+
+  // root 之外存在同名包时也不能解析到它——否则闭包就不是自包含的。
+  const outside = join(dirname(dirname(nm)), "node_modules", "outside-only-pkg");
+  mkdirSync(outside, { recursive: true });
+  writeFileSync(join(outside, "package.json"), JSON.stringify({ name: "outside-only-pkg", version: "1.0.0" }));
+  assert.equal(resolvePackageDir(nm, "outside-only-pkg", nm), null, "源树之外的包不该被解析进来");
+});
+
+test("matchesPlatform 支持正向与 `!` 反向两种写法，缺省表示不限", () => {
+  assert.equal(matchesPlatform({}, "win32", "x64"), true);
+  assert.equal(matchesPlatform({ os: ["win32"] }, "win32", "x64"), true);
+  assert.equal(matchesPlatform({ os: ["win32"] }, "darwin", "arm64"), false);
+  assert.equal(matchesPlatform({ os: ["!darwin"] }, "win32", "x64"), true);
+  assert.equal(matchesPlatform({ os: ["!darwin"] }, "darwin", "arm64"), false);
+  assert.equal(matchesPlatform({ cpu: ["x64"] }, "win32", "arm64"), false);
+});
+
+test("matchesPlatform：libc 只在确认本机 libc 时才参与判断（拿不到证据就全放行）", () => {
+  const musl = { os: ["linux"], cpu: ["x64"], libc: ["musl"] };
+  const glibc = { os: ["linux"], cpu: ["x64"], libc: ["glibc"] };
+  // 确认了（glibc / musl）就按 libc 排他。
+  assert.equal(matchesPlatform(glibc, "linux", "x64", "glibc"), true);
+  assert.equal(matchesPlatform(musl, "linux", "x64", "glibc"), false);
+  assert.equal(matchesPlatform(musl, "linux", "x64", "musl"), true);
+  // 没确认 = 不过滤：宁多下十几兆，也不赌错方向装出一份跑不起来的运行时。
+  assert.equal(matchesPlatform(musl, "linux", "x64", null), true);
+  assert.equal(matchesPlatform(musl, "linux", "x64"), true);
+  // 不带 libc 字段的包（绝大多数）任何情况下都不因此被排除。
+  assert.equal(matchesPlatform({ os: ["linux"] }, "linux", "x64", "glibc"), true);
+});