@dsh-workbench/module-tools 0.3.10 → 1.0.0-beta.0

package/src/checks/source.mjs

@@ -1,30 +1,139 @@
-// 模块包的**源码边界**（S2 第三块：门禁跟着自述清单走到模块包）。
-//
-// 外壳那份 `arch/rules/units.mjs` 是按**路径**发现套件的（`src/modules/<id>/unit.ts`），
-// 模块搬出 `src/` 之后它照跑但不报。那几条规则守的多是「外壳不许认识套件」——对模块包没意义；
-// 模块包自己要守的是另外几条，写在下面。判据全部来自源码里的 import 说明符，覆盖范围跟着
-// `dsh.workbench` 自述清单走（新加模块不用改这里）。
-//
-// 关于 dsh 的包：「哪一半」**不靠目录名猜**，而是从两个入口（`dsh.workbenchFaces.host` /
-// `dsh.workbenchFaces.client`）做一次本包内可达性分析。种子词（模块表里天生就有的那几个）在
-// **只被客户端入口可达**的文件里可以用（ADR-0028）；宿主侧一个都不许碰 —— 那些包只在浏览器侧存在。
-//
-// 这两个入口是 dsh.workbenchFaces 的**唯一**用途（工具链字段，不是协议的一部分，见 ADR-0038 §7 第 7 条）：
-// 装机预检与外壳都不读它。所以这里必须拿**源码**入口 —— 从产物 dist/host.js 反推不出是哪一份源码
-// 把 dsh 的包拖进来的。
-//
-// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
-// 打印与退出码归 `../check.mjs` 那一层。
-
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import ts from 'typescript';
 import { dirname, join, relative, resolve } from 'node:path';
 import { discoverModulePackages } from '../discover.mjs';
 import { isSeedSpecifier } from '../seed.mjs';
+import { LIB_CAPABILITIES, importsPreferred } from '@dsh-workbench/shared/host';
 
-// 静态 `from '…'`、副作用 `import '…'`、动态 `import('…')` —— 动态那条不能漏，
-// 模块入口常见写法是 `await import('./views/…')`，漏了就会把可达文件判成"死代码"。
 const IMPORT = /from\s*'([^']+)'|import\s*\(?\s*'([^']+)'/g;
 
+const SHARED_FROM =
+  /(?:^|[;}\s])(import|export)\s+(type\s+)?([^'";]{0,600}?)\s*from\s*['"](@dsh-workbench\/shared(?:\/host)?)['"]/g;
+
+const SHARED_DYNAMIC = /import\s*\(\s*['"](@dsh-workbench\/shared(?:\/host)?)['"]/g;
+
+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: '两个入口都到不了（可能是死代码）',
+};
+
+const COMMENT_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.css']);
+const COMMENT_DIRECTIVE = /^(?:\/\/|\/\*)\s*(?:!?\s*@(?:license|preserve)\b|eslint-(?:disable|enable)\b|@ts-(?:ignore|expect-error|nocheck|check)\b|@vitest-|@jest-|@flow\b|@jsx|prettier-ignore\b|global\b|exported\b|c8\b|v8\b|istanbul\b|#\s*sourceMappingURL\b|@__PURE__|#__PURE__|\/?\s*<reference\b)/u;
+
+function codeFiles(dir, acc = []) {
+  if (!existsSync(dir)) return acc;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === 'dist') continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      codeFiles(full, acc);
+      continue;
+    }
+    const ext = entry.name.slice(entry.name.lastIndexOf('.'));
+    if (COMMENT_EXT.has(ext)) acc.push(full);
+  }
+  return acc;
+}
+
+function tsCommentRanges(text) {
+  const source = ts.createSourceFile('scan.tsx', text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const found = new Map();
+  const add = (ranges) => {
+    for (const range of ranges ?? []) found.set(range.pos, range);
+  };
+  const visit = (node) => {
+    add(ts.getLeadingCommentRanges(text, node.getFullStart()));
+    add(ts.getTrailingCommentRanges(text, node.getEnd()));
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  add(ts.getLeadingCommentRanges(text, 0));
+  add(ts.getTrailingCommentRanges(text, text.length));
+  return [...found.values()].sort((a, b) => a.pos - b.pos);
+}
+
+function cssCommentRanges(text) {
+  const found = [];
+  let at = 0;
+  let quote = null;
+  while (at < text.length) {
+    const ch = text[at];
+    if (quote !== null) {
+      if (ch === '\\') at += 2;
+      else {
+        if (ch === quote) quote = null;
+        at += 1;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      at += 1;
+      continue;
+    }
+    if (ch === '/' && text[at + 1] === '*') {
+      const end = text.indexOf('*/', at + 2);
+      if (end === -1) break;
+      found.push({ pos: at, end: end + 2 });
+      at = end + 2;
+      continue;
+    }
+    at += 1;
+  }
+  return found;
+}
+
+export function commentViolationsOf(text, { css = false } = {}) {
+  const ranges = css ? cssCommentRanges(text) : tsCommentRanges(text);
+  const bad = [];
+  for (const range of ranges) {
+    const raw = text.slice(range.pos, range.end);
+    if (!css && COMMENT_DIRECTIVE.test(raw)) continue;
+    bad.push(text.slice(0, range.pos).split('\n').length);
+  }
+  return bad;
+}
+
+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);
@@ -38,11 +147,6 @@ function sourceFiles(dir, acc = []) {
   return acc;
 }
 
-/**
- * 把一条 import 说明符解析成本包内的文件；解析不到就是包说明符（不外追）。
- * 别名两条（与 `build.mjs` 的 aliasResolver 同一条约定）：
- *   `@/modules/<unit>/X` → `src/X`   ·   `@/platforms/X` → `src/platforms/X`
- */
 function resolveLocal(pkgDir, unit, fromFile, specifier) {
   let base;
   if (specifier.startsWith('@/')) {
@@ -69,7 +173,6 @@ function resolveLocal(pkgDir, unit, fromFile, specifier) {
   return undefined;
 }
 
-/** 从某个入口出发，本包内可达的源文件。 */
 function reachableFrom(pkgDir, unit, entry) {
   const seen = new Set();
   const start = join(pkgDir, entry);
@@ -95,7 +198,7 @@ function hasPlatformPackage(manifest) {
   return names.some((name) => /(^|\/)platform-/.test(name));
 }
 
-export const title = '模块源码边界';
+export const title = '模块源码边界与零注释';
 
 export async function run() {
   const modulePackages = discoverModulePackages({ root: process.cwd() });
@@ -110,6 +213,16 @@ export async function run() {
     const srcDir = join(pkg.dir, 'src');
     const viaPlatform = hasPlatformPackage(pkg.manifest);
 
+    for (const file of codeFiles(srcDir)) {
+      const rel = relative(pkg.dir, file);
+      const text = readFileSync(file, 'utf8');
+      for (const line of commentViolationsOf(text, { css: file.endsWith('.css') })) {
+        problems.push(
+          `${name}: ${rel}:${line} 有注释 —— 模块源码零注释（说明写 README.md 或 spec；eslint / ts / vitest 指令注释除外）`,
+        );
+      }
+    }
+
     if (viaPlatform && existsSync(join(srcDir, 'platforms'))) {
       problems.push(
         `${name}: 已经改用平台包了，src/platforms/ 就别再留一份 —— 平台知识两处都有，改平台要改两处`,
@@ -180,7 +293,7 @@ export async function run() {
         if (platform !== null && viaPlatform) {
           problems.push(
             `${name}: ${rel} 里 import 了 ${specifier} —— 这个模块已经改用平台包了，平台知识走包名` +
-              `（比如 @pagoda-dsh-workbench/platform-coding），不许再用 @/platforms/*`,
+              `（比如 @acme-dsh-workbench/platform），不许再用 @/platforms/*`,
           );
         } else if (platform !== null && !existsSync(join(srcDir, 'platforms', `${platform[2]}.ts`))) {
           problems.push(
@@ -189,6 +302,26 @@ 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);
+      }
+
+      for (const entry of LIB_CAPABILITIES) {
+        if (importsPreferred(text, entry.preferred)) continue;
+        if (!entry.pattern.test(text)) continue;
+        const line = text.split('\n').findIndex((one) => entry.pattern.test(one)) + 1;
+        problems.push(
+          `${name}: ${rel}:${String(line < 1 ? 1 : line)} 手写了 ${entry.capability} —— ${entry.why}` +
+            `（首选 ${entry.preferred}；import 它，或把这件事交给外壳）`,
+        );
+      }
     }
   }
 
@@ -207,7 +340,8 @@ export async function run() {
     notes: [
       `${scanned} 个源文件 · 不伸进外壳 app/ · 不跨模块 · ` +
         `平台知识要么在自己包里、要么走平台包（不许两样都有）· ` +
-        `dsh 的浏览器包只在客户端侧可用（${seedUsers} 处）`,
+        `dsh 的浏览器包只在客户端侧可用（${seedUsers} 处）· ` +
+        `共享包根入口只取类型、/host 只在宿主侧取运行值 · 不手写进程/锁/原子写`,
     ],
     problems: [],
   };

package/src/checks/standalone.mjs

@@ -1,16 +1,6 @@
-// 模块**离开外壳源码**也得能 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';
+import { execaSync } from 'execa';
 import { discoverModulePackages, discoverPackages } from '../discover.mjs';
 
 const SHELL = '@dsh-workbench/core';
@@ -24,7 +14,7 @@ export async function run() {
   if (visible === undefined || !existsSync(visible)) {
     return {
       status: 'skip',
-      notes: [`本仓没有 ${SHELL} 的源码（"不许 @/ 指外壳"那条判据照旧在守）`],
+      notes: [`当前目录没有 ${SHELL} 的源码（"不许 @/ 指外壳"那条判据照旧在守）`],
       problems: [],
     };
   }
@@ -50,7 +40,7 @@ export async function run() {
   const restore = () => {
     if (existsSync(hidden) && !existsSync(visible)) renameSync(hidden, visible);
   };
-  // Ctrl-C 时也必须还原（进程被杀时 finally 不跑）：还原完把信号还回去，让默认行为收场。
+
   const onInterrupt = () => {
     restore();
     process.removeListener('SIGINT', onInterrupt);
@@ -66,7 +56,7 @@ export async function run() {
       for (const script of ['build', 'typecheck']) {
         if (pkg.manifest.scripts?.[script] === undefined) continue;
         try {
-          execFileSync('pnpm', ['run', script], { cwd: pkg.dir, stdio: 'pipe' });
+          execaSync('pnpm', ['run', script], { cwd: pkg.dir, stdio: 'pipe' });
         } catch (error) {
           const output = `${error.stdout ?? ''}${error.stderr ?? ''}`;
           const first = output