@dsh-workbench/module-tools 0.3.10 → 1.0.0-beta.0

package/src/build.mjs

@@ -1,4 +1,3 @@
-
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { builtinModules } from 'node:module';
@@ -11,9 +10,6 @@ const SHELL_CLIENT = '@dsh-workbench/core/client';
 const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.js', '.json'];
 const SINGLETON = /^@\/shared\/(hooks|components)\//;
 
-// dsh 的客户端模块表里"天生就有"的包（seed 词）。模块的浏览器产物**默认**把它们标成外部：
-// 这些是外壳那一份实例，内联进来就是第二份 —— 两份 React 组件树、两套样式、hover 与浮层失联。
-// 名单在 `../seed.mjs`（唯一真相）；判据侧由 `checks/source.mjs` 与 `checks/primitives.mjs` 守。
 const SEED_EXTERNAL = SEED_SPECIFIERS;
 
 function pickEntry(root, names) {
@@ -48,8 +44,7 @@ function aliasResolver({ root, unit }) {
               `模块自己的文件用 @/modules/${unit ?? '<unit>'}/… 或相对路径`,
           );
         }
-        // `@/…/X.module.css` 这类：把解析结果直接交给 CSS 落点（namespace 由 cssInjector 接管），
-        // 不要按 .ts/.tsx 去找 —— 否则别名插件的候选表把样式文件挡在外面。
+
         if (base.endsWith('.css') && existsSync(base)) {
           return { path: base, namespace: 'dsh-wb-css' };
         }
@@ -71,15 +66,7 @@ function cssInjector({ root }) {
         namespace: 'dsh-wb-css',
       }));
       context.onLoad({ filter: /.*/, namespace: 'dsh-wb-css' }, (args) => {
-        // 来自被 external 的那份 kit（@dsh-workbench/shared）的样式一律不收：外壳运行时自己会注入
-        // 那一份，产物里再带一份就变成"两份 kit 样式按选择器混合"（2026-10-18 实测：模块内联了 145
-        // 条外壳规则、冻结构建时的版本，与运行的外壳混用 ⇒ 折行 / 塌列 / 标签压值）。见 ADR-0028 §5.1。
-        // 两条路径都要认：
-        //   · 装了依赖的模块仓 —— `node_modules/@dsh-workbench/{shared,core}/…`（pnpm 的 store 里也含这段）；
-        //   · 本仓自己开发时 —— `packages/{shared,workbench}/dist/…`。**是 dist 不是 src**：esbuild 默认
-        //     跟随软链（`preserveSymlinks:false`），workspace 的 `node_modules/@dsh-workbench/shared`
-        //     软链会被解成真实源码包路径，而 `exports."."` 指的是编译产物 `dist/index.js`，组件样式
-        //     与它同住 `dist/components/**`（只写 `src` 会在本仓场景漏收：实测 148 条规则照进产物）。
+
         const outsourcedKitCss =
           /node_modules\/@dsh-workbench\/(shared|core)\//.test(args.path) ||
           /\/packages\/(shared|workbench)\/(src|dist)\//.test(args.path);
@@ -87,16 +74,12 @@ function cssInjector({ root }) {
         const raw = readFileSync(args.path, 'utf8');
         const key = relative(root, args.path).split('/').reverse()[0] + ':' + args.path;
         const scoped = /\.module\.css$/.test(args.path);
-        // `*.module.css` 按 CSS Modules 处理：类名哈希后写回 CSS，同时把映射交给调用点
-        // （`import styles from './X.module.css'` → `styles.foo`）。哈希取"模块内相对路径"，
-        // 同一个类在同一次构建里稳定，跨模块不同名。非 module 的 .css 原样注入（依赖里的就是这种）。
+
         let css = raw;
         let map = '{}';
         if (scoped) {
           const hash = createHash('sha1').update(relative(root, args.path)).digest('hex').slice(0, 6);
-          // `:global(...)` 里的类名**不许哈希** —— 那是外壳的契约类（比如 `.wb-iconButton`），
-          // 模块借用它时只能这样写：`.wb-envRefresh:global(.wb-iconButton)`。先把这些片段挖出来存着，
-          // 哈希完再放回去。
+
           const globals = [];
           const guarded = raw.replace(/:global\([^)]*\)/g, (piece) => {
             globals.push(piece.slice(':global('.length, -1));
@@ -105,9 +88,7 @@ function cssInjector({ root }) {
           const names = [
             ...new Set([...guarded.matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)].map((match) => match[1])),
           ].sort((a, b) => b.length - a.length);
-          // 类名**不能以数字开头**：哈希是十六进制，直接接在 `.` 后面会写出 `.3a0f86_x` 这种
-          // 非法选择器 —— 浏览器会把整条规则丢掉（实测：20 条规则只解析出 1 条，界面整屏掉样式）。
-          // 前面加一个下划线，保持 CSS Modules 的老习惯（`._3a0f86_x`）。
+
           const pairs = names.map((name) => [name, `_${hash}_${name}`]);
           css = guarded;
           for (const [from, to] of pairs) css = css.split(`.${from}`).join(`.${to}`);
@@ -169,9 +150,6 @@ export async function build({ root }) {
     logLevel: 'warning',
   });
 
-  // 物证：metafile 列出**这次真的被打进包里**的每个输入文件。dsh 的包只要出现，
-  // 就说明它没走外部化（声明漏了 / 名字写错 / 从 shared 内联进来）—— 那正是"第二份实例"。
-  // 不靠产物里的字符串去猜（tree-shaking 之后标记可能根本不进包），也不靠它自己报错。
   const inlinedDsh = Object.keys(client.metafile.inputs).filter((path) => /@deepseek-ai[\\/]/.test(path));
   if (inlinedDsh.length > 0) {
     throw new Error(
@@ -188,8 +166,6 @@ export async function build({ root }) {
   const wrapped = `// ⚠️ 本文件由 dsh-wb-module build 生成，请勿手改。改 src/ 后跑：dsh-wb-module build\nwindow.__ModuleLoader__.load({\n  id: ${JSON.stringify(id)},\n  factory(require) {\n    const module = { exports: {} };\n    const exports = module.exports;\n${indented}\n    return module.exports;\n  },\n});\n`;
 
   writeFileSync(join(root, 'client.js'), wrapped);
-  // `wrapped.length` 是 **UTF-16 码元数**（字符数），不是字节数 —— 产物里有中文头注释与模块自己的
-  // 中文文案，报出来会比真实文件小（实测 `module-hello/client.js`：3095 字符 / 3131 字节）。
-  // 报字节就按字节算。
+
   console.log(`${id}：client.js 已更新（${Buffer.byteLength(wrapped, 'utf8')} 字节）`);
 }

package/src/changelog.mjs

@@ -0,0 +1,167 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  CHANGELOG_FILE,
+  CHANGELOG_KINDS,
+  appendChangelogEntry,
+  changelogDate,
+  changelogHasEntry,
+  changelogSkeleton,
+  changelogVersion,
+} from '@dsh-workbench/shared/host';
+
+const SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+
+const USAGE = `用法：
+  changelog init                              建一份 ${CHANGELOG_FILE}（已有就不动）
+  changelog add <版本> [--type ${CHANGELOG_KINDS.join('|')}] [--note <文字>] [--date <日期>]
+  changelog check [版本]                      查这一版有没有记录（省略版本用 package.json 的）
+版本也可以省略：用 package.json 里的 version。发布时这一版必须有记录，否则拦下。`;
+
+function argValue(args, flag) {
+  const at = args.indexOf(flag);
+  return at === -1 ? undefined : args[at + 1];
+}
+
+function positional(args, at) {
+  const value = args[at];
+  return value === undefined || value.startsWith('--') ? undefined : value;
+}
+
+export function changelogFileOf(root) {
+  return join(root, CHANGELOG_FILE);
+}
+
+export function readChangelogText(root) {
+  try {
+    return readFileSync(changelogFileOf(root), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+export function manifestVersionOf(root) {
+  try {
+    const version = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+    return typeof version === 'string' ? version.trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+export function changelogProblemOf(root, version) {
+  const text = readChangelogText(root);
+  if (text.trim() === '') {
+    return {
+      reason: `包里还没有 ${CHANGELOG_FILE} —— 更新日志要随包发布`,
+      command: 'dsh-wb-module changelog init',
+    };
+  }
+  if (!changelogHasEntry(text, version)) {
+    return {
+      reason: `${CHANGELOG_FILE} 里没有 ${version} 这一版的内容 —— 发布前先把这一版写进去`,
+      command: `dsh-wb-module changelog add ${version} --note "这一版改了什么"`,
+    };
+  }
+  return undefined;
+}
+
+export function initChangelog(root) {
+  const file = changelogFileOf(root);
+  if (existsSync(file)) return { file, created: false };
+  writeFileSync(file, changelogSkeleton());
+  return { file, created: true };
+}
+
+export class ChangelogError extends Error {
+  constructor(message, code = 2) {
+    super(message);
+    this.name = 'ChangelogError';
+    this.code = code;
+  }
+}
+
+export function addChangelog(root, { version, kind = 'changed', note, date }) {
+  const text = (note ?? '').trim();
+  if (text === '') throw new ChangelogError('changelog add 要一句 --note：这一版改了什么');
+  if (!CHANGELOG_KINDS.includes(kind)) {
+    throw new ChangelogError(`--type 只认 ${CHANGELOG_KINDS.join(' / ')}（收到「${kind}」）`);
+  }
+  const wanted = changelogVersion(version === undefined || version === '' ? manifestVersionOf(root) : version);
+  if (!SEMVER.test(wanted)) {
+    throw new ChangelogError(`版本要写成 x.y.z（收到「${String(version)}」）—— 也可以省略，用 package.json 里的`);
+  }
+  const file = changelogFileOf(root);
+  const body = appendChangelogEntry(readChangelogText(root), { version: wanted, kind, note: text, date });
+  writeFileSync(file, body);
+  return { file, version: wanted, kind };
+}
+
+function runInit(root, args) {
+  const result = initChangelog(root);
+  if (args.includes('--json')) {
+    console.log(JSON.stringify({ ok: true, ...result }));
+    return;
+  }
+  if (!result.created) {
+    console.log(`${CHANGELOG_FILE} 已经在：${result.file} —— 没动它`);
+    return;
+  }
+  console.log(`✔ 建好了 ${result.file}`);
+  console.log(`  下一步：dsh-wb-module changelog add ${manifestVersionOf(root) || '<版本>'} --note "这一版改了什么"`);
+}
+
+function runAdd(root, args) {
+  const version = positional(args, 1) ?? manifestVersionOf(root);
+  const kind = argValue(args, '--type') ?? 'changed';
+  const note = argValue(args, '--note') ?? '';
+  const date = (argValue(args, '--date') ?? changelogDate()).trim();
+  let result;
+  try {
+    result = addChangelog(root, { version, kind, note, date });
+  } catch (error) {
+    if (!(error instanceof ChangelogError)) throw error;
+    console.error(error.message);
+    process.exit(error.code);
+  }
+  if (args.includes('--json')) {
+    console.log(JSON.stringify({ ok: true, ...result, date }));
+    return;
+  }
+  console.log(`✔ ${CHANGELOG_FILE} 已记下 ${result.version}（${result.kind}）`);
+}
+
+function runCheck(root, args) {
+  const version = changelogVersion(positional(args, 1) ?? manifestVersionOf(root));
+  if (!SEMVER.test(version)) {
+    console.error('changelog check 要知道查哪一版：给一个 x.y.z，或先让 package.json 有 version');
+    process.exit(2);
+  }
+  const problem = changelogProblemOf(root, version);
+  if (args.includes('--json')) {
+    console.log(
+      JSON.stringify(
+        problem === undefined
+          ? { ok: true, version }
+          : { ok: false, version, reason: problem.reason, command: problem.command },
+      ),
+    );
+  } else if (problem === undefined) {
+    console.log(`✔ ${CHANGELOG_FILE} 里有 ${version} 的更新日志`);
+  } else {
+    console.error(`✖ ${problem.reason}`);
+    console.error(`  补上：${problem.command}`);
+  }
+  if (problem !== undefined) process.exit(1);
+}
+
+export async function changelog({ root, args = [] }) {
+  const sub = args[0];
+  if (sub === 'init') return runInit(root, args);
+  if (sub === 'add') return runAdd(root, args);
+  if (sub === 'check') return runCheck(root, args);
+  console.error(`不认识的 changelog 子命令：${String(sub)}`);
+  console.error(USAGE);
+  process.exit(2);
+}

package/src/check-flags.mjs

@@ -1,9 +1,3 @@
-// `dsh-wb-module check --only <名字>` 单跑时透传的开关。
-//
-// 聚合层只认 `--only` / `--cwd`，其余开关（`--all` / `--files` / `--json`）原样经
-// `DSH_WB_ONLY_ARGS`（JSON 数组）交给**单跑的那一条** —— 这是 `check.mjs` 的加法之一
-// （给 `run()` 加参数会让"所有判据都是无参 `run()`"这条统一形状多一个例外）。
-// 名字只有这一处写，别把环境变量名抄成第二份真相。
 export function flagsOf() {
   try {
     const parsed = JSON.parse(process.env.DSH_WB_ONLY_ARGS ?? '[]');
@@ -13,7 +7,6 @@ export function flagsOf() {
   }
 }
 
-/** `--file <名字>` 那种带值的开关取它的值（没给值返回 undefined）。 */
 export function flagValue(flags, flag) {
   const at = flags.indexOf(flag);
   if (at === -1) return undefined;

package/src/check.mjs

@@ -1,55 +1,116 @@
-// 判据的**聚合层**：跑、收集三态、打印、决定退出码。有几条以 `CHECKS` 表为准。
-// ── 为什么判据改成"导出函数"，打印与退出码都搬到这里 ──────────────────────────
-//
-// 在这之前，每条 `checks/*.mjs` 都是"import 即执行 + 自己 console.log + 自己 process.exit"
-// 的脚本。那样"不适用"就没有一等形状 —— 只能靠"这条判据不许 exit(0)"这条**纪律**维持：
-// 谁哪天写个 `process.exit(0)`，排在它后面的判据就静默不跑，而屏幕看着还是全绿
-// （standalone 在仓外工作区就是这么吞掉 markers / style / alias 三条的，见
-// `.scratch/workbench-diy/spec.md` §20）。
-//
-// 另一件后果是聚合层拿不到"跑了哪些、跳了哪些、为什么跳"，只能看判据自己打的字。
-//
-// 新形状：每条判据导出 `run()`，返回
-//     { status: 'pass' | 'fail' | 'skip', notes: string[], problems: string[] }
-// ——"不适用"于是是一等结果，而**截断在形状上就不可能**：
-// 判据手里没有 exit，退出码只有这一层按汇总给。
-//
-// 打印形状（三态，稳定）：
-//     通过   ✔ <title>：<notes 拼起来>
-//     不适用 ○ <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 = {
-  contracts: { title: '模块契约', load: () => import('./checks/contracts.mjs') },
-  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') },
-  standalone: { title: '独立构建', load: () => import('./checks/standalone.mjs') },
-  markers: { title: '公开包无内部标识', load: () => import('./checks/markers.mjs') },
-  style: { title: '样式归属', load: () => import('./checks/style.mjs') },
-  alias: { title: '模块不指外壳', load: () => import('./checks/alias.mjs') },
+  contracts: {
+    title: '模块契约',
+    summary: '单元 id、两个面、四个脚本、files、peer 下限，以及清单与代码注册对账',
+    layer: 'manifest',
+    load: () => import('./checks/contracts.mjs'),
+  },
+  protocol: {
+    title: '模块声明协议',
+    summary: 'dsh.workbench 的 apiVersion、静态半形状与未知键',
+    layer: 'manifest',
+    load: () => import('./checks/protocol.mjs'),
+  },
+  bundles: {
+    title: '模块产物边界',
+    summary: '宿主产物不含浏览器侧、浏览器产物不内联外壳 CSS 与夹具',
+    layer: 'build',
+    load: () => import('./checks/bundles.mjs'),
+  },
+  source: {
+    title: '模块源码边界与零注释',
+    summary: '零注释、包与运行时入口分开、不手写进程/锁/原子写',
+    layer: 'source',
+    load: () => import('./checks/source.mjs'),
+  },
+  arch: {
+    title: '模块架构（分层 / 边界 / 设计系统）',
+    summary: '模块自己的层序、运行时边界与设计系统配置',
+    layer: 'source',
+    load: () => import('./checks/arch.mjs'),
+  },
+  lint: {
+    title: '模块代码卫生（eslint）',
+    summary: '模块自己的 eslint.config.mjs 与规则集',
+    layer: 'source',
+    load: () => import('./checks/lint.mjs'),
+  },
+  primitives: {
+    title: 'dsh 原语只从模块表拿',
+    summary: 'dsh 包只从 kit 取，模块自己声明 external',
+    layer: 'build',
+    load: () => import('./checks/primitives.mjs'),
+  },
+  kit: {
+    title: '外壳 kit 面',
+    summary: '模块产物对得上所装外壳的 kit 面与 peer 下限',
+    layer: 'build',
+    load: () => import('./checks/kit.mjs'),
+  },
+  cards: {
+    title: '卡片渲染',
+    summary: '八态 × zh/en 渲染：不抛、不空白、不冒裸键名',
+    layer: 'render',
+    load: () => import('./checks/cards.mjs'),
+  },
+  standalone: {
+    title: '独立构建',
+    summary: '外壳源码不在场时仍能 build + typecheck',
+    layer: 'build',
+    load: () => import('./checks/standalone.mjs'),
+  },
+  markers: {
+    title: '公开包无内部标识',
+    summary: '公开包不含私有源、私网 IP、内部域名后缀',
+    layer: 'meta',
+    load: () => import('./checks/markers.mjs'),
+  },
+  style: {
+    title: '样式归属',
+    summary: '不定义 wb-* 规则；裸标签控件改走 kit；令牌名对现读的清单校验',
+    layer: 'source',
+    load: () => import('./checks/style.mjs'),
+  },
+  alias: {
+    title: '模块不指外壳',
+    summary: '模块源码里没有指向外壳 @/ 的引用',
+    layer: 'source',
+    load: () => import('./checks/alias.mjs'),
+  },
 };
 
-/** 判据只许回这三态；聚合层的打印与汇总都按它分支。 */
+export function checkList() {
+  return Object.entries(CHECKS).map(([name, entry]) => ({
+    name,
+    title: entry.title,
+    summary: entry.summary,
+    layer: entry.layer,
+  }));
+}
+
+export function renderCheckTable(rows = checkList()) {
+  return [
+    '| 判据 | 层 | 摘要 |',
+    '|---|---|---|',
+    ...rows.map((row) => `| \`${row.name}\` | ${row.layer} | ${row.summary} |`),
+  ].join('\n');
+}
+
+function list(args) {
+  const rows = checkList();
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  if (args.includes('--markdown')) {
+    console.log(renderCheckTable(rows));
+    return;
+  }
+  for (const row of rows) console.log(`${row.name}\t${row.layer}\t${row.title}\t${row.summary}`);
+}
+
 const STATES = ['pass', 'fail', 'skip'];
 
-/** 一屏一条：三态各一种前缀，notes 的第一条跟在标题后面，其余各占一行。 */
 function report(title, result) {
   const notes = Array.isArray(result.notes) ? result.notes : [];
   if (result.status === 'fail') {
@@ -68,6 +129,10 @@ function report(title, result) {
 }
 
 export async function check({ only, args = [] } = {}) {
+  if (args.includes('--list')) {
+    list(args);
+    return;
+  }
   const names = only === undefined ? Object.keys(CHECKS) : [only];
   const jsonMode = args.includes('--json');
   const tally = { pass: 0, skip: 0, fail: 0 };
@@ -81,12 +146,11 @@ export async function check({ only, args = [] } = {}) {
         console.error(`不认识的判据：${name}（有：${Object.keys(CHECKS).join(' / ')}）`);
         process.exit(2);
       }
-      // 告诉这一条"这次是不是只跑它"：有的判据在单跑时顺带当查询口（`--only kit` 会把
-      // 这份外壳的 kit 成员列出来），聚合跑时那些清单属于噪音，不该倒。
+
       process.env.DSH_WB_ONLY = only === undefined ? '' : name;
       const module = await entry.load();
       const result = await module.run();
-      // title 的发声处是判据模块自己；表里那份是兜底（两边必须一字不差，selfcheck 钉着）。
+
       const title = typeof module.title === 'string' && module.title !== '' ? module.title : entry.title;
       ran += 1;
       if (!STATES.includes(result.status)) {
@@ -108,15 +172,13 @@ export async function check({ only, args = [] } = {}) {
     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} 不过`);
-  // 「不适用」不是「通过」。汇总行里那两个数字长得很像，读的人（尤其 agent）很容易把
-  // "8 通过 · 2 不适用" 念成"全过了" —— 而工坊里那两条是**结构性**跑不了，不是这次没问题。
+
   if (skipped.length > 0) {
     console.log(`  这 ${skipped.length} 条这次一条都没查（不是"没问题"）：`);
     for (const one of skipped) console.log(`  ○ ${one}`);

package/src/checks/alias.mjs

@@ -1,12 +1,3 @@
-// 模块的源码只许引**自己的** `@/modules/<unit>/*`，不许出现任何指向外壳的 `@/`。
-//
-// 为什么：模块出包后用户手上没有外壳源码，`@/app/...` 这类别名只在**本仓的构建配置**里
-// 解析得到 —— 装到别人那里就是构建期找不到文件（`check:standalone` 会把它变成红灯，
-// 这条判据则直接指到源码那一行）。
-//
-// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
-// 打印与退出码归 `../check.mjs` 那一层。
-
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { discoverModulePackages } from '../discover.mjs';

package/src/checks/arch.mjs

@@ -1,20 +1,3 @@
-// 模块包的**架构判据**（`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';
@@ -24,7 +7,6 @@ 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` +
@@ -36,7 +18,6 @@ const severityIndex = (rules) => new Map(rules.map((rule) => [rule.id, rule.seve
 
 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}` : '';
@@ -68,7 +49,7 @@ export async function run() {
   const problems = [];
   let files = 0;
   let warnings = 0;
-  // 真的跑过的规则 id（与 arch-guard 报告头那句"规则 58/107"同一个口径：`stats` 是逐规则执行统计）。
+
   const ranRules = new Set();
 
   for (const pkg of declared) {
@@ -77,8 +58,7 @@ export async function run() {
     try {
       result = await runGuard({
         cwd: pkg.dir,
-        // **相对**路径：arch-guard 把 configPath 拼在 cwd 后面（实测传绝对路径会拼成
-        // `<cwd>/<绝对路径>`，再报"找不到配置文件"）。
+
         configPath: CONFIG_FILE,
         sourceForms: builtinSourceForms,
         cache: false,
@@ -94,8 +74,6 @@ export async function run() {
       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);
@@ -108,7 +86,7 @@ export async function run() {
   if (problems.length > 0) {
     return {
       status: 'fail',
-      // 提示放在 notes 里，判据层照旧只报"哪几条不过"。
+
       notes: [`红了怎么修：先看位置与规则号，再决定"改代码"还是"在 ${CONFIG_FILE} 里开口子"。`],
       problems,
     };

package/src/checks/bundles.mjs

@@ -1,22 +1,3 @@
-// 模块包的**运行时边界**（S2 第二块：门禁跟着自述清单走，覆盖到模块包）。
-//
-// 判据与外壳 `packages/workbench/scripts/check-runtimes.mjs` 是同一条：**能力，不是目录名**。
-// 外壳那份走的是 vite 的 import 图；这里走**产物** —— 模块的两个入口各打成一个文件，
-// 越界的依赖一定会被 inline 进来，所以：
-//
-//   浏览器产物里出现 node 内置  = 宿主传输层混进来了（例如某个视图 import 了 host/opencli）
-//   宿主产物里出现 DOM / react = 浏览器侧混进来了
-//
-// 判据要挑**只有宿主侧才有的能力**：node 内置、`process.env`、`Buffer`。
-// 这类错误在源码里看目录名是看不出来的（`model/blockers.ts` 这种纯函数浏览器当然可以用），
-// 所以只能按能力判 —— 而产物就是能力的物证。
-//
-// 覆盖范围跟着**自述清单**走：凡 `package.json` 里声明了 `dsh.workbench` 的包都被检查，
-// 新加一个模块不用改这个脚本。
-//
-// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
-// 打印与退出码归 `../check.mjs` 那一层。
-
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { inlinedShellRules } from '../css-shell.mjs';
@@ -36,13 +17,6 @@ const HOST_FORBIDDEN = [
 
 export const title = '模块产物边界';
 
-/**
- * 模块产物里的夹具标记 —— 这几串一出现就说明"夹具又长回模块里了"。
- *
- * 为什么是"串"而不是"符号"：模块产物是打包后的 JS，符号名会被内联/保留，用固定串更稳。
- * `-mock'` 那一条故意只匹配**带引号的模块路径尾巴**（`from './cmdb-mock'` 这类），
- * 避免误伤 vitest 的 `vi.mock`（那在测试里，不进产物）。
- */
 const FIXTURE_MARKERS = [
   'wbMock',
   'wbCrash',
@@ -88,10 +62,7 @@ export async function run() {
           );
         }
       }
-      // 夹具只属于**外壳开发者的调试**（.scratch/dev-only-fixtures/spec.md）：外壳自 0.2.12 起
-      // 把它整棵树挪出发布构建，kit 面也不再提供那几个成员。模块带着夹具只有坏处：
-      // 取不到旧成员会当场抛（2026-10-17 实测三个模块无条件渲染的包装组件就是这么崩的），
-      // 而且夹具数据会跟真取数抢同一条渲染路径。这条盯**产物**：出现任何一个标记就红。
+
       if (fixtureMarkersIn(source).length > 0) {
         const hits = fixtureMarkersIn(source);
         problems.push(
@@ -100,10 +71,7 @@ export async function run() {
             '模块自己的 vitest 把几态各喂一遍就够。',
         );
       }
-      // 外壳的组件样式**只有一份**（外壳注入那一次）。模块从 `@dsh-workbench/shared` 的**根入口**
-      // 取运行期值（`h` / `Fragment` / `useState` / 纯函数…）就会把整份组件 barrel 连 CSS 一起打进
-      // 自己的产物，注入后按顺序覆盖外壳那一份 —— 用户看到的是旧样式，而且外壳改了也不生效。
-      // 判断看复合选择器：`._hash_row.wb-iconButton` 这种「自己的类 + 外壳的槽类」是合规的，不算。
+
       if (artifact.file === 'client.js') {
         const inlined = inlinedShellRules(source);
         if (inlined.length > 0) {