@fast-china/eslint-config 2.1.7 → 2.1.8

package/docs/rules-risk.md

@@ -1,119 +1,113 @@
 # Default Rules and Risk Guide
 
-This document describes the current 2.1.7 configuration model, major rules, and migration risks. Source comments explain current intent only; historical changes belong in `CHANGELOG.md`.
+This guide describes the current configuration model, major rules, and auto-fix risks. Source comments explain current intent; historical differences belong in `CHANGELOG.md`.
+
+## Policy
+
+Rules are selected in this order:
+
+1. Follow common JavaScript, TypeScript, and Vue conventions while keeping code concise and readable.
+2. Detect real bugs and type-safety problems.
+3. Preserve cross-project consistency.
+4. Apply Fast project style preferences last.
+
+Rules that only satisfy ESLint by changing valid semantics, adding boilerplate, or forcing uncommon forms do not belong in the defaults.
 
 ## Configuration model
 
-SDKs, OA systems, administration apps, Vue web apps, and UniApp clients share one JavaScript, TypeScript, Import, and RegExp rule set. There are no strictness tiers.
+Vue 3 and UniApp are separate named complete configurations from the root entry:
 
-The root entry is a fixed Vue 3 + TypeScript + UniApp preset:
+- `vueConfig` handles plain Vue projects only.
+- `uniAppConfig` adds `.nvue`, UniApp globals, manifest behavior, and the `unpackage` ignore.
 
-- `environment: "browser"`
-- `.gitignore`
-- JavaScript and type-aware TypeScript
-- Vue 3, `.nvue`, UniApp globals, and manifest handling
-- Import, RegExp, JSON, JSONC, and JSON5
-- `package.json` and `tsconfig*.json` sorting
-- Prettier conflict handling
-- Node.js tooling globals and trailing rule overrides
+The root entry has no default export. It exposes `vueConfig`, `uniAppConfig`, `createVueProjectConfigs()`, `createUniAppProjectConfigs()`, `createBaseConfigs()`, `defineRules()`, and their types.
 
-`fastConfig()` retains only `environment`. React, Angular, Markdown, and Lodash compose from `./configs`; rules, globals, ignores, and special parser settings use trailing Flat Config objects.
+SDKs, Node.js, and other framework-neutral projects use `createBaseConfigs()`. React, Angular, Markdown, and Lodash compose explicitly from `./configs`; manifest sorting is part of every complete configuration.
 
 ## Preset sources
 
-| Domain     | Preset or implementation                                                      |
-| ---------- | ----------------------------------------------------------------------------- |
-| JavaScript | `@eslint/js` recommended plus local rules                                     |
-| TypeScript | typescript-eslint strict and stylistic type-checked presets + Project Service |
-| Vue        | `eslint-plugin-vue` `flat/recommended` plus type-aware TypeScript             |
-| React      | `@eslint-react` recommended/type-checked plus React Hooks Flat Recommended    |
-| Angular    | Angular ESLint TypeScript, template, and accessibility recommended presets    |
-| JSON       | `eslint-plugin-jsonc` recommended presets for three dialects                  |
-| Import     | `eslint-plugin-import-x` recommended plus a fixed ordering policy             |
-| RegExp     | Explicit correctness, safety, and super-linear backtracking rules             |
-| Prettier   | `eslint-config-prettier` conflict disabling                                   |
-
-## Major rules
-
-### JavaScript
-
-- `camelcase: ["error", { properties: "never" }]` requires camelCase variables and types while preserving external protocol property names.
-- `no-empty` allows intentionally empty catches and still reports other empty blocks.
-- `no-eval` and `no-void` are errors; `curly: ["error", "multi-line", "consistent"]` applies, and an existing `default` branch must come last.
-- `no-debugger: "error"`
-- `no-use-before-define` warns; classes and variables must be declared first while function declarations may be hoisted.
-- `prefer-arrow-callback`, `logical-assignment-operators`, and `prefer-object-spread` are errors.
-- `prefer-exponentiation-operator` and `prefer-object-has-own` are errors.
-- `sort-imports` warns and only sorts members within one import.
-- `import-x/order` is an error with `warnOnUnassignedImports: true` and `sortTypesGroup: true`; `@/**` belongs to `internal`, type imports follow every non-style import and retain source-category ordering inside the final type group, and stylesheet imports do not participate in this rule.
-- `import-x/style-imports-last` is an error; CSS, SCSS, LESS, and related styles must form the final contiguous import group, with their internal order preserved and no automatic fix.
-
-### TypeScript
-
-- `strictTypeChecked`, `stylisticTypeChecked`, and `projectService: true` are always enabled; TypeScript, TSX, Vue, and NVue share `extraFileExtensions: [".vue", ".nvue"]` to prevent Project Service reloads during mixed-file linting.
-- `no-floating-promises` and `strict-void-return` are disabled so Promise waiting follows business semantics; `no-void` rejects `void promise` workarounds. `no-misused-promises`, `await-thenable`, `require-await`, and the unsafe-type rules remain strict, while Promise-returning handlers are allowed in Vue templates and TSX attributes.
-- Named TypeScript and TSX functions require explicit return types, except inline callbacks and already typed function expressions; exported module boundaries still require explicit types.
-- Vue/NVue SFCs disable function-return and module-boundary annotations and unused parameter checks, while unused variables and imports remain errors. Templates do not infer parameter types back into standalone script handlers, so those parameters still require explicit annotations.
-- `explicit-module-boundary-types` is an error and does not allow explicitly typed `any` arguments as an escape hatch.
-- `no-explicit-any` warns.
-- Regular TS/TSX parameters and caught errors can use an `_` prefix to mark intentional omissions; ordinary variables cannot use that prefix to evade the check.
-- `no-empty-function` only allows empty constructors and override methods.
-- `consistent-type-imports` fixes type-only dependencies as separate `import type` declarations, and `no-import-type-side-effects` rejects runtime imports containing only inline type specifiers.
-- `no-non-null-assertion` is an error.
-- `switch-exhaustiveness-check` is an error; `no-deprecated` and `no-unnecessary-condition` warn.
-- Numeric template interpolation and concise void arrow callbacks are allowed; dynamic object deletion and static-only utility classes are not forcibly rewritten.
-- `consistent-type-exports` and `prefer-readonly` are errors; primitive values are not forced from `||` to `??`.
-- `no-eval`, `no-implied-eval`, and `no-new-func` reject direct or indirect dynamic string execution; `no-promise-executor-return` rejects ignored executor returns, and Vue setup props or refs cannot be used in ways that lose reactivity.
-- `unified-signatures` preserves public overloads with different parameter names or standalone JSDoc; the stricter core `no-void` replaces `no-meaningless-void-operator`.
-- `consistent-type-definitions`, `consistent-indexed-object-style`, `class-literal-property-style`, and `prefer-regexp-exec` are disabled as syntax-only preferences.
-
-### Vue
-
-- Uses `flat/recommended`.
-- `attribute-hyphenation: ["error", "always"]`.
-- `no-v-html` warns.
-- `no-v-text-v-html-on-component` is an error.
-- `require-explicit-emits`, `attributes-order`, and `no-mutating-props` are errors.
-- `.vue` and `.nvue` share the TypeScript parser and Project Service.
-
-## Type-aware requirements
-
-TypeScript, Vue, and React TSX always require type information. Linted files must belong to a discoverable `tsconfig.json`, or Project Service reports a configuration error.
-
-The `typeChecked` and `tsconfigRootDir` wrapper options no longer exist. Complex monorepos can override `languageOptions.parserOptions` in trailing Flat Config, but should not disable type checking to hide project-boundary problems.
+| Domain     | Preset or implementation                                                   |
+| ---------- | -------------------------------------------------------------------------- |
+| JavaScript | `@eslint/js` recommended plus local high-confidence rules                  |
+| TypeScript | typescript-eslint `recommendedTypeChecked` plus Project Service            |
+| Vue        | `eslint-plugin-vue` `flat/recommended` plus type-aware TypeScript          |
+| React      | `@eslint-react` recommended/type-checked plus React Hooks Flat Recommended |
+| Angular    | Angular ESLint TypeScript, template, and accessibility recommended presets |
+| JSON       | `eslint-plugin-jsonc` recommended presets for three dialects               |
+| Import     | `eslint-plugin-import-x` recommended plus a general ordering warning       |
+| RegExp     | Explicit correctness, safety, and super-linear backtracking rules          |
+| Prettier   | `eslint-config-prettier` conflict disabling                                |
+
+The complete `strictTypeChecked`, `stylisticTypeChecked`, and mechanical `all` presets are not enabled. Extra rules are limited to low-false-positive checks that directly improve correctness or readability.
+
+## JavaScript and Import
+
+- `camelcase: ["error", { properties: "never" }]` applies to variables and types while external protocol properties retain their original names.
+- `no-empty` permits a completely empty `catch` and reports other empty blocks.
+- `no-void` is an error; `void` is not used to hide a Promise or express an ignored return value.
+- Real-risk rules such as `no-eval`, `no-implied-eval`, `no-new-func`, `no-promise-executor-return`, and `no-debugger` are errors.
+- `curly` requires consistent braces only for multiline branches and does not force braces on every single-line branch.
+- `import-x/first` and `import-x/no-duplicates` are errors.
+- `import-x/order` is an error and fixes declaration order; common framework, tool, and `@/**` path groups extend the general groups.
+- `pathGroupsExcludedImportTypes: ["type"]` keeps type imports in the final type group.
+- Non-style side-effect imports participate in ordering. `style-imports-last` requires a final contiguous stylesheet group without sorting within it, preserving CSS cascade order.
+- `sort-imports` is an error and only normalizes members inside one import declaration; `prefer-object-has-own` is not enabled.
+
+## TypeScript
+
+TypeScript always uses Project Service and `recommendedTypeChecked`. Linted files must belong to a discoverable `tsconfig.json`.
+
+- `.ts`, `.mts`, and `.cts` files are SDK-like module boundaries: `explicit-module-boundary-types` is an error, so exported functions and public boundaries of exported classes require explicit types.
+- `.tsx` files are UI component files: type-aware correctness rules remain enabled, but module-boundary annotations are not required for inferable JSX return types.
+- `explicit-function-return-type` is disabled, leaving internal functions, local handlers, and callbacks to TypeScript inference.
+- `no-inferrable-types` preserves explicit parameter and property types and only removes annotations without contract value, such as obvious local-variable types.
+- Vue/NVue SFCs and standalone TSX components disable module-boundary and function-return requirements to preserve common concise component forms.
+- `no-floating-promises` is disabled because waiting, returning, or handling a Promise depends on business semantics.
+- `require-await` is an error; an `async` function without `await` changes return and exception semantics and should lose `async`.
+- `no-misused-promises`, `await-thenable`, unsafe-type rules, exhaustive switches, getter/setter compatibility, and other high-confidence checks are errors.
+- `return-await` requires `await` only when needed for correct error handling.
+- Standard non-null assertions are permitted, while contradictory optional-chain or nullish-coalescing combinations remain errors.
+- `no-explicit-any` and `no-deprecated` warn.
+- `no-unnecessary-condition`, `unified-signatures`, and syntax-only preferences are disabled to preserve runtime guards and public overloads.
+- Template strings allow numbers and booleans; dynamic property deletion and static utility classes are not forcibly rewritten.
+- `prefer-nullish-coalescing` does not force primitive values from `||` to `??`; `prefer-optional-chain` applies only when the type explicitly contains null or undefined.
+
+## Vue
+
+- The official `flat/recommended` preset is the general Vue baseline.
+- `no-v-html` warns so XSS risk is visible while sanitized content remains possible.
+- `require-explicit-emits`, `no-dupe-keys`, `no-mutating-props`, `no-setup-props-reactivity-loss`, `no-ref-object-reactivity-loss`, and `no-reserved-component-names` are errors for Vue SFC and Vue JSX/TSX component scripts.
+- `attribute-hyphenation`, `no-v-text-v-html-on-component`, and `attributes-order` remain limited to `.vue/.nvue` templates; `attributes-order` sorts definition, list-rendering, conditional, render-modifier, unique, global, ordinary, event, and content attributes.
+- JSX attributes retain JavaScript camelCase conventions and do not inherit the template kebab-case rule.
+- Setup props/ref reactivity loss and invalid custom-event names remain errors.
 
 ## UniApp boundary
 
-The root entry declares `uni`, `uniCloud`, page APIs, and conditional-platform objects, and permits comments in `pages.json` and `manifest.json`.
+Only the UniApp entry declares `uni`, `uniCloud`, page APIs, and conditional-platform objects such as `wx`, `plus`, `my`, and `tt`. The plain Vue entry neither receives these globals nor ignores `unpackage`.
 
-ESLint does not execute conditional compilation, so `wx`, `plus`, and similar objects are visible in every code file handled by the root entry. This prevents `no-undef` inside platform branches but cannot verify that objects occur under the correct `#ifdef`. Plain Vue projects that do not want these globals should compose focused fragments instead of using the root entry.
+ESLint does not execute conditional compilation. It can avoid `no-undef` inside platform branches but cannot prove that an object occurs under the correct `#ifdef`.
 
-## Auto-fix risks
+## Manifest sorting and auto-fix
 
-Review these fixes carefully:
+`package.json` and `tsconfig*.json` sorting is enabled by default in `createBaseConfigs()`, `vueConfig`, and `uniAppConfig`. The individual factories remain available for custom composition.
 
-- Import groups, type-source categories, member order, and side-effect import placement.
-- Separate TypeScript `import type` declarations.
-- Vue attribute naming and ordering.
-- `package.json` and `tsconfig*.json` key order.
+Review these fixes carefully:
 
-`package.json` sorting does not enter conditional `exports` objects whose order has runtime meaning.
+- Import groups, path groups, type-import placement, and non-style side-effect import order.
+- Stylesheet imports are only checked for final placement and are not moved or reordered automatically.
+- Separate TypeScript `import type` and `export type` declarations.
+- Default manifest key ordering.
 
-Run a check first:
+Check before fixing:
 
 ```sh
 pnpm exec eslint .
-```
-
-Then apply fixes after reviewing the scope:
-
-```sh
 pnpm exec eslint . --fix
 ```
 
 ## Maintenance policy
 
-1. Rule comments explain current behavior, risk, and exceptions without referring to historical versions.
-2. After upgrading recommended presets, inspect the final effective rules to prevent silent severity changes.
-3. New frameworks add parsers, file scopes, and framework semantics without creating another language-rule tier.
-4. New public factories, parsers, or auto-fix behavior require type and runtime tests.
+1. Inspect effective rules after recommended preset upgrades so upstream changes do not silently alter severity.
+2. Every new rule must explain the real problem it catches, its false-positive boundary, and whether it auto-fixes.
+3. Frameworks add parsers, file scopes, and framework semantics without creating another language strictness tier.
+4. Public entries, parser scopes, or auto-fix changes require matching type, runtime, and package tests.

package/docs/rules-risk.zh.md

@@ -1,119 +1,113 @@
 # 默认规则与风险指南
 
-本文说明 2.1.7 当前配置模型、主要规则和迁移风险。规则源码注释只解释现行意图；历史差异统一记录在 `CHANGELOG.md`。
+本文说明当前配置模型、主要规则和自动修复风险。源码注释只解释现行意图；历史差异记录在 `CHANGELOG.md`。
+
+## 规则原则
+
+规则按以下顺序取舍：
+
+1. 符合 JavaScript、TypeScript 与 Vue 社区的通用标准写法，并以简洁、可读为前提。
+2. 发现真实 Bug 和类型安全问题。
+3. 保持跨项目代码一致性。
+4. 最后才采用 Fast 系列项目的风格偏好。
+
+纯粹为了 ESLint 而改变正常语义、增加样板代码或强制冷门写法的规则，不进入默认配置。
 
 ## 配置模型
 
-SDK、OA、Admin、Vue Web 与 UniApp 客户端共享同一套 JavaScript、TypeScript、Import 和 RegExp 规则，不提供严格度档位。
+Vue 3 和 UniApp 是根入口的两个独立具名完整配置：
 
-根入口固定面向 Vue 3 + TypeScript + UniApp：
+- `vueConfig` 仅处理普通 Vue 项目。
+- `uniAppConfig` 在 Vue 能力之外增加 `.nvue`、UniApp globals、清单适配和 `unpackage` 忽略。
 
-- `environment: "browser"`
-- `.gitignore`
-- JavaScript、类型感知 TypeScript
-- Vue 3、`.nvue`、UniApp globals 与清单适配
-- Import、RegExp、JSON/JSONC/JSON5
-- `package.json` 和 `tsconfig*.json` 排序
-- Prettier 冲突关闭层
-- Node.js 工程文件 globals 与末尾规则覆写
+根入口不提供默认导出，公开 `vueConfig`、`uniAppConfig`、`createVueProjectConfigs()`、`createUniAppProjectConfigs()`、`createBaseConfigs()`、`defineRules()` 及相关类型。
 
-`fastConfig()` 只保留 `environment`。React、Angular、Markdown 和 Lodash 通过 `./configs` 子路径组合；规则、globals、ignores 和解析器特殊设置使用后置 Flat Config。
+SDK、Node.js 和其他无框架项目使用 `createBaseConfigs()`。React、Angular、Markdown 和 Lodash 从 `./configs` 显式组合；清单排序属于所有完整配置的基础能力。
 
 ## 预置来源
 
 | 领域       | 预置或实现                                                              |
 | ---------- | ----------------------------------------------------------------------- |
-| JavaScript | `@eslint/js` recommended + 本地规则                                     |
-| TypeScript | typescript-eslint 严格与风格类型感知预置 + Project Service              |
+| JavaScript | `@eslint/js` recommended + 本地高置信度规则                             |
+| TypeScript | typescript-eslint `recommendedTypeChecked` + Project Service            |
 | Vue        | `eslint-plugin-vue` `flat/recommended` + 类型感知 TypeScript            |
 | React      | `@eslint-react` recommended/type-checked + React Hooks Flat Recommended |
 | Angular    | Angular ESLint TypeScript、模板及无障碍 recommended                     |
 | JSON       | `eslint-plugin-jsonc` 三种方言 recommended                              |
-| Import     | `eslint-plugin-import-x` recommended + 固定顺序策略                     |
+| Import     | `eslint-plugin-import-x` recommended + 通用顺序警告                     |
 | RegExp     | 显式正确性、安全和超线性回溯规则                                        |
 | Prettier   | `eslint-config-prettier` 冲突关闭层                                     |
 
-## 主要规则
-
-### JavaScript
-
-- `camelcase: ["error", { properties: "never" }]`：变量和类型使用 camelCase，对象属性允许沿用外部协议字段名。
-- `no-empty` 允许明确忽略失败的空 catch，其他空代码块仍报错。
-- `no-eval` 与 `no-void` 为 `error`；`curly: ["error", "multi-line", "consistent"]`，已有的 `default` 分支必须位于最后。
-- `no-debugger: "error"`
-- `no-use-before-define` 为 `warn`；类和变量必须先声明，函数声明允许提升。
-- `prefer-arrow-callback`、`logical-assignment-operators`、`prefer-object-spread` 为 `error`。
-- `prefer-exponentiation-operator`、`prefer-object-has-own` 为 `error`。
-- `sort-imports` 为 `warn`，只排序同一 import 的成员。
-- `import-x/order` 为 `error`，并设置 `warnOnUnassignedImports: true` 和 `sortTypesGroup: true`；`@/**` 归入 `internal`，类型导入位于所有非样式导入之后并在 `type` 总分组内按来源层级排序，样式导入不参与该规则。
-- `import-x/style-imports-last` 为 `error`；CSS、SCSS、LESS 等样式必须形成最后一个连续导入分组，组内顺序保持不变且不自动修复。
-
-### TypeScript
-
-- 始终启用 `strictTypeChecked`、`stylisticTypeChecked` 与 `projectService: true`；TypeScript、TSX、Vue 与 NVue 统一使用 `extraFileExtensions: [".vue", ".nvue"]`，避免混合检查时 Project Service 重载项目。
-- `no-floating-promises` 与 `strict-void-return` 关闭，Promise 是否等待由业务语义决定；`no-void` 禁止用 `void promise` 规避检查。`no-misused-promises`、`await-thenable`、`require-await` 和 unsafe 类型规则保持严格，但 Vue 模板与 TSX 属性允许 Promise 返回的事件处理函数。
-- TypeScript 与 TSX 的命名函数要求显式返回类型，内联回调和已有函数类型约束的表达式除外；模块导出边界仍要求显式类型。
-- Vue/NVue SFC 关闭函数返回类型与模块边界类型要求，并关闭形参和 catch 形参的未使用检查；普通未使用变量和导入仍报错。模板不会反向推断独立处理函数的参数类型，这类参数仍需显式标注。
-- `explicit-module-boundary-types` 为 `error`，模块导出边界必须显式声明类型，不允许用显式 `any` 参数规避。
-- `no-explicit-any` 为 `warn`。
-- 普通 TS/TSX 的未使用参数和异常可用 `_` 前缀明确忽略；未使用普通变量不能用该前缀规避。
-- `no-empty-function` 仅允许空构造函数和空覆写方法。
-- `consistent-type-imports` 使用独立 `import type` 修复形式，`no-import-type-side-effects` 禁止仅含内联类型说明符的运行时导入。
-- `no-non-null-assertion` 为 `error`。
-- `switch-exhaustiveness-check` 为 `error`；`no-deprecated` 与 `no-unnecessary-condition` 为 `warn`。
-- 模板字符串允许数字插值，箭头简写允许直接返回 void；动态对象字段删除和纯静态工具类不强制改写。
-- `consistent-type-exports` 与 `prefer-readonly` 为 `error`；原始类型不强制将 `||` 改成 `??`。
-- `no-eval`、`no-implied-eval` 与 `no-new-func` 禁止直接或间接动态执行字符串代码；`no-promise-executor-return` 禁止误用 Promise executor 返回值；Vue setup props 和 ref 禁止以丢失响应性的方式使用。
-- `unified-signatures` 保留参数名不同或具有独立 JSDoc 的公共重载；`no-meaningless-void-operator` 由更严格的核心 `no-void` 替代。
-- `consistent-type-definitions`、`consistent-indexed-object-style`、`class-literal-property-style`、`prefer-regexp-exec` 关闭，避免纯语法偏好阻断构建。
-
-### Vue
-
-- 使用 `flat/recommended`。
-- `attribute-hyphenation: ["error", "always"]`。
-- `no-v-html` 为 `warn`。
-- `no-v-text-v-html-on-component` 为 `error`。
-- `require-explicit-emits`、`attributes-order`、`no-mutating-props` 为 `error`。
-- `.vue` 与 `.nvue` 统一使用 TypeScript parser 和 Project Service。
-
-## 类型感知要求
-
-TypeScript、Vue 和 React TSX 始终依赖类型信息。被检查文件必须属于可发现的 `tsconfig.json`，否则 Project Service 会报告配置错误。
-
-本包不再提供 `typeChecked` 或 `tsconfigRootDir` 包装选项。复杂 monorepo 可以通过后置 Flat Config 直接覆盖 `languageOptions.parserOptions`，但不应通过关闭类型检查绕过项目边界问题。
+没有启用完整 `strictTypeChecked`、`stylisticTypeChecked` 或机械式 `all` 预置。额外规则只选择误报低、能直接改善正确性或可读性的部分。
+
+## JavaScript 与 Import
+
+- `camelcase: ["error", { properties: "never" }]`：变量和类型使用 camelCase，外部协议属性可以保留原名。
+- `no-empty` 允许完全空的 `catch`；其他空块仍报错。
+- `no-void` 为错误，不使用 `void` 隐藏 Promise 或表达“忽略返回值”。
+- `no-eval`、`no-implied-eval`、`no-new-func`、`no-promise-executor-return`、`no-debugger` 等真实风险规则为错误。
+- `curly` 只要求多行条件分支使用一致花括号；不会强制所有单行分支加括号。
+- `import-x/first` 和 `import-x/no-duplicates` 为错误。
+- `import-x/order` 为错误，支持修复声明顺序；在通用分组之上保留常用框架、工具和 `@/**` pathGroups。
+- `pathGroupsExcludedImportTypes: ["type"]` 保证类型导入统一留在最后的 type 总分组。
+- 非样式副作用导入参与顺序检查；样式导入由 `style-imports-last` 强制形成最后一个连续分组，但组内不排序，避免改变 CSS 层叠顺序。
+- `sort-imports` 为错误，只统一同一 import 声明内的成员顺序；`prefer-object-has-own` 不启用。
+
+## TypeScript
+
+TypeScript 始终启用 Project Service 和 `recommendedTypeChecked`。被检查文件必须属于可发现的 `tsconfig.json`。
+
+- `.ts`、`.mts`、`.cts` 视为 SDK 式模块封装：`explicit-module-boundary-types` 为错误，导出函数及导出类的公共边界必须显式声明类型。
+- `.tsx` 视为 UI 组件文件：保留类型感知正确性规则，但关闭模块边界类型强制，不要求补写可推断的 JSX 返回类型。
+- `explicit-function-return-type` 关闭，内部函数、局部处理函数和回调使用 TypeScript 推断。
+- `no-inferrable-types` 保留参数和属性上的显式类型，只清理局部变量等没有契约价值的冗余标注。
+- Vue/NVue SFC 与独立 TSX 组件关闭模块边界和函数返回类型要求，保留常见组件写法。
+- `no-floating-promises` 关闭；是否等待、返回或处理 Promise 由业务语义决定。
+- `require-await` 为错误；没有 `await` 的 `async` 会改变返回值和异常语义，应删除 `async`。
+- `no-misused-promises`、`await-thenable`、unsafe 类型规则、穷尽 switch、getter/setter 类型一致性等高置信度检查为错误。
+- `return-await` 只在错误处理正确性需要时要求 `await`。
+- 标准非空断言允许使用；可选链后非空断言、空值合并前非空断言等矛盾组合仍报错。
+- `no-explicit-any` 和 `no-deprecated` 为警告。
+- `no-unnecessary-condition`、`unified-signatures` 及纯语法偏好关闭，避免删除运行时防御或改写公共重载。
+- 模板字符串允许 number 和 boolean；动态字段删除和纯静态工具类不强制改写。
+- `prefer-nullish-coalescing` 不强制原始类型从 `||` 改为 `??`；`prefer-optional-chain` 只在类型明确包含 null/undefined 时要求改写。
+
+## Vue
+
+- 使用官方 `flat/recommended` 作为通用 Vue 基线。
+- `no-v-html` 为警告，提醒审查 XSS 风险但允许已净化内容。
+- `require-explicit-emits`、`no-dupe-keys`、`no-mutating-props`、`no-setup-props-reactivity-loss`、`no-ref-object-reactivity-loss` 和 `no-reserved-component-names` 为错误，并应用于 Vue SFC 与 Vue JSX/TSX 的组件脚本。
+- `attribute-hyphenation`、`no-v-text-v-html-on-component` 和 `attributes-order` 仅应用于 `.vue/.nvue` 模板；`attributes-order` 按定义、循环、条件、渲染修饰、唯一属性、全局属性、普通属性、事件和内容排序。
+- JSX 属性继续使用 JavaScript 的 camelCase 约定，不受模板 kebab-case 规则影响。
+- setup props/ref 响应性丢失和自定义事件命名错误仍为错误。
 
 ## UniApp 边界
 
-根入口默认声明 `uni`、`uniCloud`、页面 API 及条件编译平台对象，并允许 `pages.json`、`manifest.json` 中的注释。
+只有 UniApp 入口声明 `uni`、`uniCloud`、页面 API 及 `wx`、`plus`、`my`、`tt` 等条件编译平台对象。普通 Vue 入口不会获得这些 globals，也不会忽略 `unpackage`。
 
-ESLint 不执行条件编译，因此 `wx`、`plus` 等对象在根入口处理的全部代码文件中可见。这避免平台分支中的 `no-undef`，但不能验证对象是否位于正确的 `#ifdef` 分支。普通 Vue 项目如不希望获得这些 globals，应直接组合所需配置片段，而不是使用根入口。
+ESLint 不执行条件编译，所以能避免平台分支中的 `no-undef`，但不能验证对象是否出现在正确的 `#ifdef` 分支。
 
-## 自动修复风险
+## 清单排序与自动修复
 
-重点审查以下自动修复：
+`package.json` 和 `tsconfig*.json` 排序属于 `createBaseConfigs()`、`vueConfig` 和 `uniAppConfig` 的默认配置。独立片段工厂仍可用于自定义组合。
 
-- Import 分组、类型来源层级、成员顺序和副作用导入位置。
-- TypeScript 独立 `import type` 声明。
-- Vue 属性命名与排序。
-- `package.json` 和 `tsconfig*.json` 字段顺序。
+重点审查以下自动修复：
 
-`package.json` 排序不会进入顺序具有运行时语义的条件 `exports` 对象。
+- Import 分组、pathGroups、类型导入位置与非样式副作用导入顺序。
+- 样式导入只检查是否位于最后，不自动移动或重排。
+- TypeScript 独立 `import type` / `export type`。
+- 默认启用的清单字段排序。
 
-建议先运行：
+先检查，再修复：
 
 ```sh
 pnpm exec eslint .
-```
-
-确认问题范围后再运行：
-
-```sh
 pnpm exec eslint . --fix
 ```
 
 ## 维护约定
 
-1. 修改规则时解释当前行为、风险和例外，不在源码注释中引用历史版本。
-2. 升级 recommended 预置后检查最终生效规则，避免上游变化静默改变严重级别。
-3. 新增框架只增加解析器、文件范围和框架语义，不建立第二套语言规则档位。
-4. 新增公共配置工厂、解析器或自动修复行为时同步增加类型和运行时测试。
+1. 升级 recommended 预置后检查最终生效配置，避免上游变化静默改变严重级别。
+2. 新规则必须说明它解决的真实问题、误报边界和是否自动修复。
+3. 框架只增加解析器、文件范围和框架语义，不建立第二套语言严格度。
+4. 公共入口、解析器范围或自动修复行为变化时同步更新类型、运行时和发布测试。

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fast-china/eslint-config",
-	"version": "2.1.7",
+	"version": "2.1.8",
 	"description": "Practical, typed ESLint Flat Config for Vue 3, UniApp, React, Angular, Vite, TypeScript, JavaScript, and Node.js.",
 	"type": "module",
 	"keywords": [
@@ -72,6 +72,8 @@
 		"dev": "eslint-config-inspector --config src/eslint-inspector.config.ts",
 		"build": "pnpm run typegen:check && tsdown",
 		"build:inspector": "eslint-config-inspector build --config src/eslint-inspector.config.ts",
+		"docs:rules": "tsx scripts/rules-docs.ts",
+		"docs:rules:check": "tsx scripts/rules-docs.ts --check",
 		"typegen": "tsx scripts/typegen.ts",
 		"typegen:check": "tsx scripts/typegen.ts --check",
 		"typecheck": "tsc --noEmit",
@@ -83,7 +85,7 @@
 		"test:types": "tsc --noEmit --project tests/tsconfig.json",
 		"test:runtime": "node --test tests/config.test.mjs",
 		"test:package": "node --test tests/package.test.mjs",
-		"check": "pnpm run typecheck && pnpm run test && pnpm run lint && pnpm run format:check",
+		"check": "pnpm run typecheck && pnpm run docs:rules:check && pnpm run test && pnpm run lint && pnpm run format:check",
 		"prepack": "pnpm run check"
 	},
 	"peerDependencies": {