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

package/src/lint.mjs

@@ -1,57 +1,12 @@
-// 模块包的**语法卫生方言**（eslint 的模块版）。
-//
-// 为什么要有这一份：arch-guard 的 README 把自己的边界写得很清楚 ——「本工具不是 linter：
-// 单文件语法卫生（any、console、`!important`、颜色字面量、行数上限…）交给 eslint / oxlint /
-// stylelint / knip」。上一期（`./arch.mjs`）把**结构**那半边管住了，语法这半边一条都没有：
-// `as any` 把契约绕过去、`console.log` 留在产物里、渲染期写 ref、漏依赖、内联颜色 ——
-// 这些都不改变文件的形状，S16 / S23 那种判据永远看不见。
-//
-// 为什么方言住 module-tools、而不是让每个模块抄一份配置：与 `moduleArch()` 逐条同一个理由 ——
-// ① 抄一份就会各自漂成十几份"方言"；② 方言应当跟**工具链**同代（工坊三个包随外壳同代自愈，
-// 见 ADR-0056），规则变严时用户重跑一次门禁就跟着严，不用重抄。模板里那份 `eslint.config.mjs`
-// 只留一行工厂调用，要改规则就在**这一处**改。
-//
-// 为什么依赖装在 module-tools 一家（eslint / @eslint/js / typescript-eslint / 两个 react 插件）：
-// 模块与工坊根的清单**一个字都不用改** —— 这个文件 import 的是 module-tools 自己的依赖，
-// Node 从 module-tools 的位置解析；代价是工坊安装多约 17MB（第一次），换来的是用户拿到
-// `dsh-wb-module lint [--fix]` 就能跑，不必自己装一套 eslint 再跟版本漂移打架。
-//
-// 为什么是这几条规则（逐条的口径都在下面各块的注释里）：挑的是"语法级就能判、命中了基本
-// 就是真错"的那批 —— 不做类型感知规则（`no-floating-promises` 那种要建 program，模块 tsconfig
-// 形状各异、慢一个量级；外壳自己那份也把它排到 L2，见 `.scratch/eslint/spec.md`）。
-//
-// 指纹（**逐块比整份方言**，不只是比个名字）：本文件导出的 `DIALECT_BLOCKS` 是 `moduleLint()`
-// （不带 options）产出的**全部块**（`@eslint/js/recommended` · 三块 `typescript-eslint/*` ·
-// `dsh-wb/module-lint` 那四块），只排除两块 options 驱动的（`/overrides`、`/root`）。
-// 全局 ignores 那一块单列成 `DIALECT_IGNORES`，按**超集**比（模块可以多忽略，不许少忽略）。
-// 判据（`./checks/lint.mjs`）import 模块那份配置之后**逐块对**：名字 / `files` / `rules` 有一处
-// 不一致就红。这不是风格洁癖：没有它，模块可以把下限悄悄削掉（只留一个同名空块、筛掉基础层）
-// 而门禁照绿 —— 2026-10-19 verifier 先用 `export default [{ name: 'dsh-wb/module-lint',
-// rules: {} }]` 绕过去；随后又量到"只比 `dsh-wb/module-lint*` 那 4 块"还不够：**基础层**
-//（`@eslint/js/recommended` 与三块 `typescript-eslint/*`）与**全局 ignores 块**都不在比对面里。
-// 两者入口不同：前者**有名字**，要筛掉得显式点名（`filter((b) => b.name !== '@eslint/js/recommended')`）；
-// 后者是唯一**没有名字**的那块（全局 ignores 不能带 `name`），`filter((b) => b.name !== undefined)`
-// 筛掉的正是它。后果一样（下限被削），所以比对面扩到整份。
-//
-// **残余（这类校验的天花板，文档要如实写）**：模块若自己 import 本方言、再把这几块**照抄**成
-// 一份自己的配置（`moduleLint().map((b) => ({ ...b }))` 这类），判据分不出来 —— 它比的是形状，
-// 不是"这段代码从哪来"。这条的目标是**抬高门槛 + 让改动必须明着写**（改方言那几块会被点名；
-// 开口子只能走 `moduleLint({ rules, ignores })` 或自己追加一块），**不是**防住蓄意伪造。
-
 import js from '@eslint/js';
 import react from 'eslint-plugin-react';
 import reactHooks from 'eslint-plugin-react-hooks';
 import tseslint from 'typescript-eslint';
 
-/** 方言主块的名字。判据按它认"这一块属于方言"；改名字等于改协议。 */
 export const FINGERPRINT = 'dsh-wb/module-lint';
 
-// 只有 options 才会变的两块：它们不进"固定的方言"清单（判据不拿它们比 —— 开口子正是改它们）。
 const OPTION_BLOCK_NAMES = new Set([`${FINGERPRINT}/overrides`, `${FINGERPRINT}/root`]);
 
-// 全局 ignores 那一块（`{ ignores: [...] }`：没有 `name` / `files` / `rules`）。它**不按形状**比，
-// 单列成下面的 `DIALECT_IGNORES` 按**超集**比 —— 模块多忽略几条可以（那是开口子），少一条不行。
-// 导出它是为了让判据按**同一处**认出这一块，不在判据里另写一份"什么样的块算全局 ignores"。
 export function isGlobalIgnoresBlock(block) {
   return (
     block !== null &&
@@ -62,7 +17,6 @@ export function isGlobalIgnoresBlock(block) {
   );
 }
 
-/** 对象/数组递归重建、对象键排序：同一份形状在任何机器上 `JSON.stringify` 都是同一个串。 */
 function sortedDeep(value) {
   if (Array.isArray(value)) return value.map(sortedDeep);
   if (value === null || typeof value !== 'object') return value;
@@ -73,11 +27,6 @@ function sortedDeep(value) {
   );
 }
 
-/**
- * 一块方言的**规范形状**（判据逐块比的就是它）：名字 + `files`（没有就是 `null`）+ 键排序后的
- * `rules`。只认这三样 —— `plugins` / `settings` / `languageOptions` 是"怎么跑起来"的细节，
- * 掉了它们 ESLint 自己会报错，不必在这里比。
- */
 export function dialectShapeOf(block) {
   return {
     name: block.name,
@@ -86,11 +35,6 @@ export function dialectShapeOf(block) {
   };
 }
 
-// 产物与声明不判：`dist/**` 是 build 出来的，`client.js` 是浏览器面的产物，`*.d.ts` 是声明
-// （`types/styles.d.ts` 那种）。
-//
-// `src/components/vendor/**` 是**唯一**允许 `!important` 的地方 —— 与 arch 方言的
-// `DESIGN.vendorDir` 同一处（`./arch.mjs`）：那是"覆盖第三方样式"的那一格，不是我们的代码。
 const DEFAULT_IGNORES = [
   '**/node_modules/**',
   '**/dist/**',
@@ -100,9 +44,6 @@ const DEFAULT_IGNORES = [
   '**/components/vendor/**',
 ];
 
-// `src/**` 里能一眼看出"手搓外观"的两串字面量。CSS 那一半归 arch-guard 的 D 族
-// （`*.module.css` 已经管着 D09 / D12 / D17），这一半管 **TS 里的内联样式** —— 两条合起来
-// "手搓外观"才闭合：写进 CSS 文件的和写进 style={{}} 的都跑不掉。
 const COLOR_LITERAL = {
   selector:
     'Literal[value=/^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/], Literal[value=/^(?:rgba?|hsla?)\\(/]',
@@ -112,12 +53,18 @@ const BANG_IMPORTANT = {
   selector: 'Literal[value=/!important/]',
   message: '!important：只许在 src/components/vendor/** 里覆盖第三方样式',
 };
+const PLATFORM_READ = {
+  selector:
+    "MemberExpression[object.name='process'][property.name='platform'], " +
+    "MemberExpression[object.object.name='process'][object.property.name='versions'][property.name='electron'], " +
+    "MemberExpression[object.name='window'][property.name='dshDesktop'], " +
+    "MemberExpression[property.name='hostOs'], " +
+    "MemberExpression[object.name='navigator'][property.name='userAgent']",
+  message:
+    '平台/外壳差异走能力面（HostSurface / ClientSurface）：模块源码不直接读 ' +
+    'process.platform / versions.electron / dshDesktop / hostOs / navigator.userAgent',
+};
 
-// `js.configs.recommended` 的 `no-undef` 在 `.mjs` / `.js` 上是开的（TS 那边 typescript-eslint
-// 把它关了，类型才是那里的真相）。脚本与配置文件要干"算路径、起进程"的活，Node 的全局量得列出来。
-//
-// `URLSearchParams` 那一行是**实测**撞出来的：模板自带的 `scripts/smoke.mjs` 用它拼取数地址，
-// 照抄仓库根那份 globals（没有它）会让模板开箱就两条 `no-undef`。
 const NODE_GLOBALS = {
   Buffer: 'readonly',
   URL: 'readonly',
@@ -130,12 +77,6 @@ const NODE_GLOBALS = {
   clearTimeout: 'readonly',
 };
 
-// 非源码那一组（脚本 / 配置）。为什么不判 `console`：`scripts/smoke.mjs` 里那 6 处 `console.log`
-// 是它的**本职工作**（把一次冒烟的结果打给人看）—— 把 `no-console` 加到这一组，模板开箱就红，
-// 而那是误报。所以 `no-console` 只住在下面那个 `src/**` 块里。
-//
-// 这一组是 2026-10-19 拆 selfcheck 时真被两类**静默**错误咬过才补的（标识符少写引号、模板串
-// 写进了普通字符串），与仓库根那份同表；命中基本就是真错，不必跟噪声搏斗。
 const SCRIPT_RULES = {
   'no-template-curly-in-string': 'error',
   'require-atomic-updates': ['error', { allowProperties: true }],
@@ -154,50 +95,13 @@ const SCRIPT_RULES = {
 const SRC_FILES = ['src/**/*.{ts,tsx}'];
 const TSX_FILES = ['**/*.tsx'];
 const TS_FILES = ['**/*.{ts,tsx}'];
-// `*.config.{js,mjs,cjs}` 把模块根那几份配置（`eslint.config.mjs` / `arch.config.mjs` /
-// 以后可能有的 `*.config.mjs`）一起收进来；`scripts/**` 是模块自己的脚本。
+
 const SCRIPT_FILES = ['scripts/**/*.{js,mjs,cjs}', '*.config.{js,mjs,cjs}'];
 
-/**
- * 模块包的 eslint 方言。模板里那两行就是默认值：
- *
- * ```js
- * import { moduleLint } from '@dsh-workbench/module-tools/lint';
- * export default moduleLint({ rootDir: import.meta.dirname });
- * ```
- *
- * （为什么模板那份带 `rootDir`、不传行不行：见上面 `rootDir` 那一段 —— 单配置可省，多份并存必需。）
- *
- * 复杂模块要开口子时**从参数进**（每条口子都有名字，评审时看得见），别换掉方言：
- *
- * - `ignores`：追加忽略的 glob（默认那六条见 `DEFAULT_IGNORES`）
- * - `rules`：追加 / 覆盖规则，**最后一块**，所以它对所有文件生效、且压过前面每一块
- * - `rootDir`：这份配置所在的那个目录（模块自己那份配置里写 `import.meta.dirname`）。
- *   为什么要有它：typescript-eslint 的 parser 在**没拿到** `tsconfigRootDir` 时会去猜 —— 猜法是看
- *   "现在正在评估哪份 `eslint.config.*`"（V8 调用栈）。一个进程里只有一份配置时它猜得对（用户在
- *   自己模块里 `eslint .` 就是这种情形，所以**不传也能跑**）；但只要同时有多份（本仓根上那份
- *   + 模块自己那份，ESLint 会按目录就近选一份），它就猜不出来，**每个文件一条解析错**
- *   （`No tsconfigRootDir was set, and multiple candidate TSConfigRootDirs are present`，
- *   2026-10-19 整链实测）。模块这份配置声明了自己的根目录，这一条就没了。
- *
- * 要按目录细调（比如"只给 `src/legacy/**` 放行 `no-explicit-any`"），就在自己那份配置里
- * 展开再追一块：
- *
- * ```js
- * export default [
- *   ...moduleLint({ rules: { 'no-console': 'off' } }),
- *   { files: ['src/legacy/**'], rules: { '@typescript-eslint/no-explicit-any': 'off' } },
- * ];
- * ```
- *
- * @param {{ ignores?: string[], rules?: Record<string, unknown>, rootDir?: string }} [options]
- * @returns {import('eslint').Linter.Config[]} 标准 flat config 数组（编辑器与 eslint 认的就是它）
- */
 export function moduleLint(options = {}) {
   const { ignores = [], rules = {}, rootDir } = options;
   const overrideRules = Object.keys(rules).length === 0 ? [] : [{ name: 'dsh-wb/module-lint/overrides', rules }];
-  // 解析根目录那一块只在**明说** rootDir 时出现：不说就维持"typescript-eslint 自己猜"（单配置情形
-  // 猜得对，且不给用户的模块凭空塞一个他不知道的 parserOptions）。
+
   const rootBlock =
     rootDir === undefined
       ? []
@@ -209,43 +113,39 @@ export function moduleLint(options = {}) {
         ];
 
   return [
-    // 第一条是**全局 ignores**（只有 `ignores` 一个键；加 `name` 会让 ESLint 不把它当全局忽略）。
+
     { ignores: [...DEFAULT_IGNORES, ...ignores] },
     ...rootBlock,
-    // 基础正确性：`no-unreachable` / `no-dupe-keys` / `no-undef`…
+
     js.configs.recommended,
-    // `any` / `@ts-ignore` / 空的 interface 那一批。typescript-eslint 的 recommended 是**语法级**的
-    // （不建 program），所以它不属于"被推迟的类型感知规则"。
+
     ...tseslint.configs.recommended,
     {
       name: FINGERPRINT,
       files: SRC_FILES,
       rules: {
-        // `catch {}` 是"实现里不留注释"这条约定下的刻意写法（要表达在场就 `_` 前缀命名），不是漏写。
+
         'no-empty': ['error', { allowEmptyCatch: true }],
         'prefer-const': 'error',
-        // 上一期的非目标之一：`as any` 把契约绕过去 —— 复杂模块最先烂在这里。
+
         '@typescript-eslint/no-explicit-any': 'error',
-        // 死代码。`^_` 放行：参数位保留（给契约留形状）时用下划线命名，是刻意的。
+
         '@typescript-eslint/no-unused-vars': [
           'error',
           { args: 'after-used', argsIgnorePattern: '^_', caughtErrors: 'none', ignoreRestSiblings: true },
         ],
-        // arch-guard 把 H01（console 残留）委派给了 eslint。放行 `warn` / `error`：真报错要能报，
-        // 调试残留（`log` / `info` / `debug`）不许留。
+
         'no-console': ['error', { allow: ['warn', 'error'] }],
         'no-debugger': 'error',
-        // 手搓外观的 TS 那一半（CSS 那一半归 arch-guard 的 D 族）。
-        'no-restricted-syntax': ['error', COLOR_LITERAL, BANG_IMPORTANT],
+
+        'no-restricted-syntax': ['error', COLOR_LITERAL, BANG_IMPORTANT, PLATFORM_READ],
       },
     },
     {
       name: 'dsh-wb/module-lint/react',
       files: TSX_FILES,
       plugins: { react },
-      // `pragma: 'h'` 是模板的形状（`h()` 手写，不经 JSX 编译）：`jsx-uses-react` / `jsx-key`
-      // 这类规则照样咬得住手写的 `h()`。版本写死而不是 `detect`：`detect` 要读文件系统、
-      // 还会打一句警告，而模块拿到的 react 是外壳经模块表给的那一份（与外壳同代）。
+
       settings: { react: { version: '19.3.0', pragma: 'h', fragment: 'Fragment' } },
       rules: {
         'react/jsx-key': 'error',
@@ -263,9 +163,7 @@ export function moduleLint(options = {}) {
       files: TS_FILES,
       plugins: { 'react-hooks': reactHooks },
       rules: {
-        // 这一组是**这一期最值钱的一条**：本仓 2026-10-16 那次真实事故（渲染期写 `useRef.current`、
-        // 漏订阅、依赖写错）就是没有 lint 造成的。recommended 全量先按 **warn** 收进来（新规则
-        // 先看一段时间，不挡门禁），四条已知会真炸的提到 **error**。
+
         ...Object.fromEntries(Object.keys(reactHooks.configs.recommended.rules).map((rule) => [rule, 'warn'])),
         'react-hooks/rules-of-hooks': 'error',
         'react-hooks/refs': 'error',
@@ -283,27 +181,9 @@ export function moduleLint(options = {}) {
   ];
 }
 
-/**
- * `moduleLint()`（不带 options）产出的**整份方言**的规范形状 —— 判据拿它**逐块比**。
- *
- * 比对面（2026-10-19 扩过一次，是个行为变更）：**全部块**，只排除两块 options 驱动的
- * （`/overrides`、`/root`）；全局 ignores 那一块也不在这里（它没有 `name` / `files` / `rules`，
- * 形状比不了），单列成下面的 `DIALECT_IGNORES` 按**超集**比。也就是说现在这些块也必须在：
- * `@eslint/js/recommended` · `typescript-eslint/base` · `typescript-eslint/eslint-recommended` ·
- * `typescript-eslint/recommended`，以及 `dsh-wb/module-lint` 那四块 —— 一共 8 块。
- *
- * 为什么算一次就够：方言只有这一份，`moduleLint()` 不带 options 时产出是确定的（同一套常量、
- * 同一个 `tseslint.configs.recommended`），所以"该长什么样"可以在导入时钉死，判据不必自己
- * 再拼一遍。放在文件**最尾**：`moduleLint()` 读的是上面那批模块级常量，早算会撞 TDZ。
- */
 export const DIALECT_BLOCKS = moduleLint()
   .filter((block) => !isGlobalIgnoresBlock(block))
   .filter((block) => !(typeof block?.name === 'string' && OPTION_BLOCK_NAMES.has(block.name)))
   .map(dialectShapeOf);
 
-/**
- * 全局 ignores 的默认那几条（"一条都不许少"的那半）。判据按**超集**比：模块可以再多忽略几条
- * （那是 `moduleLint({ ignores })` 这个命名口子），但少一条就点名缺哪条。
- */
 export const DIALECT_IGNORES = [...DEFAULT_IGNORES];
-