@rsdoctor/docs 1.0.0-beta.0 → 1.0.0-beta.2

package/docs/en/index.md

@@ -1,38 +1,4 @@
 ---
 pageType: home
-
-hero:
-  name: Rsdoctor
-  text: Analyzer for Rspack & Webpack
-  tagline: Visualize the building process
-  actions:
-    - theme: brand
-      text: Introduction
-      link: /guide/start/intro
-    - theme: alt
-      text: Quick Start
-      link: /guide/start/quick-start
-  image:
-    src: https://assets.rspack.dev/rsdoctor/rsdoctor-logo-960x960.png
-    alt: Rsdoctor Logo
-
-features:
-  - title: Unlimited Framework
-    details: Rsdoctor support all projects built on Webpack or Rspack.
-    icon: 🛠️
-  - title: Compile’s Time
-    details: To display the compile execution time and process in the form of a timing diagram.
-    icon: 🚀
-  - title: Compile’s Actions
-    details: Visually view the compilation changes of each file in each loader.
-    icon: 🦄
-  - title: Bundle Analysis
-    details: Visually view the bundles & modules relationship, module reference relationship and repeated packages in detail.
-    icon: 🎯
-  - title: Bundle Diff
-    details: Through comparison, the deterioration and change of the product are found.
-    icon: 🎨
-  - title: Build Scan
-    details: Built-in build rule scanning, and also supports custom rules.
-    icon: 🔍
+titleSuffix: ' - Build Analyzer'
 ---

package/docs/zh/blog/release/release-note-0_3.mdx

@@ -10,9 +10,9 @@ Rsdoctor v0.3 的新特性有:
 
 ## 自定义拓展规则
 
-考虑到用户会有特有的规则定义需求，Rsdoctor 除了内部已有的规则外，还提供了外部接口供用户定制自己的规则检查。外部扩展接口通过 `extends` 字段配置到 Rsdoctor 插件上，配置也放在 `rules` 字段内。详情请查看：[自定义拓展规则](/guide/custom/rule-custom)。
+考虑到用户会有特有的规则定义需求，Rsdoctor 除了内部已有的规则外，还提供了外部接口供用户定制自己的规则检查。外部扩展接口通过 `extends` 字段配置到 Rsdoctor 插件上，配置也放在 `rules` 字段内。详情请查看：[自定义拓展规则](/guide/rules/rule-custom)。
 
-此外，利用自定义规则的方式还可以用于用户数据收集和上报。请参阅[数据上报](/guide/custom/upload-data)。
+此外，利用自定义规则的方式还可以用于用户数据收集和上报。请参阅[数据上报](/guide/rules/upload-data)。
 
 - 示例：
 

package/docs/zh/config/options/options.mdx

@@ -153,15 +153,16 @@ import ModeIntro from '@zh/shared/mode-intro.md';
 
 <ModeIntro />
 
-### reportDir
+#### banner
 
-<Badge text="Version: 0.4.0" type="warning" />
+:::danger
+开启 BannerPlugin 分析时，请勿在生产版本中使用 Rsdoctor。
+:::
 
-- **Type:** string
-- **Optional:** `true`
-- **Default:** undefined
+- default: true.
+- type: boolean.
 
-Rsdoctor 报告输出目录，默认是构建产物输出目录。
+如果开启 `supports.banner` 则会开启 Rsdoctor 对 BannerPlugin 的兼容逻辑。详细请看：[支持 BannerPlugin](../../guide/usage/bundle-size#%E6%94%AF%E6%8C%81-bannerplugin)
 
 ### brief
 
@@ -185,7 +186,11 @@ interface BriefConfig {
 }
 ```
 
-### reportCodeType
+### output
+
+<Badge text="Version: 1.0.0" type="warning" />
+
+#### reportCodeType
 
 - Type: `{ noModuleSource?: boolean; noAssetsAndModuleSource?: boolean }`
 - Optional: true
@@ -205,6 +210,42 @@ new RsdoctorRspackPlugin({
 }),
 ```
 
+#### reportDir
+
+- **Type:** string
+- **Optional:** `true`
+- **Default:** undefined
+
+Rsdoctor 报告输出目录，默认是构建产物输出目录。
+
+#### compressData
+
+- **Type:** boolean
+- **Optional:** `true`
+- **Default:** true
+
+compressData 用于配置是否将 [outputDir]/.rsdoctor 下的分析数据进行压缩处理。
+
+### port
+
+- **Type:** `number`
+- **Optional:** `true`
+- **Default:** `random(3000, 8999)`
+
+配置 Rsdoctor 服务的端口。
+
+### ~~reportCodeType [**Deprecated**]~~
+
+<Badge text="Deprecated" type="warning" />
+
+请使用 [output.reportCodeType](#reportcodetype)
+
+### ~~reportDir [**Deprecated**]~~
+
+<Badge text="Deprecated" type="warning" />
+
+请使用 [output.reportDir](#reportDir)
+
 ### supports
 
 - **Type:** [Supports Types](#supports-types)
@@ -223,17 +264,6 @@ type ISupport = {
 };
 ```
 
-#### banner
-
-:::danger
-开启 BannerPlugin 分析时，请勿在生产版本中使用 Rsdoctor。
-:::
-
-- default: true.
-- type: boolean.
-
-如果开启 `supports.banner` 则会开启 Rsdoctor 对 BannerPlugin 的兼容逻辑。详细请看：[支持 BannerPlugin](../../guide/usage/bundle-size#%E6%94%AF%E6%8C%81-bannerplugin)
-
 #### parseBundle
 
 - default: true.
@@ -281,11 +311,3 @@ chain.plugin('Rsdoctor').use(RsdoctorRspackPlugin, [
   width="500px"
   style={{ margin: 'auto' }}
 />
-
-### port
-
-- **Type:** `number`
-- **Optional:** `true`
-- **Default:** `random(3000, 8999)`
-
-配置 Rsdoctor 服务的端口。

package/docs/zh/guide/_meta.json

@@ -11,8 +11,8 @@
   },
   {
     "type": "dir",
-    "name": "custom",
-    "label": "自定义"
+    "name": "rules",
+    "label": "扫描规则"
   },
   {
     "type": "dir",

package/docs/zh/guide/more/faq.mdx

@@ -5,9 +5,9 @@
 当我们**只需要** Rsdoctor 内 [Bundle Size](../usage/bundle-size) 分析产物大小的功能时，我们可以在接入 Rsdoctor 插件时配置对应的 [Features](/config/options/options) 配置项，参考下方代码：
 
 ```ts
-import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
 
-new RsdoctorWebpackPlugin({
+new RsdoctorRspackPlugin({
   features: ['bundle'], // 代表只开启 bundle size 的功能分析
 });
 ```
@@ -42,13 +42,13 @@ Rsdoctor 提供的 Loader 耗时时间是**预估耗时**，为什么没法统
 下面示例是开启了 lite 模式以及构建时和构建产物分析：
 
 ```js
-const { RsdoctorWebpackPlugin } = require('@rsdoctor/webpack-plugin');
+const { RsdoctorRspackPlugin } = require('@rsdoctor/rspack-plugin');
 
 // adding the plugin to your configuration
 module.exports = {
   // ...
   plugins: [
-    new RsdoctorWebpackPlugin({
+    new RsdoctorRspackPlugin({
       disableClientServer: false,
       features: ['lite', 'loader', 'plugins', 'bundle'],
     }),

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

@@ -0,0 +1 @@
+["rules", "rule-custom", "upload-data"]

package/docs/zh/guide/rules/rules.mdx

@@ -0,0 +1,281 @@
+# 内置规则
+
+## 功能介绍
+
+:::tip
+
+`linter` 的类型定义请参见本文档的[Linter 类型定义](#linter-%E7%B1%BB%E5%9E%8B%E5%AE%9A%E4%B9%89)。
+
+:::
+
+### [E1001] Duplicate Packages
+
+#### 规则详情
+
+- `Duplicate Packages` 卡片上展示了项目重复第三方包数目。点击图片可以查看重复第三方包的具体详情。注：这里的第三方都是被打包的第三方包。
+
+  <div style={{ display: 'flex' }}>
+    <img
+      src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-1.png"
+      height="200px"
+      width="260px"
+      style={{ margin: 'auto' }}
+    />
+    <img
+      src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-2.png"
+      height="300px"
+      width="340px"
+      style={{ margin: 'auto' }}
+    />
+  </div>
+
+- 重复包预警卡片
+
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alerts.png" />
+
+- 点击图标展开重复包详情，可以看到：重复包的包名、版本、大小、引用文件。
+
+  - 点击最右侧 **「Show Relations」** 可以查看具体这个第三方的引用链路和对应的引用文件代码位置。
+
+  <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-relations.png" />
+
+  - 点击最右侧 **「!（叹号）」** 图标，可以查看重复第三方包的规则的具体解释。
+
+  <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-rule.png" />
+
+#### 配置
+
+- 配置示例：
+
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugin: [
+    new RsdoctorRspackPlugin({
+      linter: {
+        level: 'Error',
+        extends: [],
+        rules: {
+          'duplicate-package': [
+            'Error',
+            {
+              checkVersion: 'minor',
+              ignore: ['chalk', '@babel/runtime'],
+            },
+          ],
+        },
+      },
+    }),
+  ],
+};
+```
+
+##### 类型
+
+- **ignore**: 配置需要忽略的 Packages。
+- **checkVersion**: 是指要检查的最大版本级别，例如：如果设置了 `minor`，那么重复包将不再检查 `major` 级别的差异。**默认为 `major`**。
+
+```ts
+interface Config {
+  checkVersion: keyof typeof CheckVersion;
+  ignore: string[];
+}
+
+enum CheckVersion {
+  null = 0,
+  prerelease = 0x1,
+  prepatch = 0x10,
+  patch = 0x100,
+  preminor = 0x1000,
+  minor = 0x10000,
+  premajor = 0x100000,
+  major = 0x1000000,
+}
+```
+
+#### 重复包优化问题
+
+请查看[重复包优化方案](../../blog/topic/duplicate-pkg-problem)。
+
+点击 「**More**」可以查看对应规则解释。
+
+### [E1002] Cross Chunks Package
+
+跨 Chunks 的重复包规则能够扫描**不同 `chunks` 中的重复包**。这些重复包也有可能导致打包代码冗余，具体还要看业务逻辑及冗余代码大小。
+
+- 展示
+  - Module 是指被重复打在多个 chunk 中的 Module。
+  - Chunks 则是被重复打包的产物。
+
+<img src="/cross-chunks-package.png" />
+
+#### 解决方案
+
+可查看 [[E1002] Cross Chunks Packages](../more/rules)
+
+### [E1003] Loader Performance Optimization
+
+通过该模块可以比较直观的看到我们项目在编译方面的一些预警信息，有助于我们可以更进一步优化项目的编译性能。
+
+#### 解决方案
+
+可查看 [[E1003] Loader Performance Optimization](../more/rules)
+
+#### 配置类型
+
+- **ignore**：可以包含字符串或正则表达式，用于指定需要被忽略的 loader 。
+- **threshold**： 表示 Loader 的总耗时阈值，单位为毫秒（millisecond）。如果 Loader 的执行时间超过这个阈值，则可能会触发警告或错误。默认值为5000毫秒。
+- **extensions**：字符串或正则表达式，用于指定在规则检查中需要匹配的文件扩展名。默认情况下，它包括常见的文件类型，如 js、css、jpg、jpeg、png、gif、webp 和 svg。
+
+```ts
+interface Config {
+  /**
+   * loaders which should be ignore.
+   */
+  ignore: (string | RegExp)[];
+  /**
+   * threshold which the loader total costs.
+   * @unit millisecond
+   * @default 5000
+   */
+  threshold: number;
+  /**
+   * the file extensions which will be match in rule check.
+   * @default ["js", "css", "jpg", "jpeg", "png", "gif", "webp", "svg"]
+   */
+  extensions: (string | RegExp)[];
+}
+```
+
+### [E1004] ECMA Version Check
+
+该规则用于检测不兼容的高级语法。在规则扫描时，优先使用 `browserslist` 的配置；如果未配置 `browserslist`，则需要手动进行检测，示例如下：
+
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugin: [
+    new RsdoctorRspackPlugin({
+      linter: {
+        rules: {
+          'ecma-version-check': [
+            'Warn',
+            {
+              ecmaVersion: 2015,
+              // targets: ["chrome >= 53"],
+            },
+          ],
+        },
+      },
+    }),
+  ],
+};
+```
+
+#### 类型定义
+
+```ts
+type CheckSyntaxOptions = {
+  /**
+   * The target browser range of the project.
+   * Its value is a standard browserslist array.
+   */
+  targets?: string[];
+  /**
+   * Used to exclude a portion of source files during detection.
+   * You can pass in one or more regular expressions to match the paths of source files.
+   */
+  exclude?: CheckSyntaxExclude;
+  /**
+   * Used to exclude files by output path before detection.
+   * You can pass in one or more regular expressions to match the paths of source files.
+   */
+  excludeOutput?: CheckSyntaxExclude;
+  /**
+   * The minimum ECMAScript syntax version that can be used in the build artifact.
+   * The priority of `ecmaVersion` is higher than `targets`.
+   */
+  ecmaVersion?: EcmaVersion;
+  /**
+   * Used to ignore specified syntax error messages after detection.
+   * You can pass in one or more error message types to ignore.
+   */
+  excludeErrorLogs?: SyntaxErrorKey[];
+};
+```
+
+更多 `ECMA Version Check` 配置请参考 [ECMA Version Check Options](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax?tab=readme-ov-file#options)
+
+### [E1005] Default Import Check
+
+通常，Rspack 会自动兼容不同类型的模块，但在某些情况下，兼容性操作可能会失败。例如，当使用 `Default Import` 导入一个 `cjs` 模块时，如果该模块没有兼容的语句（如 `exports.default`），则会出现问题。
+
+#### 解决方案
+
+可查看 [[E1005] Default Import Check](../more/rules)
+
+#### 配置
+
+- **ignore**：配置忽略一些引入的文件。
+
+```ts
+interface Config {
+  /** Packages that need to be ignored */
+  ignore: string[];
+}
+```
+
+## Linter 类型定义
+
+- `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];
+```
+
+如果要**关闭某个规则**，则可以 `SeverityInput` 设为 `off`，如下示例：
+
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugin: [
+    new RsdoctorRspackPlugin({
+      linter: {
+        level: 'Error',
+        extends: [],
+        rules: {
+          'duplicate-package': 'off',
+        },
+      },
+    }),
+  ],
+};
+```

package/docs/zh/guide/usage/bundle-alerts.mdx

@@ -2,48 +2,16 @@
 
 ## 功能介绍
 
-### 重复第三方包
+Overall 页面中的 `Alerts` 部分用于展示「构建规则」及「编译规则」结果，如下图。规则展示除了展示在页面中，还会展示在终端日志中。
 
-- `Duplicate Packages` 卡片上展示了项目重复第三方包数目。点击图片可以查看重复第三方包的具体详情。注：这里的第三方都是被打包的第三方包。
+<img src="/bundle-alerts.png" />
 
-  <div style={{ display: 'flex' }}>
-    <img
-      src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-1.png"
-      height="200px"
-      width="360px"
-      style={{ margin: 'auto' }}
-    />
-    <img
-      src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-2.png"
-      height="300px"
-      width="440px"
-      style={{ margin: 'auto' }}
-    />
-  </div>
+可以查看下方的产物预警内置规则了解各个规则详情。
 
-- 重复包预警卡片
+### 内置规则
 
-<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alerts.png" />
+1. [[E1001] Duplicate Packages](../../guide/rules/rules#e1001-duplicate-packages)
+2. [[E1002] Cross Chunks Package](../../guide/rules/rules#e1002-cross-chunks-package)
+3. [[E1004] ECMA Version Check](../../guide/rules/rules#e1004-ecma-version-check)
 
-- 点击图标展开重复包详情，可以看到：重复包的包名、版本、大小、引用文件。
-
-  - 点击最右侧 **「Show Relations」** 可以查看具体这个第三方的引用链路和对应的引用文件代码位置。
-
-  <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-relations.png" />
-
-  - 点击最右侧 **「!（叹号）」** 图标，可以查看重复第三方包的规则的具体解释。
-
-  <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-rule.png" />
-
-### 重复包优化问题
-
-请查看[重复包优化方案](../../blog/topic/duplicate-pkg-problem)。
-
-### ECMA 版本检查
-
-产物预警中会对产物进行 ECMA 版本做检查，如下图：
-
-{' '}
-<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alerts-ecma.png" />
-
-点击 「**More**」可以查看对应规则解释。
+具体可以查看[内置规则](../../guide/rules/rules)。

package/docs/zh/guide/usage/compile-alerts.mdx

@@ -14,5 +14,5 @@
 [规则列表](../more/rules)
 :::
 
-- `E1002` 默认导入检查。
-- `E1003` Loader 性能检查。
+- `E1003` Loader 性能检查。[[E1003] Loader Performance Optimization](/guide/rules/rules#e1003-loader-performance-optimization)
+- `E1005` 默认导入检查。[[E1005] Default Import Check](/guide/rules/rules#e1005-default-import-check)

package/docs/zh/guide/usage/resolver.mdx

@@ -7,7 +7,7 @@
 - Resolver 分析能力默认关闭，如需开启，可以在 `features` 数组中添加 `resolver`，如下示例。[features 配置](../../config/options/options)。
 
 ```js
-new rsdoctorWebpackPlugin({
+new rsdoctorRspackPlugin({
   features: [
     'resolver',
     // ...other features

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

@@ -18,97 +18,20 @@
 
 ## 如何使用
 
-诊断规则的使用很简单，它配置在整个插件的`linter`选项下，如下用例：
+目前 Rsdoctor 提供**内置规则**和**自定义规则**两种。
 
-```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', '@babel/runtime'],
-            },
-          ],
-        },
-      },
-    }),
-  ],
-};
-```
+在现有的诊断器中已经包含了多个规则，默认都已全部开启，它们分别是：
 
-#### 开启 ECMA version check
+1. [[E1001] Duplicate Packages](/guide/rules/rules#e1001-duplicate-packages)
+2. [[E1002] Cross Chunks Package](/guide/rules/rules#e1002-cross-chunks-package)
+3. [[E1003] Loader Performance Optimization](/guide/rules/rules#e1003-loader-performance-optimization)
+4. [[E1004] ECMA Version Check](/guide/rules/rules#e1004-ecma-version-check)
+5. [[E1005] Default Import Check](/guide/rules/rules#e1005-default-import-check)
 
-优先使用 `browserslist` 的配置，如果没有 `browserslist` 则通过以下配置的方式进行检测
+具体可以查看[内置规则](/guide/rules/rules)。
 
-```ts
-import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
+### 自定义规则
 
-export default {
-  plugin: [
-    new RsdoctorWebpackPlugin({
-      linter: {
-        rules: {
-          'ecma-version-check': [
-            'Warn',
-            {
-              ecmaVersion: 2015,
-              // targets: ["chrome >= 53"],
-            },
-          ],
-        },
-      },
-    }),
-  ],
-};
-```
-
-更多 `ECMA Version Check` 配置请参考 [ECMA Version Check Options](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax?tab=readme-ov-file#options)
-
-`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)
+Rsdoctor 还会把分析后的数据收集后，用户可以通过 Linter API 接入自定义规则，自定义规则详情查看[自定义规则](/guide/rules/rule-custom)。