@dsh-workbench/module-tools 0.3.10 → 0.3.11

package/README.md

@@ -23,8 +23,8 @@ dsh-wb-module publish               # 发货前的清单：门禁 + 三张表 +
 |---|---|
 | `contracts` | 模块契约：单元 id 唯一、两个面、四个脚本、`files`、peer 下限；以及**清单 ↔ 代码**（真正注册的工具）与**底稿 ↔ 清单**（`design.json` 的能力名）两处对账（见下） |
 | `protocol` | 模块声明协议：`dsh.workbench` 的 `apiVersion` 要在、静态半形状要对、不许有协议不认识的键（`scope` 现在**就是**不认识的键之一 —— 见下） |
-| `bundles` | 产物边界：宿主面里不许出现浏览器侧的东西；浏览器产物里不许出现**内联的外壳 CSS**（模块从 `@dsh-workbench/shared` 根入口取运行期值就会这样）；**产物里出现夹具标记（`wbMock` / `MockStrip` / `useFixturePick` / `-mock'` / `SCENES`…）判红** —— 模块不带夹具：夹具只服务工作台开发者的调试，模块自己的 vitest 把几态各喂一遍就够 |
-| `source` | 源码边界：不直接引 dsh 的包、不引不是种子词的 `@deepseek-ai/*` |
+| `bundles` | 产物边界：宿主面里不许出现浏览器侧的东西；浏览器产物里不许出现**内联的外壳 CSS**（构建会把来自 `@dsh-workbench/shared` / `core` 的 CSS 丢掉，这里是兜底：漏进来一条就说明构建那条闸被绕过了）；**产物里出现夹具标记（`wbMock` / `MockStrip` / `useFixturePick` / `-mock'` / `SCENES`…）判红** —— 模块不带夹具：夹具只服务工作台开发者的调试，模块自己的 vitest 把几态各喂一遍就够 |
+| `source` | 源码边界：不直接引 dsh 的包、不引不是种子词的 `@deepseek-ai/*`；**共享包的两个入口按运行时分开** —— 根入口（浏览器 barrel）**只许 `import type`**（取运行值：浏览器侧会打进第二份实例、宿主侧会让 `dist/host.js` 在 Node 里 import 不进来）；`/host` 只许**宿主侧**取运行值（里面有 `node:crypto` / `node:fs`） |
 | `primitives` | dsh 原语只从模块表（`kit`）拿 |
 | `kit` | 这份外壳的 kit 成员到底有哪些（缺什么会当场点名） |
 | `cards` | 卡片渲染：**八态 × zh/en 各渲一遍**（外壳侧输入 idle / loading / loading-刷新保留旧值（含旧时间戳 `at`）/ ready / ready-空容器 / unreadable-error / unreadable-能力闸缺插件 / unreadable-能力闸缺命令；`useApiResource` 与 `useCapabilityGate` 由判据喂，`useUnitBoard` 用模块仓里装的那份**真壳**）—— 不许抛、不许空白、文字里不许出现 `undefined` / `NaN` / `[object Object]` / `null`、不许裸键名、要套外壳的卡壳、清单 `titleKey` 在两语字典里都有落点。**不断言"画的是哪一态那一屏"**（那归模块自己的逐态测试与 `design.json` 状态矩阵）；模块没装外壳时逐态那半跳过、单次全桩渲染照旧跑 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,7 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
     "typescript-eslint": "^8.71.0",
-    "@dsh-workbench/shared": "0.3.10"
+    "@dsh-workbench/shared": "0.3.11"
   },
   "scripts": {
     "selfcheck": "node scripts/selfcheck/index.mjs"

package/src/checks/contracts.mjs

@@ -964,6 +964,9 @@ export async function run() {
         // `{ kind: 'ask', reason, question{zh,en}, fallback{zh,en} }`（要问，且问得清）。
         // 别的返回值（**包括 undefined**）外壳会当场 deny —— 那才是要拦的。
         const read = verdict?.kind === 'read';
+        // deny（ADR-0032 第五态）：套件说"这一通根本跑不成" —— 外壳在备料之前就拒，连问都不问。
+        // 合成调用上它合法，但和 read 一样验不到"真的调用会不会问"，进 notes 让作者自己确认。
+        const deny = verdict?.kind === 'deny' && text(verdict.reason) !== '';
         const ask =
           verdict?.kind === 'ask' &&
           text(verdict.reason) !== '' &&
@@ -971,19 +974,20 @@ export async function run() {
           text(verdict.question?.en) !== '' &&
           text(verdict.fallback?.zh) !== '' &&
           text(verdict.fallback?.en) !== '';
-        if (!read && !ask) {
+        if (!read && !deny && !ask) {
           problems.push(
             `${name}: 工具 ${tool.name} 的清单里写着 writes:true，但 needsApproval 对合成调用 ` +
               `${JSON.stringify(call.arguments)} 没给出合法口径 —— ` +
-              `要么 { kind: 'read' }（这件事不用问），要么 { kind: 'ask', reason, question: {zh,en}, ` +
+              `要么 { kind: 'read' }（这件事不用问），要么 { kind: 'deny', reason }（这一通根本跑不成，` +
+              `理由原样交给 agent），要么 { kind: 'ask', reason, question: {zh,en}, ` +
               `fallback: {zh,en} }（要问，且问得清）。别的返回值外壳会当场 deny${cannotShape}`,
           );
           continue;
         }
-        // read：这次调用不用点头。**不查 approvalDetail** —— 外壳在 read 时也不会去问它
+        // read / deny：这次调用不用点头。**不查 approvalDetail** —— 外壳在这两档都不会去问它
         // （`approvalFor` 只在 verdict 是 ask 时才调 detailOf）。合成调用本来就不是一次真实写入，
         // 拿它逼模块给"这次会发生什么"就是让判据替外壳问一个外壳不会问的问题。
-        if (read) {
+        if (read || deny) {
           readOnProbe.push(tool.name);
           continue;
         }
@@ -1046,8 +1050,8 @@ export async function run() {
       }
       if (readOnProbe.length > 0) {
         probeNotes.push(
-          `写工具 ${readOnProbe.join(' / ')} 按合成调用回了"这次不用问"（kind: 'read'）—— ` +
-            `判据只能验到这一步：它是不是"参数里带 confirm 才真的写"那种**合法**口径，` +
+          `写工具 ${readOnProbe.join(' / ')} 按合成调用回了"这次不用问"（kind: 'read' 或 'deny'）—— ` +
+            `判据只能验到这一步：它是不是"参数里带 confirm 才真的写" / "这一通真跑不成"那种**合法**口径，` +
             `合成调用看不出来（必填项给的是占位值，不是真实写入参数）。作者自己确认一次：` +
             `真的调用会不会 ask、ask 时 approvalDetail 说没说清`,
         );

package/src/checks/source.mjs

@@ -13,6 +13,17 @@
 // 装机预检与外壳都不读它。所以这里必须拿**源码**入口 —— 从产物 dist/host.js 反推不出是哪一份源码
 // 把 dsh 的包拖进来的。
 //
+// 共享包（`@dsh-workbench/shared`）的**两个入口也是两个运行时**，这里守它的「运行值」边界：
+//   · 根入口 `.` 是浏览器 barrel（组件 + 它们自己的样式）。**两侧都不许从它取运行值**：
+//     浏览器侧该走 kit（`@dsh-workbench/core/client`，单例只有那一份），宿主侧该走 `/host` ——
+//     根 barrel 会在 `dist/host.js` 里把 dsh 的浏览器件一路拉进来，Node 里 import 不进来（实测）。
+//   · 宿主入口 `/host` 里有 node:crypto / node:fs，**只有宿主侧能引**；浏览器产物装不下。
+//   · 类型是例外：`import type` / `export type`（含逐个 `type X`）编译期擦除，两侧随便引 ——
+//     契约类型（`Translate` / `ApiError` / `UnitClientFace` …）正是从根入口拿的。
+//
+// 为什么这一条住在**源码**判据里：它要知道"这个文件属于哪一侧"，而侧只能从两个源码入口做可达性分析
+// 得到（产物里看不出是哪份源码把东西拖进来的）。判据的负例在 `scripts/selfcheck/checks/negative-probe.mjs`。
+//
 // 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
 // 打印与退出码归 `../check.mjs` 那一层。
 
@@ -25,6 +36,65 @@ import { isSeedSpecifier } from '../seed.mjs';
 // 模块入口常见写法是 `await import('./views/…')`，漏了就会把可达文件判成"死代码"。
 const IMPORT = /from\s*'([^']+)'|import\s*\(?\s*'([^']+)'/g;
 
+// 共享包那两条规则要分清「取运行值」与「只取类型」，所以按**整条语句**匹配（`import { a }` 与
+// `import type { A }` 的差别在语句开头与花括号里）。片段里不许出现引号或分号：否则一条 `import type`
+// 会把后面那条运行值 import 一起吞进来，判据就漏了。
+const SHARED_FROM =
+  /(?:^|[;}\s])(import|export)\s+(type\s+)?([^'";]{0,600}?)\s*from\s*['"](@dsh-workbench\/shared(?:\/host)?)['"]/g;
+// 动态 `import('…')` 一定是运行值（`import type` 没有这个写法）。
+const SHARED_DYNAMIC = /import\s*\(\s*['"](@dsh-workbench\/shared(?:\/host)?)['"]/g;
+
+/**
+ * 这条 import/export 是不是**只取类型**：`import type …`、`export type …`、
+ * 以及每个具名都带 `type` 的 `import { type A, type B }`。
+ * `import X, { type A }` / `import * as ns` / `export *` 都算运行值。
+ */
+function typeOnlyOf(keyword, clause) {
+  if (keyword !== undefined) return true;
+  const braces = /\{([\s\S]*)\}/.exec(clause);
+  if (braces === null) return false;
+  if (clause.slice(0, braces.index).replace(/[,\s]/g, '') !== '') return false;
+  const parts = braces[1]
+    .split(',')
+    .map((one) => one.trim())
+    .filter((one) => one !== '');
+  return parts.length > 0 && parts.every((one) => one.startsWith('type '));
+}
+
+const SIDE_TEXT = {
+  client: '客户端侧可达',
+  host: '宿主侧可达',
+  both: '两个入口都到得了',
+  orphan: '两个入口都到不了（可能是死代码）',
+};
+
+/** 共享包两个入口的「运行值」违规 → 一句人话（说清为什么、改哪、类型怎么引）。 */
+function sharedProblem(name, rel, specifier, side, dynamic) {
+  const what = dynamic ? `动态 import 了 ${specifier}` : `从 ${specifier} 取了运行值`;
+  if (specifier === '@dsh-workbench/shared') {
+    const fix =
+      side === 'host'
+        ? '宿主侧改从 @dsh-workbench/shared/host 引'
+        : side === 'client'
+          ? '浏览器侧改从 kit（@dsh-workbench/core/client）引；kit 里没有的，先看它是不是该补进 kit'
+          : side === 'both'
+            ? '这个文件两个入口都到得了：宿主要的走 /host、浏览器要的走 kit —— 两边的运行值挤在一个文件里就拆开'
+            : '这个文件两个入口都到不了（可能是死代码），证明不了它在哪一侧；挪进真正的面再引';
+    return (
+      `${name}: ${rel} 里${what} —— 根入口是浏览器 barrel` +
+      `（组件 + 它们自己的样式），两侧都不该从这里取运行值：浏览器侧会打进第二份实例、宿主侧会让 ` +
+      `dist/host.js 在 Node 里 import 不进来（实测：一路拉到 dsh 的浏览器件）。${fix}。` +
+      `只取类型就写 \`import type\`（编译期擦除、两侧都行）`
+    );
+  }
+  if (side === 'host') return undefined;
+  return (
+    `${name}: ${rel} 里${what} —— 宿主入口里有 node:crypto / node:fs，` +
+    `只有宿主侧能引（这个文件${SIDE_TEXT[side]}）；浏览器产物装不下它。` +
+    `浏览器侧要的纯函数走 kit（@dsh-workbench/core/client）或自己写一个；只取类型就写 \`import type\``
+  );
+}
+
 function sourceFiles(dir, acc = []) {
   for (const entry of readdirSync(dir)) {
     const full = join(dir, entry);
@@ -189,6 +259,17 @@ export async function run() {
           );
         }
       }
+
+      // 共享包的两个入口：根入口只许取类型、宿主入口只许宿主侧取运行值（理由见文件头）。
+      for (const match of text.matchAll(SHARED_FROM)) {
+        if (typeOnlyOf(match[2], match[3])) continue;
+        const problem = sharedProblem(name, rel, match[4], sideOf(file), false);
+        if (problem !== undefined) problems.push(problem);
+      }
+      for (const match of text.matchAll(SHARED_DYNAMIC)) {
+        const problem = sharedProblem(name, rel, match[1], sideOf(file), true);
+        if (problem !== undefined) problems.push(problem);
+      }
     }
   }
 
@@ -207,7 +288,8 @@ export async function run() {
     notes: [
       `${scanned} 个源文件 · 不伸进外壳 app/ · 不跨模块 · ` +
         `平台知识要么在自己包里、要么走平台包（不许两样都有）· ` +
-        `dsh 的浏览器包只在客户端侧可用（${seedUsers} 处）`,
+        `dsh 的浏览器包只在客户端侧可用（${seedUsers} 处）· ` +
+        `共享包根入口只取类型、/host 只在宿主侧取运行值`,
     ],
     problems: [],
   };

package/template-diy/src/messages.ts.tpl

@@ -3,9 +3,9 @@ export const messages = {
     '__UNIT__.cardTitle': '目录概览',
     '__UNIT__.needProject': '先打开一个项目',
     '__UNIT__.loading': '正在读目录…',
-    '__UNIT__.loadingHint': '宿主侧真读盘：文件数 / 目录数 / 总字节 / 最大的几个文件',
+    '__UNIT__.loadingHint': '正在统计文件数、目录数与最大的几个文件',
     '__UNIT__.errorTitle': '读不到这个目录',
-    '__UNIT__.errorHint': '点右上角刷新重试；路径不存在、没权限、不是目录都会走到这里',
+    '__UNIT__.errorHint': '先确认这个目录还在、你也能读它，然后点右上角刷新重试',
     '__UNIT__.empty': '这个目录是空的：没有文件，也没有子目录',
     '__UNIT__.largest': '最大的几个文件',
     '__UNIT__.fileUnit': ' 个文件',
@@ -15,9 +15,9 @@ export const messages = {
     '__UNIT__.cardTitle': 'Directory overview',
     '__UNIT__.needProject': 'Open a project first',
     '__UNIT__.loading': 'Reading the directory…',
-    '__UNIT__.loadingHint': 'The host really reads the disk: files / dirs / bytes / largest files',
+    '__UNIT__.loadingHint': 'Counting files, folders, and the largest files',
     '__UNIT__.errorTitle': 'Cannot read this directory',
-    '__UNIT__.errorHint': 'Hit refresh in the header; a missing path, no permission, or a non-directory lands here',
+    '__UNIT__.errorHint': 'Check that the folder still exists and you can read it, then hit refresh in the header',
     '__UNIT__.empty': 'This directory is empty: no files and no subdirectories',
     '__UNIT__.largest': 'Largest files',
     '__UNIT__.fileUnit': ' files',