@dsh-workbench/module-tools 0.3.11 → 1.0.0-beta.1

package/src/checks/source.mjs

@@ -1,54 +1,17 @@
-// 模块包的**源码边界**（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 的包拖进来的。
-//
-// 共享包（`@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` 那一层。
-
 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;
 
-// 共享包那两条规则要分清「取运行值」与「只取类型」，所以按**整条语句**匹配（`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);
@@ -68,7 +31,83 @@ const SIDE_TEXT = {
   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') {
@@ -108,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('@/')) {
@@ -139,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);
@@ -165,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() });
@@ -180,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/ 就别再留一份 —— 平台知识两处都有，改平台要改两处`,
@@ -250,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(
@@ -260,7 +303,6 @@ 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);
@@ -270,6 +312,16 @@ export async function run() {
         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 它，或把这件事交给外壳）`,
+        );
+      }
     }
   }
 
@@ -289,7 +341,7 @@ export async function run() {
       `${scanned} 个源文件 · 不伸进外壳 app/ · 不跨模块 · ` +
         `平台知识要么在自己包里、要么走平台包（不许两样都有）· ` +
         `dsh 的浏览器包只在客户端侧可用（${seedUsers} 处）· ` +
-        `共享包根入口只取类型、/host 只在宿主侧取运行值`,
+        `共享包根入口只取类型、/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