@dsh-workbench/module-tools 0.1.14 → 0.1.16

package/src/checks/kit.mjs

@@ -16,6 +16,9 @@
 //      用 `DSH_WB_CORE_CLIENT` 指着下限那份外壳跑（且面差通过）= 验过了，规则②不再报。
 //
 // 判据跟着 `dsh.workbench` 自述清单走；没有 client.js 的包这里没事可查（由 build/契约判据管）。
+//
+// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
@@ -25,6 +28,8 @@ import { discoverModulePackages } from '../discover.mjs';
 const SHELL = '@dsh-workbench/core';
 const KIT_SPECIFIER = '@dsh-workbench/core/client';
 
+export const title = '外壳 kit 面';
+
 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;
@@ -106,78 +111,136 @@ function below(a, b) {
   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;
+// `--only kit` 顺带当"这份外壳的 kit 里有什么"的查询口。
+//
+// 为什么放在这条判据里：它本来就要把外壳真实产物 `client.js` 跑一遍、取出那份 kit ——
+// 这已经是**唯一可信**的取数方式（手抄一份清单就是第二份真相，迟早跟外壳漂）。
+// 造模块的人（尤其 DIY 工坊里那位）要的正是"有哪些成员能用"，于是单跑这一条时把它打出来。
+//
+// 只在单跑时打：外壳把整份 `@dsh-workbench/shared` barrel 摊进了每个桶，所以这份名单
+// 有一百多个名字 —— 聚合跑时它只是噪音，查询时才值钱。
+//
+// 返回的是若干 `notes`（每条一行，交给聚合层加缩进），而不是打印 —— 打印归 check.mjs。
+function faceNotes(asked, shells) {
+  const faceShell = shells[shells.length - 1] ?? shellClientPathOf(process.cwd());
+  if (!asked) {
+    return ['（想知道这份外壳的 kit 里有什么：dsh-wb-module check --only kit）'];
   }
-  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) {
+  if (faceShell === undefined || !existsSync(faceShell)) {
+    return ['（没找到外壳的 client.js，列不出 kit 面：先确认 node_modules 里装着 @dsh-workbench/core）'];
+  }
+  try {
+    const kit = shellKitOf(faceShell);
+    const buckets = Object.keys(kit)
+      .filter((bucket) => typeof kit[bucket] === 'object' && kit[bucket] !== null)
+      .sort();
+    if (buckets.length === 0) {
+      return [`（${faceShell} 里没取出 kit：外壳版本可能太旧）`];
+    }
+    const every = new Map();
+    for (const bucket of buckets) {
+      for (const name of Object.keys(kit[bucket])) every.set(name, (every.get(name) ?? 0) + 1);
+    }
+    const notes = [`这份外壳（${faceShell}）的 kit 面 —— 只能用这些，别自己造：`];
+    for (const bucket of buckets) {
+      const names = Object.keys(kit[bucket]);
+      const only = names.filter((name) => every.get(name) === 1).sort();
+      notes.push(`  ${bucket}(${names.length})：${only.length === 0 ? '（全部来自下面的共用面）' : only.join(', ')}`);
+    }
+    const shared = [...every.entries()].filter(([, count]) => count > 1).map(([name]) => name).sort();
+    notes.push(`  共用面(${shared.length})：每个桶里都有 —— ${shared.join(', ')}`);
+    return notes;
+  } catch (error) {
+    return [`（取不出这份外壳的 kit 面：${error instanceof Error ? error.message : String(error)}）`];
+  }
+}
+
+export async function run() {
+  const problems = [];
+  let inspected = 0;
+  let noArtifact = 0;
+  let noShell = 0;
+  const override = process.env.DSH_WB_CORE_CLIENT;
+  const shells = [];
+  const modulePackages = discoverModulePackages({ root: process.cwd() });
+
+  for (const pkg of modulePackages) {
+    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}: 产物用了这份外壳（${shellClient}）里没有的 ${missing.join('、')} —— ` +
-              `顶层解构不会抛（拿到 undefined），卡片首帧渲染才炸 "Element type is invalid"，` +
-              `而外壳没有错误边界 ⇒ 整块面板会跟着没。要么去掉/换掉这些成员，要么把 peer 下限提到真正需要的那版`,
+            `${name}: 取不出这份外壳的 kit（${shellClient}）—— ${error instanceof Error ? error.message : String(error)}。` +
+              `执行产物是这份判据唯一可信的取数方式；看不懂就别放着不管`,
           );
+          kit = undefined;
+        }
+        if (kit !== undefined) {
+          if (!shells.includes(shellClient)) shells.push(shellClient);
+          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 证明面够用`,
+      );
+    }
   }
 
-  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) {
+    return { status: 'fail', notes: [], problems };
   }
-}
 
-if (problems.length > 0) {
-  console.error(`✖ 外壳 kit 面 ${problems.length} 条不过：`);
-  for (const problem of problems) console.error(`  · ${problem}`);
-  process.exit(1);
-}
+  const asked = process.env.DSH_WB_ONLY === 'kit';
+  const face = faceNotes(asked, shells);
 
-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(' · ')}`);
+  if (inspected === 0) {
+    const why =
+      modulePackages.length === 0
+        ? '没有模块包（没有声明 dsh.workbench 的包）—— 没有产物可对'
+        : `${noArtifact} 个还没建产物（跳过）`;
+    return { status: 'skip', notes: [why, ...face], problems: [] };
+  }
+
+  const notes = [
+    `${inspected} 个模块的产物对过外壳 kit 面`,
+    override === undefined ? '（按各自装的那份外壳）' : `（DSH_WB_CORE_CLIENT=${override}）`,
+  ];
+  if (noArtifact > 0) notes.push(`${noArtifact} 个还没建产物（跳过）`);
+  if (noShell > 0) notes.push(`${noShell} 个没装外壳（跳过面差）`);
+  return { status: 'pass', notes: [...notes, ...face], problems: [] };
+}

package/src/checks/markers.mjs

@@ -1,3 +1,12 @@
+// 公开包里不许出现公司内部标识（内网域名 / 内网 npm 源 / 企业内部名）。
+//
+// 只扫**工作台自己会发出去的**包：声明了 `dsh.workbench` 的模块，或 `@dsh-workbench/*` 名下的。
+// 不能照搬"本 workspace 里所有 access=public 的包" —— 在外壳仓里等价，但把这个工具拿到
+// 别人的 monorepo（例如 pdv2）里跑时，那条会把人家二十几个自家 SDK 包一起判了。
+//
+// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
+
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { discoverPackages } from '../discover.mjs';
@@ -12,6 +21,12 @@ const MARKERS = [
 
 const SKIP = new Set(['node_modules', 'dist', 'coverage', '.git', '.turbo']);
 
+const OWN_SCOPE = '@dsh-workbench/';
+
+const isOurs = (pkg) =>
+  pkg.manifest.dsh?.workbench !== void 0 ||
+  String(pkg.manifest.name ?? '').startsWith(OWN_SCOPE);
+
 function walk(dir, acc = []) {
   for (const entry of readdirSync(dir)) {
     if (SKIP.has(entry)) continue;
@@ -22,40 +37,48 @@ function walk(dir, acc = []) {
   return acc;
 }
 
-// 只扫**工作台自己会发出去的**包：声明了 `dsh.workbench` 的模块，或 `@dsh-workbench/*` 名下的。
-// 不能照搬"本 workspace 里所有 access=public 的包" —— 在外壳仓里等价，但把这个工具拿到
-// 别人的 monorepo（例如 pdv2）里跑时，那条会把人家二十几个自家 SDK 包一起判了。
-const OWN_SCOPE = '@dsh-workbench/';
-const isOurs = (pkg) =>
-  pkg.manifest.dsh?.workbench !== void 0 ||
-  String(pkg.manifest.name ?? '').startsWith(OWN_SCOPE);
+export const title = '公开包无内部标识';
 
-const publicPackages = discoverPackages({ root: process.cwd() }).filter(
-  (pkg) => isOurs(pkg) && pkg.manifest.publishConfig?.access === 'public',
-);
-const problems = [];
-for (const pkg of publicPackages) {
-  for (const file of walk(pkg.dir)) {
-    let text;
-    try {
-      text = readFileSync(file, 'utf8');
-    } catch {
-      continue;
-    }
-    text.split('\n').forEach((line, index) => {
-      for (const [label, pattern] of MARKERS) {
-        if (pattern.test(line)) {
-          problems.push(`${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 命中${label} —— ${line.trim().slice(0, 120)}`);
-        }
+export async function run() {
+  const publicPackages = discoverPackages({ root: process.cwd() }).filter(
+    (pkg) => isOurs(pkg) && pkg.manifest.publishConfig?.access === 'public',
+  );
+  const problems = [];
+  for (const pkg of publicPackages) {
+    for (const file of walk(pkg.dir)) {
+      let text;
+      try {
+        text = readFileSync(file, 'utf8');
+      } catch {
+        continue;
       }
-    });
+      text.split('\n').forEach((line, index) => {
+        for (const [label, pattern] of MARKERS) {
+          if (pattern.test(line)) {
+            problems.push(`${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 命中${label} —— ${line.trim().slice(0, 120)}`);
+          }
+        }
+      });
+    }
   }
-}
 
-if (problems.length > 0) {
-  console.error(`✖ 公开包里不许有公司内部标识：${problems.length} 处`);
-  for (const problem of problems) console.error(`  · ${problem}`);
-  console.error('  （发布前扫一遍：内网源地址、内网域名、企业内部名都不该出现在公网包里）');
-  process.exit(1);
+  if (problems.length > 0) {
+    return {
+      status: 'fail',
+      notes: ['（发布前扫一遍：内网源地址、内网域名、企业内部名都不该出现在公网包里）'],
+      problems,
+    };
+  }
+  if (publicPackages.length === 0) {
+    return {
+      status: 'skip',
+      notes: [`没有要发出去的公开包（${OWN_SCOPE}* 名下、或声明了 dsh.workbench 的，且 access=public）—— 没有包要扫`],
+      problems: [],
+    };
+  }
+  return {
+    status: 'pass',
+    notes: [`${publicPackages.length} 个 access=public 的包扫过`],
+    problems: [],
+  };
 }
-console.log(`✔ 公开包无内部标识：${publicPackages.length} 个 access=public 的包扫过`);

package/src/checks/primitives.mjs

@@ -11,6 +11,9 @@
 //      由 `checks/source.mjs` 拦，这里对着产物再确认一次）。
 //
 // 判据跟着 `dsh.workbench` 自述清单走：没用 dsh 原语的模块直接跳过（0 命中 = 通过）。
+//
+// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
@@ -41,76 +44,98 @@ function sourceFiles(dir, acc = []) {
   return acc;
 }
 
-const problems = [];
-let modulesUsingPrimitives = 0;
-let modulesUsingReactOnly = 0;
+export const title = 'dsh 原语只从模块表拿';
 
-for (const pkg of discoverModulePackages({ root: process.cwd() })) {
-  const name = pkg.manifest.name;
-  const declared = new Set(pkg.manifest.dsh?.client?.external ?? []);
-  const used = new Map();
+export async function run() {
+  const modulePackages = discoverModulePackages({ root: process.cwd() });
+  const problems = [];
+  let modulesUsingPrimitives = 0;
+  let modulesUsingReactOnly = 0;
+  let modulesTouchingSeeds = 0;
 
-  for (const file of sourceFiles(join(pkg.dir, 'src'))) {
-    const text = readFileSync(file, 'utf8');
-    for (const match of text.matchAll(IMPORT)) {
-      const specifier = match[1] ?? match[2];
-      if (specifier === undefined || !SEED.has(specifier)) continue;
-      if (!used.has(specifier)) used.set(specifier, relative(pkg.dir, file));
-    }
-  }
-  if (used.size === 0) continue;
-  const dshSeeds = [...used.keys()].filter((specifier) => BROWSER_SEED_SPECIFIERS.includes(specifier));
-  if (dshSeeds.length === 0) modulesUsingReactOnly += 1;
-  else modulesUsingPrimitives += 1;
+  for (const pkg of modulePackages) {
+    const name = pkg.manifest.name;
+    const declared = new Set(pkg.manifest.dsh?.client?.external ?? []);
+    const used = new Map();
 
-  // ① 只管 **dsh 的那些浏览器包**：react / react-dom 是构建一直默认外部化的（从第一天就是），
-  //    要求每个模块去声明它只会制造噪音。dsh 的包不一样 —— 旧版 module-tools 的默认表里没有它们。
-  const needsDeclaration = new Set(BROWSER_SEED_SPECIFIERS);
-  for (const [specifier, where] of used) {
-    if (needsDeclaration.has(specifier) && !declares(declared, specifier)) {
-      problems.push(
-        `${name}: ${where} 用了 ${specifier}，但 package.json 的 dsh.client.external 里没声明它 —— ` +
-          `漏声明会被构建内联进来（第二份实例）。加上 "${specifier}"`,
-      );
+    for (const file of sourceFiles(join(pkg.dir, 'src'))) {
+      const text = readFileSync(file, 'utf8');
+      for (const match of text.matchAll(IMPORT)) {
+        const specifier = match[1] ?? match[2];
+        if (specifier === undefined || !SEED.has(specifier)) continue;
+        if (!used.has(specifier)) used.set(specifier, relative(pkg.dir, file));
+      }
     }
-  }
+    if (used.size === 0) continue;
+    modulesTouchingSeeds += 1;
+    const dshSeeds = [...used.keys()].filter((specifier) => BROWSER_SEED_SPECIFIERS.includes(specifier));
+    if (dshSeeds.length === 0) modulesUsingReactOnly += 1;
+    else modulesUsingPrimitives += 1;
 
-  const client = join(pkg.dir, 'client.js');
-  if (!existsSync(client)) {
-    problems.push(`${name}: 源码用了 dsh 的种子词，但没有 client.js —— 先跑 dsh-wb-module build`);
-  } else {
-    const text = readFileSync(client, 'utf8');
+    // ① 只管 **dsh 的那些浏览器包**：react / react-dom 是构建一直默认外部化的（从第一天就是），
+    //    要求每个模块去声明它只会制造噪音。dsh 的包不一样 —— 旧版 module-tools 的默认表里没有它们。
+    const needsDeclaration = new Set(BROWSER_SEED_SPECIFIERS);
     for (const [specifier, where] of used) {
-      if (!text.includes(`require(${JSON.stringify(specifier)})`)) {
+      if (needsDeclaration.has(specifier) && !declares(declared, specifier)) {
         problems.push(
-          `${name}: ${where} 用了 ${specifier}，但产物 client.js 里没有 require("${specifier}") —— ` +
-            `它被**内联**进产物了（第二份实例）。检查 dsh.client.external 与构建用的 module-tools 版本`,
+          `${name}: ${where} 用了 ${specifier}，但 package.json 的 dsh.client.external 里没声明它 —— ` +
+            `漏声明会被构建内联进来（第二份实例）。加上 "${specifier}"`,
         );
       }
     }
-  }
 
-  const host = join(pkg.dir, 'dist', 'host.js');
-  if (existsSync(host)) {
-    const text = readFileSync(host, 'utf8');
-    for (const specifier of BROWSER_SEED_SPECIFIERS) {
-      if (text.includes(`"${specifier}"`)) {
-        problems.push(
-          `${name}: 宿主产物 dist/host.js 里出现了 ${specifier} —— 那些包只在浏览器侧存在，` +
-            `宿主侧引用它就是起来那一刻炸`,
-        );
+    const client = join(pkg.dir, 'client.js');
+    if (!existsSync(client)) {
+      problems.push(`${name}: 源码用了 dsh 的种子词，但没有 client.js —— 先跑 dsh-wb-module build`);
+    } else {
+      const text = readFileSync(client, 'utf8');
+      for (const [specifier, where] of used) {
+        if (!text.includes(`require(${JSON.stringify(specifier)})`)) {
+          problems.push(
+            `${name}: ${where} 用了 ${specifier}，但产物 client.js 里没有 require("${specifier}") —— ` +
+              `它被**内联**进产物了（第二份实例）。检查 dsh.client.external 与构建用的 module-tools 版本`,
+          );
+        }
+      }
+    }
+
+    const host = join(pkg.dir, 'dist', 'host.js');
+    if (existsSync(host)) {
+      const text = readFileSync(host, 'utf8');
+      for (const specifier of BROWSER_SEED_SPECIFIERS) {
+        if (text.includes(`"${specifier}"`)) {
+          problems.push(
+            `${name}: 宿主产物 dist/host.js 里出现了 ${specifier} —— 那些包只在浏览器侧存在，` +
+              `宿主侧引用它就是起来那一刻炸`,
+          );
+        }
       }
     }
   }
-}
 
-if (problems.length > 0) {
-  console.error(`✖ dsh 原语 ${problems.length} 条不过：`);
-  for (const problem of problems) console.error(`  · ${problem}`);
-  process.exit(1);
+  if (problems.length > 0) {
+    return { status: 'fail', notes: [], problems };
+  }
+  if (modulePackages.length === 0) {
+    return {
+      status: 'skip',
+      notes: ['没有模块包（没有声明 dsh.workbench 的包）—— 没有 dsh 原语的声明与产物可对'],
+      problems: [],
+    };
+  }
+  if (modulesTouchingSeeds === 0) {
+    return {
+      status: 'skip',
+      notes: ['没有模块用到平台种子词（react / react-dom / dsh 的浏览器包）—— 没有可对照的声明与产物'],
+      problems: [],
+    };
+  }
+  return {
+    status: 'pass',
+    notes: [
+      `${modulesUsingPrimitives} 个模块在用 dsh 的包（都声明了 external、产物里都是 ` +
+        `require、宿主产物里没有它们）· 另有 ${modulesUsingReactOnly} 个模块只用到 react/react-dom`,
+    ],
+    problems: [],
+  };
 }
-
-console.log(
-  `✔ dsh 原语通过：${modulesUsingPrimitives} 个模块在用 dsh 的包（都声明了 external、产物里都是 ` +
-    `require、宿主产物里没有它们）· 另有 ${modulesUsingReactOnly} 个模块只用到 react/react-dom`,
-);