@dsh-workbench/module-tools 0.3.2 → 0.3.4

package/src/check.mjs

@@ -19,6 +19,15 @@
 //     不适用 ○ <title>：（不适用）<notes>
 //     失败   ✖ <title> <N> 条不过：  然后逐条 `  · <problem>`
 // 最后一行是汇总；有任何 fail 就 exit 1。
+//
+// ── 两条加法（2026-10-19，dsh-primitives-face）────────────────────────────────
+//
+//   ① 开关透传：聚合层只认 `--only` / `--cwd`，其余开关（`--all` / `--json`）原样经
+//      `DSH_WB_ONLY_ARGS`（JSON 数组）交给**单跑的那一条**。为什么走 env 而不是给 `run()`
+//      加参数：所有判据的形状都是 `run()` 无参，加参数会让"统一形状"这条纪律多一个例外。
+//   ② 可选 `payload`：判据可以额外返回 `payload`；带着 `--json` 跑时，聚合层打它、**跳过**
+//      人话版 report 与最后的汇总行（stdout 只有一份 JSON）。老判据不返回它，行为一字不变 ——
+//      这是加法，不是新形状。
 
 // 名字与 title 一字不变 —— selfcheck 会把它与各判据模块导出的 `title` 逐个对一遍。
 export const CHECKS = {
@@ -26,6 +35,8 @@ export const CHECKS = {
   protocol: { title: '模块声明协议', load: () => import('./checks/protocol.mjs') },
   bundles: { title: '模块产物边界', load: () => import('./checks/bundles.mjs') },
   source: { title: '模块源码边界', load: () => import('./checks/source.mjs') },
+  arch: { title: '模块架构（分层 / 边界 / 设计系统）', load: () => import('./checks/arch.mjs') },
+  lint: { title: '模块代码卫生（eslint）', load: () => import('./checks/lint.mjs') },
   primitives: { title: 'dsh 原语只从模块表拿', load: () => import('./checks/primitives.mjs') },
   kit: { title: '外壳 kit 面', load: () => import('./checks/kit.mjs') },
   cards: { title: '卡片渲染', load: () => import('./checks/cards.mjs') },
@@ -56,11 +67,13 @@ function report(title, result) {
   for (const note of notes.slice(1)) console.log(`  ${note}`);
 }
 
-export async function check({ only } = {}) {
+export async function check({ only, args = [] } = {}) {
   const names = only === undefined ? Object.keys(CHECKS) : [only];
+  const jsonMode = args.includes('--json');
   const tally = { pass: 0, skip: 0, fail: 0 };
   const skipped = [];
   let ran = 0;
+  process.env.DSH_WB_ONLY_ARGS = JSON.stringify(args);
   try {
     for (const name of names) {
       const entry = CHECKS[name];
@@ -87,10 +100,18 @@ export async function check({ only } = {}) {
       }
       tally[result.status] += 1;
       if (result.status === 'skip') skipped.push(`${title}（${result.notes[0] ?? ''}）`);
-      report(title, result);
+      if (jsonMode && result.payload !== undefined) console.log(JSON.stringify(result.payload, null, 2));
+      else report(title, result);
     }
   } finally {
     process.env.DSH_WB_ONLY = '';
+    process.env.DSH_WB_ONLY_ARGS = '';
+  }
+
+  // `--json` 的 stdout 只有那几份 payload：汇总行与"不适用"那几段都是人话，不进机器档。
+  if (jsonMode) {
+    if (tally.fail > 0) process.exit(1);
+    return;
   }
 
   console.log(`${ran} 条判据：${tally.pass} 通过 · ${tally.skip} 不适用 · ${tally.fail} 不过`);

package/src/checks/arch.mjs

@@ -0,0 +1,127 @@
+// 模块包的**架构判据**（`check` 的第十二条）：把 arch-guard 跑在**模块自己的方言**上。
+//
+// 为什么模块包需要这一条：另外十一条判据全是"边界"（自述清单 / 产物 / 可达性 / 卡片渲染 / 样式归属），
+// 没有一条在看**代码结构** —— 而模块包是用户自己写的、模板给的又是能一路长成几百行的起步形状。
+// 结构退化（巨文件、反向依赖、宿主侧拖进组件、未登记的目录、模型层没有测试）以前只靠人自觉。
+//
+// 判据的口径（三条，都要守住）：
+//   ① **只跑带 `arch.config.mjs` 的模块**：没有那份声明就 `skip`（不适用），不是红。
+//      工坊里已经造好的模块（以及别的仓里已经发出去的模块）不会被这次升级炸掉 —— 补一行就上车。
+//   ② 方言住 `../arch.mjs`（`@dsh-workbench/module-tools/arch`），不在这条判据里 ——
+//      判据只负责"跑起来 + 把结果翻成人话"。
+//   ③ `cache: false`：模块目录不一定有 node_modules，arch-guard 的 facts 缓存会落到模块根下
+//      （实测会打一句"记得加进 .gitignore"）—— 门禁不该往用户的包里拉屎。
+//
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { builtinSourceForms, runGuard } from '@arch-guard/core';
+import { discoverModulePackages } from '../discover.mjs';
+
+export const title = '模块架构（分层 / 边界 / 设计系统）';
+
+const CONFIG_FILE = 'arch.config.mjs';
+
+// "怎么上车"那句话只写一遍：skip 的提示与 fail 的提示都要它。
+const HOW_TO_JOIN =
+  `在模块包里放一份 ${CONFIG_FILE}，内容一行就够：\n` +
+  `    import { moduleArch } from '@dsh-workbench/module-tools/arch';\n` +
+  '    export default moduleArch();\n' +
+  '  形状（层序表 / 两个运行时 / 阈值）见 packages/module-tools/src/arch.mjs；' +
+  '要开口子就从 moduleArch() 的参数进（deps / layers / roles / exceptions）。';
+
+const severityIndex = (rules) => new Map(rules.map((rule) => [rule.id, rule.severity]));
+
+const severityOf = (finding, index) => finding.severity ?? index.get(finding.rule) ?? 'error';
+
+/** 一条 finding 翻成一行人话：位置 → 说明 → 规则与修法。 */
+function lineOf(name, finding) {
+  const where = `${name}: ${finding.file}:${String(finding.line)}`;
+  const hint = typeof finding.hint === 'string' && finding.hint !== '' ? ` —— ${finding.hint}` : '';
+  return `${where} ${finding.text}（${finding.rule}）${hint}`;
+}
+
+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 = [];
+  let files = 0;
+  let warnings = 0;
+  // 真的跑过的规则 id（与 arch-guard 报告头那句"规则 58/107"同一个口径：`stats` 是逐规则执行统计）。
+  const ranRules = new Set();
+
+  for (const pkg of declared) {
+    const name = pkg.manifest.name;
+    let result;
+    try {
+      result = await runGuard({
+        cwd: pkg.dir,
+        // **相对**路径：arch-guard 把 configPath 拼在 cwd 后面（实测传绝对路径会拼成
+        // `<cwd>/<绝对路径>`，再报"找不到配置文件"）。
+        configPath: CONFIG_FILE,
+        sourceForms: builtinSourceForms,
+        cache: false,
+        quiet: true,
+        format: 'json',
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      problems.push(
+        `${name}: ${CONFIG_FILE} 跑不起来 —— ${message}（先确认这份配置能 import、没有语法错，` +
+          '再确认它 import 的东西在工坊里解析得到）',
+      );
+      continue;
+    }
+
+    // `scopeFiles` 在 full 档是空的（实测）—— 解析过的文件数从 facts 缓存那份统计里拿
+    // （`cache: false` 时 `misses` 就是这一轮解析了几个文件，见 arch-guard 的 RunResult 注释）。
+    files += result.cache.misses;
+    for (const stat of result.stats) ranRules.add(stat.rule);
+    const index = severityIndex(result.config.rules);
+    for (const finding of result.active) {
+      if (severityOf(finding, index) === 'error') problems.push(lineOf(name, finding));
+      else warnings += 1;
+    }
+  }
+
+  if (problems.length > 0) {
+    return {
+      status: 'fail',
+      // 提示放在 notes 里，判据层照旧只报"哪几条不过"。
+      notes: [`红了怎么修：先看位置与规则号，再决定"改代码"还是"在 ${CONFIG_FILE} 里开口子"。`],
+      problems,
+    };
+  }
+
+  return {
+    status: 'pass',
+    notes: [
+      `${declared.length}/${modulePackages.length} 个模块包带 ${CONFIG_FILE} · ${files} 个源文件 · ` +
+        `${ranRules.size} 条规则在跑` +
+        (warnings === 0 ? '' : ` · ${warnings} 条 warn（不挡门禁）`) +
+        (declared.length === modulePackages.length ? '' : `；其余 ${modulePackages.length - declared.length} 个没声明（不适用）`),
+    ],
+    problems: [],
+  };
+}

package/src/checks/kit.mjs

@@ -22,7 +22,9 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { flagValue, flagsOf } from '../check-flags.mjs';
 import { discoverModulePackages } from '../discover.mjs';
+import { memberFilesOf } from '../shell-type-files.mjs';
 import { shellClientPathOf, shellKitOf } from './shell-artifact.mjs';
 
 const SHELL = '@dsh-workbench/core';
@@ -82,14 +84,19 @@ function below(a, b) {
 // 只在单跑时打：外壳把整份 `@dsh-workbench/shared` barrel 摊进了每个桶，所以这份名单
 // 有一百多个名字 —— 聚合跑时它只是噪音，查询时才值钱。
 //
-// 返回的是若干 `notes`（每条一行，交给聚合层加缩进），而不是打印 —— 打印归 check.mjs。
+// 名字还要能落到**文件**（"想问哪个直接去看"）：默认打两棵类型树的绝对根 + 取法，
+// `--files` 打逐条 `名字 → 绝对路径`（190 条 / ~9k 字符，会被 tool-result-pruner 裁中间，
+// 所以它得配 `| grep <名字>` 用，默认档不内联）。`--json` 给机器档。
+//
+// 返回的是 `{ notes, payload }`（notes 每条一行，交给聚合层加缩进；payload 归 `--json`）——
+// 打印归 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）'];
+    return { notes: ['（想知道这份外壳的 kit 里有什么：dsh-wb-module check --only kit）'] };
   }
   if (faceShell === undefined || !existsSync(faceShell)) {
-    return ['（没找到外壳的 client.js，列不出 kit 面：先确认 node_modules 里装着 @dsh-workbench/core）'];
+    return { notes: ['（没找到外壳的 client.js，列不出 kit 面：先确认 node_modules 里装着 @dsh-workbench/core）'] };
   }
   try {
     const kit = shellKitOf(faceShell);
@@ -97,23 +104,59 @@ function faceNotes(asked, shells) {
       .filter((bucket) => typeof kit[bucket] === 'object' && kit[bucket] !== null)
       .sort();
     if (buckets.length === 0) {
-      return [`（${faceShell} 里没取出 kit：外壳版本可能太旧）`];
+      return { notes: [`（${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 flags = flagsOf();
+    const one = flagValue(flags, '--file');
+    const { roots, files, missing } = memberFilesOf(faceShell, [...every.keys()]);
+    const rootLine =
+      Object.entries(roots).length === 0
+        ? '  类型面：读不到（外壳包里没有 dist/types，@dsh-workbench/shared 也没装）'
+        : `  类型面（绝对路径）：${Object.entries(roots).map(([pkg, dir]) => `${pkg} → ${dir}`).join(' ｜ ')}` +
+          ` （某个名字的文件：--file <名字>，或 --files | grep <名字>）`;
+
+    const notes = [`这份外壳（${faceShell}）的 kit 面 —— 只能用这些，别自己造：`, rootLine];
+    if (one !== undefined) {
+      const file = files.get(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(
+        `  名字 → 类型文件（绝对路径，全表 ${every.size} 条、会被 tool-result-pruner 裁中间：用 --files | grep <名字> 取一件）`,
+      );
+      for (const name of [...every.keys()].sort()) {
+        notes.push(`    ${name} → ${files.get(name) ?? '（没扫到，见上面那两棵根）'}`);
+      }
+      if (missing.length > 0) notes.push(`  ${missing.length} 个没扫到：${missing.join('、')}`);
+    } else if (one === undefined) {
+      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(', ')}`);
     }
-    const shared = [...every.entries()].filter(([, count]) => count > 1).map(([name]) => name).sort();
-    notes.push(`  共用面(${shared.length})：每个桶里都有 —— ${shared.join(', ')}`);
-    return notes;
+    return {
+      notes,
+      payload: {
+        shell: faceShell,
+        roots,
+        buckets: Object.fromEntries(buckets.map((bucket) => [bucket, Object.keys(kit[bucket])])),
+        files: Object.fromEntries([...every.keys()].sort().map((name) => [name, files.get(name) ?? null])),
+        missing,
+      },
+    };
   } catch (error) {
-    return [`（取不出这份外壳的 kit 面：${error instanceof Error ? error.message : String(error)}）`];
+    return { notes: [`（取不出这份外壳的 kit 面：${error instanceof Error ? error.message : String(error)}）`] };
   }
 }
 
@@ -183,19 +226,25 @@ export async function run() {
     }
   }
 
-  if (problems.length > 0) {
-    return { status: 'fail', notes: [], problems };
-  }
-
   const asked = process.env.DSH_WB_ONLY === 'kit';
   const face = faceNotes(asked, shells);
+  const payload = face.payload === undefined ? {} : { payload: face.payload };
+
+  if (problems.length > 0) {
+    // 清单是**事实**、红是**判据**：判据红不该把清单一起扣下。`--json` 的消费者（工坊那把
+    // `workbench_diy_components`）要靠这份机器档回答"这份外壳有哪些件"，而判据红经常是**别的
+    // 模块**的事 —— 2026-10-20 真机：三个模块用了 MockStrip / useFixturePick，工具整条查询直接
+    // 报错、agent 什么也没拿到。退出码照旧 1（红没被藏起来），problems 也一起进机器档。
+    const extra = face.payload === undefined ? {} : { payload: { ...face.payload, problems } };
+    return { status: 'fail', notes: [], problems, ...extra };
+  }
 
   if (inspected === 0) {
     const why =
       modulePackages.length === 0
         ? '没有模块包（没有声明 dsh.workbench 的包）—— 没有产物可对'
         : `${noArtifact} 个还没建产物（跳过）`;
-    return { status: 'skip', notes: [why, ...face], problems: [] };
+    return { status: 'skip', notes: [why, ...face.notes], problems: [], ...payload };
   }
 
   const notes = [
@@ -204,5 +253,5 @@ export async function run() {
   ];
   if (noArtifact > 0) notes.push(`${noArtifact} 个还没建产物（跳过）`);
   if (noShell > 0) notes.push(`${noShell} 个没装外壳（跳过面差）`);
-  return { status: 'pass', notes: [...notes, ...face], problems: [] };
+  return { status: 'pass', notes: [...notes, ...face.notes], problems: [], ...payload };
 }