@dsh-workbench/module-tools 0.3.3 → 0.3.5

package/src/shell-type-files.mjs

@@ -0,0 +1,119 @@
+// kit 成员 → 类型文件：外壳那两个包的类型树（`@dsh-workbench/shared` 的 `dist` 与外壳自己的 `dist/types`）。
+//
+// 为什么要扫：kit 的成员是**运行期**从外壳产物 `client.js` 里跑出来的（见 `checks/kit.mjs`），
+// 产物里没有"这个成员来自哪个模块"；而类型树里每个成员的声明都躺在某份 `.d.ts` 里 ——
+// 扫一遍就能把"名字"落到"文件"，于是 agent「想问哪个直接去看那份文件」有确切路径。
+//
+// 为什么是名字扫描而不是真正的类型解析：这些 `.d.ts` 是 tsc 生成的、声明形状规整
+// （`export declare const X` / `export interface X` / `export { X } from '…'`），而 kit 的成员
+// 本来就是运行期对象上的键名。扫描不引 TypeScript 依赖、贵在稳；代价是"同名声明出现在多处"时
+// 要挑一个（挑法见 `preferred`），以及极少数成员指到的是 barrel 而不是最终实现文件。
+// 实测本机 190 个 kit 成员 190 个都落得到文件（见 `.scratch/dsh-primitives-face/verify.md` §2）。
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const PATTERNS = [
+  /^export declare (?:const|function|class) (\w+)/gm,
+  /^export (?:interface|type) (\w+)/gm,
+  /^export \{([^}]*)\}/gm,
+  /^declare (?:const|function|class) (\w+)/gm,
+  /^(?:interface|type) (\w+)/gm,
+];
+
+function walk(dir, acc = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, acc);
+    else if (full.endsWith('.d.ts')) acc.push(full);
+  }
+  return acc;
+}
+
+function namesIn(clause) {
+  if (!clause.includes(',') && !clause.includes(' ')) return [clause];
+  return clause
+    .split(',')
+    .map((raw) => raw.trim().split(/\s+as\s+/).pop().trim())
+    .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
+}
+
+/** 外壳那两个包的类型树（`shared` 没装就只给外壳那棵）。 */
+export function shellTypeRoots(shellClientPath) {
+  const shellRoot = dirname(shellClientPath);
+  const roots = {};
+  const shellTypes = join(shellRoot, 'dist', 'types');
+  if (existsSync(shellTypes)) roots.shell = shellTypes;
+  // 打印用"从 node_modules 看"的那条路径（pnpm 的真身在 `.pnpm/` 哈希目录里）；读文件两条都行。
+  const viaNodeModules = join(shellRoot, 'node_modules', '@dsh-workbench', 'shared', 'dist');
+  try {
+    // 解析 "." 那个入口（= `dist/index.js`）再取 dirname —— shared 的 `exports` 里**没有**
+    // `./package.json` 这一条，直接 resolve 它的 package.json 会 ERR_PACKAGE_PATH_NOT_EXPORTED。
+    const sharedEntry = createRequire(join(shellRoot, 'package.json')).resolve('@dsh-workbench/shared');
+    const sharedTypes = dirname(sharedEntry);
+    if (existsSync(sharedTypes)) roots.shared = existsSync(viaNodeModules) ? viaNodeModules : sharedTypes;
+  } catch {
+    // 没装 shared：只有外壳自己那棵，仍然能落一部分成员
+  }
+  return { shellRoot, roots };
+}
+
+/**
+ * 同名多处时挑哪个：组件 > hooks > 库 > 其他 > **套件内部（`app/` / `modules/`）垫底**，同档挑路径短的。
+ *
+ * 垫底那一档是 2026-10-20 补的（ADR-0067 的 kit JSDoc 判据撞出来的）：kit 的 `readText`（共享包
+ * `config/storage.ts`）与外壳内部 `modules/panels/model/diy-report.ts` 里的同名函数撞了，而 `modules/`
+ * 那条路径在 `node_modules` 那份类型树旁边**更短**，于是 `--file readText` 一直指到别人的实现上。
+ * kit 的成员只从 `client.tsx` 那几处 spread 来（共享包 + 外壳 `shared/**`），套件内部不会是它 ——
+ * 所以垫底只影响撞名时的取舍，掉不到"本来该选的那份"。
+ */
+function preferred(candidates) {
+  const rank = (file) =>
+    file.includes('/components/')
+      ? 0
+      : file.includes('/hooks/')
+        ? 1
+        : file.includes('/lib/')
+          ? 2
+          : /\/(app|modules)\//.test(file)
+            ? 9
+            : 3;
+  return [...candidates].sort((a, b) => rank(a.file) - rank(b.file) || a.file.length - b.file.length)[0];
+}
+
+/**
+ * 把 kit 的成员名落到类型文件。
+ * 返回 `{ roots, files: Map<名字, 绝对路径>, missing: 名字[] }` —— `roots` 是两棵类型树的绝对根。
+ */
+export function memberFilesOf(shellClientPath, names) {
+  const { roots } = shellTypeRoots(shellClientPath);
+  const index = new Map();
+  for (const root of Object.values(roots)) {
+    for (const file of walk(root)) {
+      let text;
+      try {
+        text = readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      for (const pattern of PATTERNS) {
+        for (const match of text.matchAll(pattern)) {
+          for (const name of namesIn(match[1])) {
+            if (!index.has(name)) index.set(name, []);
+            const found = index.get(name);
+            if (!found.some((one) => one.file === file)) found.push({ file });
+          }
+        }
+      }
+    }
+  }
+  const files = new Map();
+  const missing = [];
+  for (const name of names) {
+    const candidates = index.get(name);
+    if (candidates === undefined || candidates.length === 0) missing.push(name);
+    else files.set(name, preferred(candidates).file);
+  }
+  return { roots, files, missing };
+}

package/template/package.json.tpl

@@ -23,7 +23,7 @@
     "client": {
       "platform": "web",
       "inject": ["@dsh-workbench/core"],
-      "external": ["@dsh-workbench/core/client"]
+      "external": ["@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives"]
     },
     "workbench": {
       "apiVersion": 1,
@@ -37,6 +37,7 @@
   "peerDependencies": { "@dsh-workbench/core": "__SHELL_RANGE__", "react": "*" },
   "peerDependenciesMeta": { "react": { "optional": true } },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-primitives": "__DSH_UI_VERSION__",
     "@dsh-workbench/core": "__SHELL_RANGE__",
     "@dsh-workbench/module-tools": "__SHELL_RANGE__",
     "@types/node": "^24.19.0",

package/template-diy/package.json.tpl

@@ -24,7 +24,7 @@
     "client": {
       "platform": "web",
       "inject": ["@dsh-workbench/core"],
-      "external": ["@dsh-workbench/core/client"]
+      "external": ["@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives"]
     },
     "workbench": {
       "apiVersion": 1,
@@ -38,6 +38,7 @@
   "peerDependencies": { "@dsh-workbench/core": "__SHELL_RANGE__", "react": "*" },
   "peerDependenciesMeta": { "react": { "optional": true } },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-primitives": "__DSH_UI_VERSION__",
     "@dsh-workbench/core": "__SHELL_RANGE__",
     "@dsh-workbench/module-tools": "__SHELL_RANGE__",
     "@types/node": "^24.19.0",