@rsdoctor/docs 0.2.2 → 0.2.3

package/docs/en/guide/usage/_meta.json

@@ -9,5 +9,6 @@
   "plugins-analysis",
   "bundle-size",
   "module-analysis",
-  "resolver"
+  "resolver",
+  "rule-config"
 ]

package/docs/en/guide/usage/rule-config.mdx

@@ -0,0 +1,85 @@
+# Compilation Diagnostic Rules
+
+Building diagnostic rules is similar to lint tools like `ESLint`, but with a difference. `ESLint` performs static code scanning and is independent of the build process. On the other hand, the code diagnostics here are closely related to the build process of `Rspack` or `Webpack`. It incorporates various internal parameters generated during the build process to assist in the analysis, such as ModuleGraph, internal markers for each module by Webpack, and runtime added after code transformation, and so on...
+
+If any issues are detected during the build process, they will be displayed in the CLI and the diagnostic summary webpage, as shown in the following image:
+
+<img
+  width="700"
+  style={{ margin: '10px auto' }}
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/rule-config-cli.png"
+/>
+
+<img
+  width="700"
+  style={{ margin: '10px auto' }}
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/rule-config-1.png"
+/>
+
+## How to Use
+
+Using diagnostic rules is simple. They are configured under the `linter` option of the entire plugin, as shown in the following example:
+
+```ts
+import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
+
+export default {
+  plugin: [
+    new RsdoctorWebpackPlugin({
+      linter: {
+        level: 'Error',
+        extends: [],
+        rules: {
+          'default-import-check': 'off',
+          'duplicate-package': [
+            'Error',
+            {
+              checkVersion: 'minor',
+              ignore: ['chalk', '@bable/runtime'],
+            },
+          ],
+        },
+      },
+    }),
+  ],
+};
+```
+
+The type of `linter`：
+
+```ts
+interface Options {
+  rules?: RulesMap;
+  level?: SeverityString;
+  extends?: ExtendRuleData[];
+}
+
+/**
+ * Validation Level
+ *   - When set to `'Warn'`, only rules with the category `'Warn'` will be executed
+ *   - When set to `'Error'`, all rules will be executed
+ */
+type SeverityString = 'Warn' | 'Error';
+
+/** Rule Level */
+type SeverityInput = SeverityString | 'off' | 'on';
+
+/** Rule Configuration */
+type RulesMap = Record<string, RuleConfigItem>;
+
+/** Individual Rule Configuration */
+type RuleConfigItem =
+  // Only severity level, which takes precedence over the rule's own configuration
+  | SeverityInput
+  // In the case of an array, the first item is the severity level, and the second item is the rule configuration
+  | [SeverityInput, unknown];
+```
+
+## Existing Internal Rules
+
+There are already three rules included in the existing diagnostic tool, which are:
+
+1. [[E1001] Duplicate Packages](./bundle-alerts#%E9%87%8D%E5%A4%8D%E7%AC%AC%E4%B8%89%E6%96%B9%E5%8C%85)
+2. [[E1002] Default Import Check](../more/rules)
+3. [[E1003] Loader Performance Optimization](../more/rules)
+4. [[E1004] ECMA Version Check](../more/rules)

package/docs/zh/guide/usage/_meta.json

@@ -9,5 +9,6 @@
   "plugins-analysis",
   "bundle-size",
   "module-analysis",
-  "resolver"
+  "resolver",
+  "rule-config"
 ]

package/docs/zh/guide/usage/rule-config.mdx

@@ -0,0 +1,86 @@
+# 编译诊断规则
+
+构建诊断规则是类似于 `ESLint` 的 lint 工具，但是与其不同之处在于，`ESLint` 是在静态情况下进行代码扫描和构建流程无关。而这里的代码诊断是和 `Rspack 或 Webpack` 的构建流程紧密相关的，其中会加入许许多多构建中产生的内部参数用于辅助判断，比如 ModuleGraph，比如 Webpack 对每个模块的内部标记，比如代码经过转换之后加入的 runtime 等等……
+
+在构建过程中发现了问题，会在 CLI 和最后弹出的诊断汇总网页中看到，如下图：
+
+<img
+  width="700"
+  style={{ margin: '10px auto' }}
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/rule-config-cli.png"
+/>
+
+<img
+  width="700"
+  style={{ margin: '10px auto' }}
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/rule-config-1.png"
+/>
+
+## 如何使用
+
+诊断规则的使用很简单，它配置在整个插件的`linter`选项下，如下用例：
+
+```ts
+import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
+
+export default {
+  plugin: [
+    new RsdoctorWebpackPlugin({
+      linter: {
+        level: 'Error',
+        extends: [],
+        rules: {
+          'default-import-check': 'off',
+          'duplicate-package': [
+            'Error',
+            {
+              checkVersion: 'minor',
+              ignore: ['chalk', '@bable/runtime'],
+            },
+          ],
+        },
+      },
+    }),
+  ],
+};
+```
+
+`linter`字段的类型为：
+
+```ts
+/** 校验器选项 */
+interface Options {
+  rules?: RulesMap;
+  level?: SeverityString;
+  extends?: ExtendRuleData[];
+}
+
+/**
+ * 校验等级
+ *   - `'Warn'`时只运行类别为`'Warn'`的规则
+ *   - `'Error'`时运行全部规则
+ */
+type SeverityString = 'Warn' | 'Error';
+
+/** 规则等级 */
+type SeverityInput = SeverityString | 'off' | 'on';
+
+/** 规则配置 */
+type RulesMap = Record<string, RuleConfigItem>;
+
+/** 单规则配置 */
+type RuleConfigItem =
+  // 仅有报错等级，此等级优先级高于规则自身配置
+  | SeverityInput
+  // 数组情况下，第一项为报错等级，后一项是规则配置
+  | [SeverityInput, unknown];
+```
+
+## 内部已有规则
+
+在现有的诊断器中已经包含了三个规则，它们分别是：
+
+1. [[E1001] Duplicate Packages](./bundle-alerts#%E9%87%8D%E5%A4%8D%E7%AC%AC%E4%B8%89%E6%96%B9%E5%8C%85)
+2. [[E1002] Default Import Check](../more/rules)
+3. [[E1003] Loader Performance Optimization](../more/rules)
+4. [[E1004] ECMA Version Check](../more/rules)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsdoctor/docs",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/rsdoctor",
@@ -28,7 +28,7 @@
     "rsbuild-plugin-open-graph": "1.0.0",
     "rspress-plugin-font-open-sans": "^1.0.0",
     "typescript": "^5.2.2",
-    "@rsdoctor/types": "0.2.2"
+    "@rsdoctor/types": "0.2.3"
   },
   "dependencies": {
     "framer-motion": "^10.17.6",