@rsdoctor/docs 1.5.3 → 1.5.4

package/docs/en/blog/release/release-note-1_2.mdx

@@ -73,7 +73,7 @@ Rsdoctor v1.1 introduced MCP support, which is based on **Model Context Protocol
 
 Rsdoctor MCP supports natural language Q&A - you can directly ask questions like "Which packages have the largest volume?" or "Why wasn't this module tree-shaken?" The system will intelligently analyze and provide optimization suggestions, helping you quickly identify and resolve build issues.
 
-> [View usage details](/guide/start/mcp)
+> [View usage details](/guide/usage/mcp)
 
 <video
   src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/mcp-bundle-optimize-2.mp4"

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

@@ -284,6 +284,65 @@ export default {
 };
 ```
 
+### [E1007] Tree Shaking Side Effects Only
+
+Rule key: `tree-shaking-side-effects-only`
+
+This rule detects modules that are pulled in and bundled solely due to side effects. This is often caused by unintended tree-shaking failures (e.g. missing or incorrect `"sideEffects"` field in `package.json`, or non-tree-shakeable import patterns), resulting in the entire module being bundled even though none of its exports are used.
+
+#### Common causes
+
+- The package's `package.json` is missing `"sideEffects": false` (or incorrectly set to `true`), preventing the bundler from pruning unused exports.
+- An import statement like `import 'some-module'` or `import './styles.css'` is being treated as a side-effect-only import, but the intended use was to consume exports.
+- Barrel files (index files that re-export many things) cause the whole module to be kept alive when only a side-effect import is present.
+
+#### Solutions
+
+1. **Audit import statements**: Make sure you are actually importing and using named exports from this module. Replace bare side-effect imports with explicit named imports when you intend to use the module's exports.
+2. **Set `"sideEffects"` correctly**: In the module's `package.json`, set `"sideEffects": false` if the module has no global side effects, so the bundler can safely tree-shake unused exports.
+3. **Avoid unintended side-effect imports**: Remove or convert `import 'module'` patterns to explicit `import { foo } from 'module'` patterns where the exports are needed.
+
+#### Configuration
+
+- **ignore**: Module path patterns to ignore (string match: if the module path contains any of these strings, it is ignored).
+- **include**: Module path patterns to include when the module is under `node_modules` (by default, modules in `node_modules` are skipped).
+
+```ts
+interface Config {
+  /** Module path fragments to ignore */
+  ignore: string[];
+  /**
+   * Module path patterns to include when the module is under node_modules.
+   * Example: ['react', '@babel/runtime']
+   */
+  include: string[];
+}
+```
+
+Configuration example:
+
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugins: [
+    new RsdoctorRspackPlugin({
+      linter: {
+        rules: {
+          'tree-shaking-side-effects-only': [
+            'Warn',
+            {
+              ignore: ['src/polyfills'],
+              include: ['some-lib'],
+            },
+          ],
+        },
+      },
+    }),
+  ],
+};
+```
+
 ## Linter type
 
 - The type definition for the `linter` field is as follows:

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

@@ -5,6 +5,6 @@
   "cicd",
   "action",
   "cli",
-  "mcp",
+  "ai",
   "playground"
 ]

package/docs/en/guide/start/ai.mdx

@@ -0,0 +1,101 @@
+import { PackageManagerTabs } from '@theme';
+
+# AI
+
+To help AI better understand Rsdoctor's features, configuration, and best practices so it can provide more accurate assistance during day-to-day development and troubleshooting, Rsdoctor provides the following capabilities:
+
+- [Agent Skills](#agent-skills)
+- [MCP Server](#mcp-server)
+- [llms.txt](#llmstxt)
+- [Markdown docs](#markdown-docs)
+- [AGENTS.md](#agentsmd)
+
+## Agent Skills
+
+Agent Skills are domain-specific knowledge packs that can be installed into Agents, enabling them to give more accurate and professional suggestions or perform actions in specific scenarios.
+
+In the [rstackjs/agent-skills](https://github.com/rstackjs/agent-skills) repository, there are many skills for the Rstack ecosystem. The skills related to Rsdoctor include:
+
+- [rsdoctor-analysis](https://github.com/rstackjs/agent-skills#rsdoctor-skills): Use Rsdoctor for build analysis and provide optimization recommendations.
+
+In Coding Agents that support skills, you can use the [skills](https://www.npmjs.com/package/skills) package to install a specific skill with the following command:
+
+<PackageManagerTabs
+  command="skills add rstackjs/agent-skills --skill rsdoctor-analysis"
+  dlx
+/>
+
+After installation, simply use natural language prompts to trigger the skill, for example:
+
+```
+Use Rsdoctor to analyze this project and provide optimization suggestions
+```
+
+## MCP Server
+
+Rsdoctor provides MCP Server so AI tools can query your local build analysis data. See the [MCP Server](/guide/usage/mcp) documentation.
+
+## llms.txt
+
+[llms.txt](https://llmstxt.org/) is a standard that helps LLMs discover and use project documentation. Rsdoctor follows this standard and publishes the following two files:
+
+- [llms.txt](https://rsdoctor.rs/llms.txt): A structured index file containing the titles, links, and brief descriptions of all documentation pages.
+
+```
+https://rsdoctor.rs/llms.txt
+```
+
+- [llms-full.txt](https://rsdoctor.rs/llms-full.txt): A full-content file that concatenates the complete content of every documentation page into a single file.
+
+```
+https://rsdoctor.rs/llms-full.txt
+```
+
+You can choose the file that best fits your use case:
+
+- `llms.txt` is smaller and consumes fewer tokens, making it suitable for AI to fetch specific pages on demand.
+- `llms-full.txt` contains the complete documentation content, so AI doesn't need to follow individual links - ideal when you need AI to have a comprehensive understanding of Rsdoctor, though it consumes more tokens and is best used with AI tools that support large context windows.
+
+## Markdown docs
+
+Every Rsdoctor documentation page has a corresponding `.md` plain-text version that can be provided directly to AI. On any doc page, you can click "Copy Markdown" or "Copy Markdown Link" under the title to get the Markdown content or link.
+
+```
+https://rsdoctor.rs/guide/start/intro.md
+```
+
+Providing the Markdown link or content allows AI to focus on a specific chapter, which is useful for targeted troubleshooting or looking up a particular topic.
+
+## AGENTS.md
+
+You can create an `AGENTS.md` file in the root of a project that uses Rsdoctor. This file follows the [AGENTS.md](https://agents.md/) specification and provides key project information to Agents.
+
+Here is an example of Rsdoctor-related content you can add to `AGENTS.md`:
+
+```markdown wrapCode
+# AGENTS.md
+
+You are an expert in JavaScript, Rsdoctor, and build analysis.
+
+## Tools
+
+### Rsdoctor
+
+- Run `RSDOCTOR=true npm run build` to build the app with Rsdoctor
+
+## Docs
+
+- Rsdoctor: https://rsdoctor.rs/llms.txt
+```
+
+You can also customize it for your project, adding more details about the project structure, overall architecture, and other relevant information so Agents can better understand your project.
+
+::: tip
+
+If you are using Claude Code, you can create a `CLAUDE.md` file and reference the `AGENTS.md` file in it.
+
+```markdown title="CLAUDE.md"
+@AGENTS.md
+```
+
+:::

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

@@ -11,5 +11,6 @@
   "module-analysis",
   "resolver",
   "rule-config",
-  "bundle-diff"
+  "bundle-diff",
+  "mcp"
 ]

package/docs/en/guide/{start → usage}/mcp.mdx

@@ -298,4 +298,4 @@ new RsdoctorRspackPlugin({
 - Ensure the Rsdoctor local Server has been successfully started.
   - Manually start the local Server, do not use MCP Client to start the project, as the local service of Rsdoctor will block the dialogue process of MCP Client.
 - If the Rsdoctor MCP server uses the `--port` parameter, please ensure the Rsdoctor startup port configuration is correct.
-- Check if the Rsdoctor plugin version meets the requirements. [Version requirements](/guide/start/mcp#-version-requirements)
+- Check if the Rsdoctor plugin version meets the requirements. [Version requirements](/guide/usage/mcp#-version-requirements)

package/docs/en/guide/usage/module-analysis.mdx

@@ -71,4 +71,4 @@ You can also use MCP for analysis. By asking "Please help me to check why react-
   alt="tree-shaking"
 />
 
-> For MCP analysis, see [MCP Analysis](/guide/start/mcp)
+> For MCP analysis, see [MCP Analysis](/guide/usage/mcp)

package/docs/zh/blog/release/release-note-1_2.mdx

@@ -73,7 +73,7 @@ Rsdoctor v1.1 引入了 MCP 支持，它基于 **Model Context Protocol (MCP)**
 
 Rsdoctor MCP 支持自然语言问答，你可以直接问"哪些包体积最大？"、"为什么这个模块没有被 Tree Shaking？"等问题，系统会智能分析并给出优化建议，帮助你快速定位和解决构建问题。主要功能包括获取产物信息、依赖分析、优化建议、编译性能及 tree shaking 分析等核心分析能力。
 
-> [查看使用详情](/guide/start/mcp)
+> [查看使用详情](/guide/usage/mcp)
 
 <video
   src="https://lf3-static.bytednsdoc.com/obj/eden-cn/lognuvj/rsdoctor/docs/mcp-bundle-optimize-2.mp4"

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

@@ -280,6 +280,65 @@ export default {
 };
 ```
 
+### [E1007] Tree Shaking Side Effects Only
+
+规则 key: `tree-shaking-side-effects-only`
+
+当某个模块仅以副作用（side effects）方式被引入并打进产物时，该规则会发出警告。这通常是由于意外的 tree-shaking 失败导致的（例如 `package.json` 中缺少或错误设置了 `"sideEffects"` 字段，或使用了不可 tree-shake 的 import 写法），使整个模块被打包进产物，即使其导出的内容没有被实际使用。
+
+#### 常见原因
+
+- 包的 `package.json` 缺少 `"sideEffects": false`（或错误地设置为 `true`），导致打包器无法裁剪未使用的导出。
+- `import 'some-module'` 或 `import './styles.css'` 这类语句被当作纯副作用引入处理，而实际意图是使用该模块的导出内容。
+- Barrel 文件（将许多内容重新导出的 index 文件）在只存在副作用引入时，导致整个模块被保留。
+
+#### 解决方案
+
+1. **审查 import 语句**：确认你确实在引入并使用该模块的具名导出。当你需要使用模块的导出时，将裸副作用引入替换为显式的具名引入。
+2. **正确设置 `"sideEffects"`**：如果该模块没有全局副作用，在其 `package.json` 中设置 `"sideEffects": false`，使打包器可以安全地 tree-shake 未使用的导出。
+3. **避免非预期的副作用引入**：将 `import 'module'` 模式转换为 `import { foo } from 'module'` 的显式写法（当需要使用导出时）。
+
+#### 配置
+
+- **ignore**：需要忽略的模块路径匹配规则（字符串匹配：模块路径包含配置中的某字符串即忽略）。
+- **include**：当模块位于 `node_modules` 下时，需要纳入检查的模块路径匹配规则（默认情况下 `node_modules` 中的模块会被跳过）。
+
+```ts
+interface Config {
+  /** 需要忽略的模块路径片段 */
+  ignore: string[];
+  /**
+   * 当模块位于 node_modules 下时，需要纳入检查的模块路径匹配规则。
+   * 示例：['react', '@babel/runtime']
+   */
+  include: string[];
+}
+```
+
+配置示例：
+
+```ts
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  plugins: [
+    new RsdoctorRspackPlugin({
+      linter: {
+        rules: {
+          'tree-shaking-side-effects-only': [
+            'Warn',
+            {
+              ignore: ['src/polyfills'],
+              include: ['some-lib'],
+            },
+          ],
+        },
+      },
+    }),
+  ],
+};
+```
+
 ## Linter 类型定义
 
 - `linter`字段的类型如下：

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

@@ -5,6 +5,6 @@
   "cicd",
   "action",
   "cli",
-  "mcp",
+  "ai",
   "playground"
 ]

package/docs/zh/guide/start/ai.mdx

@@ -0,0 +1,101 @@
+import { PackageManagerTabs } from '@theme';
+
+# AI
+
+为了帮助 AI 更全面地了解 Rsdoctor 的功能、配置与最佳实践，从而在日常开发和问题排查过程中提供更准确的帮助，Rsdoctor 提供了以下能力：
+
+- [Agent Skills](#agent-skills)
+- [MCP Server](#mcp-server)
+- [llms.txt](#llmstxt)
+- [Markdown 文档](#markdown-文档)
+- [AGENTS.md](#agentsmd)
+
+## Agent Skills
+
+Agent Skills 是可安装到 Agent 中的领域知识包，能够让 Agent 在特定场景下更准确、更专业地给出建议或执行操作。
+
+我们在 [rstackjs/agent-skills](https://github.com/rstackjs/agent-skills) 仓库中为 Rstack 生态提供了许多 Skills，其中关于 Rsdoctor 的 Skills 包括：
+
+- [rsdoctor-analysis](https://github.com/rstackjs/agent-skills#rsdoctor-skills)：使用 Rsdoctor 进行构建分析并提供优化建议。
+
+在支持 Skills 的 Coding Agent 中，可以通过以下命令使用 [skills](https://www.npmjs.com/package/skills) 包安装指定的 Skill：
+
+<PackageManagerTabs
+  command="skills add rstackjs/agent-skills --skill rsdoctor-analysis"
+  dlx
+/>
+
+安装完成后，用自然语言输入相关提示词即可触发对应 Skill，例如：
+
+```
+使用 Rsdoctor 对该项目进行构建分析并给出优化建议
+```
+
+## MCP Server
+
+Rsdoctor 提供 MCP Server 让 AI 工具可以查询本地构建分析数据，详见 [MCP Server](/guide/usage/mcp) 文档。
+
+## llms.txt
+
+[llms.txt](https://llmstxt.org/) 是一种帮助 LLM 发现和使用项目文档的标准规范。Rsdoctor 遵循该规范，发布了以下两个文件：
+
+- [llms.txt](https://rsdoctor.rs/llms.txt)：结构化索引文件，包含所有文档页面的标题、链接与简要描述。
+
+```
+https://rsdoctor.rs/llms.txt
+```
+
+- [llms-full.txt](https://rsdoctor.rs/llms-full.txt)：完整内容文件，将所有文档页面的内容合并为单个文件。
+
+```
+https://rsdoctor.rs/llms-full.txt
+```
+
+你可以根据使用场景选择合适的文件：
+
+- `llms.txt` 体积较小、消耗 token 少，适合让 AI 按需获取具体页面。
+- `llms-full.txt` 包含全量文档内容，无需 AI 逐一跟随链接，适合需要 AI 全面了解 Rsdoctor 的场景，但会消耗更多 token，建议在支持大上下文窗口的 AI 工具中使用。
+
+## Markdown 文档
+
+Rsdoctor 文档的每个页面都提供对应的 `.md` 纯文本版本，可直接作为上下文提供给 AI。你可以在文档任意页面的标题下方点击「复制 Markdown」或「复制 Markdown 链接」按钮，获取该页面对应的 Markdown 文件内容或链接。
+
+```
+https://rsdoctor.rs/guide/start/intro.md
+```
+
+将 Markdown 链接或内容提供给 AI，即可让其精确了解某一具体章节的内容，适合在针对性问题排查或查阅特定内容时使用。
+
+## AGENTS.md
+
+你可以在使用 Rsdoctor 的项目根目录创建一个 `AGENTS.md` 文件。该文件遵循 [AGENTS.md](https://agents.md/) 规范，向 Agents 提供项目的关键信息。
+
+以下是可以在 `AGENTS.md` 中添加的 Rsdoctor 相关内容示例：
+
+```markdown wrapCode
+# AGENTS.md
+
+You are an expert in JavaScript, Rsdoctor, and build analysis.
+
+## Tools
+
+### Rsdoctor
+
+- Run `RSDOCTOR=true npm run build` to build the app with Rsdoctor
+
+## Docs
+
+- Rsdoctor: https://rsdoctor.rs/llms.txt
+```
+
+你也可以根据项目的实际情况进行修改，添加更多关于项目结构、整体架构等多方面的信息，以便 Agents 更好地理解你的项目。
+
+::: tip
+
+如果你使用的是 Claude Code，可以创建一个 `CLAUDE.md` 文件，并在其中引用 `AGENTS.md` 文件。
+
+```markdown title="CLAUDE.md"
+@AGENTS.md
+```
+
+:::

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

@@ -11,5 +11,6 @@
   "module-analysis",
   "resolver",
   "rule-config",
-  "bundle-diff"
+  "bundle-diff",
+  "mcp"
 ]

package/docs/zh/guide/{start → usage}/mcp.mdx

@@ -312,4 +312,4 @@ new RsdoctorRspackPlugin({
 - 确保 Rsdoctor 本地 Server 已成功启动。
   - 手动启动本地 Server，请勿使用 MCP Client 启动项目，因为 Rsdoctor 的挂载的本地服务会卡住 MCP Client 的对话进程。
 - 如果 Rsdoctor MCP server 使用了 `--port` 参数，请确保 Rsdoctor 的启动端口配置正确。
-- 检查 Rsdoctor 插件版本是否符合要求。[版本要求](/guide/start/mcp#-%E7%89%88%E6%9C%AC%E8%A6%81%E6%B1%82)
+- 检查 Rsdoctor 插件版本是否符合要求。[版本要求](/guide/usage/mcp#-%E7%89%88%E6%9C%AC%E8%A6%81%E6%B1%82)

package/docs/zh/guide/usage/module-analysis.mdx

@@ -71,4 +71,4 @@
   alt="tree-shaking"
 />
 
-> MCP 分析请查看 [MCP 分析](/guide/start/mcp)
+> MCP 分析请查看 [MCP 分析](/guide/usage/mcp)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsdoctor/docs",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "repository": {
     "type": "git",
     "url": "https://github.com/web-infra-dev/rsdoctor",
@@ -19,28 +19,28 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@rspress/plugin-algolia": "2.0.3",
-    "@rspress/plugin-llms": "2.0.3",
-    "@rspress/plugin-rss": "2.0.2",
+    "@rspress/plugin-algolia": "2.0.5",
+    "@rspress/plugin-rss": "2.0.5",
     "@types/node": "^22.8.1",
     "@types/react": "^18.3.28",
     "@types/react-dom": "^18.3.7",
     "cross-env": "^7.0.3",
     "react": "18.3.1",
     "react-dom": "18.3.1",
+    "react-render-to-markdown": "^18.3.1",
     "rsbuild-plugin-google-analytics": "^1.0.5",
     "rsbuild-plugin-open-graph": "^1.1.2",
     "rspress-plugin-font-open-sans": "^1.0.3",
     "rspress-plugin-sitemap": "^1.2.1",
     "typescript": "^5.9.2",
-    "@rsbuild/plugin-sass": "^1.5.0",
-    "@rsdoctor/types": "1.5.3"
+    "@rsbuild/plugin-sass": "^1.5.1",
+    "@rsdoctor/types": "1.5.4"
   },
   "dependencies": {
     "@rstack-dev/doc-ui": "1.12.4",
     "clsx": "^2.1.1",
     "react-markdown": "^9.1.0",
-    "@rspress/core": "2.0.3"
+    "@rspress/core": "2.0.5"
   },
   "scripts": {
     "dev": "cross-env RSPRESS_PERSIST_CACHE=false rspress dev",