@fast-china/eslint-config 1.1.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +40 -0
- package/README.md +158 -83
- package/README.zh.md +159 -84
- package/dist/{define-rules-CSwQ8C1q.d.ts → define-rules.d.mts} +6010 -4651
- package/dist/define-rules.d.mts.map +1 -0
- package/dist/index.d.mts +181 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +475 -0
- package/dist/index.mjs.map +1 -0
- package/dist/rules/index.d.mts +309 -0
- package/dist/rules/index.d.mts.map +1 -0
- package/dist/rules/index.mjs +2 -0
- package/dist/rules.mjs +485 -0
- package/dist/rules.mjs.map +1 -0
- package/docs/engineering-audit.zh.md +77 -82
- package/docs/rules-risk.md +40 -45
- package/docs/rules-risk.zh.md +41 -46
- package/package.json +26 -18
- package/dist/index.d.ts +0 -259
- package/dist/index.js +0 -786
- package/dist/index.js.map +0 -1
- package/dist/rules/index.d.ts +0 -229
- package/dist/rules/index.js +0 -486
- package/dist/rules/index.js.map +0 -1
|
@@ -1,82 +1,68 @@
|
|
|
1
1
|
# 工程质量审查报告
|
|
2
2
|
|
|
3
|
-
审查日期：2026-07-
|
|
3
|
+
审查日期：2026-07-26
|
|
4
4
|
|
|
5
|
-
审查对象：`@fast-china/eslint-config`
|
|
5
|
+
审查对象：`@fast-china/eslint-config` 2.0.1 工作区
|
|
6
6
|
|
|
7
7
|
## 结论
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
当前仓库已经具备完整 ESLint Flat Config 开源库所需的核心能力：稳定且精简的公共 API、明确的语言作用域、可选类型感知检查、精确规则类型、可重复构建、集成测试、CI、发布归档检查和中英文文档。
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
默认场景面向 Vue 3 + Vite + TypeScript，同时提供按需启用的一等 React 与 Angular 集成，并支持 JavaScript、Node.js、JSON、JSONC、JSON5、Markdown、正则表达式和模块导入检查。所有可选能力均通过 `fastConfig(options, ...overrides)` 组合，项目覆写始终位于内置配置之后。
|
|
12
12
|
|
|
13
13
|
## 审查范围
|
|
14
14
|
|
|
15
|
-
- npm
|
|
16
|
-
- TypeScript
|
|
17
|
-
- Flat Config
|
|
18
|
-
- JavaScript、TypeScript、Vue、JSON 方言、Markdown、RegExp
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
|
|
|
34
|
-
|
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
-
|
|
61
|
-
-
|
|
62
|
-
-
|
|
63
|
-
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
### 第四阶段：建立防回归机制
|
|
67
|
-
|
|
68
|
-
- 使用 Node.js 内置测试运行器，直接测试构建后的公开包。
|
|
69
|
-
- 覆盖默认导出、工厂开关、Vue 2、类型感知配置与所有主要文件类型。
|
|
70
|
-
- CI 覆盖 Node.js 20.19、22.13 和 24，并检查发布归档。
|
|
71
|
-
- `pnpm check` 统一构建、类型、lint、格式和测试门禁。
|
|
72
|
-
|
|
73
|
-
### 第五阶段：规则可维护性与风险治理
|
|
74
|
-
|
|
75
|
-
- 每条本地规则覆写都在源码旁说明作用、启用原因和重要例外。
|
|
76
|
-
- 使用 `[高影响]`、`[可自动修复]`、`[安全关注]` 等统一标记维护风险。
|
|
77
|
-
- 增加中英文规则风险指南，公开默认上游预置、高影响清单和按文件降级示例。
|
|
78
|
-
- 禁止排序 `package.json#exports` 条件键，并通过自动修复回归测试锁定这一语义边界。
|
|
79
|
-
- 从 ESLint 和内置插件 schema 生成公开 `RuleOptions`，并用 `defineRules()`、漂移检查和消费者编译测试保证自动补全可用。
|
|
15
|
+
- npm 包元数据、ESM 入口、公开子路径与发布文件
|
|
16
|
+
- TypeScript 6、tsdown、类型生成与声明文件
|
|
17
|
+
- ESLint Flat Config 顺序、文件作用域、解析器和插件注册
|
|
18
|
+
- JavaScript、TypeScript、Vue、React、Angular、JSON 方言、Markdown、RegExp 与 import 集成
|
|
19
|
+
- 浏览器、Node.js、通用环境和项目自定义全局变量
|
|
20
|
+
- Lodash 静态导入策略、清单排序与 Prettier 职责边界
|
|
21
|
+
- README、规则风险说明、贡献流程、CI、测试和发布前检查
|
|
22
|
+
|
|
23
|
+
## 当前工程基线
|
|
24
|
+
|
|
25
|
+
| 领域 | 状态 | 质量保障 |
|
|
26
|
+
| -------------- | ---- | ------------------------------------------------------------------------- |
|
|
27
|
+
| 公共 API | 通过 | 根入口提供 `fastConfig`、`defaultConfigOptions`、`defineRules` 和相关类型 |
|
|
28
|
+
| Flat Config | 通过 | 所有语言和插件配置限定到明确文件范围，项目覆写最后应用 |
|
|
29
|
+
| Vue 3 | 通过 | `vue-eslint-parser` 处理 SFC，TypeScript 解析器正确嵌套 |
|
|
30
|
+
| React | 通过 | 按需覆盖 JSX/TSX、组件、官方 Hooks、Compiler 诊断与 DOM 安全 |
|
|
31
|
+
| Angular | 通过 | 按需覆盖框架 TypeScript、外部 HTML、内联模板与模板无障碍 |
|
|
32
|
+
| TypeScript | 通过 | 默认使用推荐规则，可选 Project Service 类型感知模式 |
|
|
33
|
+
| JavaScript | 通过 | 应用 `@eslint/js` 推荐规则并区分应用环境与 Node.js 工程文件 |
|
|
34
|
+
| 数据与文档文件 | 通过 | JSON、JSONC、JSON5 和 Markdown 分别使用对应语言配置 |
|
|
35
|
+
| 规则自动补全 | 通过 | 从 ESLint 核心和随包插件 schema 生成精确 `RuleOptions` |
|
|
36
|
+
| Lodash 策略 | 通过 | 可选统一 `lodash` 或 `lodash-unified`，默认不限制项目依赖选择 |
|
|
37
|
+
| 清单排序 | 通过 | 默认关闭；启用后不会重排 `package.json#exports` 条件键 |
|
|
38
|
+
| Prettier | 通过 | 只关闭冲突规则，格式化由 Prettier CLI 或编辑器负责 |
|
|
39
|
+
| 构建与发布 | 通过 | tsdown 生成 `.mjs`、`.d.mts` 和 source map，`prepack` 执行完整质量门禁 |
|
|
40
|
+
| 自动化验证 | 通过 | 运行时测试、消费者类型测试、格式检查、静态检查和 Node.js 多版本 CI |
|
|
41
|
+
|
|
42
|
+
## 配置组合模型
|
|
43
|
+
|
|
44
|
+
`fastConfig()` 按以下顺序生成配置：
|
|
45
|
+
|
|
46
|
+
1. 内置忽略项、项目附加忽略项和可选 `.gitignore`。
|
|
47
|
+
2. 应用运行环境、项目全局变量和 Node.js 工程文件全局变量。
|
|
48
|
+
3. JavaScript、import-x、Lodash 策略、RegExp、TypeScript、JSON 方言、Vue、React、Angular 和 Markdown 配置。
|
|
49
|
+
4. 可选 `package.json`、`tsconfig*.json` 排序配置。
|
|
50
|
+
5. Prettier 冲突关闭配置。
|
|
51
|
+
6. 工厂级 `rules` 与调用方传入的文件级覆写。
|
|
52
|
+
|
|
53
|
+
这一顺序保证调用方可以覆盖任何内置规则，同时避免语言规则进入不支持的文件类型。
|
|
54
|
+
|
|
55
|
+
## 规则与类型维护
|
|
56
|
+
|
|
57
|
+
- 每条本地规则旁必须说明作用、启用理由和重要风险。
|
|
58
|
+
- 高影响、可自动修复、安全相关和按需启用规则使用统一标签。
|
|
59
|
+
- 默认高影响规则同步记录在中英文风险指南中。
|
|
60
|
+
- `src/typegen.d.ts` 由规则 schema 生成，不允许手工编辑。
|
|
61
|
+
- React、Angular 插件也参与类型生成，因此框架规则名与选项可获得同样的精确自动补全。
|
|
62
|
+
- ESLint 或插件升级后必须运行 `pnpm typegen` 并审查类型差异。
|
|
63
|
+
- `@fast-china/eslint-config/rules` 提供有完整注释的原始规则记录，便于高级组合。
|
|
64
|
+
|
|
65
|
+
Lodash 选项使用 ESLint 核心 `no-restricted-imports`，因此无需增加插件依赖。它负责防止静态 import/export 混用包入口，不负责安装目标包，也不检查动态 `import()` 或 CommonJS `require()`。
|
|
80
66
|
|
|
81
67
|
## 质量门禁
|
|
82
68
|
|
|
@@ -87,19 +73,28 @@ pnpm check
|
|
|
87
73
|
pnpm pack --dry-run
|
|
88
74
|
```
|
|
89
75
|
|
|
90
|
-
|
|
76
|
+
`pnpm check` 包含：
|
|
91
77
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
78
|
+
1. 生成类型漂移检查。
|
|
79
|
+
2. 正式 ESM 与声明文件构建。
|
|
80
|
+
3. TypeScript 源码类型检查。
|
|
81
|
+
4. ESLint 全仓检查。
|
|
82
|
+
5. Prettier 格式检查。
|
|
83
|
+
6. 消费者类型测试和运行时集成测试。
|
|
98
84
|
|
|
99
|
-
|
|
85
|
+
发布归档必须包含根入口和 `./rules` 子入口的 JavaScript 与声明文件，以及生成的 JavaScript、声明 source map；且不得包含源码缓存、测试缓存或本地依赖目录。
|
|
100
86
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
87
|
+
## CI 与发布边界
|
|
88
|
+
|
|
89
|
+
GitHub Actions 在 `master`、`main` 推送和 Pull Request 上运行，覆盖 Node.js 22.18 和 24.11。CI 使用 pnpm 11.x、冻结锁文件安装、完整质量门禁和发布归档预览。
|
|
90
|
+
|
|
91
|
+
CI 只验证代码和发布包，不自动发布 npm。正式发布仍由维护者确认版本、Changelog、归档内容和 npm 身份后执行。
|
|
92
|
+
|
|
93
|
+
## 剩余风险
|
|
94
|
+
|
|
95
|
+
- ESLint 和插件推荐预置会随依赖升级变化，每次升级都要检查实际生效配置和生成类型差异。
|
|
96
|
+
- React 与 Angular 默认关闭；启用 Angular 时必须同时启用 TypeScript，并把现代组件、变更检测、控制流和无障碍规则作为框架接入成本审查。
|
|
97
|
+
- 类型感知模式依赖项目 `tsconfig.json` 覆盖被检查文件，复杂 monorepo 应显式设置 `tsconfigRootDir`。
|
|
98
|
+
- 自动修复可能调整 import、模板属性、正则表达式和清单字段，应在独立提交中审查结果。
|
|
99
|
+
- Lodash 策略只覆盖静态模块语法；需要限制 CommonJS 或动态导入的项目应追加自己的文件级规则或代码审查约定。
|
|
100
|
+
- npm 发布自动化尚未启用，后续应在可信发布、分支保护和维护者审批策略确定后单独设计。
|
package/docs/rules-risk.md
CHANGED
|
@@ -4,22 +4,24 @@ This document records what the default config inherits, which rules can have a l
|
|
|
4
4
|
|
|
5
5
|
## Risk labels
|
|
6
6
|
|
|
7
|
-
- `[High impact]`: the rule can create a large diff, block
|
|
7
|
+
- `[High impact]`: the rule can create a large diff, block existing patterns, or require a review of runtime or public API behavior.
|
|
8
8
|
- `[Auto-fixable]`: the currently locked ESLint or plugin version declares the rule fixable by `eslint --fix`. It does not remove the need for review.
|
|
9
9
|
- `[Security]`: the rule primarily protects a trust or injection boundary.
|
|
10
10
|
- `[Disabled by default]` and `[Opt-in]`: the rule record exists but is not loaded by the default config.
|
|
11
11
|
|
|
12
12
|
High impact does not mean inherently unsafe. It means adoption or fix review is relatively expensive. Module side effects, getters and proxies, build-tool conventions, and public component APIs deserve particular attention.
|
|
13
13
|
|
|
14
|
-
##
|
|
14
|
+
## Bundled preset sources
|
|
15
15
|
|
|
16
|
-
`
|
|
16
|
+
`fastConfig()` defaults to Vue 3, TypeScript, JavaScript, import, RegExp, JSON, Markdown, and the Prettier compatibility layer. React, Angular, type-aware TypeScript linting, and manifest sorting are opt-in.
|
|
17
17
|
|
|
18
18
|
| Scope | Inherited preset | Notes |
|
|
19
19
|
| ---------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
20
20
|
| JavaScript | `@eslint/js` `recommended` | Core syntax and runtime correctness, including `no-undef` and `no-unused-vars`. |
|
|
21
21
|
| TypeScript | typescript-eslint `recommended` + `stylistic` | Does not read type information by default; local overrides are applied afterward. |
|
|
22
|
-
| Vue 3 | `@eslint/js`, non-type-aware typescript-eslint presets, and `eslint-plugin-vue` `flat/recommended` | Vue
|
|
22
|
+
| Vue 3 | `@eslint/js`, non-type-aware typescript-eslint presets, and `eslint-plugin-vue` `flat/recommended` | Handles Vue 3 SFCs and applies TypeScript rules to `<script lang="ts">` correctly. |
|
|
23
|
+
| React (opt-in) | `@eslint-react/recommended*` and `eslint-plugin-react-hooks` `flat/recommended` | Checks components, JSX/TSX, DOM APIs, Hooks, and stable React Compiler diagnostics. |
|
|
24
|
+
| Angular (opt-in) | angular-eslint 22.x TypeScript, template recommended, and template accessibility rule sets | Checks Angular TypeScript plus external and extracted inline templates; requires TypeScript support. |
|
|
23
25
|
| Imports | `eslint-plugin-import-x` `recommended` | Local rules add import placement, deduplication, and ordering. Resolver-dependent checks stay disabled. |
|
|
24
26
|
| RegExp | `eslint-plugin-regexp` `flat/recommended` | Some rules can rewrite regular expressions; run tests after bulk fixes. |
|
|
25
27
|
| JSON dialects | The matching `eslint-plugin-jsonc` `flat/recommended-*` preset | JSON, JSONC, and JSON5 are scoped separately. |
|
|
@@ -30,71 +32,64 @@ The exact upstream rule set is defined by the dependency versions in `pnpm-lock.
|
|
|
30
32
|
|
|
31
33
|
## High-impact defaults
|
|
32
34
|
|
|
33
|
-
| Rule | Severity | Auto-fix | Main impact | Recommended review
|
|
34
|
-
| ------------------------------------------------------- | ---------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
35
|
-
| `
|
|
36
|
-
|
|
|
37
|
-
| `@typescript-eslint/
|
|
38
|
-
| `@typescript-eslint/
|
|
39
|
-
|
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `vue/
|
|
46
|
-
| `vue/
|
|
47
|
-
| `
|
|
48
|
-
|
|
|
49
|
-
| RegExp recommended preset | Upstream-defined | Some rules | May rewrite character classes, quantifiers, or assertions. | Exercise representative real-world inputs after fixing. |
|
|
35
|
+
| Rule | Severity | Auto-fix | Main impact | Recommended review |
|
|
36
|
+
| ------------------------------------------------------- | ---------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
|
|
37
|
+
| `import-x/order` | error | Yes | Groups and reorders imports. Unassigned side-effect imports are reported but cannot be safely moved automatically. | Check entrypoints, polyfills, styles, and registration imports. |
|
|
38
|
+
| `@typescript-eslint/no-unused-vars` | error | Yes in the locked plugin | Can remove unused imports, variables, or declarations. An underscore prefix is the explicit escape hatch. | Run type checking, builds, and tests after an isolated cleanup. |
|
|
39
|
+
| `@typescript-eslint/consistent-type-imports` | error | Yes | Converts type-only dependencies to inline `type` imports; an import used only for side effects could disappear from emitted code. | Express side effects as a separate `import "module"` and inspect build output. |
|
|
40
|
+
| `@typescript-eslint/no-require-imports` | error | No | Blocks CommonJS, conditional loading, and some toolchain interop patterns. | Disable only for configuration files that genuinely require it. |
|
|
41
|
+
| `no-var` | error | Yes | Moves `var` declarations to block scope; hoisting and loop closures need attention. | Run behavior tests, especially around callbacks created in loops. |
|
|
42
|
+
| `prefer-arrow-callback` | error | Yes | Rewrites callbacks; code relying on `this`, `arguments`, or named stack frames needs review. | Check event handlers, library callbacks, and stack traces. |
|
|
43
|
+
| `logical-assignment-operators` | error | Yes | Rewrites conditional assignment; getter and Proxy access counts deserve review. | Test state containers and reactive objects. |
|
|
44
|
+
| `no-restricted-syntax` (`LabeledStatement`) | error | No | Requires control-flow refactoring for labeled break or continue. | Downgrade only in affected files and restore after refactoring. |
|
|
45
|
+
| `sort-imports` | warn | Yes | Sorts members inside one import declaration and usually creates text-only diffs. | Keep it in an isolated cleanup with `import-x/order`. |
|
|
46
|
+
| `vue/require-explicit-emits` | error | No | Makes emitted events an explicit component API and can surface undeclared events. | Model the real event list instead of disabling it blindly. |
|
|
47
|
+
| `vue/no-mutating-props` | error | No | Enforces one-way data flow and may require local state or event changes. | Review the fix as a component-design change. |
|
|
48
|
+
| `vue/attributes-order` | error | Yes | Can reorder many template attributes on first use. | Keep template sorting separate from business changes. |
|
|
49
|
+
| `no-unused-vars`, `no-undef` from the JavaScript preset | error | No | Can report many existing issues and expose missing runtime-global declarations. | Select the correct `environment` before cleanup. |
|
|
50
|
+
| RegExp recommended preset | Upstream-defined | Some rules | May rewrite character classes, quantifiers, or assertions. | Exercise representative real-world inputs after fixing. |
|
|
50
51
|
|
|
51
52
|
`vue/no-v-html` is also enabled as a warning. It is a security signal rather than an automatic rewrite: HTML must be trusted or reliably sanitized.
|
|
52
53
|
|
|
53
54
|
## High-impact features not enabled by default
|
|
54
55
|
|
|
55
56
|
- Type-aware TypeScript and Vue presets require `typeChecked: true`. They add project-service cost and rules such as `no-floating-promises`.
|
|
56
|
-
-
|
|
57
|
-
- `
|
|
57
|
+
- React requires `react: true`. Its upstream recommended and official Hooks presets include blocking component, Hooks, and React Compiler rules; review existing custom hook and memoization patterns when adopting it.
|
|
58
|
+
- Angular requires `angular: true`. The framework bundle enables `prefer-inject`, OnPush change detection, standalone components, modern template control flow, and template accessibility. These policies are intentionally not active in the default Vue configuration.
|
|
59
|
+
- The `jsonc/sort-keys` and `jsonc/sort-array-values` manifest rules require `sortPackageJson: true` or `sortTsconfig: true`. Isolate the first fix and verify the publish manifest.
|
|
60
|
+
- Lodash import restrictions require `lodash: "lodash"` or `lodash: "lodash-unified"`. They use `no-restricted-imports` to prevent mixed static package entry points but do not inspect dynamic `import()` or CommonJS `require()`.
|
|
58
61
|
- Resolver-dependent import checks such as `import-x/no-unresolved` and `import-x/named` stay disabled.
|
|
59
62
|
- Keys inside `package.json#exports` are never sorted. Node conditional exports use key order during matching, so reordering can change the loaded file.
|
|
60
63
|
|
|
61
|
-
|
|
64
|
+
When Angular is enabled, the highest-adoption-cost rules are `@angular-eslint/prefer-inject`, `@angular-eslint/prefer-on-push-component-change-detection`, `@angular-eslint/prefer-standalone`, and `@angular-eslint/template/prefer-control-flow`. Treat their fixes as framework migrations rather than formatting cleanup. Set `angular: { templateAccessibility: false }` only when accessibility is enforced by another equivalent tool; individual exceptions should normally use file-scoped trailing overrides.
|
|
65
|
+
|
|
66
|
+
## Scoped overrides
|
|
62
67
|
|
|
63
68
|
Overrides must follow the shared config and should target only the affected files:
|
|
64
69
|
|
|
65
70
|
```js
|
|
66
|
-
import {
|
|
67
|
-
|
|
68
|
-
import { createConfig } from "@fast-china/eslint-config";
|
|
71
|
+
import fastChina, { defineRules } from "@fast-china/eslint-config";
|
|
69
72
|
|
|
70
|
-
export default
|
|
71
|
-
|
|
73
|
+
export default fastChina(
|
|
74
|
+
{},
|
|
72
75
|
{
|
|
73
|
-
name: "project/typescript-
|
|
76
|
+
name: "project/typescript-exceptions",
|
|
74
77
|
files: ["**/*.{ts,tsx,mts,cts,vue}"],
|
|
75
|
-
rules: {
|
|
78
|
+
rules: defineRules({
|
|
76
79
|
"@typescript-eslint/consistent-type-imports": "warn",
|
|
77
80
|
"@typescript-eslint/no-require-imports": "off",
|
|
78
81
|
"@typescript-eslint/no-unused-vars": "warn",
|
|
79
|
-
},
|
|
82
|
+
}),
|
|
80
83
|
},
|
|
81
84
|
{
|
|
82
|
-
name: "project/vue-
|
|
85
|
+
name: "project/vue-exceptions",
|
|
83
86
|
files: ["**/*.vue"],
|
|
84
|
-
rules: {
|
|
87
|
+
rules: defineRules({
|
|
85
88
|
"vue/attributes-order": "warn",
|
|
86
89
|
"vue/require-explicit-emits": "warn",
|
|
87
|
-
},
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
name: "project/json-migration",
|
|
91
|
-
files: ["**/{package.json,tsconfig*.json}"],
|
|
92
|
-
rules: {
|
|
93
|
-
"jsonc/sort-array-values": "off",
|
|
94
|
-
"jsonc/sort-keys": "off",
|
|
95
|
-
},
|
|
96
|
-
},
|
|
97
|
-
]);
|
|
90
|
+
}),
|
|
91
|
+
}
|
|
92
|
+
);
|
|
98
93
|
```
|
|
99
94
|
|
|
100
95
|
Run a read-only lint first, then apply `eslint --fix` on a separate branch or commit. Review imports, side-effect entrypoints, package exports, component events, and manifests before running the project's type checks, build, and tests.
|
package/docs/rules-risk.zh.md
CHANGED
|
@@ -6,22 +6,24 @@
|
|
|
6
6
|
|
|
7
7
|
源码中的标记采用以下含义：
|
|
8
8
|
|
|
9
|
-
- `[高影响]
|
|
9
|
+
- `[高影响]`：规则可能产生大面积差异、阻断既有写法，或要求人工确认运行时与公共 API 行为。
|
|
10
10
|
- `[可自动修复]`：当前锁定的 ESLint/插件版本声明该规则可被 `eslint --fix` 修改；不代表无需代码审查。
|
|
11
11
|
- `[安全关注]`：规则主要提示注入、信任边界等安全问题。
|
|
12
12
|
- `[默认关闭]`、`[按需启用]`：规则记录存在，但默认配置不会启用。
|
|
13
13
|
|
|
14
14
|
“高影响”不等于规则本身不安全。它表示规则的采用成本或修复审查成本较高。默认自动修复的目标仍是保持语义，但模块副作用、getter/Proxy、构建器约定和公共组件 API 都需要项目维护者复核。
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## 内置预置来源
|
|
17
17
|
|
|
18
|
-
`
|
|
18
|
+
`fastConfig()` 默认开启 Vue 3、TypeScript、JavaScript、import、RegExp、JSON、Markdown 与 Prettier 兼容层；React、Angular、TypeScript 类型感知和清单排序默认关闭。
|
|
19
19
|
|
|
20
20
|
| 范围 | 默认继承 | 说明 |
|
|
21
21
|
| ---------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
22
22
|
| JavaScript | `@eslint/js` 的 `recommended` | 基础语法和运行时正确性，包括 `no-undef`、`no-unused-vars` 等。 |
|
|
23
23
|
| TypeScript | typescript-eslint 的 `recommended` + `stylistic` | 默认不读取类型信息；本库规则在预置之后覆写。 |
|
|
24
|
-
| Vue 3 | `@eslint/js`、typescript-eslint 非类型感知预置、`eslint-plugin-vue` 的 `flat/recommended` | Vue
|
|
24
|
+
| Vue 3 | `@eslint/js`、typescript-eslint 非类型感知预置、`eslint-plugin-vue` 的 `flat/recommended` | 处理 Vue 3 单文件组件，并让 TypeScript 规则正确作用于 `<script lang="ts">`。 |
|
|
25
|
+
| React（按需） | `@eslint-react/recommended*` 与 `eslint-plugin-react-hooks` 的 `flat/recommended` | 检查组件、JSX/TSX、DOM API、Hooks 与稳定的 React Compiler 诊断。 |
|
|
26
|
+
| Angular（按需） | angular-eslint 22.x 的 TypeScript、模板推荐与模板无障碍规则集 | 检查 Angular TypeScript、外部模板和提取后的内联模板；必须启用 TypeScript。 |
|
|
25
27
|
| import | `eslint-plugin-import-x` 的 `recommended` | 本库额外配置导入位置、去重和排序。解析器相关规则默认关闭，避免绑定具体别名方案。 |
|
|
26
28
|
| RegExp | `eslint-plugin-regexp` 的 `flat/recommended` | 部分规则可自动改写正则表达式，批量修复后需运行测试。 |
|
|
27
29
|
| JSON/JSONC/JSON5 | `eslint-plugin-jsonc` 对应方言的 `flat/recommended-*` | 三种方言按扩展名隔离，不会互相叠加。 |
|
|
@@ -32,73 +34,66 @@
|
|
|
32
34
|
|
|
33
35
|
## 默认启用的高影响规则
|
|
34
36
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
| 规则 | 等级 | 自动修复 | 主要影响 | 建议
|
|
38
|
-
| --------------------------------------------------- | ---------- | ------------------ | --------------------------------------------------------------------------------------------------- |
|
|
39
|
-
| `
|
|
40
|
-
|
|
|
41
|
-
| `@typescript-eslint/
|
|
42
|
-
| `@typescript-eslint/
|
|
43
|
-
|
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
49
|
-
| `vue/
|
|
50
|
-
| `vue/
|
|
51
|
-
| `
|
|
52
|
-
|
|
|
53
|
-
| RegExp 推荐预置 | 由上游决定 | 部分规则是 | 可能改写字符类、量词或断言；语法等价不代表业务输入覆盖充分。 | 修复后运行覆盖真实输入的正则测试。 |
|
|
37
|
+
下表覆盖本库主动设置的高影响规则，以及上游默认预置中采用成本较高、最需要审查的规则。
|
|
38
|
+
|
|
39
|
+
| 规则 | 等级 | 自动修复 | 主要影响 | 建议 |
|
|
40
|
+
| --------------------------------------------------- | ---------- | ------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
|
|
41
|
+
| `import-x/order` | error | 是 | 重排并分组 import。带副作用的裸 import 会被报告但不会安全地自动移动，人工调整顺序可能改变启动行为。 | 先检查入口、polyfill、样式和注册器 import。 |
|
|
42
|
+
| `@typescript-eslint/no-unused-vars` | error | 是（当前插件版本） | 可能删除未使用的 import、变量或声明；以下划线开头是显式保留出口。 | 在独立提交中修复并运行类型检查、构建和测试。 |
|
|
43
|
+
| `@typescript-eslint/consistent-type-imports` | error | 是 | 将纯类型依赖改成内联 `type` import；若原 import 还承担模块副作用，编译后行为可能变化。 | 副作用应改成独立的 `import "module"`，并复核构建产物。 |
|
|
44
|
+
| `@typescript-eslint/no-require-imports` | error | 否 | 阻断 CommonJS、条件加载和部分工具链互操作写法。 | 仅在确实需要的配置文件上按范围关闭，不要全局隐藏。 |
|
|
45
|
+
| `no-var` | error | 是 | 将 `var` 改为块级声明；声明提升和循环闭包行为需要关注。 | 先运行现有测试，重点复核循环内回调。 |
|
|
46
|
+
| `prefer-arrow-callback` | error | 是 | 批量改写回调形式，影响 `this`、`arguments` 或函数名调试体验的代码需要人工确认。 | 检查事件处理器、类库回调和栈追踪。 |
|
|
47
|
+
| `logical-assignment-operators` | error | 是 | 将条件赋值改成 `\|\|=`、`&&=`、`??=`；getter 或 Proxy 场景要确认读取和写入次数。 | 对状态容器和响应式对象运行行为测试。 |
|
|
48
|
+
| `no-restricted-syntax`（`LabeledStatement`） | error | 否 | 禁止 labeled break/continue，可能要求重构多层循环控制流。 | 必要时按文件降级，重构后再恢复。 |
|
|
49
|
+
| `sort-imports` | warn | 是 | 排序同一 import 声明中的成员，通常只产生文本差异。 | 与 `import-x/order` 一起在独立整理提交中执行。 |
|
|
50
|
+
| `vue/require-explicit-emits` | error | 否 | 要求组件声明事件，相当于补全组件公共 API；旧组件可能大量报错。 | 先补齐实际事件清单，不要盲目关闭。 |
|
|
51
|
+
| `vue/no-mutating-props` | error | 否 | 强制单向数据流，可能要求引入本地状态或事件。 | 把修复当作组件设计变更审查。 |
|
|
52
|
+
| `vue/attributes-order` | error | 是 | 首次运行会重排大量模板属性，通常不改变运行逻辑但会形成大 diff。 | 单独提交模板排序，不与业务修改混合。 |
|
|
53
|
+
| `no-unused-vars`、`no-undef`（JavaScript 上游预置） | error | 否 | JavaScript 代码可能出现较多阻断错误；`no-undef` 还会暴露缺失的运行时全局变量声明。 | 正确选择 `environment`，再逐步清理无用代码。 |
|
|
54
|
+
| RegExp 推荐预置 | 由上游决定 | 部分规则是 | 可能改写字符类、量词或断言；语法等价不代表业务输入覆盖充分。 | 修复后运行覆盖真实输入的正则测试。 |
|
|
54
55
|
|
|
55
56
|
另外，`vue/no-v-html` 默认是 `warn`，属于安全关注而非自动重写规则。它提示调用方必须保证 HTML 来自可信来源或经过可靠净化。
|
|
56
57
|
|
|
57
58
|
## 明确不默认启用的高影响能力
|
|
58
59
|
|
|
59
60
|
- TypeScript 和 Vue 的类型感知预置仅在 `typeChecked: true` 时启用；它们会增加项目服务开销，并启用 `no-floating-promises` 等需要类型信息的规则。
|
|
60
|
-
-
|
|
61
|
-
-
|
|
61
|
+
- React 仅在 `react: true` 时启用。其上游推荐预置和官方 Hooks 预置包含阻断级组件、Hooks 与 React Compiler 规则；接入旧项目时应重点审查自定义 Hook 和 memoization 写法。
|
|
62
|
+
- Angular 仅在 `angular: true` 时启用。框架规则默认要求 `inject()`、OnPush 变更检测、独立组件、现代模板控制流和模板无障碍；这些约束不会进入默认 Vue 配置。
|
|
63
|
+
- 清单排序规则 `jsonc/sort-keys`、`jsonc/sort-array-values` 分别仅在 `sortPackageJson: true`、`sortTsconfig: true` 时启用；首次修复应单独提交并核对发布清单。
|
|
64
|
+
- Lodash 静态导入限制仅在 `lodash: "lodash"` 或 `lodash: "lodash-unified"` 时启用。该策略使用 `no-restricted-imports` 阻止混用包入口，但不会检查动态 `import()` 或 CommonJS `require()`。
|
|
62
65
|
- `import-x/no-unresolved`、`import-x/named` 等依赖 resolver 的检查默认关闭。
|
|
63
66
|
- `package.json` 的 `exports` 条件键永不自动排序。Node 条件导出按键顺序匹配，改写顺序可能改变实际加载文件。
|
|
64
67
|
|
|
68
|
+
启用 Angular 后，采用成本最高的规则是 `@angular-eslint/prefer-inject`、`@angular-eslint/prefer-on-push-component-change-detection`、`@angular-eslint/prefer-standalone` 与 `@angular-eslint/template/prefer-control-flow`。应把修复视为框架迁移，而不是格式整理。只有项目已使用等效工具保障无障碍时，才建议设置 `angular: { templateAccessibility: false }`；个别例外通常应通过末尾的文件级覆写处理。
|
|
69
|
+
|
|
65
70
|
## 按项目降低规则强度
|
|
66
71
|
|
|
67
72
|
覆盖项必须放在共享配置之后，并尽量限定文件范围：
|
|
68
73
|
|
|
69
74
|
```js
|
|
70
|
-
import {
|
|
71
|
-
|
|
72
|
-
import { createConfig } from "@fast-china/eslint-config";
|
|
75
|
+
import fastChina, { defineRules } from "@fast-china/eslint-config";
|
|
73
76
|
|
|
74
|
-
export default
|
|
75
|
-
|
|
77
|
+
export default fastChina(
|
|
78
|
+
{},
|
|
76
79
|
{
|
|
77
|
-
name: "project/typescript-
|
|
80
|
+
name: "project/typescript-exceptions",
|
|
78
81
|
files: ["**/*.{ts,tsx,mts,cts,vue}"],
|
|
79
|
-
rules: {
|
|
82
|
+
rules: defineRules({
|
|
80
83
|
"@typescript-eslint/consistent-type-imports": "warn",
|
|
81
84
|
"@typescript-eslint/no-require-imports": "off",
|
|
82
85
|
"@typescript-eslint/no-unused-vars": "warn",
|
|
83
|
-
},
|
|
86
|
+
}),
|
|
84
87
|
},
|
|
85
88
|
{
|
|
86
|
-
name: "project/vue-
|
|
89
|
+
name: "project/vue-exceptions",
|
|
87
90
|
files: ["**/*.vue"],
|
|
88
|
-
rules: {
|
|
91
|
+
rules: defineRules({
|
|
89
92
|
"vue/attributes-order": "warn",
|
|
90
93
|
"vue/require-explicit-emits": "warn",
|
|
91
|
-
},
|
|
92
|
-
}
|
|
93
|
-
|
|
94
|
-
name: "project/json-migration",
|
|
95
|
-
files: ["**/{package.json,tsconfig*.json}"],
|
|
96
|
-
rules: {
|
|
97
|
-
"jsonc/sort-array-values": "off",
|
|
98
|
-
"jsonc/sort-keys": "off",
|
|
99
|
-
},
|
|
100
|
-
},
|
|
101
|
-
]);
|
|
94
|
+
}),
|
|
95
|
+
}
|
|
96
|
+
);
|
|
102
97
|
```
|
|
103
98
|
|
|
104
99
|
建议先执行只读检查，再在独立分支或独立提交中运行 `eslint --fix`。重点审查 import、副作用入口、包导出、组件事件和清单文件，并运行项目的类型检查、构建与测试。
|