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

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

@@ -13,9 +13,9 @@ The new features of Rsdoctor v0.3 include:
 Considering that users may have their own specific rule definition requirements, Rsdoctor provides an external interface for users to customize their own rule checks in addition to the internal rules already available.
 External extension interfaces need to be configured on the Rsdoctor plugin through the `extends` field, and their configurations are also placed in the `rules` field.
 
-For more details, please refer to: [Custom Extension Rules](/guide/custom/rule-custom)
+For more details, please refer to: [Custom Extension Rules](/guide/rules/rule-custom)
 
-Additionally, the use of custom rules can also be applied for user data collection and reporting. [Data Reporting](/guide/custom/upload-data)
+Additionally, the use of custom rules can also be applied for user data collection and reporting. [Data Reporting](/guide/rules/upload-data)
 
 - Example:
 

package/docs/en/config/options/options.mdx

@@ -77,6 +77,28 @@ This is the options for the [RsdoctorWebpackPlugin](#rsdoctorwebpackplugin) and
 - [disableClientServer](#disableclientserver)
 - [features](#features)
 
+### brief
+
+<Badge text="Version: 0.4.0" type="warning" />
+
+- **Type:** [BriefType](#brieftype)
+- **Optional:** `true`
+- **Default:** undefined
+
+More configurations for Brief mode are as follows:
+
+- **reportHtmlName:** Configures the name of the HTML report for Brief mode. The default value is `report-rsdoctor.html`.
+- **writeDataJson:** By default, in Brief mode, the analysis data is injected into the HTML file, so no additional build analysis data is generated. If you want to generate additional local data, you need to configure `writeDataJson: true`.
+
+#### briefType
+
+```ts
+interface BriefConfig {
+  reportHtmlName?: string | undefined;
+  writeDataJson: boolean;
+}
+```
+
 ### disableClientServer
 
 - **Type:** `boolean`
@@ -151,9 +173,11 @@ import ModeIntro from '@en/shared/mode-intro.md';
 
 <ModeIntro />
 
-### reportDir
+### output
 
-<Badge text="Version: 0.4.0" type="warning" />
+<Badge text="Version 1.0.0" type="warning" />
+
+#### reportDir
 
 - **Type:** string
 - **Optional:** `true`
@@ -161,29 +185,7 @@ import ModeIntro from '@en/shared/mode-intro.md';
 
 The output directory for Rsdoctor reports. By default, it is the build output directory.
 
-### brief
-
-<Badge text="Version: 0.4.0" type="warning" />
-
-- **Type:** [BriefType](#brieftype)
-- **Optional:** `true`
-- **Default:** undefined
-
-More configurations for Brief mode are as follows:
-
-- **reportHtmlName:** Configures the name of the HTML report for Brief mode. The default value is `report-rsdoctor.html`.
-- **writeDataJson:** By default, in Brief mode, the analysis data is injected into the HTML file, so no additional build analysis data is generated. If you want to generate additional local data, you need to configure `writeDataJson: true`.
-
-#### briefType
-
-```ts
-interface BriefConfig {
-  reportHtmlName?: string | undefined;
-  writeDataJson: boolean;
-}
-```
-
-### reportCodeType
+#### reportCodeType
 
 - Type: `{ noModuleSource?: boolean; noAssetsAndModuleSource?: boolean }`
 - Optional: true
@@ -206,6 +208,34 @@ new RsdoctorRspackPlugin({
 }),
 ```
 
+#### compressData
+
+- **Type:** boolean
+- **Optional:** `true`
+- **Default:** true
+
+compressData is used to configure whether to compress the analysis data under [outputDir]/.rsdoctor.
+
+### port
+
+- **Type:** `number`
+- **Optional:** `true`
+- **Default:** `random(3000, 8999)`
+
+Configure the port for the Rsdoctor server.
+
+### ~~reportCodeType [**Deprecated**]~~
+
+<Badge text="Deprecated" type="warning" />
+
+Please use [output.reportCodeType](#reportcodetype)
+
+### ~~reportDir [**Deprecated**]~~
+
+<Badge text="Deprecated" type="warning" />
+
+Please use [output.reportDir](#reportDir)
+
 ### supports
 
 - **Type:** [Supports Types](#supports-types)
@@ -282,11 +312,3 @@ Whether to enable the ability to generate tile graphs, which affects whether the
   width="500px"
   style={{ margin: 'auto' }}
 />
-
-### port
-
-- **Type:** `number`
-- **Optional:** `true`
-- **Default:** `random(3000, 8999)`
-
-Configure the port for the Rsdoctor server.

package/docs/en/guide/_meta.json

@@ -11,8 +11,8 @@
   },
   {
     "type": "dir",
-    "name": "custom",
-    "label": "User Custom"
+    "name": "rules",
+    "label": "Scan Rules"
   },
   {
     "type": "dir",

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

@@ -5,9 +5,9 @@
 When we **only need** the [bundle size analysis](../usage/bundle-size) feature of Rsdoctor, we can configure the corresponding [Features](/config/options/options) option when integrating the Rsdoctor plugin. Refer to the code snippet below:
 
 ```ts
-import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
 
-new RsdoctorWebpackPlugin({
+new RsdoctorRspackPlugin({
   features: ['bundle'], // Represents enabling only the bundle size analysis feature
 });
 ```
@@ -44,13 +44,13 @@ You can add the `lite` field to the `features` array to use the lite mode. Addit
 The following example enables the lite mode, build-time analysis, and bundle analysis:
 
 ```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/en/guide/rules/_meta.json

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

package/docs/en/guide/rules/rules.mdx

@@ -0,0 +1,281 @@
+# Built-in rules
+
+## Introduction
+
+:::tip
+
+Please refer to the [Linter Type](#linter-type) in this document for the type definition of `linter`.
+
+:::
+
+### [E1001] Duplicate Packages
+
+#### Rule Details
+
+- The `Duplicate Packages` card displays the number of duplicate third-party packages in the project. Clicking the image allows you to view the specific details of the duplicate third-party packages. Note: The third-party packages referred to here are all bundled third-party 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>
+
+- Duplicate Package Warning Card
+
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alerts.png" />
+
+- Clicking the icon to expand the duplicate package details allows you to see: the name, version, size, and reference files of the duplicate package.
+
+  - Clicking the **「Show Relations」** on the far right can view the specific reference chain and the corresponding reference file code position of this third-party package.
+
+  <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-relations.png" />
+
+  - Clicking the **「!（exclamation mark）」** icon on the far right can view the specific explanation of the rule for the duplicate third-party package.
+
+  <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-rule.png" />
+
+#### Configuration
+
+- Configuration Example:
+
+```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'],
+            },
+          ],
+        },
+      },
+    }),
+  ],
+};
+```
+
+##### Type
+
+- **ignore**: Configures the packages to be ignored.
+- **checkVersion**: Refers to the maximum version level to be checked, for example: if set to `minor`, then the duplicate package will no longer check the `major` level differences. **Default is `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,
+}
+```
+
+#### Duplicate Package Optimization Problem
+
+Please refer to the [Duplicate Package Optimization Solution](../../blog/topic/duplicate-pkg-problem).
+
+Clicking 「**More**」 can view the corresponding rule explanation.
+
+### [E1002] Cross Chunks Package
+
+The cross chunks duplicate package rule can scan **duplicate packages in different `chunks`**. These duplicate packages may also lead to redundant code in the build artifacts, depending on the business logic and the size of the redundant code.
+
+- Display
+  - Module refers to the module that is repeatedly packaged in multiple chunks.
+  - Chunks are the build artifacts that are repeatedly packaged.
+
+<img src="/cross-chunks-package.png" />
+
+#### Solution
+
+Please refer to [[E1002] Cross Chunks Packages](../more/rules)
+
+### [E1003] Loader Performance Optimization
+
+This module allows you to visually see some warning information about our project's compilation, which can help us further optimize the project's compilation performance.
+
+#### Solution
+
+Please refer to [[E1003] Loader Performance Optimization](../more/rules)
+
+#### Configuration Type
+
+- **ignore**: Can include strings or regular expressions, used to specify the loaders to be ignored.
+- **threshold**: Represents the total time threshold for the loader, in milliseconds. If the loader's execution time exceeds this threshold, it may trigger warnings or errors. The default value is 5000 milliseconds.
+- **extensions**: Strings or regular expressions, used to specify the file extensions that need to be matched in rule checks. By default, it includes common file types such as js, css, jpg, jpeg, png, gif, webp, and 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
+
+This rule is used to detect incompatible advanced syntax. When scanning the rule, the configuration of `browserslist` is prioritized; if `browserslist` is not configured, manual detection is required, as shown below:
+
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugin: [
+    new RsdoctorRspackPlugin({
+      linter: {
+        rules: {
+          'ecma-version-check': [
+            'Warn',
+            {
+              ecmaVersion: 2015,
+              // targets: ["chrome >= 53"],
+            },
+          ],
+        },
+      },
+    }),
+  ],
+};
+```
+
+#### Type Definitions
+
+```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[];
+};
+```
+
+For more `ECMA Version Check` configuration options, please refer to [ECMA Version Check Options](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax?tab=readme-ov-file#options)
+
+### [E1005] Default Import Check
+
+Typically, Rspack automatically supports different types of modules, but in some cases, compatibility operations may fail. For example, when using `Default Import` to import a `cjs` module, if the module does not have a compatible statement (such as `exports.default`), issues may arise.
+
+#### Solution
+
+Please refer to [[E1005] Default Import Check](../more/rules)
+
+#### Configuration
+
+- **ignore**：Configure to ignore some imported files.
+
+```ts
+interface Config {
+  /** Packages that need to be ignored */
+  ignore: string[];
+}
+```
+
+## Linter Type
+
+- The type definition for the `linter` field is as follows:
+
+```ts
+/** Linter options */
+interface Options {
+  rules?: RulesMap;
+  level?: SeverityString;
+  extends?: ExtendRuleData[];
+}
+
+/**
+ * Linting level
+ *   - `'Warn'` runs only rules categorized as `'Warn'`
+ *   - `'Error'` runs all rules
+ */
+type SeverityString = 'Warn' | 'Error';
+
+/** Rule level */
+type SeverityInput = SeverityString | 'off' | 'on';
+
+/** Rule configuration */
+type RulesMap = Record<string, RuleConfigItem>;
+
+/** Single rule configuration */
+type RuleConfigItem =
+  // Only error level, this level has higher priority than the rule's own configuration
+  | SeverityInput
+  // In the case of an array, the first item is the error level, and the second item is the rule configuration
+  | [SeverityInput, unknown];
+```
+
+If you want to **disable a rule**, you can set `SeverityInput` to `off`, as shown in the following example:
+
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugin: [
+    new RsdoctorRspackPlugin({
+      linter: {
+        level: 'Error',
+        extends: [],
+        rules: {
+          'duplicate-package': 'off',
+        },
+      },
+    }),
+  ],
+};
+```

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

@@ -1,48 +1,17 @@
-# Bundle alerts
+# Bundle Alerts
 
 ## Introduction
 
-### Duplicate third-party packages
+The `Alerts` section in the `Overall` page is used to display the results of "Build Rules" and "Compilation Rules", as shown in the image below. In addition to being displayed on the page, the rules will also be displayed in the terminal log.
 
-- The `Duplicate Packages` card displays the number of duplicate third-party packages in the project. Click on the image to view the specific details of the duplicate packages. Note: The third-party packages mentioned here are the ones that have been bundled.
+<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"
-    width="360px"
-    style={{ margin: 'auto' }}
-  />
-  <img
-    src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-2.png"
-    width="360px"
-    style={{ margin: 'auto' }}
-  />
-</div>
+You can check the built-in rules for bundle alerts below to understand the details of each rule.
 
-- Duplicate Package Alerts Card
+### Built-in Rules
 
-<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)
 
-- Click on the icon to expand the details of the duplicate packages, where you can see the package name, version, size, and reference files.
-
-  - Click on the rightmost **"Show Relations"** to view the specific reference chain and corresponding reference file code location for this third-party package.
-
-  <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-relations.png" />
-
-  - Click on the rightmost **"!"** icon to view the specific explanation of the rule for the duplicate third-party package.
-
-  <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alters-rule.png" />
-
-### Duplicate package optimization
-
-Please check [Duplicate Package Optimization](../../blog/topic/duplicate-pkg-problem).
-
-### ECMA version check
-
-In the bundle alerts, the ECMA version of the bundle is checked, as shown in the following image:
-
-{' '}
-
-<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/bundle-alerts-ecma.png" />
-
-Click on "**More**" to view the corresponding rule explanation.
+For more details, please refer to the [Built-in Rules](../../guide/rules/rules).

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

@@ -1,18 +1,18 @@
-# Compilation alerts
+# Compile Alerts
 
-We have also integrated the ability to detect warnings based on compilation data. If the current compilation results contain data that matches the rules defined by us, the `Compile Alerts` module will appear below the **Rsdoctor** main interface, as shown in the following figure:
+We have integrated some capabilities based on compilation data detection. If the current compilation result contains data that hits the rules we define, the `Compile Alerts` module will appear at the bottom of the **Rsdoctor** main interface, as shown in the image below:
 
 <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/compile/compile-alerts.png" />
 
-Through this module, we can intuitively see some warning information about the compilation performance of our project, which helps us further optimize the compilation performance of the project.
+This module allows us to visually see some warning information about our project's compilation, which can help us further optimize the project's compilation performance.
 
 ## Rules
 
-Currently, the compilation rules include:
+The current compilation rules include:
 
 :::tip
 [Rule List](../more/rules)
 :::
 
-- `E1002` Default Import Check.
-- `E1003` Loader Performance Optimization.
+- `E1003` Loader Performance Check. [[E1003] Loader Performance Optimization](/guide/rules/rules#e1003-loader-performance-optimization)
+- `E1005` Default Import Check. [[E1005] Default Import Check](/guide/rules/rules#e1005-default-import-check)

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

@@ -1,8 +1,8 @@
-# Compilation diagnostic rules
+# 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...
+Building diagnostic rules is similar to `ESLint` like lint tools, but different from it in that `ESLint` performs code scanning and is unrelated to the build process. In contrast, the code diagnostics here are closely related to the build process of `Rspack or Webpack`, incorporating many internal parameters generated during the build process to aid judgment, such as ModuleGraph, Webpack's internal markings for each module, and runtime added after code transformation, among others.
 
-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:
+During the build process, if issues are discovered, they will be visible in the CLI and the final diagnostic summary webpage, as shown below:
 
 <img
   width="700"
@@ -16,98 +16,22 @@ If any issues are detected during the build process, they will be displayed in t
   src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/usage/bundle/rule-config-1.png"
 />
 
-## How to use
+## 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:
+Currently, Rsdoctor provides **built-in rules** and **custom rules**.
 
-```ts
-import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
+### Built-in Rules
 
-export default {
-  plugin: [
-    new RsdoctorWebpackPlugin({
-      linter: {
-        level: 'Error',
-        extends: [],
-        rules: {
-          'default-import-check': 'off',
-          'duplicate-package': [
-            'Error',
-            {
-              checkVersion: 'minor',
-              ignore: ['chalk', '@babel/runtime'],
-            },
-          ],
-        },
-      },
-    }),
-  ],
-};
-```
+The existing diagnostic tool includes multiple rules, all of which are enabled by default. They are:
 
-#### Enable 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)
 
-The configuration of `browserslist` is used first. If there is no `browserslist`, the following configuration is used for detection
+For specific details, refer to [Built-in Rules](/guide/rules/rules).
 
-```ts
-import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
+### Custom Rules
 
-export default {
-  plugin: [
-    new RsdoctorWebpackPlugin({
-      linter: {
-        rules: {
-          'ecma-version-check': [
-            'Warn',
-            {
-              ecmaVersion: 2015,
-              // targets: ["chrome >= 53"],
-            },
-          ],
-        },
-      },
-    }),
-  ],
-};
-```
-
-For more `ECMA Version Check` configuration, please refer to [ECMA Version Check Options](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax?tab=readme-ov-file#options)
-
-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)
+Rsdoctor also collects analyzed data and allows users to integrate custom rules through the Linter API. For details on custom rules, refer to [Custom Rules](/guide/rules/rule-custom).