@dsh-workbench/module-tools 0.1.9 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
   "license": "MIT",
   "type": "module",

package/src/check.mjs

@@ -4,6 +4,7 @@ const CHECKS = {
   bundles: { title: '模块产物边界', load: () => import('./checks/bundles.mjs') },
   source: { title: '模块源码边界', load: () => import('./checks/source.mjs') },
   primitives: { title: 'dsh 原语只从模块表拿', load: () => import('./checks/primitives.mjs') },
+  kit: { title: '外壳 kit 面', load: () => import('./checks/kit.mjs') },
   cards: { title: '卡片渲染', load: () => import('./checks/cards.mjs') },
   standalone: { title: '独立构建', load: () => import('./checks/standalone.mjs') },
   markers: { title: '公开包无内部标识', load: () => import('./checks/markers.mjs') },

package/src/checks/kit.mjs

@@ -0,0 +1,183 @@
+// 模块产物从外壳 kit 里取的成员，必须真的在**它承诺给用户的那份外壳**里存在。
+//
+// 起因（2026-10-10 现场）：`module-cmdb@0.1.7` 的产物用了 0.1.8 才有的
+// `kit.components.StateBlock` / `Note` / `Activity*`，而 peer 写的是 `^0.1.4`。
+// 装到旧外壳上：顶层解构不抛（`undefined` 也照样解出来），卡片**首帧渲染**时才炸
+// `Element type is invalid`；外壳里没有错误边界 ⇒ 整块面板被 React 卸掉。
+// 维护者本机复现不了，因为本机 profile 把外壳 `link:` 到本仓（永远 HEAD）。
+//
+// 两条规则：
+//   ① **面差**：产物 bind 的 kit 成员 ⊆ 指定外壳 `client.js` 里那份 kit。
+//      默认用模块包自己装的那份外壳（devDependency）；`DSH_WB_CORE_CLIENT=<路径>`
+//      可以指定别的一份 —— 用它验"对 peer 下限那份外壳会不会红"（发布前该跑一遍）。
+//   ② **下限自洽**：`peerDependencies['@dsh-workbench/core']` 的下限不许低于
+//      `devDependencies` 的下限。你对用户承诺的版本比你自己构建/测试用的还旧时，
+//      产物的面到底够不够，没人验过 —— 这一条就是把"没人验过"变成红灯。
+//      用 `DSH_WB_CORE_CLIENT` 指着下限那份外壳跑（且面差通过）= 验过了，规则②不再报。
+//
+// 判据跟着 `dsh.workbench` 自述清单走；没有 client.js 的包这里没事可查（由 build/契约判据管）。
+
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { discoverModulePackages } from '../discover.mjs';
+
+const SHELL = '@dsh-workbench/core';
+const KIT_SPECIFIER = '@dsh-workbench/core/client';
+
+function kitUsageOf(text) {
+  const bindings = new Set();
+  const BINDING = /(?:var|const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:__toESM\(\s*)?require\(\s*["']@dsh-workbench\/core\/client["']\s*\)/g;
+  for (const match of text.matchAll(BINDING)) bindings.add(match[1]);
+  if (bindings.size === 0) {
+    // 认不出绑定名时不静默放过：退化成"全文里任何 `<id>.kit.` 的 id"。
+    for (const match of text.matchAll(/([A-Za-z_$][\w$]*)\.kit\./g)) bindings.add(match[1]);
+  }
+
+  const used = new Map();
+  const add = (bucket, member) => {
+    if (bucket === undefined || member === undefined || member === '') return;
+    if (!used.has(bucket)) used.set(bucket, new Set());
+    used.get(bucket).add(member);
+  };
+  for (const id of bindings) {
+    const dotted = new RegExp(`\\b${id}\\.kit\\.([a-z]+)\\.([A-Za-z0-9_$]+)`, 'g');
+    for (const match of text.matchAll(dotted)) add(match[1], match[2]);
+    const destructured = new RegExp(`\\{([^{}]*)\\}\\s*=\\s*${id}\\.kit\\.([a-z]+)\\s*;`, 'g');
+    for (const match of text.matchAll(destructured)) {
+      for (const raw of match[1].split(',')) {
+        const name = raw.split(':')[0].trim();
+        if (name !== '') add(match[2], name);
+      }
+    }
+  }
+  return used;
+}
+
+function shellKitOf(clientPath) {
+  const stub = () => null;
+  const seed = new Proxy(
+    { default: stub },
+    { get: (target, key) => (key in target ? target[key] : stub) },
+  );
+  // react 得给一个**能 extends 的类**：外壳自己那段 `class CardBoundary extends Component`
+  // 在工厂体里就跑（错误边界只能这么写），换成箭头函数会当场 "not a constructor"。
+  const react = new Proxy(
+    { default: stub, Component: class {} },
+    { get: (target, key) => (key in target ? target[key] : stub) },
+  );
+  let exports;
+  const load = (registration) => {
+    exports = registration.factory((specifier) => {
+      if (specifier === 'react' || specifier === 'react/jsx-runtime' || specifier === 'react-dom') return react;
+      if (specifier.startsWith('@deepseek-ai/')) return seed;
+      if (specifier === SHELL) return exports;
+      throw new Error(`外壳产物里出现了一个不认识的 require("${specifier}")`);
+    });
+  };
+  const window = { __ModuleLoader__: { load } };
+  // eslint-disable-next-line no-new-func -- 要的就是"按浏览器加载器那样把这份产物跑一遍"，静态解析会骗人
+  new Function('window', readFileSync(clientPath, 'utf8'))(window);
+  return exports?.kit ?? {};
+}
+
+function shellClientPathOf(pkgDir) {
+  const override = process.env.DSH_WB_CORE_CLIENT;
+  if (override !== undefined && override.trim() !== '') return override.trim();
+  try {
+    const require = createRequire(join(pkgDir, 'package.json'));
+    return join(dirname(require.resolve(`${SHELL}/package.json`)), 'client.js');
+  } catch {
+    return undefined;
+  }
+}
+
+function floorOf(range) {
+  if (typeof range !== 'string') return undefined;
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(range);
+  if (match === null) return undefined;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function below(a, b) {
+  for (let at = 0; at < 3; at += 1) {
+    if (a[at] !== b[at]) return a[at] < b[at];
+  }
+  return false;
+}
+
+const problems = [];
+let inspected = 0;
+let noArtifact = 0;
+let noShell = 0;
+const override = process.env.DSH_WB_CORE_CLIENT;
+
+for (const pkg of discoverModulePackages({ root: process.cwd() })) {
+  const name = pkg.manifest.name;
+  const client = join(pkg.dir, 'client.js');
+  if (!existsSync(client)) {
+    noArtifact += 1;
+    continue;
+  }
+  inspected += 1;
+  const text = readFileSync(client, 'utf8');
+  const used = kitUsageOf(text);
+  const uses = used.size > 0 ? text.includes(KIT_SPECIFIER) : false;
+
+  if (uses) {
+    const shellClient = shellClientPathOf(pkg.dir);
+    if (shellClient === undefined || !existsSync(shellClient)) {
+      noShell += 1;
+    } else {
+      let kit;
+      try {
+        kit = shellKitOf(shellClient);
+      } catch (error) {
+        problems.push(
+          `${name}: 取不出这份外壳的 kit（${shellClient}）—— ${error instanceof Error ? error.message : String(error)}。` +
+            `执行产物是这份判据唯一可信的取数方式；看不懂就别放着不管`,
+        );
+        kit = undefined;
+      }
+      if (kit !== undefined) {
+        const missing = [];
+        for (const [bucket, members] of used) {
+          for (const member of [...members].sort()) {
+            if (kit[bucket]?.[member] === undefined) missing.push(`kit.${bucket}.${member}`);
+          }
+        }
+        if (missing.length > 0) {
+          problems.push(
+            `${name}: 产物用了这份外壳（${shellClient}）里没有的 ${missing.join('、')} —— ` +
+              `顶层解构不会抛（拿到 undefined），卡片首帧渲染才炸 "Element type is invalid"，` +
+              `而外壳没有错误边界 ⇒ 整块面板会跟着没。要么去掉/换掉这些成员，要么把 peer 下限提到真正需要的那版`,
+          );
+        }
+      }
+    }
+  }
+
+  const peerFloor = floorOf(pkg.manifest.peerDependencies?.[SHELL]);
+  const devFloor = floorOf(pkg.manifest.devDependencies?.[SHELL]);
+  if (peerFloor !== undefined && devFloor !== undefined && below(peerFloor, devFloor) && override === undefined) {
+    problems.push(
+      `${name}: peer 下限 ${pkg.manifest.peerDependencies[SHELL]} 比 devDependency ${pkg.manifest.devDependencies[SHELL]} 还旧 —— ` +
+        `你对用户承诺的那版外壳，产物从没对着验过。把 peer 下限提到与 devDependency 同档；` +
+        `确实要支持更旧的外壳，就用 DSH_WB_CORE_CLIENT=<那版外壳的 client.js> 跑一遍 check --only kit 证明面够用`,
+    );
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✖ 外壳 kit 面 ${problems.length} 条不过：`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  process.exit(1);
+}
+
+const notes = [
+  `${inspected} 个模块的产物对过外壳 kit 面`,
+  override === undefined ? '（按各自装的那份外壳）' : `（DSH_WB_CORE_CLIENT=${override}）`,
+];
+if (noArtifact > 0) notes.push(`${noArtifact} 个还没建产物（跳过）`);
+if (noShell > 0) notes.push(`${noShell} 个没装外壳（跳过面差）`);
+console.log(`✔ 外壳 kit 面通过：${notes.join(' · ')}`);