@dsh-workbench/module-tools 0.2.9 → 0.2.10

package/package.json

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

package/src/checks/contracts.mjs

@@ -381,9 +381,100 @@ function probeCallOf(tool) {
   const required = Array.isArray(schema.required) ? schema.required : [];
   const args = {};
   for (const key of required) args[key] = placeholderOf(properties[key]);
+  if (Object.prototype.hasOwnProperty.call(properties, 'confirm')) args.confirm = true;
   return { arguments: args, shaped: true };
 }
 
+// 审批头行（dsh 那张卡的 `.headline`）的预算。
+//
+// 为什么要有这条：`.headline` 是**纯文本的一格**，没有 `white-space` —— 换行会被塌成空格，
+// 长句就不是"多几行"而是"一大坨"。三段都会落进那一格（外壳按 `明细 —— 问句 —— 附注` 拼）：
+//   · `approvalDetail` 的 zh/en  = 明细（模块写的"这次要动什么"，本该是一句短标题）
+//   · `question` 的 zh/en        = 问句（外壳拼在明细后面的那句"允许吗"）
+//   · `fallback` 的 zh/en        = 兜底整句（明细缺失时顶上来）
+// 长内容（文件路径 / diff / 列表 / 正文 / 多字段）该走模块的 `approval.render`：
+// 那是卡上**另一格**（`conversation.approval.detail`），有排版、能换行、能画 diff。
+// 实测（2026-10-16 一条真实审批卡）：明细里塞了一整条 commit message、问句 77 字、附注 75 字，
+// 屏幕上 5 行 300 字。
+export const HEAD_BUDGETS = { detail: 20, question: 40, fallback: 40 };
+
+// 英文那一侧只用来抓"真正的一坨"：按中文的 3 倍算。长度主要看中文那侧（用户读的是它），
+// 实测同一句的英文是中文的 2.2–2.8 倍（machine 直译的风格），按 2 倍算会把正常英文问句全判红。
+const EN_RATIO = 3;
+
+// 长度预算是**两轮**的：
+//   · 第 1 轮（占位短值，见 probeCallOf）：紧预算 —— 头行本来就该是一句短句；
+//   · 第 2 轮（长值，见 budgetProbeOf）：宽 3 倍 —— 专抓"把可变长字段塞进头行"。
+//    宽 3 倍是故意的：对象名、文件名这类标识符本来就有长有短，不该因为"名字长"判红；
+//    而一条 commit message、一段正文（60 字）塞进标题，3 倍也照样兜不住 —— 那才是要抓的。
+const LONG_SCALE = 3;
+
+// 只按必填项造的探针（`probeCallOf`）给的是**占位短值**（`probe` / `1` / `true`）——
+// 于是"把可变长字段塞进头行"这件事它是**瞎的**：实测那条真实审批卡的明细是
+// `改对象文件：对象「diep-dify」的「tencent-test-values.yaml」 仓库：helm 提交信息：<一整条 commit message>`（157 字），
+// 而探针上只有 20 字（`probe`）⇒ 判据照绿。所以第 2 轮把**自由文本字段**换成真长度（60 字）：
+// 名字里带 message / note / reason / body / text / content / comment / title / description / summary
+// 的字段（这些就是"人可以写一段话"的地方），其余 string（标识符）给 12 字的正常长度。
+const FREE_TEXT = /message|note|reason|body|text|content|comment|title|description|summary/i;
+const LONG_TEXT = '这里是一段真实长度的正文用来量头行预算不要把这种内容放进标题里'.repeat(2);
+const LONG_ID = '真实长度的名字十二个字';
+
+function budgetProbeOf(tool) {
+  const schema = tool?.parameters;
+  if (typeof schema !== 'object' || schema === null) return undefined;
+  const properties = typeof schema.properties === 'object' && schema.properties !== null ? schema.properties : {};
+  const args = {};
+  for (const [key, prop] of Object.entries(properties)) {
+    if (key === 'confirm') {
+      args.confirm = true;
+      continue;
+    }
+    if (Array.isArray(prop?.enum) && prop.enum.length > 0) args[key] = prop.enum[0];
+    else if (prop?.type === 'string') args[key] = FREE_TEXT.test(key) ? LONG_TEXT : LONG_ID;
+    else if (prop?.type === 'number' || prop?.type === 'integer') args[key] = 1;
+    else if (prop?.type === 'boolean') args[key] = true;
+    else if (prop?.type === 'array') args[key] = [];
+    else if (prop?.type === 'object') args[key] = {};
+  }
+  return args;
+}
+
+function headlineProblemsOf(name, toolName, verdict, facts, when = '', scale = 1) {
+  const problems = [];
+  const blocked = facts !== undefined && 'blocked' in facts;
+  const hasDetail = facts !== undefined && !blocked;
+  const segments = [
+    ['明细（approvalDetail）', 'detail', hasDetail ? text(facts.zh) : '', hasDetail ? text(facts.en) : ''],
+    ['问句（question）', 'question', text(verdict?.question?.zh), text(verdict?.question?.en)],
+    ['兜底句（fallback）', 'fallback', text(verdict?.fallback?.zh), text(verdict?.fallback?.en)],
+  ];
+  for (const [label, key, zh, en] of segments) {
+    if (zh === '' && en === '') continue;
+    if (/\n|\r/.test(zh) || /\n|\r/.test(en)) {
+      problems.push(
+        `${name}: 写工具 ${toolName} 的${label}${when}里有换行 —— 审批头行是纯文本、没有 white-space，` +
+          `换行会被塌成空格，屏幕上就是一坨。压成一句，长内容放 approval.render（卡上那一格详情）`,
+      );
+    }
+    const cap = HEAD_BUDGETS[key] * scale;
+    const enCap = Math.round(cap * EN_RATIO);
+    if (zh.length > cap) {
+      problems.push(
+        `${name}: 写工具 ${toolName} 的${label}${when}太长（${zh.length} 字 > 预算 ${cap} 字）：「${zh}」—— ` +
+          `头行三段各有预算（明细 ≤${HEAD_BUDGETS.detail} / 问句 ≤${HEAD_BUDGETS.question} / ` +
+          `兜底句 ≤${HEAD_BUDGETS.fallback} 字），其余（列表 / 正文 / 多字段 / 可变长内容）放进 approval.render 那一格`,
+      );
+    }
+    if (en.length > enCap) {
+      problems.push(
+        `${name}: 写工具 ${toolName} 的${label}${when}（英文）太长（${en.length} 字符 > 预算 ${enCap}）：「${en}」—— ` +
+          `英文侧按中文的 ${EN_RATIO} 倍算，超了同样挪进 approval.render`,
+      );
+    }
+  }
+  return problems;
+}
+
 function installed(specifier, from) {
   try {
     createRequire(join(from, 'package.json')).resolve(`${packageOf(specifier)}/package.json`);
@@ -429,6 +520,7 @@ export async function run() {
   // 判据"看到了但下不了结论"的那些，写进 notes（红绿两边都印）——
   // 与其给一个撑不住的 verdict，不如把作者该自己确认的那一件事说清楚（ADR-0038 §6.15）。
   const probeNotes = [];
+  const headlineNotes = [];
   let declared = 0;
   let modules = 0;
 
@@ -894,6 +986,44 @@ export async function run() {
           ('blocked' in facts
             ? text(facts.blocked) !== ''
             : text(facts.zh) !== '' && text(facts.en) !== '');
+        problems.push(...headlineProblemsOf(name, tool.name, verdict, facts));
+        // 第二轮：**长值**探（把声明里的 string 都填成 40 字正文、可选字段也填上），
+        // 专抓"标题里带了可变长字段"—— 第一轮用的是占位短值，对这件事是瞎的（见 budgetProbeOf）。
+        const longArgs = budgetProbeOf(registered.get(tool.name));
+        if (longArgs !== undefined) {
+          const longCall = { ...call, arguments: longArgs };
+          let longVerdict;
+          try {
+            longVerdict = mounted.needsApproval(longCall);
+          } catch {
+            longVerdict = undefined;
+          }
+          if (longVerdict?.kind === 'ask') {
+            let longFacts;
+            try {
+              longFacts = await mounted.approvalDetail?.(longCall);
+            } catch {
+              longFacts = undefined;
+            }
+            problems.push(
+              ...headlineProblemsOf(
+                name,
+                tool.name,
+                longVerdict,
+                longFacts,
+                '（把自由文本字段填上真实长度之后）',
+                LONG_SCALE,
+              ),
+            );
+          }
+        }
+        if (facts === undefined || 'blocked' in facts) {
+          headlineNotes.push(
+            `${name}: 写工具 ${tool.name} 的 approvalDetail 在合成调用上没有明细（要真的计划/预览过才有）—— ` +
+              `头行预算只验到问句与兜底句那一截；明细那一句作者自己按「一句话、≤${HEAD_BUDGETS.detail} 字」看一眼：` +
+              `超了就把长内容放进 approval.render 那一格`,
+          );
+        }
         if (!described) {
           problems.push(
             `${name}: 写工具 ${tool.name} 的 needsApproval 对合成调用回了 ask（要点头），` +
@@ -942,7 +1072,7 @@ export async function run() {
   }
 
   if (problems.length > 0) {
-    const notes = [`${declared} 个带 dsh 声明的包，其中 ${modules} 个模块`, ...probeNotes];
+    const notes = [`${declared} 个带 dsh 声明的包，其中 ${modules} 个模块`, ...probeNotes, ...headlineNotes];
     // 落不到图里最常见的成因不是"声明写错"，而是"这个包不在任何 workspace 里"（裸目录里 init
     // 出来的骨架）。不点出来的话，屏幕上的话会把责任推给那两条声明，而真正该做的是换到工坊里跑。
     const bare = [...unresolvedIn].filter(barePackage);
@@ -964,6 +1094,7 @@ export async function run() {
       '（test 不在这儿跑：状态级的东西在模块自己的 vitest 里 —— 四个脚本自己跑一遍）',
       `单元：${unitList}`,
       ...probeNotes,
+      ...headlineNotes,
     ],
     problems: [],
   };