@rsdoctor/docs 1.5.2-beta.0 → 1.5.3-alpha.0

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

@@ -69,12 +69,11 @@ Support for loader analysis for Vue projects has been added in Rsdoctor 0.4.
 
 - **Rspack's builtin:lightningcss-loader analysis**: Added support for [builtin:lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader#builtin-lightningcss-loader) analysis.
 - **Performance optimization**:
-
   - Reduced the size of the `@rsdoctor/client` package by 60%, improving page rendering speed.
 
   <img
     src="https://assets.rspack.rs/others/assets/rsdoctor/package-size-diff.png"
     style={{ width: '60%', margin: 'auto' }}
   />
-
-  - Reduced third-party dependencies, thereby reducing the total download size during installation.
+  - Reduced third-party dependencies, thereby reducing the total download size
+  during installation.

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

@@ -180,7 +180,3 @@ dist/
 ```
 
 Rsdoctor will automatically detect and analyze these `.bundle` files without any additional configuration.
-
-### Future Extensions
-
-If you need support for additional custom extensions, please open an issue on the [Rsdoctor GitHub repository](https://github.com/web-infra-dev/rsdoctor) with details about your use case.

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

@@ -34,7 +34,8 @@ Please refer to the [Linter Type](#linter-type) in this document for the type de
   - 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://assets.rspack.rs/others/assets/rsdoctor/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.
+  - 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://assets.rspack.rs/others/assets/rsdoctor/bundle-alters-rule.png" />
 
@@ -222,6 +223,67 @@ interface Config {
 }
 ```
 
+### [E1006] Module Mixed Chunks
+
+When a module is included in both **initial chunks** and **async chunks**, the same module code is bundled into multiple chunks, increasing output size and potentially affecting first-screen load and cache efficiency.
+
+- **Initial chunks**: Chunks loaded with the main entry (e.g. entry points, synchronous `import` in the main bundle).
+- **Async chunks**: Chunks loaded on demand via dynamic `import()` or similar.
+
+#### Rule details
+
+- In the **「Module Mixed Chunks」** tab of Bundle Alerts, all modules that appear in both initial and async chunks are listed.
+- Each entry shows: module path, **Initial Chunks** list, and **Async Chunks** list, so you can locate duplicated modules.
+
+#### Common causes
+
+- **Same module referenced in two ways**: The module is both synchronously `import`ed in the main bundle or entry, and dynamically `import()`ed somewhere else, so the bundler emits it in both initial and async chunks.
+- **A file is both an entry and an async chunk**: For example, a utility module is configured as an entry and also `import()`ed in app code, so it appears in the entry’s initial chunk and in a dynamically loaded async chunk.
+- **splitChunks overlapping with entry**: A path is split into an async chunk via `splitChunks` / `chunkSplit`, but that path is also an entry or a main-bundle dependency, leading to mixed chunk types.
+
+#### Solutions and recommendations
+
+1. **Use a single import style**  
+   Prefer one way to reference a module: either all synchronous imports (in initial) or all dynamic `import()` (in async). Avoid having the same file both synchronously imported in the main bundle and dynamically imported elsewhere.
+
+2. **Review entry vs dynamic loading**  
+   If a file is both an entry and part of an async chunk, either remove one of those usages or treat the file as a shared dependency and extract it into a single shared chunk via build config, so both initial and async chunks reference it instead of duplicating it.
+
+3. **Adjust splitChunks / chunkSplit**  
+   Check rules for that module path in `optimization.splitChunks` (Rspack/Webpack) or `performance.chunkSplit` (Rsbuild), and avoid the same module being split into both initial and async chunks. Use `chunks: 'async'` or `chunks: 'initial'` where appropriate, or control which chunk type it goes into via `cacheGroups` and `test` / `chunks`.
+
+4. **Trace dependencies**  
+   From the reported module path and chunk list, search the codebase for references to that module, distinguish sync vs dynamic imports, then converge to a single chunk type or extract a common chunk as above.
+
+#### Configuration
+
+- **ignore**: Module path patterns to ignore (string match: if the module path contains any of these strings, it is ignored).
+
+```ts
+interface Config {
+  /** Module path fragments to ignore */
+  ignore: string[];
+}
+```
+
+Configuration example:
+
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugin: [
+    new RsdoctorRspackPlugin({
+      linter: {
+        rules: {
+          'module-mixed-chunks': ['Warn', { ignore: ['node_modules/'] }],
+        },
+      },
+    }),
+  ],
+};
+```
+
 ## Linter type
 
 - The type definition for the `linter` field is as follows:

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

@@ -72,12 +72,10 @@ import { Badge } from '@theme';
   在 Rsdoctor 0.4 版本中支持了 Rspack 的 [builtin:lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader#builtin-lightningcss-loader) 分析。
 
 - Rsdoctor 自身的性能优化
-
   - 减少了 60% 的 `@rsdoctor/client` 包体积，提高页面渲染速度。
 
   <img
     src="https://assets.rspack.rs/others/assets/rsdoctor/package-size-diff.png"
     style={{ width: '60%', margin: 'auto' }}
   />
-
   - 减少 Rsdoctor 可替代的第三方依赖包，从而减少安装时下载总大小。

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

@@ -180,7 +180,3 @@ dist/
 ```
 
 Rsdoctor 将自动检测和分析这些 `.bundle` 文件，无需任何额外配置。
-
-### 未来扩展
-
-如果您需要支持其他自定义扩展名，请在 [Rsdoctor GitHub 仓库](https://github.com/web-infra-dev/rsdoctor) 上开启一个 issue，并详细说明您的使用场景。

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

@@ -219,6 +219,67 @@ interface Config {
 }
 ```
 
+### [E1006] Module Mixed Chunks
+
+当某个模块同时被包含在 **initial chunks**（初始 chunk）和 **async chunks**（异步 chunk）中时，会导致同一份模块代码被重复打进多个 chunk，增加产物体积，并可能影响首屏加载与缓存效率。
+
+- **Initial chunks**：随主入口一起加载的 chunk（如 entry、主包里的同步 import）。
+- **Async chunks**：通过动态 `import()` 等方式按需加载的 chunk。
+
+#### 规则详情
+
+- 在 Bundle Alerts 的 **「Module Mixed Chunks」** 标签页中，会列出所有同时出现在初始 chunk 与异步 chunk 中的模块。
+- 每个条目会展示：模块路径、所属的 **Initial Chunks** 列表和 **Async Chunks** 列表，便于定位重复打包的模块。
+
+#### 常见原因
+
+- **同一模块被两种方式引用**：既在主包或 entry 里被同步 `import`，又在某处被动态 `import()` 引用，构建工具会分别打进 initial 与 async chunk。
+- **某文件既作 entry 又作异步 chunk**：例如某工具模块既在配置里被设为 entry，又在业务代码里被 `import()`，会导致该模块同时出现在 entry 产物的 initial chunk 和动态加载的 async chunk 中。
+- **splitChunks 与 entry 重叠**：通过 `splitChunks` / `chunkSplit` 把某路径单独拆成 async chunk，但该路径同时又是 entry 或主包依赖，也会出现混合。
+
+#### 解决方案与建议
+
+1. **统一引用方式**  
+   尽量对同一模块只使用一种引用方式：要么全部同步 import（放进 initial），要么全部动态 `import()`（放进 async）。避免「主包同步引用 + 某处动态引用」同一文件。
+
+2. **审视 entry 与动态加载**  
+   若某文件既作为 entry 又被打进异步 **chunk**，考虑：去掉其中一种用法；或将该文件只作为公共依赖，通过构建配置抽成单一 shared chunk，由 initial 与 async 共同引用，而不是重复打包。
+
+3. **调整 splitChunks / chunkSplit**  
+   检查 `optimization.splitChunks`（Rspack/Webpack）或 `performance.chunkSplit`（Rsbuild）中对该模块路径的规则，避免同一模块被同时拆到 initial 与 async 两类 chunk。可适当使用 `chunks: 'async'` 或 `chunks: 'initial'` 做区分，或通过 `cacheGroups` 的 `test` 与 `chunks` 控制其只进入一类 chunk。
+
+4. **梳理依赖关系**  
+   根据报告中的模块路径与 chunk 列表，在源码中搜索该模块的引用位置，区分同步与动态引用，再按上述方式收敛为单一 chunk 类型或抽成公共 chunk。
+
+#### 配置
+
+- **ignore**：配置需要忽略的模块路径（支持字符串匹配：模块路径包含配置中的某字符串即忽略）。
+
+```ts
+interface Config {
+  /** 需要忽略的模块路径片段 */
+  ignore: string[];
+}
+```
+
+配置示例：
+
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugin: [
+    new RsdoctorRspackPlugin({
+      linter: {
+        rules: {
+          'module-mixed-chunks': ['Warn', { ignore: ['node_modules/'] }],
+        },
+      },
+    }),
+  ],
+};
+```
+
 ## Linter 类型定义
 
 - `linter`字段的类型如下：

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

@@ -13,5 +13,6 @@ Overall 页面中的 `Alerts` 部分用于展示「构建规则」及「编译
 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)
+4. [[E1006] Module Mixed Chunks](../../guide/rules/rules#e1006-module-mixed-chunks)
 
 具体可以查看[内置规则](../../guide/rules/rules)。

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

@@ -29,6 +29,7 @@
 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)
+6. [[E1006] Module Mixed Chunks](/guide/rules/rules#e1006-module-mixed-chunks)
 
 具体可以查看[内置规则](/guide/rules/rules)。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsdoctor/docs",
-  "version": "1.5.2-beta.0",
+  "version": "1.5.3-alpha.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/rsdoctor",
@@ -33,7 +33,7 @@
     "rspress-plugin-sitemap": "^1.2.1",
     "typescript": "^5.9.2",
     "@rsbuild/plugin-sass": "^1.4.1",
-    "@rsdoctor/types": "1.5.2-beta.0"
+    "@rsdoctor/types": "1.5.3-alpha.0"
   },
   "dependencies": {
     "@rstack-dev/doc-ui": "1.12.3",