@dsh-workbench/module-tools 0.3.2 → 0.3.3

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/lint.mjs

@@ -0,0 +1,351 @@
+// 模块包的**语法卫生判据**（`check` 的第十三条）：把 eslint 跑在**模块自己的方言**上。
+//
+// 为什么模块包需要这一条：另外十二条判据里，结构那一半归 arch-guard（`./arch.mjs`），
+// 而"单文件语法卫生"那一半一条都没有 —— `as any` / `console` 残留 / `debugger` / 内联颜色 /
+// 手写 `!important` / 渲染期写 ref / 漏依赖，这些都不改变文件形状，结构判据永远看不见。
+// arch-guard 自己的 README 把这一半明确委派给了 eslint。
+//
+// 判据的口径（三条，与第十二条 `arch` 逐条对齐 —— 同一套承诺）：
+//   ① **只跑带 `eslint.config.mjs` 的模块**：没有那份文件就 `skip`（不适用），不是红。
+//      工坊里已经造好的模块（以及别的仓里已经发出去的模块）不会被这次升级炸掉 —— 补两行就上车。
+//   ② **判据不自己编规则**：它 import 模块那份配置，**逐块核对整份方言**（`../lint.mjs` 的
+//      `DIALECT_BLOCKS` 八块：名字 / `files` / `rules` 一处不一致就红；全局 ignores 按 `DIALECT_IGNORES`
+//      的**超集**比）再跑；规则与阈值都在 `../lint.mjs` 那一处。
+//      **残余**：模块自己 import 方言再照抄整份，判据分不出来 —— 这条的目标是"抬高门槛 +
+//      让改动必须明着写"，不是防住蓄意伪造（详见 `../lint.mjs` 文件头那段）。
+//   ③ **只把 `error` 算红**：`warn` 照外壳口径计数、不挡门禁（`eslint .` 也只对 error 退 1）；
+//      单跑（`--only lint`）时把 warn 逐条列出来（与 `--only kit` 列 kit 成员同一个约定）。
+//
+// ESLint 的**唯一构造处**也在这里（`lintPackage`）：判据与 `dsh-wb-module lint [--fix]` 共用它，
+// 于是"门禁跑的那份"与"命令跑的那份"在形状上不可能漂。**判据永远不动手改文件**：只有
+// `fix: true` 才会写回，而 `fix` 只从命令那条路进来（自检有负例钉着这一点）。
+//
+// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
+
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ESLint } from 'eslint';
+import { discoverModulePackages } from '../discover.mjs';
+import { DIALECT_BLOCKS, DIALECT_IGNORES, FINGERPRINT, dialectShapeOf, isGlobalIgnoresBlock } from '../lint.mjs';
+
+export const title = '模块代码卫生（eslint）';
+
+/** 上车标记：模块根有这份文件才被这条判据管（opt-in，与第十二条同一形状）。 */
+export const CONFIG_FILE = 'eslint.config.mjs';
+
+// 聚合跑时逐条列出的上限：一条模块可能带几百条 error，门禁那一屏不该被它刷掉、也不该只剩
+// 最后几条 —— 截断 + 一句"还有 N 条"（单跑 `--only lint` 时不截断：那时你就是来看全的）。
+const MAX_PROBLEMS = 40;
+
+// "怎么上车"那句话只写一遍：skip 的提示与方言对不上的人都该看见它。
+// 不提本仓内部路径（`src/lint.mjs` 那句）：这份提示会随 skill 文档发给用户，用户手上只有
+// 装出来的那个包。方言与阈值随 `@dsh-workbench/module-tools` 同代。
+const HOW_TO_JOIN =
+  `在模块包里放一份 ${CONFIG_FILE}，内容两行就够（与模板里那份逐字一致）：\n` +
+  `    import { moduleLint } from '@dsh-workbench/module-tools/lint';\n` +
+  '    export default moduleLint({ rootDir: import.meta.dirname });\n' +
+  '  `rootDir` 是给 typescript-eslint 钉 tsconfigRootDir 的（一个进程里同时有多份 eslint 配置时必需；\n' +
+  '  模块自己单独跑一份配置时可以省）。规则与阈值只有这一份（随 @dsh-workbench/module-tools 同代）；\n' +
+  '  要开口子就从 moduleLint({ ignores, rules, rootDir }) 的参数进。';
+
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+
+// 一行一条：把消息压成单行再截断。react-hooks 那几条的 message 里带**整段代码框**（多行），
+// 原样倒出来会把"逐条"变成几十行、`·` 前缀也只挂在第一行；前面那句结论（"Cannot call impure
+// function during render"）才是要看的东西，所以压平 + 截断。
+const TEXT_LIMIT = 200;
+function oneLine(text) {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > TEXT_LIMIT ? `${flat.slice(0, TEXT_LIMIT)}…` : flat;
+}
+
+/** 一行人话：`名字: 文件:行:列 规则 —— 一句话`（规则缺了就是解析错误 —— 那也是要立刻看见的）。 */
+function lineOf(name, dir, result, message) {
+  const line = message.line ?? 1;
+  const column = message.column ?? 1;
+  const where = `${name}: ${relative(dir, result.filePath)}:${String(line)}:${String(column)}`;
+  const rule = message.ruleId ?? '解析错误';
+  return `${where} ${rule} —— ${oneLine(message.message)}`;
+}
+
+/** 方言那几块的名字（基础块 + 四块 `dsh-wb/module-lint*`）+ 全局 ignores 那一块 —— 认"有没有方言痕迹"。 */
+const DIALECT_NAMES = new Set(DIALECT_BLOCKS.map((block) => block.name));
+
+function isDialectNamed(block) {
+  return (
+    block !== null &&
+    typeof block === 'object' &&
+    typeof block.name === 'string' &&
+    (DIALECT_NAMES.has(block.name) || block.name.startsWith(`${FINGERPRINT}/`))
+  );
+}
+
+/** 配置里有没有一点方言的痕迹（全局 ignores 那一块 / 方言那几块）—— 用来区分"没上车"与"改坏了"。 */
+function hasDialectTrace(config) {
+  return config.some((block) => isGlobalIgnoresBlock(block) || isDialectNamed(block));
+}
+
+/** 配置里所有全局 ignores 块的 glob 并集（方言那一块 + 模块自己追加的，可能有不止一块）。 */
+function globalIgnoresOf(config) {
+  const globs = new Set();
+  for (const block of config) {
+    if (block !== null && typeof block === 'object' && isGlobalIgnoresBlock(block)) {
+      for (const glob of block.ignores) globs.add(glob);
+    }
+  }
+  return globs;
+}
+
+/** 两份 rules 差在哪：少了哪些 / 多了哪些 / 哪些值被改了（形状已键排序，逐键比即可）。 */
+function rulesDivergenceOf(expected, actual) {
+  const gone = Object.keys(expected).filter((rule) => !(rule in actual));
+  const extra = Object.keys(actual).filter((rule) => !(rule in expected));
+  const changed = Object.keys(expected).filter(
+    (rule) => rule in actual && JSON.stringify(expected[rule]) !== JSON.stringify(actual[rule]),
+  );
+  const parts = [];
+  if (gone.length > 0) parts.push(`少了 ${gone.join('、')}`);
+  if (extra.length > 0) parts.push(`多了 ${extra.join('、')}`);
+  if (changed.length > 0) parts.push(`改了 ${changed.join('、')}`);
+  return parts.join('；');
+}
+
+/**
+ * **逐块比**方言（这一期 hardening 的核心）：`moduleLint()` 产出的**整份方言**，模块那份配置里
+ * 必须一块不少、且名字 / `files` / `rules` 逐项一致；全局 ignores 那一块按**超集**比（多忽略
+ * 可以、少忽略点名）。
+ *
+ * 为什么不能只比"有没有那个名字"：2026-10-19 verifier 造出
+ * `export default [{ name: 'dsh-wb/module-lint', rules: {} }]` —— 只比名字时它给 ✔ 0 error，
+ * 而"方言只有一份、下限不能被悄悄删"正是这条判据的立论。同名多块也判红：扁平配置里**只有
+ * 最后一块算数**，"留一块好的、再追加一块掏空的"同样是把下限删掉。
+ *
+ * 为什么后来把基础块也收进来：只比 `dsh-wb/module-lint*` 那 4 块时，verifier 量到的残余有**两种
+ * 筛法**：`moduleLint().filter((b) => b.name !== undefined)` 筛掉的是**唯一没有名字**的那块（全局
+ * ignores 不能带 `name`）；基础块（`@eslint/js/recommended` 与三块 `typescript-eslint/*`，**都带
+ * 名字**）则要**显式点名**（`(b) => b.name !== '@eslint/js/recommended'` 这种）才筛得掉 ——
+ * 两种都是"下限被悄悄删"。
+ */
+function dialectDivergences(config) {
+  const blocks = config.filter((block) => block !== null && typeof block === 'object');
+  const problems = [];
+
+  const missingGlobs = DIALECT_IGNORES.filter((glob) => !globalIgnoresOf(config).has(glob));
+  if (missingGlobs.length > 0) problems.push(`少了全局 ignores（缺 ${missingGlobs.join('、')}）`);
+
+  for (const expected of DIALECT_BLOCKS) {
+    const same = blocks.filter((block) => block.name === expected.name);
+    if (same.length === 0) {
+      problems.push(`少了「${expected.name}」那一块`);
+      continue;
+    }
+    if (same.length > 1) {
+      problems.push(`「${expected.name}」出现了 ${String(same.length)} 次（同名块只有最后一块算数）`);
+      continue;
+    }
+    const actual = dialectShapeOf(same[0]);
+    if (JSON.stringify(actual.files) !== JSON.stringify(expected.files)) {
+      problems.push(`改了「${expected.name}」那一块的 files`);
+      continue;
+    }
+    const rules = rulesDivergenceOf(expected.rules, actual.rules);
+    if (rules !== '') problems.push(`改了「${expected.name}」那一块的 rules（${rules}）`);
+  }
+  return problems;
+}
+
+async function loadConfig(pkg) {
+  const file = join(pkg.dir, CONFIG_FILE);
+  let module_;
+  try {
+    module_ = await import(pathToFileURL(file).href);
+  } catch (error) {
+    return {
+      error:
+        `${pkg.manifest.name}: ${CONFIG_FILE} 跑不起来 —— ${messageOf(error)}` +
+        '（先确认这份配置能 import、没有语法错，再确认它 import 的东西在工坊里解析得到）',
+    };
+  }
+
+  const config = module_.default;
+  if (!Array.isArray(config)) {
+    return {
+      error:
+        `${pkg.manifest.name}: ${CONFIG_FILE} 的默认导出不是 flat config 数组 —— ` +
+        `这份配置不是 moduleLint() 来的。\n  ${HOW_TO_JOIN}`,
+    };
+  }
+  if (!hasDialectTrace(config)) {
+    return {
+      error:
+        `${pkg.manifest.name}: ${CONFIG_FILE} 里没有 ${FINGERPRINT} 那几块 —— ` +
+        `这份配置不是 moduleLint() 来的（要加规则请展开 moduleLint() 再追加一块，别手写一份自己的方言）。` +
+        `\n  ${HOW_TO_JOIN}`,
+    };
+  }
+  const diverged = dialectDivergences(config);
+  if (diverged.length > 0) {
+    return {
+      error:
+        `${pkg.manifest.name}: ${CONFIG_FILE} 里的方言与 moduleLint() 产出的不一致 —— ` +
+        `${diverged.join('；')}。要开口子请走 moduleLint({ rules, ignores })（rules 落在 ` +
+        `${FINGERPRINT}/overrides 那块、ignores 加在全局 ignores 那块）或展开 moduleLint() ` +
+        '再追加自己的一块，别改方言那几块。',
+    };
+  }
+  return { config };
+}
+
+/**
+ * 跑一个模块包的 lint。**ESLint 只在这里构造**（判据与 `dsh-wb-module lint` 共用）。
+ *
+ * @param {{ dir: string, manifest: { name: string } }} pkg
+ * @param {{ fix?: boolean }} [options] `fix` 会写回文件；判据那条路永远不传它。
+ * @returns {Promise<object>} `{ name, files, errors, warnings, problems, warnLines, fixed }`
+ *   或 `{ name, error }`（配置跑不起来 / 不是 moduleLint 来的）
+ */
+export async function lintPackage(pkg, { fix = false } = {}) {
+  const name = pkg.manifest.name;
+  const loaded = await loadConfig(pkg);
+  if (loaded.error !== undefined) return { name, error: loaded.error };
+
+  const runOnce = (fixMode) =>
+    new ESLint({
+      cwd: pkg.dir,
+      // 不读目录里那份配置，用**这里 import 进来的**：指纹已经核过，`files` 相对 cwd 解析
+      // （Lead 探针实测这条路可行）。这样"判据跑的那份"与"模块文件里写的那份"是同一个对象。
+      overrideConfigFile: true,
+      // 头一块**只**补 `tsconfigRootDir`：typescript-eslint 的 parser 拿不到它时会去"猜"，
+      // 猜法是看调用 `tseslint.configs` 的那段栈 —— 一次进程里跑两个模块包就累积出两个候选
+      // 根目录，于是**第二个包**每个文件都报 "No tsconfigRootDir was set, and multiple
+      // candidate TSConfigRootDirs are present"（实测：两个模板一起跑，mini 全红）。
+      // 判据知道自己在跑哪个包，就把这件事钉死；模块自己写的那份配置若声明了
+      // parserOptions，它在后面，仍然覆盖这一条。
+      overrideConfig: [
+        {
+          // 不写 `files`：typescript-eslint 的 base 块不带 `files`，于是**所有**文件（含
+          // `scripts/*.mjs` 与两份配置）都走 TS parser —— 只给 `*.ts` 补根目录，`.mjs` 那三个
+          // 照样报同一个错（实测）。
+          languageOptions: { parserOptions: { tsconfigRootDir: pkg.dir } },
+        },
+        ...loaded.config,
+      ],
+      errorOnUnmatchedPattern: false,
+      fix: fixMode,
+    }).lintFiles(['.']);
+
+  // `--fix` 的报数要"修了 N 条"：fix 那一趟返回的结果是**修完之后**的（实测：`output` 有值、
+  // messages 只剩修不动的），所以前后各跑一趟普通轮，差值才是真修掉的那批。
+  //
+  // 整段包 try：一份"长得像方言但少了 plugin / 塞了坏东西"的配置会让 ESLint 在**建配置**那一步
+  // 抛（`Could not find plugin …`）—— 那是"跑不起来"这一类，要落成一行人话，不是把判据整条崩掉。
+  let results;
+  let before;
+  try {
+    before = fix ? await runOnce(false) : undefined;
+    if (fix) {
+      const fixed = await runOnce(true);
+      await ESLint.outputFixes(fixed);
+    }
+    results = await runOnce(false);
+  } catch (error) {
+    return { name, error: `${name}: ${CONFIG_FILE} 跑不起来 —— ${messageOf(error)}` };
+  }
+
+  const problems = [];
+  const warnLines = [];
+  let files = 0;
+  let errors = 0;
+  let warnings = 0;
+  for (const result of results) {
+    files += 1;
+    errors += result.errorCount;
+    warnings += result.warningCount;
+    for (const message of result.messages) {
+      if (message.severity === 2) problems.push(lineOf(name, pkg.dir, result, message));
+      else warnLines.push(lineOf(name, pkg.dir, result, message));
+    }
+  }
+
+  const totalOf = (list) => list.reduce((sum, result) => sum + result.errorCount + result.warningCount, 0);
+  return {
+    name,
+    files,
+    errors,
+    warnings,
+    problems,
+    warnLines,
+    fixed: before === undefined ? 0 : totalOf(before) - (errors + warnings),
+  };
+}
+
+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 = [];
+  const warnLines = [];
+  let files = 0;
+  let errors = 0;
+  let warnings = 0;
+
+  for (const pkg of declared) {
+    const result = await lintPackage(pkg);
+    if (result.error !== undefined) {
+      problems.push(result.error);
+      continue;
+    }
+    files += result.files;
+    errors += result.errors;
+    warnings += result.warnings;
+    problems.push(...result.problems);
+    warnLines.push(...result.warnLines);
+  }
+
+  if (problems.length > 0) {
+    // 单跑时列全（你就是来看全的）；聚合跑截断，把"还有 N 条"说清楚。
+    const only = process.env.DSH_WB_ONLY === 'lint';
+    const shown = only ? problems : problems.slice(0, MAX_PROBLEMS);
+    const notes = [
+      '红了怎么修：先看位置与规则名，再决定"改代码"还是"就地 eslint-disable-next-line"；' +
+        '要整体放开就展开 moduleLint() 再追加一块（别把方言换掉）。',
+    ];
+    if (shown.length < problems.length) {
+      notes.push(`还有 ${problems.length - shown.length} 条没列出来（跑 dsh-wb-module check --only lint 看全）。`);
+    }
+    return { status: 'fail', notes, problems: shown };
+  }
+
+  const notes = [
+    `${declared.length}/${modulePackages.length} 个模块包带 ${CONFIG_FILE} · ${files} 个文件 · ` +
+      `${errors} error · ${warnings} warn`,
+  ];
+  if (warnLines.length > 0 && process.env.DSH_WB_ONLY === 'lint') {
+    notes.push('warn（不挡门禁）：');
+    for (const line of warnLines) notes.push(`  ${line}`);
+  }
+  if (declared.length < modulePackages.length) {
+    notes.push(`其余 ${modulePackages.length - declared.length} 个没有 ${CONFIG_FILE}（不适用）`);
+  }
+  return { status: 'pass', notes, problems: [] };
+}

package/src/design.mjs

@@ -7,11 +7,11 @@
 // README 是给人读的落点，不是给机器判的形状。
 //
 // 现在的分工：
-//   · `design.json` —— 机器可读的需求底稿（三张表 + 状态矩阵 + 数据源记录 + 验收清单）；
+//   · `design.json` —— 机器可读的需求底稿（三张表 + 状态矩阵 + 数据源记录 + 写通道记录 + 验收清单）；
 //   · `README.md`   —— 由它**生成**的那一段（夹在 `<!-- dsh-wb:design:start/end -->` 之间）；
 //   · `dsh-wb-module design check` —— 把**空着的格**列出来（红），并核对 README 没落后于 design.json。
 //
-// 这样"空格"第一次有了形状：填空 → 再往下做；写完 → `design accept` 逐条打勾。
+// 这样"空格"第一次有了形状：填空 → 再往下做；写完 → 自己在真卡片上逐条走通，`design accept` 打勾。
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -49,6 +49,7 @@ const ROWS = {
   acceptance: { fields: ['step'] },
 };
 const DATASOURCE_FIELDS = ['read', 'params', 'credentials', 'notLoggedIn', 'timeout'];
+const WRITE_FIELDS = ['command', 'params', 'credentials', 'preview', 'readback', 'failure'];
 
 /** 一条卡背后可以有多条读（甚至跨站点）：规范形状 `reads: [ … ]`，一条一行；
  *  `datasource: { … }` 是只有一条读时的写法（老模块都长这样，继续认）。 */
@@ -59,6 +60,15 @@ function readsOf(design) {
   return one === undefined || one === null || typeof one !== 'object' ? [] : [one];
 }
 
+/** 写侧与读侧对称：一个动作可以打几条写（先建后发布那种），规范形状 `writes: [ … ]`；
+ *  `write: { … }` 是只有一条写时的写法。**没有写通道的模块不写就行** —— 这里不判"一条都没有"。 */
+function writesOf(design) {
+  const list = design?.writes;
+  if (Array.isArray(list) && list.length > 0) return list;
+  const one = design?.write;
+  return one === undefined || one === null || typeof one !== 'object' ? [] : [one];
+}
+
 /** 「他能自己配什么」有两种，分不清就会写成一个不落盘的选择还自称配置： */
 function persistenceLabel(value) {
   const raw = text(value);
@@ -80,6 +90,20 @@ function datasourceRowsOf(read) {
   ];
 }
 
+function writeRowsOf(write) {
+  return [
+    '| 项 | 值（照抄，别转述） |',
+    '|---|---|',
+    `| 哪条写（命令 / URL + 方法） | ${cell(write?.command)} |`,
+    `| 参数（必填 / 取值枚举 / 上限） | ${cell(write?.params)} |`,
+    `| 凭据从哪来 | ${cell(write?.credentials)} |`,
+    `| 有没有预览档（没有就写"没有，一次就是真的"） | ${cell(write?.preview)} |`,
+    `| 写完之后怎么回读确认（哪条读 / 出参哪个字段） | ${cell(write?.readback)} |`,
+    `| 失败长什么样（含"可能已经写了"） | ${cell(write?.failure)} |`,
+    `| 当初探明 / 预览用的那次调用（原文） | ${soft(write?.probeCommand)} |`,
+  ];
+}
+
 function text(value) {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -121,6 +145,7 @@ function skeleton(manifest = {}) {
       timeout: '',
       probeCommand: '',
     },
+    writes: [],
     acceptance: [{ step: '' }],
   };
 }
@@ -178,6 +203,12 @@ export function emptyCells(design) {
     for (const field of DATASOURCE_FIELDS) need(cells, read?.[field], `${label}.${field}`);
   });
 
+  const writes = writesOf(design);
+  writes.forEach((write, index) => {
+    const label = writes.length === 1 ? 'write' : `writes[${index}]`;
+    for (const field of WRITE_FIELDS) need(cells, write?.[field], `${label}.${field}`);
+  });
+
   return cells;
 }
 
@@ -206,6 +237,7 @@ export function renderDesign(design) {
   const acceptance = asRows(design?.acceptance);
   const states = asRows(design?.states);
   const reads = readsOf(design);
+  const writes = writesOf(design);
 
   const stateRows = STATE_KEYS.map((key, index) => {
     const row = states.find((one) => text(one?.key) === key) ?? {};
@@ -277,7 +309,16 @@ export function renderDesign(design) {
     ...(reads.length <= 1
       ? [...datasourceRowsOf(reads[0]), '']
       : reads.flatMap((one, index) => [`#### 读 ${String(index + 1)}`, '', ...datasourceRowsOf(one), ''])),
-    '### 验收（做完逐条打勾：`dsh-wb-module design accept`）',
+    ...(writes.length === 0
+      ? []
+      : [
+          '### 写通道探明记录',
+          '',
+          ...(writes.length <= 1
+            ? [...writeRowsOf(writes[0]), '']
+            : writes.flatMap((one, index) => [`#### 写 ${String(index + 1)}`, '', ...writeRowsOf(one), ''])),
+        ]),
+    '### 验收（自己在真卡片上逐条走通后打勾：`dsh-wb-module design accept`）',
     '',
     ...acceptanceRows,
     '',
@@ -351,7 +392,7 @@ function checkDesign(root) {
     console.error('✖ README 里那一段落后于 design.json（或者没有标记）—— 跑 dsh-wb-module design render');
   }
   if (cells.length === 0 && fresh) {
-    console.log(`✔ 三张表填全了，README 也是最新的${accepted === acceptance.length ? '，验收也打完了' : `；验收还差 ${acceptance.length - accepted} 条（用户点头后跑 design accept）`}`);
+    console.log(`✔ 三张表填全了，README 也是最新的${accepted === acceptance.length ? '，验收也打完了' : `；验收还差 ${acceptance.length - accepted} 条（自己在真卡片上逐条走通后跑 design accept）`}`);
   }
   process.exit(cells.length === 0 && fresh ? 0 : 1);
 }
@@ -399,7 +440,7 @@ export async function design({ root, args = [] }) {
     design0.acceptedAt = new Date().toISOString();
     writeDesign(root, design0);
     applyToReadme(root, renderDesign(design0));
-    console.log(`✔ ${acceptance.length} 条验收全部打勾（只在他真的逐条看过之后再跑这条）`);
+    console.log(`✔ ${acceptance.length} 条验收全部打勾（只在真的在真卡片上逐条走通过之后再跑这条）`);
     return;
   }