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

package/docs/en/{_meta.json → _nav.json}

@@ -13,5 +13,10 @@
     "text": "Blog",
     "link": "/blog/release/release-note-1_2",
     "activeMatch": "/blog/"
+  },
+  {
+    "text": "Playground",
+    "link": "https://rsdoctor.rs/preview/#/resources/uploader",
+    "activeMatch": "/preview/"
   }
 ]

package/docs/en/config/options/_meta.json

@@ -1 +1,13 @@
-["options", "term"]
+[
+  "options",
+  "term",
+  "disableClientServer",
+  "experiments",
+  "features",
+  "output",
+  "port",
+  "supports",
+  "brief",
+  "mode",
+  "options-v2"
+]

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

@@ -0,0 +1,35 @@
+# brief
+
+import { Badge } from '@theme';
+
+:::warning
+Deprecated in V2, please use [output.mode: 'brief'](/config/options/output#mode) instead. Refer to [brief configuration migration](/config/options/options-v2#brief).
+:::
+
+- **Type:** [BriefType](#brieftype)
+- **Optional:** `true`
+- **Default:** `undefined`
+
+Detailed configuration options for Brief mode are as follows:
+
+- **reportHtmlName:** Configures the filename of the HTML report in Brief mode. The default value is `report-rsdoctor.html`.
+- **writeDataJson:** (Deprecated, please use `output.options.type: ['json', 'html']`, refer to [output.options.type](/config/options/options-v2#options).) By default, Brief mode injects the analysis data directly into the HTML file, so no additional build analysis data files are generated. If you need to generate additional local JSON data files, you need to configure `writeDataJson: true`.
+
+## briefType
+
+```ts
+interface BriefConfig {
+  reportHtmlName?: string | undefined;
+  writeDataJson: boolean;
+}
+```
+
+- **Example:**
+
+```js
+new RsdoctorRspackPlugin({
+  output: {
+    mode: 'brief',
+  },
+});
+```

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

@@ -0,0 +1,11 @@
+# disableClientServer
+
+- **Type:** `boolean`
+- **Optional:** `true`
+- **Default:** `false`, when `process.CI` is true, the default value is true, meaning the report service is disabled by default in CI environments.
+
+:::tip
+It is recommended to set disableClientServer to true in CI environments, otherwise the started service will block the pipeline process.
+:::
+
+Whether to automatically open the Rsdoctor report page. If you do not need to view the analysis report provided by Rsdoctor in the browser, you can enable this configuration item.

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

@@ -0,0 +1,21 @@
+import { Badge } from '@theme';
+
+# experiments
+
+<Badge text="Version: 1.0.0" type="warning" />
+
+## enableNativePlugin
+
+- **Type:** `boolean`
+- **Optional:** `true`
+- **Default:** `false`
+
+By enabling the enableNativePlugin option, the Rspack native plugin moves the time-consuming data processing logic from Rsdoctor to the Rspack build stage, significantly improving build analysis efficiency and greatly reducing Rsdoctor's own analysis time.
+
+- **Example:**
+
+```js
+new RsdoctorRspackPlugin({
+  experiments: { enableNativePlugin: true }
+}),
+```

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

@@ -0,0 +1,70 @@
+# features
+
+- **Type:** [RsdoctorWebpackPluginFeatures](#rsdoctorwebpackpluginfeatures) | [Array\<keyof RsdoctorWebpackPluginFeatures\>](#rsdoctorwebpackpluginfeatures) | [RsdoctorRspackPluginFeatures](#rsdoctorrspackpluginfeatures) | [Array\<keyof RsdoctorRspackPluginFeatures\>](#rsdoctorrspackpluginfeatures)
+- **Optional:** `true`
+- **Default:** `['loader', 'plugins', 'bundle']`
+
+## Configuration Description
+
+The `features` attribute is used for analysis feature toggles, and the specific functional items are as follows:
+
+- **loader**: Loader time consumption and code compilation change analysis, enabled by default.
+- **plugins**: Plugin calls and time consumption analysis, enabled by default.
+- **bundle**: Build artifact analysis, enabled by default.
+- **resolver**: Resolver analysis, disabled by default.
+- **lite**: **(lite mode will be deprecated in V2, refer to [lite mode deprecation notice](/config/options/options-v2#lite))** lite mode. The difference between lite mode and normal mode is that source code information is no longer displayed, only packaged code information is displayed, so the code analyzed on the page will also be packaged. Default is normal mode.
+
+Therefore, **the default configuration enables Bundle analysis capabilities, Loader and Plugin build-time analysis**. Resolver analysis capability is not enabled, and Rspack currently does not support Resolver analysis capabilities.
+
+### Types
+
+- If you set `features` as an **array** type, the plugin will **only enable** the features you define in the `features` array.
+- If you set `features` as a **simple object** type, the plugin will **only disable** the features you set to `false` in the `features` object.
+
+### Examples
+
+```js
+new RsdoctorRspackPlugin({
+  // Only enable bundle, loader, plugins feature analysis, array form will override default configuration.
+  features: ['bundle', 'loader', 'plugins'],
+});
+```
+
+```js
+new RsdoctorRspackPlugin({
+  features: {
+    // Disable bundle analysis, other feature analysis remains default
+    bundle: false,
+  },
+});
+```
+
+### Notes
+
+:::tip
+
+**If an "out of memory" error occurs, you can try the following:**
+
+1. Enable **lite** mode.
+2. Increase the node memory limit, for example: NODE_OPTIONS=--max-old-space-size=8096.
+
+- Reason: Because during the build process, source code information is cached, which exceeds memory, so enabling `lite` mode can help alleviate this.
+- Difference: The difference between `lite` mode and normal mode is that source code information is no longer cached, only packaged code information is cached, so the code analyzed on the page will also be packaged.
+
+:::
+
+## RsdoctorWebpackPluginFeatures
+
+`features` type:
+
+import Features from '@en/shared/features.md';
+
+<Features />
+
+## RsdoctorRspackPluginFeatures
+
+`features` type:
+
+import FeaturesRspack from '@en/shared/features-rspack.md';
+
+<FeaturesRspack />

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

@@ -0,0 +1,20 @@
+import { Badge } from '@theme';
+
+# mode
+
+:::warning
+
+- Deprecated in V2, please use [output.mode](/config/options/output#mode) instead. Refer to [mode configuration migration](/config/options/options-v2#mode).
+
+:::
+
+- **Type:** `"normal" | "brief" | "lite"`
+  - lite mode will be deprecated in V2, refer to [lite mode deprecation notice](/config/options/options-v2#lite)
+- **Optional:** `true`
+- **Default:** `normal`
+
+Select the Rsdoctor build report mode to use, which includes the following options:
+
+import ModeIntro from '@en/shared/mode-intro.md';
+
+<ModeIntro />

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

@@ -0,0 +1,40 @@
+# Configuration Migration Guide
+
+**Rsdoctor introduced new configuration options in version 1.2.4**. These new configuration options are easier to configure, more extensible, and compatible with the upcoming v2.0 release.
+
+Configuration options from version 1.2.3 and earlier will still be supported, **but will be completely deprecated in Rsdoctor v2**, so we recommend migrating to the new configuration options in `1.2.4`.
+
+| Original Configuration              | New Configuration                                                                                                              |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| mode                                | Changed to configure `output.mode`.                                                                                            |
+| brief                               | Changed to configure `mode: 'brief'`, and configure `output.options` `type` as `html`.                                         |
+| output.compressData                 | Changed to configure `mode: 'brief'`, and configure `output.options.type` as `json`.                                           |
+| `mode: 'lite'` or `feature: 'lite'` | Changed to configure `mode: 'normal'`, and configure `output.options.reportCodeType` as `noCode` or `noAssetsAndModuleSource`. |
+| None                                | New `output.options.jsonOptions.section` configuration                                                                         |
+
+## Configuration Changes Details
+
+### mode
+
+The `mode` in the original configuration is migrated to the nested `output.mode` for better integration with other output-related configurations.
+
+### brief
+
+The current brief report mode outputs an HTML file as the report page. The new brief mode still supports JSON format, and for unified management of the same configuration, the brief configuration is moved to output.options.
+The original `brief` configuration is changed to configure `output.mode: 'brief'`, and configure `output.options` `type` as `html`.
+
+### output.compressData
+
+The original `output.compressData` configuration is changed to configure `mode: 'brief'`, and configure `output.options.type` as `json`.
+
+### lite
+
+The internal logic of lite mode is equivalent to `output.options.reportCodeType` being `noCode` or `noAssetsAndModuleSource`, mainly to solve the problem of large projects being too slow when opening reports or OOM during build.
+
+Considering that users cannot clearly distinguish the actual meaning of lite mode, having too many modes is not conducive to management and configuration, and the `output.options.reportCodeType` configuration is clearer, so `mode: 'lite'` will be deprecated in the future V2 version.
+
+The original `mode: 'lite'` and `feature: 'lite'` configurations are changed to configure `mode: 'normal'`, and configure `output.options.reportCodeType` as `noCode` or `noAssetsAndModuleSource`.
+
+### output.options.jsonOptions.section
+
+Support for the new `output.options.jsonOptions.section` configuration for more granular JSON output option customization. For specific sections configuration items, refer to [output.options.jsonOptions.section](/config/options/output#jsonoptionssection).

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

@@ -1,17 +1,17 @@
-import { Badge } from '@theme';
+import { Badge, Tab, Tabs } from '@theme';
 
-# Options
+# Overview
 
 ## RsdoctorRspackPlugin
 
-`RsdoctorRspackPlugin` class are exported by `@rsdoctor/rspack-plugin`, and the option is [RsdoctorRspackPluginOptions](#options-1).
+The **RsdoctorRspackPlugin** class is exported by `@rsdoctor/rspack-plugin`, and the configuration options are [RsdoctorRspackPluginOptions](#rsdoctorrspackpluginoptions).
 
 <Tabs>
 
-<Tab label="cjs">
+<Tab label="esm">
 
-```js
-const { RsdoctorRspackPlugin } = require('@rsdoctor/rspack-plugin');
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
 
 new RsdoctorRspackPlugin({
   /** RsdoctorRspackPluginOptions */
@@ -20,10 +20,10 @@ new RsdoctorRspackPlugin({
 
 </Tab>
 
-<Tab label="esm">
+<Tab label="cjs">
 
-```ts
-import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+```js
+const { RsdoctorRspackPlugin } = require('@rsdoctor/rspack-plugin');
 
 new RsdoctorRspackPlugin({
   /** RsdoctorRspackPluginOptions */
@@ -36,16 +36,14 @@ new RsdoctorRspackPlugin({
 
 ## RsdoctorWebpackPlugin
 
-`RsdoctorWebpackPlugin` class are exported by `@rsdoctor/webpack-plugin`, and the option is [RsdoctorWebpackPluginOptions](#options-1).
-
-import { Tab, Tabs } from '@theme';
+The **RsdoctorWebpackPlugin** class is exported by `@rsdoctor/webpack-plugin`, and the configuration options are [RsdoctorWebpackPluginOptions](#rsdoctorwebpackpluginoptions).
 
 <Tabs>
 
-<Tab label="cjs">
+<Tab label="esm">
 
-```js
-const { RsdoctorWebpackPlugin } = require('@rsdoctor/webpack-plugin');
+```ts
+import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
 
 new RsdoctorWebpackPlugin({
   /** RsdoctorWebpackPluginOptions */
@@ -54,10 +52,10 @@ new RsdoctorWebpackPlugin({
 
 </Tab>
 
-<Tab label="esm">
+<Tab label="cjs">
 
-```ts
-import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';
+```js
+const { RsdoctorWebpackPlugin } = require('@rsdoctor/webpack-plugin');
 
 new RsdoctorWebpackPlugin({
   /** RsdoctorWebpackPluginOptions */
@@ -72,267 +70,64 @@ new RsdoctorWebpackPlugin({
 
 **Type:** `Object`
 
-This is the options for the [RsdoctorWebpackPlugin](#rsdoctorwebpackplugin) and [RsdoctorRspackPlugin](#rsdoctorrspackplugin). It contains these properties:
-
-- [brief](#brief)
-- [disableClientServer](#disableclientserver)
-- [experiments](#experiments)
-- [features](#features)
-- [mode](#mode)
-- [output](#output)
-- [port](#port)
-- [supports](#supports)
-
-### brief
-
-<Badge text="Version: 0.4.0" type="warning" />
-
-- **Type:** [BriefType](#brieftype)
-- **Optional:** `true`
-- **Default:** undefined
+This `Options` object is the configuration for [RsdoctorRspackPlugin](#rsdoctorrspackplugin) and [RsdoctorWebpackPlugin](#rsdoctorwebpackplugin) . It contains the following properties:
 
-More configurations for Brief mode are as follows:
+- [disableClientServer](./disableClientServer.mdx) - **Client Service Control**: Whether to not automatically open the Rsdoctor report service after analysis is complete.
+- [experiments](./experiments.mdx) - **Experimental Features Configuration**: Enable experimental features for Rspack plugins, such as native plugin performance optimization.
+- [features](./features.mdx) - **Feature Toggle Configuration**: Control various analysis features of Rsdoctor, such as loader analysis, bundle analysis, rule checking, etc.
+- [output](./output.mdx) - **Output Related Configuration**: Control report output format, directory and other options, including mode, options, reportCodeType, etc.
+- [port](./port.mdx) - **Service Port Configuration**: Set the port number for the Rsdoctor development server, used for report preview during local development.
+- [supports](./supports.mdx) - **Feature Support Configuration**: Enable compatibility support for specific build tools, such as BannerPlugin, etc.
+- [brief](./brief.mdx) - **Brief Mode Configuration**: Control the generation of brief mode reports, including HTML filename and whether to generate JSON data files.
+- [mode](./mode.mdx) - **Build Report Data Output Mode**: Select the output mode for reports, supporting normal (normal mode) and brief (brief mode).
 
-- **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
+### RsdoctorRspackPluginOptions
 
 ```ts
-interface BriefConfig {
-  reportHtmlName?: string | undefined;
-  writeDataJson: boolean;
-}
-```
-
-### disableClientServer
-
-- **Type:** `boolean`
-- **Optional:** `true`
-- **Default:** `false`
-
-Whether to automatically open the Rsdoctor report page. If you do not need to view the analysis report provided by Rsdoctor in the browser, you can enable this configuration item.
-
-### experiments
-
-<Badge text="Version: 1.0.0" type="warning" />
-
-#### enableNativePlugin
-
-- Type: `boolean`
-- Optional: true
-- Default: false
-
-##### Description
-
-By integrating Rsdoctor's native plugin into Rspack, we move Rsdoctor's time-consuming data processing logic to the Rspack build stage. This feature significantly improves the build analysis efficiency of Rsdoctor in Rspack, reducing the overall analysis time.
-
-- enableNativePlugin: Whether to enable the Rspack native plugin, enabling it can significantly reduce the analysis time of Rsdoctor itself.
-
-- Example
-
-```js
-new RsdoctorRspackPlugin({
-  experiments: { enableNativePlugin: true }
-}),
-```
-
-### features
-
-- **Type:** [RsdoctorWebpackPluginFeatures](#rsdoctorwebpackpluginfeatures) | [Array\<keyof RsdoctorWebpackPluginFeatures\>](#rsdoctorwebpackpluginfeatures) | [RsdoctorRspackPluginFeatures](#rsdoctorrspackpluginfeatures) | [Array\<keyof RsdoctorRspackPluginFeatures\>](#rsdoctorrspackpluginfeatures)
-- **Optional:** `true`
-- **Default:** `['loader', 'plugins', 'bundle']`
-
-#### features values
-
-The `features` attribute is used to analyze the function switches, and the specific functional items are as follows:
-
-- **loader**: Analysis of Loader time consumption and code compilation changes, enabled by default.
-- **plugins**: Analysis of Plugins calls and time consumption, enabled by default.
-- **bundle**: Analysis of build bundles, enabled by default.
-- **resolver**: resolver analysis, disabled by default.
-- **lite**: [**deprecated, please use [mode.lite](#mode)**]
-  lite mode. The difference between lite mode and normal mode is that source code information is no longer cached, only packaged code information is cached, so the code analyzed on the page will also be packaged. The default is normal mode.
-
-Therefore, **the default configuration enables bundle analysis capabilities and Loader and Plugin build-time analysis**. The Resolver analysis capability is not enabled, and Rspack does not currently support Resolver analysis capabilities.
-
-:::tip
-
-**If an "out of memory" error occurs, you can try the following:**
-
-1. Open the **lite** mode.[mode.lite](#mode)
-2. Increase the node memory limit, for example: NODE_OPTIONS=--max-old-space-size=8096.
-
-- Reason: During the build process, source code information is cached, which exceeds memory. Therefore, enabling the **"lite" mode** can help alleviate the problem.
-- Difference: The difference between the "lite" mode and the normal mode is that source code information is no longer cached, only packaged code information is cached. Thus, the code analyzed on the page will also only be packaged.
+interface RsdoctorWebpackPluginOptions<
+  Rules extends LinterType.ExtendRuleData[],
+> {
+  /** Linter configuration */
+  linter?: LinterType.Options<Rules, InternalRules>;
 
-:::
+  /** Rsdoctor feature toggles */
+  features?:
+    | Plugin.RsdoctorWebpackPluginFeatures
+    | Array<keyof Plugin.RsdoctorWebpackPluginFeatures>;
 
-#### features types
+  /**
+   * @deprecated Use `output.mode` instead. If using `lite` mode, please use `output.reportCodeType: 'noCode' or 'noAssetsAndModuleSource'` instead
+   * Rsdoctor mode options:
+   * - normal: Normal mode
+   * - brief: Brief mode, only displays duration analysis and build artifact analysis results, does not display any code parts
+   */
+  mode?: 'brief' | 'normal' | 'lite';
 
-- if the `features` is set as an `Array`, it will **open** the features which you define in this array **only**.
-- if the `features` is set as an `Object`, it will **close** the features which you set the value is `false`.
+  disableClientServer?: boolean;
 
-#### RsdoctorWebpackPluginFeatures
+  supports?: ISupport;
 
-`features` type:
+  port?: number;
 
-import Features from '@en/shared/features.md';
+  /**
+   * @deprecated Use `output.options.htmlOptions` instead
+   */
+  brief?: Config.BriefConfig;
 
-<Features />
+  output?: Config.IOutput<'brief' | 'normal'>;
 
-#### RsdoctorRspackPluginFeatures
-
-`features` type:
-
-import FeaturesRspack from '@en/shared/features-rspack.md';
-
-<FeaturesRspack />
-
-### mode
-
-<Badge text="Version: 0.4.0" type="warning" />
-
-- **Type:** `normal | brief | lite`
-- **Optional:** `true`
-- **Default:** `normal`
-
-Choose the Rsdoctor build report mode to use, which includes the following options:
-
-import ModeIntro from '@en/shared/mode-intro.md';
-
-<ModeIntro />
-
-### output
-
-<Badge text="Version 1.0.0" type="warning" />
-
-#### compressData
-
-- **Type:** boolean
-- **Optional:** `true`
-- **Default:** true
-
-compressData is used to configure whether to compress the analysis data under [outputDir]/.rsdoctor.
-
-#### reportDir
-
-- **Type:** string
-- **Optional:** `true`
-- **Default:** undefined
-
-The output directory for Rsdoctor reports. By default, it is the build output directory.
-
-#### reportCodeType
-
-- Type: `{ noModuleSource?: boolean; noAssetsAndModuleSource?: boolean }`
-- Optional: true
-- Default: undefined
-- Description
-
-  - Select the output analysis data:
-
-    - default is all complete data;
-
-    - noModuleSource: true is the output of data other than module code; Module code is the packaged module code of a file disassembled in the Bundle.
-
-    - noAssetsAndModuleSource: true is the output of data other than module code and Assets product code.
-
-- Example
-
-```js
-new RsdoctorRspackPlugin({
-  reportCodeType: { noModuleSource: true } // { noAssetsAndModuleSource: true }
-}),
-```
-
-### 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)
-- **Optional:** `true`
-- **Default:** `undefined`
-
-This option is used to configure whether Rsdoctor enables support for certain detailed feature analysis capabilities, such as whether to enable compatibility with BannerPlugin.
-
-#### Supports types
+  experiments?: RsdoctorRspackPluginExperiments;
+}
 
-```ts
-type ISupport = {
-  banner?: boolean;
-  parseBundle?: boolean;
-  generateTileGraph?: boolean;
-};
+interface RsdoctorRspackPluginExperiments {
+  /**
+   * Whether to enable native plugin to improve performance
+   * @default false
+   */
+  enableNativePlugin?: boolean;
+}
 ```
 
-#### banner
-
-:::danger
-`supports.banner` option is only used for debugging, do not use it in production.
-:::
-
-- default: false.
-- type: boolean.
-
-If `supports.banner` is enabled, Rsdoctor will enable compatibility logic for BannerPlugin. For more details, please refer to: [Supports BannerPlugin](../../guide/usage/bundle-size#supports-bannerplugin)
-
-#### ~~generateTileGraph [**Deprecated**]~~
-
-<Badge text="Deprecated" type="warning" />
-
-Rsdoctor supports generating Tree Map graphs by default, so this option does not need to be configured.
-
-#### parseBundle
-
-- default: true.
-- type: boolean.
-
-In some large repositories, the execution time of parsing the bundle is too long. Since the Parse Bundle analysis utilizes AST parsing and processing, it can be time-consuming when there are a large number of output files.
-If this capability is not necessary, it can be selectively disabled using the supports.parseBundle configuration. An example is shown below:
-
-```ts
-chain.plugin('Rsdoctor').use(RsdoctorRspackPlugin, [
-  {
-    supports: {
-      parseBundle: false,
-    },
-  },
-]);
-```
+### RsdoctorWebpackPluginOptions
 
-Disabling the Parse Bundle capability will only affect the visibility of the Bundled Size and Bundled Code of the modules in the bundle:
-
-<div style={{ display: 'flex' }}>
-  <img
-    src="https://assets.rspack.rs/others/assets/rsdoctor/bundled-size.jpeg"
-    height="300px"
-    width="300px"
-    style={{ margin: 'auto' }}
-  />
-
-  <img
-    src="https://assets.rspack.rs/others/assets/rsdoctor/bundled-code.png"
-    height="300px"
-    width="400px"
-    style={{ margin: 'auto' }}
-  />
-</div>
+RsdoctorWebpackPlugin is equivalent to `Omit<RsdoctorRspackPluginOptions, 'experiments'>` type.