@dsh-workbench/module-tools 0.3.2 → 0.3.4

package/src/checks/lint.mjs

@@ -0,0 +1,351 @@
+// 模块包的**语法卫生判据**（`check` 的第十三条）：把 eslint 跑在**模块自己的方言**上。
+//
+// 为什么模块包需要这一条：另外十二条判据里，结构那一半归 arch-guard（`./arch.mjs`），
+// 而"单文件语法卫生"那一半一条都没有 —— `as any` / `console` 残留 / `debugger` / 内联颜色 /
+// 手写 `!important` / 渲染期写 ref / 漏依赖，这些都不改变文件形状，结构判据永远看不见。
+// arch-guard 自己的 README 把这一半明确委派给了 eslint。
+//
+// 判据的口径（三条，与第十二条 `arch` 逐条对齐 —— 同一套承诺）：
+//   ① **只跑带 `eslint.config.mjs` 的模块**：没有那份文件就 `skip`（不适用），不是红。
+//      工坊里已经造好的模块（以及别的仓里已经发出去的模块）不会被这次升级炸掉 —— 补两行就上车。
+//   ② **判据不自己编规则**：它 import 模块那份配置，**逐块核对整份方言**（`../lint.mjs` 的
+//      `DIALECT_BLOCKS` 八块：名字 / `files` / `rules` 一处不一致就红；全局 ignores 按 `DIALECT_IGNORES`
+//      的**超集**比）再跑；规则与阈值都在 `../lint.mjs` 那一处。
+//      **残余**：模块自己 import 方言再照抄整份，判据分不出来 —— 这条的目标是"抬高门槛 +
+//      让改动必须明着写"，不是防住蓄意伪造（详见 `../lint.mjs` 文件头那段）。
+//   ③ **只把 `error` 算红**：`warn` 照外壳口径计数、不挡门禁（`eslint .` 也只对 error 退 1）；
+//      单跑（`--only lint`）时把 warn 逐条列出来（与 `--only kit` 列 kit 成员同一个约定）。
+//
+// ESLint 的**唯一构造处**也在这里（`lintPackage`）：判据与 `dsh-wb-module lint [--fix]` 共用它，
+// 于是"门禁跑的那份"与"命令跑的那份"在形状上不可能漂。**判据永远不动手改文件**：只有
+// `fix: true` 才会写回，而 `fix` 只从命令那条路进来（自检有负例钉着这一点）。
+//
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
+
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ESLint } from 'eslint';
+import { discoverModulePackages } from '../discover.mjs';
+import { DIALECT_BLOCKS, DIALECT_IGNORES, FINGERPRINT, dialectShapeOf, isGlobalIgnoresBlock } from '../lint.mjs';
+
+export const title = '模块代码卫生（eslint）';
+
+/** 上车标记：模块根有这份文件才被这条判据管（opt-in，与第十二条同一形状）。 */
+export const CONFIG_FILE = 'eslint.config.mjs';
+
+// 聚合跑时逐条列出的上限：一条模块可能带几百条 error，门禁那一屏不该被它刷掉、也不该只剩
+// 最后几条 —— 截断 + 一句"还有 N 条"（单跑 `--only lint` 时不截断：那时你就是来看全的）。
+const MAX_PROBLEMS = 40;
+
+// "怎么上车"那句话只写一遍：skip 的提示与方言对不上的人都该看见它。
+// 不提本仓内部路径（`src/lint.mjs` 那句）：这份提示会随 skill 文档发给用户，用户手上只有
+// 装出来的那个包。方言与阈值随 `@dsh-workbench/module-tools` 同代。
+const HOW_TO_JOIN =
+  `在模块包里放一份 ${CONFIG_FILE}，内容两行就够（与模板里那份逐字一致）：\n` +
+  `    import { moduleLint } from '@dsh-workbench/module-tools/lint';\n` +
+  '    export default moduleLint({ rootDir: import.meta.dirname });\n' +
+  '  `rootDir` 是给 typescript-eslint 钉 tsconfigRootDir 的（一个进程里同时有多份 eslint 配置时必需；\n' +
+  '  模块自己单独跑一份配置时可以省）。规则与阈值只有这一份（随 @dsh-workbench/module-tools 同代）；\n' +
+  '  要开口子就从 moduleLint({ ignores, rules, rootDir }) 的参数进。';
+
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+
+// 一行一条：把消息压成单行再截断。react-hooks 那几条的 message 里带**整段代码框**（多行），
+// 原样倒出来会把"逐条"变成几十行、`·` 前缀也只挂在第一行；前面那句结论（"Cannot call impure
+// function during render"）才是要看的东西，所以压平 + 截断。
+const TEXT_LIMIT = 200;
+function oneLine(text) {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > TEXT_LIMIT ? `${flat.slice(0, TEXT_LIMIT)}…` : flat;
+}
+
+/** 一行人话：`名字: 文件:行:列 规则 —— 一句话`（规则缺了就是解析错误 —— 那也是要立刻看见的）。 */
+function lineOf(name, dir, result, message) {
+  const line = message.line ?? 1;
+  const column = message.column ?? 1;
+  const where = `${name}: ${relative(dir, result.filePath)}:${String(line)}:${String(column)}`;
+  const rule = message.ruleId ?? '解析错误';
+  return `${where} ${rule} —— ${oneLine(message.message)}`;
+}
+
+/** 方言那几块的名字（基础块 + 四块 `dsh-wb/module-lint*`）+ 全局 ignores 那一块 —— 认"有没有方言痕迹"。 */
+const DIALECT_NAMES = new Set(DIALECT_BLOCKS.map((block) => block.name));
+
+function isDialectNamed(block) {
+  return (
+    block !== null &&
+    typeof block === 'object' &&
+    typeof block.name === 'string' &&
+    (DIALECT_NAMES.has(block.name) || block.name.startsWith(`${FINGERPRINT}/`))
+  );
+}
+
+/** 配置里有没有一点方言的痕迹（全局 ignores 那一块 / 方言那几块）—— 用来区分"没上车"与"改坏了"。 */
+function hasDialectTrace(config) {
+  return config.some((block) => isGlobalIgnoresBlock(block) || isDialectNamed(block));
+}
+
+/** 配置里所有全局 ignores 块的 glob 并集（方言那一块 + 模块自己追加的，可能有不止一块）。 */
+function globalIgnoresOf(config) {
+  const globs = new Set();
+  for (const block of config) {
+    if (block !== null && typeof block === 'object' && isGlobalIgnoresBlock(block)) {
+      for (const glob of block.ignores) globs.add(glob);
+    }
+  }
+  return globs;
+}
+
+/** 两份 rules 差在哪：少了哪些 / 多了哪些 / 哪些值被改了（形状已键排序，逐键比即可）。 */
+function rulesDivergenceOf(expected, actual) {
+  const gone = Object.keys(expected).filter((rule) => !(rule in actual));
+  const extra = Object.keys(actual).filter((rule) => !(rule in expected));
+  const changed = Object.keys(expected).filter(
+    (rule) => rule in actual && JSON.stringify(expected[rule]) !== JSON.stringify(actual[rule]),
+  );
+  const parts = [];
+  if (gone.length > 0) parts.push(`少了 ${gone.join('、')}`);
+  if (extra.length > 0) parts.push(`多了 ${extra.join('、')}`);
+  if (changed.length > 0) parts.push(`改了 ${changed.join('、')}`);
+  return parts.join('；');
+}
+
+/**
+ * **逐块比**方言（这一期 hardening 的核心）：`moduleLint()` 产出的**整份方言**，模块那份配置里
+ * 必须一块不少、且名字 / `files` / `rules` 逐项一致；全局 ignores 那一块按**超集**比（多忽略
+ * 可以、少忽略点名）。
+ *
+ * 为什么不能只比"有没有那个名字"：2026-10-19 verifier 造出
+ * `export default [{ name: 'dsh-wb/module-lint', rules: {} }]` —— 只比名字时它给 ✔ 0 error，
+ * 而"方言只有一份、下限不能被悄悄删"正是这条判据的立论。同名多块也判红：扁平配置里**只有
+ * 最后一块算数**，"留一块好的、再追加一块掏空的"同样是把下限删掉。
+ *
+ * 为什么后来把基础块也收进来：只比 `dsh-wb/module-lint*` 那 4 块时，verifier 量到的残余有**两种
+ * 筛法**：`moduleLint().filter((b) => b.name !== undefined)` 筛掉的是**唯一没有名字**的那块（全局
+ * ignores 不能带 `name`）；基础块（`@eslint/js/recommended` 与三块 `typescript-eslint/*`，**都带
+ * 名字**）则要**显式点名**（`(b) => b.name !== '@eslint/js/recommended'` 这种）才筛得掉 ——
+ * 两种都是"下限被悄悄删"。
+ */
+function dialectDivergences(config) {
+  const blocks = config.filter((block) => block !== null && typeof block === 'object');
+  const problems = [];
+
+  const missingGlobs = DIALECT_IGNORES.filter((glob) => !globalIgnoresOf(config).has(glob));
+  if (missingGlobs.length > 0) problems.push(`少了全局 ignores（缺 ${missingGlobs.join('、')}）`);
+
+  for (const expected of DIALECT_BLOCKS) {
+    const same = blocks.filter((block) => block.name === expected.name);
+    if (same.length === 0) {
+      problems.push(`少了「${expected.name}」那一块`);
+      continue;
+    }
+    if (same.length > 1) {
+      problems.push(`「${expected.name}」出现了 ${String(same.length)} 次（同名块只有最后一块算数）`);
+      continue;
+    }
+    const actual = dialectShapeOf(same[0]);
+    if (JSON.stringify(actual.files) !== JSON.stringify(expected.files)) {
+      problems.push(`改了「${expected.name}」那一块的 files`);
+      continue;
+    }
+    const rules = rulesDivergenceOf(expected.rules, actual.rules);
+    if (rules !== '') problems.push(`改了「${expected.name}」那一块的 rules（${rules}）`);
+  }
+  return problems;
+}
+
+async function loadConfig(pkg) {
+  const file = join(pkg.dir, CONFIG_FILE);
+  let module_;
+  try {
+    module_ = await import(pathToFileURL(file).href);
+  } catch (error) {
+    return {
+      error:
+        `${pkg.manifest.name}: ${CONFIG_FILE} 跑不起来 —— ${messageOf(error)}` +
+        '（先确认这份配置能 import、没有语法错，再确认它 import 的东西在工坊里解析得到）',
+    };
+  }
+
+  const config = module_.default;
+  if (!Array.isArray(config)) {
+    return {
+      error:
+        `${pkg.manifest.name}: ${CONFIG_FILE} 的默认导出不是 flat config 数组 —— ` +
+        `这份配置不是 moduleLint() 来的。\n  ${HOW_TO_JOIN}`,
+    };
+  }
+  if (!hasDialectTrace(config)) {
+    return {
+      error:
+        `${pkg.manifest.name}: ${CONFIG_FILE} 里没有 ${FINGERPRINT} 那几块 —— ` +
+        `这份配置不是 moduleLint() 来的（要加规则请展开 moduleLint() 再追加一块，别手写一份自己的方言）。` +
+        `\n  ${HOW_TO_JOIN}`,
+    };
+  }
+  const diverged = dialectDivergences(config);
+  if (diverged.length > 0) {
+    return {
+      error:
+        `${pkg.manifest.name}: ${CONFIG_FILE} 里的方言与 moduleLint() 产出的不一致 —— ` +
+        `${diverged.join('；')}。要开口子请走 moduleLint({ rules, ignores })（rules 落在 ` +
+        `${FINGERPRINT}/overrides 那块、ignores 加在全局 ignores 那块）或展开 moduleLint() ` +
+        '再追加自己的一块，别改方言那几块。',
+    };
+  }
+  return { config };
+}
+
+/**
+ * 跑一个模块包的 lint。**ESLint 只在这里构造**（判据与 `dsh-wb-module lint` 共用）。
+ *
+ * @param {{ dir: string, manifest: { name: string } }} pkg
+ * @param {{ fix?: boolean }} [options] `fix` 会写回文件；判据那条路永远不传它。
+ * @returns {Promise<object>} `{ name, files, errors, warnings, problems, warnLines, fixed }`
+ *   或 `{ name, error }`（配置跑不起来 / 不是 moduleLint 来的）
+ */
+export async function lintPackage(pkg, { fix = false } = {}) {
+  const name = pkg.manifest.name;
+  const loaded = await loadConfig(pkg);
+  if (loaded.error !== undefined) return { name, error: loaded.error };
+
+  const runOnce = (fixMode) =>
+    new ESLint({
+      cwd: pkg.dir,
+      // 不读目录里那份配置，用**这里 import 进来的**：指纹已经核过，`files` 相对 cwd 解析
+      // （Lead 探针实测这条路可行）。这样"判据跑的那份"与"模块文件里写的那份"是同一个对象。
+      overrideConfigFile: true,
+      // 头一块**只**补 `tsconfigRootDir`：typescript-eslint 的 parser 拿不到它时会去"猜"，
+      // 猜法是看调用 `tseslint.configs` 的那段栈 —— 一次进程里跑两个模块包就累积出两个候选
+      // 根目录，于是**第二个包**每个文件都报 "No tsconfigRootDir was set, and multiple
+      // candidate TSConfigRootDirs are present"（实测：两个模板一起跑，mini 全红）。
+      // 判据知道自己在跑哪个包，就把这件事钉死；模块自己写的那份配置若声明了
+      // parserOptions，它在后面，仍然覆盖这一条。
+      overrideConfig: [
+        {
+          // 不写 `files`：typescript-eslint 的 base 块不带 `files`，于是**所有**文件（含
+          // `scripts/*.mjs` 与两份配置）都走 TS parser —— 只给 `*.ts` 补根目录，`.mjs` 那三个
+          // 照样报同一个错（实测）。
+          languageOptions: { parserOptions: { tsconfigRootDir: pkg.dir } },
+        },
+        ...loaded.config,
+      ],
+      errorOnUnmatchedPattern: false,
+      fix: fixMode,
+    }).lintFiles(['.']);
+
+  // `--fix` 的报数要"修了 N 条"：fix 那一趟返回的结果是**修完之后**的（实测：`output` 有值、
+  // messages 只剩修不动的），所以前后各跑一趟普通轮，差值才是真修掉的那批。
+  //
+  // 整段包 try：一份"长得像方言但少了 plugin / 塞了坏东西"的配置会让 ESLint 在**建配置**那一步
+  // 抛（`Could not find plugin …`）—— 那是"跑不起来"这一类，要落成一行人话，不是把判据整条崩掉。
+  let results;
+  let before;
+  try {
+    before = fix ? await runOnce(false) : undefined;
+    if (fix) {
+      const fixed = await runOnce(true);
+      await ESLint.outputFixes(fixed);
+    }
+    results = await runOnce(false);
+  } catch (error) {
+    return { name, error: `${name}: ${CONFIG_FILE} 跑不起来 —— ${messageOf(error)}` };
+  }
+
+  const problems = [];
+  const warnLines = [];
+  let files = 0;
+  let errors = 0;
+  let warnings = 0;
+  for (const result of results) {
+    files += 1;
+    errors += result.errorCount;
+    warnings += result.warningCount;
+    for (const message of result.messages) {
+      if (message.severity === 2) problems.push(lineOf(name, pkg.dir, result, message));
+      else warnLines.push(lineOf(name, pkg.dir, result, message));
+    }
+  }
+
+  const totalOf = (list) => list.reduce((sum, result) => sum + result.errorCount + result.warningCount, 0);
+  return {
+    name,
+    files,
+    errors,
+    warnings,
+    problems,
+    warnLines,
+    fixed: before === undefined ? 0 : totalOf(before) - (errors + warnings),
+  };
+}
+
+export async function run() {
+  const modulePackages = discoverModulePackages({ root: process.cwd() });
+  if (modulePackages.length === 0) {
+    return {
+      status: 'skip',
+      notes: ['没有模块包（没有声明 dsh.workbench 的包）—— 没有源码要判卫生'],
+      problems: [],
+    };
+  }
+
+  const declared = modulePackages.filter((pkg) => existsSync(join(pkg.dir, CONFIG_FILE)));
+  if (declared.length === 0) {
+    return {
+      status: 'skip',
+      notes: [
+        `${modulePackages.length} 个模块包都没有 ${CONFIG_FILE} —— 没有这份配置就没有规则可跑（不是"没问题"）。` +
+          `\n  ${HOW_TO_JOIN}`,
+      ],
+      problems: [],
+    };
+  }
+
+  const problems = [];
+  const warnLines = [];
+  let files = 0;
+  let errors = 0;
+  let warnings = 0;
+
+  for (const pkg of declared) {
+    const result = await lintPackage(pkg);
+    if (result.error !== undefined) {
+      problems.push(result.error);
+      continue;
+    }
+    files += result.files;
+    errors += result.errors;
+    warnings += result.warnings;
+    problems.push(...result.problems);
+    warnLines.push(...result.warnLines);
+  }
+
+  if (problems.length > 0) {
+    // 单跑时列全（你就是来看全的）；聚合跑截断，把"还有 N 条"说清楚。
+    const only = process.env.DSH_WB_ONLY === 'lint';
+    const shown = only ? problems : problems.slice(0, MAX_PROBLEMS);
+    const notes = [
+      '红了怎么修：先看位置与规则名，再决定"改代码"还是"就地 eslint-disable-next-line"；' +
+        '要整体放开就展开 moduleLint() 再追加一块（别把方言换掉）。',
+    ];
+    if (shown.length < problems.length) {
+      notes.push(`还有 ${problems.length - shown.length} 条没列出来（跑 dsh-wb-module check --only lint 看全）。`);
+    }
+    return { status: 'fail', notes, problems: shown };
+  }
+
+  const notes = [
+    `${declared.length}/${modulePackages.length} 个模块包带 ${CONFIG_FILE} · ${files} 个文件 · ` +
+      `${errors} error · ${warnings} warn`,
+  ];
+  if (warnLines.length > 0 && process.env.DSH_WB_ONLY === 'lint') {
+    notes.push('warn（不挡门禁）：');
+    for (const line of warnLines) notes.push(`  ${line}`);
+  }
+  if (declared.length < modulePackages.length) {
+    notes.push(`其余 ${modulePackages.length - declared.length} 个没有 ${CONFIG_FILE}（不适用）`);
+  }
+  return { status: 'pass', notes, problems: [] };
+}

package/src/checks/primitives.mjs

@@ -12,16 +12,46 @@
 //
 // 判据跟着 `dsh.workbench` 自述清单走：没用 dsh 原语的模块直接跳过（0 命中 = 通过）。
 //
+// ── 查询口：`check --only primitives` 单跑时顺带当"dsh 原语里有什么"的取数处 ──────────────
+//
+// 与 `--only kit` 同一个惯例（`kit.mjs` 的 faceNotes）：单跑时把**能用的东西**列出来，
+// 聚合跑时只留一句提示。这份清单的真相只有一处 —— 装机包里那份类型面
+// （`lib/types/**/*.d.ts`；源码树不随包发布），详见 `../primitives-surface.mjs` 与
+// `.scratch/dsh-primitives-face/spec.md`。
+//
+// 为什么放在这条判据里：它本来就要按模块逐个解析种子词的声明与产物，而"有哪些名字可用"正是
+// 造模块的人（尤其 DIY 工坊里那位）要的那件事；单开一个顶层命令要多一处分发、一处用法文案、
+// 一处文档，而这里的机制（`DSH_WB_ONLY`）已经在了。
+//
 // 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
-// 打印与退出码归 `../check.mjs` 那一层。
+// 打印与退出码归 `../check.mjs` 那一层。`--json` 时聚合层打 `payload`（见 `check.mjs` 头注释）。
 
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
+import { flagValue, flagsOf } from '../check-flags.mjs';
 import { discoverModulePackages } from '../discover.mjs';
+import {
+  PRIMITIVES_SPECIFIER,
+  installedPrimitives,
+  pinnedPrimitivesVersion,
+  surfaceOf,
+} from '../primitives-surface.mjs';
 import { BROWSER_SEED_SPECIFIERS, SEED_SPECIFIERS } from '../seed.mjs';
+import { shellClientPathOf, shellKitOf } from './shell-artifact.mjs';
 
 const IMPORT = /from\s*'([^']+)'|import\s*\(?\s*'([^']+)'/g;
 const SEED = new Set(SEED_SPECIFIERS);
+const SHELL = '@dsh-workbench/core';
+
+/** 摘要档每个桶最多列几个名字；`--all` 去掉截断。 */
+const SUMMARY_PER_BUCKET = 12;
+const BUCKETS = [
+  ['components', 'components'],
+  ['icons', 'icons'],
+  ['hooks', 'hooks'],
+  ['lib', 'lib'],
+];
 
 /** 短名写法（`ui-primitives`）也算声明过 —— 老包里有这种写法，不该因为写法短被判红。 */
 function declares(declared, specifier) {
@@ -46,8 +76,203 @@ function sourceFiles(dir, acc = []) {
 
 export const title = 'dsh 原语只从模块表拿';
 
+/** 从 `from` 找到一份能解析到的原语包：先看模块包自己装的，再看当前 cwd。 */
+function primitivesFrom(modulePackages) {
+  for (const pkg of modulePackages) {
+    const found = installedPrimitives(pkg.dir);
+    if (found !== undefined) return { ...found, from: pkg.dir };
+  }
+  const here = installedPrimitives(process.cwd());
+  return here === undefined ? undefined : { ...here, from: process.cwd() };
+}
+
+/** 外壳 manifest 的路径（那份 `devDependencies` 里钉着原语版本）。 */
+function shellManifestOf(from) {
+  try {
+    return createRequire(join(from, 'package.json')).resolve(`${SHELL}/package.json`);
+  } catch {
+    return undefined;
+  }
+}
+
+/** 外壳 kit 的成员表：`名字 → 桶`（取不到就空表 —— 求交只是锦上添花，不该把查询口弄崩）。 */
+function kitMembersOf(from) {
+  const client = shellClientPathOf(from);
+  if (client === undefined || !existsSync(client)) return new Map();
+  try {
+    const kit = shellKitOf(client);
+    const members = new Map();
+    for (const [bucket, value] of Object.entries(kit)) {
+      if (typeof value !== 'object' || value === null) continue;
+      for (const name of Object.keys(value)) if (!members.has(name)) members.set(name, bucket);
+    }
+    return members;
+  } catch {
+    return new Map();
+  }
+}
+
+function truncated(names, all) {
+  if (all || names.length <= SUMMARY_PER_BUCKET) return names.join(', ');
+  return `${names.slice(0, SUMMARY_PER_BUCKET).join(', ')} …（还有 ${names.length - SUMMARY_PER_BUCKET} 个，加 --all 看全表）`;
+}
+
+/**
+ * 单跑这一条时的清单。返回 `{ notes, payload }`：
+ * notes 是人话（聚合层逐行打），payload 是 `--json` 的机器档。
+ */
+function faceOf(modulePackages) {
+  const flags = flagsOf();
+  const all = flags.includes('--all');
+  const from = primitivesFrom(modulePackages) ?? { from: process.cwd() };
+  const shellManifest = shellManifestOf(from.from);
+  const pinned = shellManifest === undefined ? undefined : pinnedPrimitivesVersion(shellManifest);
+  const shellVersion = shellManifest === undefined ? undefined : versionOf(shellManifest);
+
+  const declaredLines = [];
+  const modules = [];
+  for (const pkg of modulePackages) {
+    const declared = pkg.manifest.devDependencies?.[PRIMITIVES_SPECIFIER];
+    modules.push({ name: pkg.manifest.name, declared: declared ?? null });
+    if (declared !== undefined) declaredLines.push(`${pkg.manifest.name} → ${declared}`);
+  }
+  const drift =
+    pinned === undefined ? [] : modules.filter((one) => one.declared !== null && one.declared !== pinned);
+  const moduleLine =
+    declaredLines.length > 0
+      ? `模块声明：${declaredLines.join(' ｜ ')}` +
+        (drift.length > 0
+          ? ` ⚠️ 与外壳钉的 ${pinned} 不一致（只提醒，不判红；对齐它的写法见下面那段）`
+          : '')
+      : '模块声明：（还没有模块声明它 —— 模板生成的骨架默认带这一行）';
+
+  const installed = installedPrimitives(from.from);
+  if (installed === undefined) {
+    const want = pinned ?? '<外壳钉的那版>';
+    const notes = [
+      `这份工程里没装 ${PRIMITIVES_SPECIFIER} —— 列不出清单。`,
+      `  它在 @deepseek-ai/dsh-client-ui-primitives 那个包的 lib/types/**/*.d.ts 里（源码不随包发布）。`,
+      `  先加一行再 pnpm install：`,
+      `    "devDependencies": { "${PRIMITIVES_SPECIFIER}": "${want}" }`,
+      `  两个模板默认带这一行；加完在 dsh.client.external 里也声明 "${PRIMITIVES_SPECIFIER}"（两处都要）。`,
+    ];
+    if (pinned !== undefined) notes.push(`  外壳（${SHELL}${shellVersion === undefined ? '' : `@${shellVersion}`}）钉的是 ${pinned} —— 对齐它。`);
+    return { notes, payload: { installed: null, pinned: pinned ?? null, modules, snippet: devDependencySnippet(want) } };
+  }
+
+  let surface;
+  try {
+    surface = surfaceOf(join(installed.dir, 'lib', 'types'));
+  } catch (error) {
+    return {
+      notes: [
+        `装了 ${PRIMITIVES_SPECIFIER}@${installed.version}，但读不出类型面：${error instanceof Error ? error.message : String(error)}`,
+        `  上游可能换了 emit 形状 —— 先打开 ${join(installed.dir, 'lib', 'types', 'index.d.ts')} 看一眼，再改 ../primitives-surface.mjs`,
+      ],
+      payload: { installed: { version: installed.version, dir: installed.dir }, pinned: pinned ?? null, modules, error: String(error) },
+    };
+  }
+
+  const kit = from.from === undefined ? new Map() : kitMembersOf(from.from);
+  const covered = [];
+  const only = { components: [], icons: [], hooks: [], lib: [] };
+  for (const [bucket] of BUCKETS) {
+    for (const name of surface[bucket]) {
+      if (kit.has(name)) covered.push({ name, bucket: kit.get(name) });
+      else only[bucket].push(name);
+    }
+  }
+  covered.sort((a, b) => a.name.localeCompare(b.name));
+
+  const notes = ['这份装机包的 dsh 原语面（kit 里没有的才用它）：'];
+  notes.push(`  装机：${installed.version}`);
+  notes.push(`  类型面（绝对路径）：${join(installed.dir, 'lib', 'types')} （某个名字的文件：--files | grep <名字>）`);
+  notes.push(
+    pinned === undefined
+      ? `  外壳钉的：读不到（${shellManifest ?? '找不到 @dsh-workbench/core 的 manifest'}）`
+      : `  外壳钉的：${pinned}${shellVersion === undefined ? '' : `（${SHELL}@${shellVersion} 的 devDependencies）`}${pinned === installed.version ? '' : ' ⚠️ 与装机那份不一致'}`,
+  );
+  notes.push(`  ${moduleLine}`);
+  const one = flagValue(flags, '--file');
+  if (one !== undefined) {
+    const file = surface.files[one];
+    notes.push(
+      file === undefined
+        ? `  --file ${one}：不在这份清单里（用 --files | grep ${one} 找找近似的名字）`
+        : `  --file ${one}：${file} （打开看它的 JSDoc 与 prop：sed -n '1,60p' 那一份）`,
+    );
+  }
+  if (flags.includes('--files')) {
+    notes.push(
+      `  名字 → 类型文件（绝对路径，全表约 ${Object.keys(surface.files).length} 条、会被 tool-result-pruner 裁中间：用 --files | grep <名字> 取一件）`,
+    );
+    const iconsFile = surface.files[surface.icons[0]];
+    for (const [bucket] of BUCKETS) {
+      const names = only[bucket];
+      if (names.length === 0) continue;
+      if (bucket === 'icons') {
+        notes.push(`    ${bucket}(${names.length})：全部在 ${iconsFile ?? '？'}`);
+        continue;
+      }
+      for (const name of names) notes.push(`    ${name} → ${surface.files[name] ?? '？'}`);
+    }
+  } else if (one === undefined) {
+    notes.push(
+      covered.length === 0
+        ? '  kit 里已有（优先用 kit）：（这份外壳的 kit 里没有同名的，下面这些都得引原语）'
+        : `  kit 里已有（优先用 kit，别重复引原语）：${truncated(covered.map((one) => `${one.name}(${one.bucket})`), all)}`,
+    );
+    notes.push(`  只有原语有（用之前先在 dsh.client.external 里声明 "${PRIMITIVES_SPECIFIER}"）：`);
+    for (const [bucket] of BUCKETS) {
+      const names = only[bucket];
+      if (names.length === 0) continue;
+      notes.push(`    ${bucket}(${names.length})：${truncated(names, all)}`);
+    }
+  }
+  if (one === undefined) {
+    notes.push('  package.json 两处这样写：');
+    notes.push(`    "dsh": { "client": { "external": [ …, "${PRIMITIVES_SPECIFIER}" ] } }`);
+    notes.push(`    "devDependencies": { "${PRIMITIVES_SPECIFIER}": "${pinned ?? installed.version}" }${pinned !== undefined && pinned !== installed.version ? '  ← 与外壳对齐的那版' : ''}`);
+  }
+
+  return {
+    notes,
+    payload: {
+      installed: { version: installed.version, dir: installed.dir },
+      roots: { primitives: join(installed.dir, 'lib', 'types') },
+      files: surface.files,
+      pinned: pinned ?? null,
+      shellVersion: shellVersion ?? null,
+      modules,
+      kitCovered: covered,
+      onlyPrimitives: only,
+      counts: { total: surface.total, ...Object.fromEntries(BUCKETS.map(([bucket]) => [bucket, only[bucket].length])) },
+      snippet: devDependencySnippet(pinned ?? installed.version),
+    },
+  };
+}
+
+function devDependencySnippet(version) {
+  return {
+    external: PRIMITIVES_SPECIFIER,
+    devDependency: { name: PRIMITIVES_SPECIFIER, version },
+  };
+}
+
+function versionOf(manifestPath) {
+  try {
+    const version = JSON.parse(readFileSync(manifestPath, 'utf8')).version;
+    return typeof version === 'string' ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function run() {
   const modulePackages = discoverModulePackages({ root: process.cwd() });
+  const face = process.env.DSH_WB_ONLY === 'primitives'
+    ? faceOf(modulePackages)
+    : { notes: ['（想知道 dsh 原语里有什么：dsh-wb-module check --only primitives）'], payload: undefined };
   const problems = [];
   let modulesUsingPrimitives = 0;
   let modulesUsingReactOnly = 0;
@@ -113,21 +338,28 @@ export async function run() {
     }
   }
 
+  const payload = face.payload === undefined ? {} : { payload: face.payload };
+
   if (problems.length > 0) {
-    return { status: 'fail', notes: [], problems };
+    return { status: 'fail', notes: face.notes, problems, ...payload };
   }
   if (modulePackages.length === 0) {
     return {
       status: 'skip',
-      notes: ['没有模块包（没有声明 dsh.workbench 的包）—— 没有 dsh 原语的声明与产物可对'],
+      notes: ['没有模块包（没有声明 dsh.workbench 的包）—— 没有 dsh 原语的声明与产物可对', ...face.notes],
       problems: [],
+      ...payload,
     };
   }
   if (modulesTouchingSeeds === 0) {
     return {
       status: 'skip',
-      notes: ['没有模块用到平台种子词（react / react-dom / dsh 的浏览器包）—— 没有可对照的声明与产物'],
+      notes: [
+        '没有模块用到平台种子词（react / react-dom / dsh 的浏览器包）—— 没有可对照的声明与产物',
+        ...face.notes,
+      ],
       problems: [],
+      ...payload,
     };
   }
   return {
@@ -135,7 +367,9 @@ export async function run() {
     notes: [
       `${modulesUsingPrimitives} 个模块在用 dsh 的包（都声明了 external、产物里都是 ` +
         `require、宿主产物里没有它们）· 另有 ${modulesUsingReactOnly} 个模块只用到 react/react-dom`,
+      ...face.notes,
     ],
     problems: [],
+    ...payload,
   };
 }