@dsh-workbench/module-tools 0.1.14 → 0.1.16

package/src/checks/source.mjs

@@ -8,6 +8,9 @@
 // 关于 dsh 的包：「哪一半」**不靠目录名猜**，而是从两个入口（`faces.host` / `faces.client`）
 // 做一次本包内可达性分析。种子词（模块表里天生就有的那几个）在**只被客户端入口可达**的文件里
 // 可以用（ADR-0028）；宿主侧一个都不许碰 —— 那些包只在浏览器侧存在。
+//
+// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -88,107 +91,118 @@ function hasPlatformPackage(manifest) {
   return names.some((name) => /(^|\/)platform-/.test(name));
 }
 
-const modulePackages = () => discoverModulePackages({ root: process.cwd() });
-
-const problems = [];
-let scanned = 0;
-let seedUsers = 0;
-
-for (const pkg of modulePackages()) {
-  const name = pkg.manifest.name;
-  const unit = pkg.manifest.dsh.workbench.unit;
-  const faces = pkg.manifest.dsh.workbench.faces ?? {};
-  const srcDir = join(pkg.dir, 'src');
-  const viaPlatform = hasPlatformPackage(pkg.manifest);
-
-  if (viaPlatform && existsSync(join(srcDir, 'platforms'))) {
-    problems.push(
-      `${name}: 已经改用平台包了，src/platforms/ 就别再留一份 —— 平台知识两处都有，改平台要改两处`,
-    );
-  }
-
-  const hostReach = faces.host === undefined ? new Set() : reachableFrom(pkg.dir, unit, faces.host);
-  const clientReach = faces.client === undefined ? new Set() : reachableFrom(pkg.dir, unit, faces.client);
-  const sideOf = (file) => {
-    const host = hostReach.has(file);
-    const client = clientReach.has(file);
-    if (host && client) return 'both';
-    if (host) return 'host';
-    if (client) return 'client';
-    return 'orphan';
-  };
-
-  for (const file of sourceFiles(srcDir)) {
-    scanned += 1;
-    const rel = relative(pkg.dir, file);
-    const text = readFileSync(file, 'utf8');
-
-    for (const match of text.matchAll(IMPORT)) {
-      const specifier = match[1] ?? match[2];
-      if (specifier === undefined) continue;
+export const title = '模块源码边界';
+
+export async function run() {
+  const modulePackages = discoverModulePackages({ root: process.cwd() });
+  const problems = [];
+  let scanned = 0;
+  let seedUsers = 0;
+
+  for (const pkg of modulePackages) {
+    const name = pkg.manifest.name;
+    const unit = pkg.manifest.dsh.workbench.unit;
+    const faces = pkg.manifest.dsh.workbench.faces ?? {};
+    const srcDir = join(pkg.dir, 'src');
+    const viaPlatform = hasPlatformPackage(pkg.manifest);
+
+    if (viaPlatform && existsSync(join(srcDir, 'platforms'))) {
+      problems.push(
+        `${name}: 已经改用平台包了，src/platforms/ 就别再留一份 —— 平台知识两处都有，改平台要改两处`,
+      );
+    }
 
-      if (specifier.startsWith('@deepseek-ai/')) {
-        if (isSeedSpecifier(specifier) && sideOf(file) === 'client') {
-          seedUsers += 1;
+    const hostReach = faces.host === undefined ? new Set() : reachableFrom(pkg.dir, unit, faces.host);
+    const clientReach = faces.client === undefined ? new Set() : reachableFrom(pkg.dir, unit, faces.client);
+    const sideOf = (file) => {
+      const host = hostReach.has(file);
+      const client = clientReach.has(file);
+      if (host && client) return 'both';
+      if (host) return 'host';
+      if (client) return 'client';
+      return 'orphan';
+    };
+
+    for (const file of sourceFiles(srcDir)) {
+      scanned += 1;
+      const rel = relative(pkg.dir, file);
+      const text = readFileSync(file, 'utf8');
+
+      for (const match of text.matchAll(IMPORT)) {
+        const specifier = match[1] ?? match[2];
+        if (specifier === undefined) continue;
+
+        if (specifier.startsWith('@deepseek-ai/')) {
+          if (isSeedSpecifier(specifier) && sideOf(file) === 'client') {
+            seedUsers += 1;
+            continue;
+          }
+          if (isSeedSpecifier(specifier)) {
+            const side = sideOf(file);
+            const why =
+              side === 'both'
+                ? '这个文件**两个入口都到得了** —— 它会被拖进宿主产物'
+                : side === 'orphan'
+                  ? '这个文件两个入口都到不了（可能是死代码），证明不了它只在客户端侧'
+                  : '这个文件在宿主侧可达';
+            problems.push(
+              `${name}: ${rel} 里 import 了 ${specifier}（dsh 的浏览器包，是平台种子词）—— ${why}，` +
+                `而它只在浏览器侧存在。把它挪到只被 faces.client 可达的文件里`,
+            );
+            continue;
+          }
+          problems.push(
+            `${name}: ${rel} 里 import 了 ${specifier} —— 它不是平台种子词，模块表里没有它，` +
+              `浏览器侧要用 dsh 的组件只能 import 种子词那几个（ADR-0028）；其余平台契约按需自己声明`,
+          );
           continue;
         }
-        if (isSeedSpecifier(specifier)) {
-          const side = sideOf(file);
-          const why =
-            side === 'both'
-              ? '这个文件**两个入口都到得了** —— 它会被拖进宿主产物'
-              : side === 'orphan'
-                ? '这个文件两个入口都到不了（可能是死代码），证明不了它只在客户端侧'
-                : '这个文件在宿主侧可达';
+        if (specifier === '@/app' || specifier.startsWith('@/app/')) {
           problems.push(
-            `${name}: ${rel} 里 import 了 ${specifier}（dsh 的浏览器包，是平台种子词）—— ${why}，` +
-              `而它只在浏览器侧存在。把它挪到只被 faces.client 可达的文件里`,
+            `${name}: ${rel} 里 import 了 ${specifier} —— 模块不许伸进外壳的入口/外壳层，只能走 kit 与 mount(deps)`,
           );
           continue;
         }
-        problems.push(
-          `${name}: ${rel} 里 import 了 ${specifier} —— 它不是平台种子词，模块表里没有它，` +
-            `浏览器侧要用 dsh 的组件只能 import 种子词那几个（ADR-0028）；其余平台契约按需自己声明`,
-        );
-        continue;
-      }
-      if (specifier === '@/app' || specifier.startsWith('@/app/')) {
-        problems.push(
-          `${name}: ${rel} 里 import 了 ${specifier} —— 模块不许伸进外壳的入口/外壳层，只能走 kit 与 mount(deps)`,
-        );
-        continue;
-      }
-      const cross = /^@\/modules\/([^/]+)\//.exec(specifier);
-      if (cross !== null && cross[1] !== unit) {
-        problems.push(
-          `${name}: ${rel} 里 import 了 ${specifier} —— 模块之间不许互相 import（另一个套件没装就没有这份源码）`,
-        );
-        continue;
-      }
-      const platform = /^@\/platforms\/([^/]+)\/(.+)$/.exec(specifier);
-      if (platform !== null && viaPlatform) {
-        problems.push(
-          `${name}: ${rel} 里 import 了 ${specifier} —— 这个模块已经改用平台包了，平台知识走包名` +
-            `（比如 @pagoda-dsh-workbench/platform-coding），不许再用 @/platforms/*`,
-        );
-      } else if (platform !== null && !existsSync(join(srcDir, 'platforms', `${platform[2]}.ts`))) {
-        problems.push(
-          `${name}: ${rel} 里 import 了 ${specifier}，但本包 src/platforms/${platform[2]}.ts 不存在 —— ` +
-            `平台知识要么放在自己包里的 src/platforms/，要么整个走平台包，两条只能选一条`,
-        );
+        const cross = /^@\/modules\/([^/]+)\//.exec(specifier);
+        if (cross !== null && cross[1] !== unit) {
+          problems.push(
+            `${name}: ${rel} 里 import 了 ${specifier} —— 模块之间不许互相 import（另一个套件没装就没有这份源码）`,
+          );
+          continue;
+        }
+        const platform = /^@\/platforms\/([^/]+)\/(.+)$/.exec(specifier);
+        if (platform !== null && viaPlatform) {
+          problems.push(
+            `${name}: ${rel} 里 import 了 ${specifier} —— 这个模块已经改用平台包了，平台知识走包名` +
+              `（比如 @pagoda-dsh-workbench/platform-coding），不许再用 @/platforms/*`,
+          );
+        } else if (platform !== null && !existsSync(join(srcDir, 'platforms', `${platform[2]}.ts`))) {
+          problems.push(
+            `${name}: ${rel} 里 import 了 ${specifier}，但本包 src/platforms/${platform[2]}.ts 不存在 —— ` +
+              `平台知识要么放在自己包里的 src/platforms/，要么整个走平台包，两条只能选一条`,
+          );
+        }
       }
     }
   }
-}
 
-if (problems.length > 0) {
-  console.error(`✖ 模块源码边界 ${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 的包）—— 没有源码要查边界'],
+      problems: [],
+    };
+  }
+  return {
+    status: 'pass',
+    notes: [
+      `${scanned} 个源文件 · 不伸进外壳 app/ · 不跨模块 · ` +
+        `平台知识要么在自己包里、要么走平台包（不许两样都有）· ` +
+        `dsh 的浏览器包只在客户端侧可用（${seedUsers} 处）`,
+    ],
+    problems: [],
+  };
 }
-
-console.log(
-  `✔ 模块源码边界通过：${scanned} 个源文件 · 不伸进外壳 app/ · 不跨模块 · ` +
-    `平台知识要么在自己包里、要么走平台包（不许两样都有）· ` +
-    `dsh 的浏览器包只在客户端侧可用（${seedUsers} 处）`,
-);

package/src/checks/standalone.mjs

@@ -1,3 +1,13 @@
+// 模块**离开外壳源码**也得能 build + typecheck（发布出去的是模块，用户手上没有本仓的 src）。
+//
+// 手法：把外壳的 `src/` 暂时改名藏起来，再对每个模块包跑它自己的 build 与 typecheck，
+// 最后无论成败都还原。藏起来还过不了 = 这条模块在用"只有本仓才有"的相对路径 / 别名 ——
+// 发布出去会散架。
+//
+// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。所以这里**不许**自己退出：
+// 仓外工作区（没有外壳源码）以前就是"提前成功退出"（退出码 0）—— 那会把排在后面的判据静默吞掉。
+
 import { execFileSync } from 'node:child_process';
 import { existsSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
@@ -5,33 +15,49 @@ import { discoverModulePackages, discoverPackages } from '../discover.mjs';
 
 const SHELL = '@dsh-workbench/core';
 
-const shell = discoverPackages({ root: process.cwd() }).find((pkg) => pkg.manifest.name === SHELL);
-const visible = shell === undefined ? undefined : join(shell.dir, 'src');
+export const title = '独立构建';
 
-if (visible === undefined || !existsSync(visible)) {
-  console.log(`✔ 独立构建：跳过 —— 本仓没有 ${SHELL} 的源码（"不许 @/ 指外壳"那条判据照旧在守）`);
-} else {
-  runStandalone(visible);
-}
+export async function run() {
+  const shell = discoverPackages({ root: process.cwd() }).find((pkg) => pkg.manifest.name === SHELL);
+  const visible = shell === undefined ? undefined : join(shell.dir, 'src');
+
+  if (visible === undefined || !existsSync(visible)) {
+    return {
+      status: 'skip',
+      notes: [`本仓没有 ${SHELL} 的源码（"不许 @/ 指外壳"那条判据照旧在守）`],
+      problems: [],
+    };
+  }
 
-function runStandalone(visible) {
   const modules = discoverModulePackages({ root: process.cwd() });
+  if (modules.length === 0) {
+    return {
+      status: 'skip',
+      notes: ['没有模块包（没有声明 dsh.workbench 的包）—— 没有可独立构建的对象'],
+      problems: [],
+    };
+  }
+
   const hidden = join(shell.dir, 'src.hidden');
+  if (existsSync(hidden)) {
+    return {
+      status: 'fail',
+      notes: [],
+      problems: [`上次没还原干净：${hidden} 还在，手动改名回去再跑。`],
+    };
+  }
 
   const restore = () => {
     if (existsSync(hidden) && !existsSync(visible)) renameSync(hidden, visible);
   };
-  process.on('SIGINT', () => {
+  // Ctrl-C 时也必须还原（进程被杀时 finally 不跑）：还原完把信号还回去，让默认行为收场。
+  const onInterrupt = () => {
     restore();
-    process.exit(130);
-  });
-
-  if (existsSync(hidden)) {
-    console.error(`上次没还原干净：${hidden} 还在，手动改名回去再跑。`);
-    process.exit(1);
-  }
+    process.removeListener('SIGINT', onInterrupt);
+    process.kill(process.pid, 'SIGINT');
+  };
+  process.on('SIGINT', onInterrupt);
 
-  const rows = [];
   const problems = [];
   renameSync(visible, hidden);
   try {
@@ -41,7 +67,6 @@ function runStandalone(visible) {
         if (pkg.manifest.scripts?.[script] === undefined) continue;
         try {
           execFileSync('pnpm', ['run', script], { cwd: pkg.dir, stdio: 'pipe' });
-          rows.push(`${name} ${script}: ✅`);
         } catch (error) {
           const output = `${error.stdout ?? ''}${error.stderr ?? ''}`;
           const first = output
@@ -50,20 +75,25 @@ function runStandalone(visible) {
             .slice(0, 2)
             .map((line) => line.trim())
             .join(' | ');
-          rows.push(`${name} ${script}: ❌`);
           problems.push(`${name} ${script} 在外壳源码不在场时失败 —— ${first.slice(0, 220)}`);
         }
       }
     }
   } finally {
     restore();
+    process.removeListener('SIGINT', onInterrupt);
   }
 
   if (problems.length > 0) {
-    console.error(`✖ 独立构建 ${problems.length} 条不过：`);
-    for (const problem of problems) console.error(`  · ${problem}`);
-    console.error('  （上面的清单就是"发布出去会散架"的地方：模块只许依赖已发布的接口）');
-    process.exit(1);
+    return {
+      status: 'fail',
+      notes: ['（上面的清单就是"发布出去会散架"的地方：模块只许依赖已发布的接口）'],
+      problems,
+    };
   }
-  console.log(`✔ 独立构建通过：${modules.length} 个模块包在外壳源码不在场时都能 build + typecheck`);
+  return {
+    status: 'pass',
+    notes: [`${modules.length} 个模块包在外壳源码不在场时都能 build + typecheck`],
+    problems: [],
+  };
 }

package/src/checks/style.mjs

@@ -1,3 +1,13 @@
+// 模块的样式归属：① 不许定义外壳前缀（`wb-*`）的规则；② 借用的 `wb-*` 类必须在契约里；
+// ③ `*.module.css` 的绑定不许指向不存在的类。
+//
+// 为什么：`wb-*` 是**全局**类名，两份同名规则按注入顺序互相覆盖，用户看到的是随机的那个；
+// CSS Modules 的哈希类名靠"同一份文件、同一个导出"配对，调用点拿到 undefined 时真机渲染成
+// `class="undefined"` —— 元素整片没样式，而且控制台一声不响。
+//
+// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
+
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -5,6 +15,9 @@ import { discoverModulePackages } from '../discover.mjs';
 
 const SHELL_SELECTOR = /(^|[\s,>+~])\.wb-[a-z0-9-]+/;
 const RULE = /\.wb-[a-z0-9-]+[^{}]*\{/;
+// 外链一律走 kit 的 `Link`：它自带的样式（正文色 / hover 下划线 / 12px / 那个外链小箭头）是唯一一份。
+// 手写 `<a>` / `h('a', …)` 拿到的是浏览器默认样式，而且每个人写的都不一样（这正是"同一个东西样式不一样"的来源）。
+const BARE_ANCHOR = /(h\(\s*['"]a['"]|jsx\(\s*['"]a['"]|<a[\s>])/;
 const CLASS_TOKEN = /(^|[^-\w])\.?(wb-[a-zA-Z0-9-]+)/g;
 // 契约 = 外壳**所有**声明了 `wb-*` 的样式表，不只是那份全局 `board.css`：
 // ADR-0029 要求组件的样式跟组件走，所以 `wb-card` / `wb-rows` / `wb-note` 这些已经搬进
@@ -21,6 +34,8 @@ const CONTRACT_FILES = [
   })(),
 ];
 
+export const title = '样式归属';
+
 function walk(dir, acc = []) {
   for (const entry of readdirSync(dir)) {
     if (entry === 'node_modules' || entry === 'dist') continue;
@@ -35,109 +50,133 @@ function isTestSource(file) {
   return /(^|[\\/])__tests__[\\/]/.test(file) || /\.test\.[cm]?tsx?$/.test(file);
 }
 
-const contract = CONTRACT_FILES.some((file) => existsSync(file))
-  ? new Set(
-      CONTRACT_FILES.filter((file) => existsSync(file)).flatMap((file) =>
-        Array.from(readFileSync(file, 'utf8').matchAll(CLASS_TOKEN), (match) => match[2]),
-      ),
-    )
-  : null;
+export async function run() {
+  const contract = CONTRACT_FILES.some((file) => existsSync(file))
+    ? new Set(
+        CONTRACT_FILES.filter((file) => existsSync(file)).flatMap((file) =>
+          Array.from(readFileSync(file, 'utf8').matchAll(CLASS_TOKEN), (match) => match[2]),
+        ),
+      )
+    : null;
 
-const problems = [];
-const borrowed = [];
-const modules = discoverModulePackages({ root: process.cwd() });
-for (const pkg of modules) {
-  for (const file of walk(pkg.dir)) {
-    if (!/\.(css|ts|tsx)$/.test(file)) continue;
-    let text;
-    try {
-      text = readFileSync(file, 'utf8');
-    } catch {
-      continue;
-    }
-    const lines = text.split('\n');
-    lines.forEach((line, index) => {
-      if (!RULE.test(line)) return;
-      const selector = line.slice(0, line.indexOf('{'));
-      if (!SHELL_SELECTOR.test(selector)) return;
-      problems.push(
-        `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 定义了外壳前缀的 CSS 规则 —— ${line.trim().slice(0, 100)}`,
-      );
-    });
-
-    if (contract === null || isTestSource(file)) continue;
-    if (!/\.tsx?$/.test(file)) continue;
-    lines.forEach((line, index) => {
-      for (const match of line.matchAll(CLASS_TOKEN)) {
-        const name = match[2];
-        if (line[match.index + match[0].indexOf(name) - 1] === '-') continue;
-        if (name.endsWith('-')) continue;
-        if (contract.has(name)) continue;
-        borrowed.push(
-          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 借用了 ${name}，契约里没有它 —— ${line.trim().slice(0, 100)}`,
+  const problems = [];
+  const borrowed = [];
+  const anchors = [];
+  const modules = discoverModulePackages({ root: process.cwd() });
+  for (const pkg of modules) {
+    for (const file of walk(pkg.dir)) {
+      if (!/\.(css|ts|tsx)$/.test(file)) continue;
+      let text;
+      try {
+        text = readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      const lines = text.split('\n');
+      lines.forEach((line, index) => {
+        if (!RULE.test(line)) return;
+        const selector = line.slice(0, line.indexOf('{'));
+        if (!SHELL_SELECTOR.test(selector)) return;
+        problems.push(
+          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 定义了外壳前缀的 CSS 规则 —— ${line.trim().slice(0, 100)}`,
         );
+      });
+
+      if (isTestSource(file)) continue;
+      if (!/\.tsx?$/.test(file)) continue;
+      if (contract !== null) {
+        lines.forEach((line, index) => {
+          if (!BARE_ANCHOR.test(line)) return;
+          anchors.push(
+            `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 手写了裸 <a> —— ` +
+              `外链一律用 kit 的 Link（新窗口、noopener、自带那个外链小箭头；样式只有这一份）：${line.trim().slice(0, 80)}`,
+          );
+        });
       }
-    });
+      lines.forEach((line, index) => {
+        for (const match of line.matchAll(CLASS_TOKEN)) {
+          const name = match[2];
+          if (line[match.index + match[0].indexOf(name) - 1] === '-') continue;
+          if (name.endsWith('-')) continue;
+          if (contract.has(name)) continue;
+          borrowed.push(
+            `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 借用了 ${name}，契约里没有它 —— ${line.trim().slice(0, 100)}`,
+          );
+        }
+      });
+    }
   }
-}
 
-const bindings = [];
-for (const pkg of modules) {
-  const defined = new Map();
-  for (const file of walk(pkg.dir)) {
-    if (!/\.module\.css$/.test(file)) continue;
-    const text = readFileSync(file, 'utf8').replace(/:global\([^)]*\)/g, '');
-    defined.set(file, new Set(Array.from(text.matchAll(/\.([A-Za-z][\w-]*)/g), (m) => m[1])));
-  }
-  for (const file of walk(pkg.dir)) {
-    if (!/\.tsx?$/.test(file) || isTestSource(file)) continue;
-    const text = readFileSync(file, 'utf8');
-    for (const hit of text.matchAll(/import\s+([A-Za-z_$][\w$]*)\s+from\s+'([^']*\.module\.css)'/g)) {
-      const bind = hit[1];
-      const names = defined.get(resolve(dirname(file), hit[2]));
-      if (names === undefined) continue;
-      for (const use of text.matchAll(new RegExp(`\\b${bind}\\.([A-Za-z_$][\\w$]*)`, 'g'))) {
-        if (names.has(use[1])) continue;
-        bindings.push(
-          `${pkg.manifest.name}: ${relative(pkg.dir, file)} 用了 ${bind}.${use[1]}，` +
-            `${relative(pkg.dir, resolve(dirname(file), hit[2]))} 里没有这个类`,
-        );
+  const bindings = [];
+  for (const pkg of modules) {
+    const defined = new Map();
+    for (const file of walk(pkg.dir)) {
+      if (!/\.module\.css$/.test(file)) continue;
+      const text = readFileSync(file, 'utf8').replace(/:global\([^)]*\)/g, '');
+      defined.set(file, new Set(Array.from(text.matchAll(/\.([A-Za-z][\w-]*)/g), (m) => m[1])));
+    }
+    for (const file of walk(pkg.dir)) {
+      if (!/\.tsx?$/.test(file) || isTestSource(file)) continue;
+      const text = readFileSync(file, 'utf8');
+      for (const hit of text.matchAll(/import\s+([A-Za-z_$][\w$]*)\s+from\s+'([^']*\.module\.css)'/g)) {
+        const bind = hit[1];
+        const names = defined.get(resolve(dirname(file), hit[2]));
+        if (names === undefined) continue;
+        for (const use of text.matchAll(new RegExp(`\\b${bind}\\.([A-Za-z_$][\\w$]*)`, 'g'))) {
+          if (names.has(use[1])) continue;
+          bindings.push(
+            `${pkg.manifest.name}: ${relative(pkg.dir, file)} 用了 ${bind}.${use[1]}，` +
+              `${relative(pkg.dir, resolve(dirname(file), hit[2]))} 里没有这个类`,
+          );
+        }
       }
     }
   }
-}
 
-if (bindings.length > 0) {
-  console.error(`✖ 样式绑定指向了 CSS 里不存在的类：${bindings.length} 处`);
-  for (const one of bindings) console.error(`  · ${one}`);
-  console.error(
-    '  （CSS Modules 的哈希类名靠"同一份文件、同一个导出"配对：调用点拿到的会是 undefined，' +
-      '真机上渲染成 class="undefined" —— 元素整片没样式，而且控制台一声不响）',
-  );
-  process.exit(1);
-}
+  if (bindings.length + problems.length + borrowed.length + anchors.length > 0) {
+    const notes = [];
+    if (bindings.length > 0) {
+      notes.push(
+        `${bindings.length} 处是「样式绑定指向了 CSS 里不存在的类」：（CSS Modules 的哈希类名靠"同一份文件、同一个导出"配对：` +
+          '调用点拿到的会是 undefined，真机上渲染成 class="undefined" —— 元素整片没样式，而且控制台一声不响）',
+      );
+    }
+    if (problems.length > 0) {
+      notes.push(
+        `${problems.length} 处是「模块不许定义外壳前缀的 CSS 规则」：（wb-* 是全局类名：两份同名规则按注入顺序互相覆盖，用户看到的是随机的那个）`,
+      );
+    }
+    if (borrowed.length > 0) {
+      notes.push(
+        `${borrowed.length} 处是「模块借用了契约里没有的 wb-* 类」：（契约是本仓 board.css：模块只许借它里面有的类。` +
+          '没有的那个要么是拼错/改了名漏改，要么本该进 board.css —— 空类名在真机上就是没样式，而且没人会报错）',
+      );
+    }
+    if (anchors.length > 0) {
+      notes.push(
+        `${anchors.length} 处是「手写了裸 <a>」：（外链用 kit 的 Link —— 样式只有一份，改一处全局一致；` +
+          '裸 <a> 拿到的是浏览器默认样式，看着和卡片其它地方不是一套）',
+      );
+    }
+    // 四类问题各自成串，按原来的输出顺序（绑定 → 规则 → 借用 → 裸 <a>）拼在一起。
+    return { status: 'fail', notes, problems: [...bindings, ...problems, ...borrowed, ...anchors] };
+  }
 
-if (problems.length > 0) {
-  console.error(`✖ 模块不许定义外壳前缀的 CSS 规则：${problems.length} 处`);
-  for (const problem of problems) console.error(`  · ${problem}`);
-  console.error('  （wb-* 是全局类名：两份同名规则按注入顺序互相覆盖，用户看到的是随机的那个）');
-  process.exit(1);
-}
+  if (modules.length === 0) {
+    return {
+      status: 'skip',
+      notes: ['没有模块包（没有声明 dsh.workbench 的包）—— 没有样式要查归属'],
+      problems: [],
+    };
+  }
 
-if (borrowed.length > 0) {
-  console.error(`✖ 模块借用了契约里没有的 wb-* 类：${borrowed.length} 处`);
-  for (const one of borrowed) console.error(`  · ${one}`);
-  console.error(
-    '  （契约是本仓 board.css：模块只许借它里面有的类。没有的那个要么是拼错/改了名漏改，' +
-      '要么本该进 board.css —— 空类名在真机上就是没样式，而且没人会报错）',
-  );
-  process.exit(1);
+  const contractNote =
+    contract === null
+      ? '契约文件不在（这次只查了"模块不许定义 wb-*"）'
+      : `借用的类都在契约里（board.css + 外壳组件自己的样式表）`;
+  return {
+    status: 'pass',
+    notes: [`${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则；${contractNote}`],
+    problems: [],
+  };
 }
-
-const contractNote =
-  contract === null
-    ? '契约文件不在（这次只查了"模块不许定义 wb-*"）'
-    : `借用的类都在契约里（board.css + 外壳组件自己的样式表）`;
-console.log(
-  `✔ 样式归属清楚：${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则；${contractNote}`,
-);

package/src/css-injection.mjs

@@ -0,0 +1,27 @@
+// `*.module.css` / `.css` 落到页面上的那一小段代码：构建时生成，随模块的 client.js 发出去。
+//
+// 为什么是"有就改写"、而不是"没有才插入"（2026-10-11 实测）：
+// 去重的 key（`<文件名>:<绝对路径>`）与类名哈希（`sha1(相对路径)`）都只跟**文件路径**有关，
+// 跟 CSS 内容无关。于是热更新重新执行这段代码时，页面里**已经有一份同 key 的 <style>**：
+//   · 旧写法 `if (querySelector(...) === null) { 新建 + append }` → 直接跳过 → 新 CSS 写不进去
+//     （症状一："改了没变"）；而**新增 / 改名的类**在新 bundle 里被引用、旧表里没有规则 →
+//     那个元素掉样式（症状二）；外壳重新挂载时它自己的 <style> 会挪到后面，同特异性的规则
+//     谁赢也跟着变（症状三）。合起来就是用户嘴里的"有时候热更新样式会乱"。
+//   · 现在：有就改写 textContent，没有才插入 —— 幂等，且节点位置不动（顺序不漂），
+//     顺手用"内容不同才写"避开每次热更新的空改写。
+export function cssInjectionCode(key, css) {
+  return [
+    `const css = ${JSON.stringify(css)};`,
+    `const key = ${JSON.stringify(key)};`,
+    "if (typeof document !== 'undefined') {",
+    "  const selector = 'style[data-dsh-wb-css=\"' + key + '\"]';",
+    "  const applied = document.querySelector(selector);",
+    "  const style = applied === null ? document.createElement('style') : applied;",
+    "  if (applied === null) {",
+    "    style.setAttribute('data-dsh-wb-css', key);",
+    "    document.head.appendChild(style);",
+    "  }",
+    "  if (style.textContent !== css) style.textContent = css;",
+    "}",
+  ].join('\n');
+}