deps-conflict-resolver 1.1.0 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ben-lau
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md ADDED
@@ -0,0 +1,321 @@
1
+ # deps-conflict-resolver
2
+
3
+ [![npm version](https://img.shields.io/npm/v/deps-conflict-resolver.svg)](https://www.npmjs.com/package/deps-conflict-resolver)
4
+ [![CI](https://github.com/ben-lau/deps-conflict-resolver/actions/workflows/ci.yml/badge.svg)](https://github.com/ben-lau/deps-conflict-resolver/actions/workflows/ci.yml)
5
+ [![codecov](https://codecov.io/gh/ben-lau/deps-conflict-resolver/branch/main/graph/badge.svg)](https://codecov.io/gh/ben-lau/deps-conflict-resolver)
6
+
7
+ > [中文文档](./README.md)
8
+
9
+ A Webpack and Vite plugin that automatically resolves peer dependency conflicts by creating aliases for conflicting versions, allowing different versions of the same dependency to coexist.
10
+
11
+ ## Features
12
+
13
+ - **Recursive Dependency Analysis**: Deep traversal of the entire dependency tree, including nested sub-dependencies, while preserving nested instances by their installed paths
14
+ - **Smart Conflict Detection**: Automatically identifies peer dependency version conflicts against the host project
15
+ - **Automatic Alias Installation**: Creates aliases for conflicting dependencies and installs the appropriate versions
16
+ - **Module Resolution Redirection**: At build time, redirects module imports from conflicting libraries to their aliased versions
17
+ - **Remote Version Querying**: Fetches version lists from the npm registry and intelligently selects the best version
18
+ - **Webpack & Vite Support**: Provides plugin implementations for both build tools
19
+
20
+ ## Use Case
21
+
22
+ The canonical scenario: your Vue 3 project needs to use a third-party library that only supports Vue 2. The library's dependency chain may include Vue 2, vue-router 3, and other older dependencies. This plugin can:
23
+
24
+ 1. Automatically detect these version conflicts
25
+ 2. Create aliases for conflicting dependencies (e.g., `aliased-vue2` for `vue@2.x`)
26
+ 3. Automatically install the aliased dependencies
27
+ 4. Redirect module resolution at build time: `import Vue from 'vue'` inside the third-party library resolves to `vue@2.x`, while the same import in your host project still resolves to `vue@3.x`
28
+
29
+ ## Installation
30
+
31
+ ```bash
32
+ npm install deps-conflict-resolver --save-dev
33
+ # or
34
+ yarn add deps-conflict-resolver -D
35
+ # or
36
+ pnpm add deps-conflict-resolver -D
37
+ ```
38
+
39
+ ## Usage
40
+
41
+ ### Vite
42
+
43
+ ```typescript
44
+ // vite.config.ts
45
+ import { defineConfig } from 'vite';
46
+ import { depsConflictResolverVitePlugin } from 'deps-conflict-resolver/vite';
47
+
48
+ export default defineConfig({
49
+ plugins: [
50
+ depsConflictResolverVitePlugin({
51
+ // Packages to analyze
52
+ dependencies: ['legacy-vue2-library'],
53
+
54
+ // Optional
55
+ autoInstall: true, // Auto-install missing aliased dependencies
56
+ packageManager: 'npm', // npm | yarn | pnpm
57
+ debug: false, // Enable debug logging
58
+ }),
59
+ ],
60
+ });
61
+ ```
62
+
63
+ ### Webpack
64
+
65
+ ```typescript
66
+ // webpack.config.js
67
+ const { DepsConflictResolverWebpackPlugin } = require('deps-conflict-resolver/webpack');
68
+
69
+ module.exports = {
70
+ plugins: [
71
+ new DepsConflictResolverWebpackPlugin({
72
+ dependencies: ['legacy-vue2-library'],
73
+ autoInstall: true,
74
+ packageManager: 'npm',
75
+ }),
76
+ ],
77
+ };
78
+ ```
79
+
80
+ ### Programmatic Usage
81
+
82
+ ```typescript
83
+ import { createResolver } from 'deps-conflict-resolver';
84
+
85
+ const resolver = await createResolver({
86
+ dependencies: ['legacy-vue2-library'],
87
+ projectRoot: process.cwd(),
88
+ autoInstall: true,
89
+ });
90
+
91
+ // Get analysis results
92
+ const result = resolver.getAnalysisResult();
93
+ console.log('Peer conflicts:', result.peerConflicts);
94
+ console.log('Alias mappings:', result.aliasMappings);
95
+
96
+ // Manually resolve a module
97
+ const resolved = resolver.resolveModule('vue', '/path/to/importer.js');
98
+ ```
99
+
100
+ ## Configuration
101
+
102
+ | Option | Type | Default | Description |
103
+ | ------------------ | ------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
104
+ | `dependencies` | `string[]` | - | **Required.** List of package names to analyze |
105
+ | `projectRoot` | `string` | `process.cwd()` | Project root directory path |
106
+ | `autoInstall` | `boolean` | `true` | Whether to auto-install missing aliased dependencies |
107
+ | `packageManager` | `'auto' \| 'npm' \| 'yarn' \| 'pnpm'` | `'auto'` | Package manager type. `'auto'` detects automatically |
108
+ | `registry` | `string` | Auto-detected | npm registry URL; an explicit value is used for both version queries and alias installation |
109
+ | `debug` | `boolean` | `false` | Whether to enable debug logging |
110
+ | `aliasPrefix` | `string` | `'aliased-'` | Prefix for generated alias names |
111
+ | `excludeRedirects` | `Record<string, string[]>` | `{}` | Exclude specific packages from the redirect list. Keys are original package names, values are importer package names to exclude. Example: `{ vue: ['vue-demi', 'pinia'] }` |
112
+ | `includeRedirects` | `Record<string, string[]>` | `{}` | Force specific packages into the redirect list. Applied before `excludeRedirects`. Useful when semver ranges are too broad (e.g., `>=2.5.0`) but the package still needs the older version at runtime. Example: `{ vue: ['@rili/ui', '@kmt/meeting-setting'] }` |
113
+
114
+ ### Vite Plugin Exclusive Options
115
+
116
+ | Option | Type | Default | Description |
117
+ | --------------- | --------- | ------- | ------------------------------------------ |
118
+ | `enableInDev` | `boolean` | `true` | Whether to enable in development mode |
119
+ | `enableInBuild` | `boolean` | `true` | Whether to enable in production build mode |
120
+
121
+ ### Auto-Detection
122
+
123
+ The plugin supports automatic detection of the package manager and registry:
124
+
125
+ **Package Manager Detection Priority:**
126
+
127
+ 1. `packageManager` field in `package.json` (e.g., `"pnpm@8.0.0"`)
128
+ 2. Lock file presence (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm)
129
+ 3. Falls back to npm
130
+
131
+ **Registry Detection Priority:**
132
+
133
+ 1. Project-level `.npmrc` file
134
+ 2. User-level `~/.npmrc` file
135
+ 3. User-level `.pnpmrc` for pnpm or `.yarnrc.yml` in yarn projects
136
+ 4. Falls back to `https://registry.npmjs.org`
137
+
138
+ An explicit `registry` option overrides this detection. The resolver uses it for remote version queries, and the package manager uses the same registry when installing aliases.
139
+
140
+ ## How It Works
141
+
142
+ ### 1. Dependency Analysis
143
+
144
+ The plugin recursively analyzes the entire dependency tree of the specified packages:
145
+
146
+ ```
147
+ package-a
148
+ ├── package-b
149
+ │ └── package-c (peerDeps: vue@^2.0.0)
150
+ └── package-d (peerDeps: vue-router@^3.0.0)
151
+ ```
152
+
153
+ ### 2. Conflict Detection
154
+
155
+ Compares installed versions in the host project against peer dependency requirements:
156
+
157
+ - Host project: `vue@3.2.0`, `vue-router@4.1.0`
158
+ - Peer dependency requirements: `vue@^2.0.0`, `vue-router@^3.0.0`
159
+ - Conflict detected ✗
160
+
161
+ ### 3. Version Resolution
162
+
163
+ Before making a remote request, the resolver checks installed local and workspace npm aliases whose package identity and version satisfy the conflicting range. A matching alias is reused offline with no registry access or reinstall; only unresolved requests query the registry and select the best version that satisfies all peer dependency ranges:
164
+
165
+ - `vue@^2.0.0` → selects `vue@2.7.14`
166
+ - `vue-router@^3.0.0` → selects `vue-router@3.6.5`
167
+
168
+ ### 4. Alias Installation
169
+
170
+ Creates and installs aliased dependencies:
171
+
172
+ ```bash
173
+ npm install aliased-vue2@npm:vue@2.7.14
174
+ npm install aliased-vue-router3@npm:vue-router@3.6.5
175
+ ```
176
+
177
+ ### 5. Module Resolution Redirection
178
+
179
+ At build time, module imports are automatically redirected:
180
+
181
+ ```javascript
182
+ // Inside package-c
183
+ import Vue from 'vue'; // → resolves to aliased-vue2
184
+
185
+ // In the host project
186
+ import Vue from 'vue'; // → resolves to vue (3.x)
187
+ ```
188
+
189
+ ### Behavioral Boundaries
190
+
191
+ - **Conflict Detection Scope**: Only the first-level `peerDependencies` of user-specified `dependencies` are checked for version conflicts against the host project. Sub-dependency `peerDependencies` still contribute to graph construction and runtime redirect matching, but do not independently trigger alias installation. First-level peers marked `optional: true` are skipped entirely: they produce no conflict, missing-peer warning, or alias.
192
+ - **Redirect Scope**: Packages that declare conflicting peers and all their sub-dependencies (`dependencies` + `peerDependencies` recursively) are added to the redirect candidate list. The conflict target packages themselves (e.g., `vue`, `vue-router`) are automatically excluded during collection to prevent host project imports from being incorrectly redirected.
193
+ - **Nested Versions**: The installed dependency graph is keyed by normalized package directories, and each child is resolved relative to its owning package. Nested instances with the same name but different versions remain distinct; generated redirect rules prefer importer-path matching. Consequently, `excludeRedirects` applies to concrete package instances and their subtrees rather than globally deduplicating by name.
194
+ - **`excludeRedirects`**: Removes specified packages from the redirect candidate list. Useful for shared packages (e.g., `vue-demi`, `pinia`) that actually use the host's Vue 3 version at runtime.
195
+ - **`includeRedirects`**: Forces specified packages into the redirect list. Useful when semver ranges are too broad (e.g., `vue: ">=2.5.0"` satisfies both Vue 2 and Vue 3) but the package still needs the older version at runtime. `includeRedirects` is applied before `excludeRedirects`.
196
+ - **Alias Installation and Reuse**: Aliases are only auto-installed for dependencies that are "declared by the host project with a version conflict." Undeclared peer dependencies only emit a warning without auto-installation. A matching installed local or workspace alias is reused without registry access or installation; a declared but uninstalled workspace alias is not reusable. If an existing alias directory has the wrong identity or version, the resolver reports a collision and leaves that directory unchanged rather than replacing it.
197
+ - **Registry**: An explicit `registry` value controls both remote version resolution and package-manager alias installation; automatic detection is used only when it is omitted.
198
+ - **Initialization Failure Policy**: `createResolver()` and the Vite plugin propagate initialization failures to the caller. The Webpack plugin remains fail-open: initialization or module-resolution errors are logged and compilation continues without aliases for that generation. Each Webpack `watchRun` invalidates the previous generation, waits for a fresh analysis, and can retry on the next watch cycle if initialization fails.
199
+
200
+ ## Advanced Usage
201
+
202
+ ### Hooks
203
+
204
+ ```typescript
205
+ depsConflictResolverVitePlugin({
206
+ dependencies: ['legacy-lib'],
207
+ hooks: {
208
+ // After analysis completes
209
+ onAnalysisComplete: (result) => {
210
+ console.log('Found conflicts:', result.peerConflicts);
211
+ },
212
+
213
+ // After the installation attempt completes
214
+ onInstallComplete: (mappings) => {
215
+ console.log('Alias mappings after install attempt:', mappings);
216
+ },
217
+
218
+ // Custom module resolution
219
+ beforeResolve: (source, importer) => {
220
+ // Return a new module name, or null to skip
221
+ if (source === 'special-module') {
222
+ return 'custom-alias';
223
+ }
224
+ return null;
225
+ },
226
+ },
227
+ });
228
+ ```
229
+
230
+ `onInstallComplete` runs after the installation attempt; its argument is the alias mappings produced by that analysis and does not guarantee that every mapping was installed successfully (reused, installed, and failed outcomes must be checked in logs or installation results).
231
+
232
+ ### Fine-Grained Redirect Control (includeRedirects + excludeRedirects)
233
+
234
+ When a project contains both Vue 2 and Vue 3 dependencies, auto-detection may not accurately distinguish them. Use these two options for manual control:
235
+
236
+ ```typescript
237
+ new DepsConflictResolverWebpackPlugin({
238
+ dependencies: ['@uikit/vue-finder', '@rili/ui'],
239
+
240
+ // Force these packages (broad semver range, but actually need Vue 2) into the redirect list
241
+ includeRedirects: {
242
+ vue: ['@rili/ui', '@kmt/meeting-setting'],
243
+ },
244
+
245
+ // Exclude these packages from the redirect list (they use the host's Vue 3 at runtime)
246
+ excludeRedirects: {
247
+ vue: ['vue-demi', 'pinia', '@ks-email/editor'],
248
+ },
249
+
250
+ aliasPrefix: 'never-ever-gonna-import-',
251
+ autoInstall: true,
252
+ });
253
+ ```
254
+
255
+ Priority: `includeRedirects` is applied first, then `excludeRedirects`. If the same package appears in both, `excludeRedirects` wins (not redirected).
256
+
257
+ ### Reusing Existing Aliases
258
+
259
+ If the project already has aliases installed with suitable versions (e.g., `vue2@npm:vue@2.6.14`), the plugin detects and reuses them before contacting the registry, without reinstalling. Workspace aliases are reusable only when actually installed and when package identity/version validation succeeds. A mismatched existing directory is reported as a collision and left unchanged.
260
+
261
+ ## API Reference
262
+
263
+ ### `createResolver(options): Promise<DepsConflictResolver>`
264
+
265
+ Creates and initializes a dependency resolver.
266
+
267
+ ### `DepsConflictResolver`
268
+
269
+ Main resolver class:
270
+
271
+ - `initialize(): Promise<void>` — Initialize the resolver
272
+ - `resolveModule(request, importer): string | null` — Resolve a module
273
+ - `getAnalysisResult(): AnalysisResult` — Get the analysis result
274
+ - `getAliasPathMappings(): AliasPathMapping[]` — Get generic alias path mappings
275
+
276
+ > The core module returns a generic `AliasPathMapping[]` format, which each build tool plugin (Webpack/Vite) converts to its own alias configuration format.
277
+
278
+ ### Utility Functions
279
+
280
+ To minimize the public API surface and improve tree-shaking, internal utility functions (semver, fs, npm registry, etc.) are no longer exported from the main entry point. For capabilities like version comparison, use the `semver` package directly.
281
+
282
+ ## Development
283
+
284
+ ```bash
285
+ # Install dependencies
286
+ pnpm install
287
+
288
+ # Development mode
289
+ pnpm dev
290
+
291
+ # Build
292
+ pnpm build
293
+
294
+ # Run tests
295
+ pnpm test
296
+
297
+ # Type checking
298
+ pnpm typecheck
299
+
300
+ # Lint
301
+ pnpm lint
302
+
303
+ # Format
304
+ pnpm fmt
305
+ ```
306
+
307
+ ## Release Process
308
+
309
+ This project uses [release-please](https://github.com/googleapis/release-please) for automated releases:
310
+
311
+ 1. Merge commits to `main` following [Conventional Commits](https://www.conventionalcommits.org/)
312
+ 2. release-please automatically creates/updates a Release PR with changelog
313
+ 3. Review and merge the Release PR
314
+ 4. A GitHub Release + tag is automatically created
315
+ 5. Manually run `npm publish` to publish to npm
316
+
317
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
318
+
319
+ ## License
320
+
321
+ MIT
package/README.md CHANGED
@@ -1,10 +1,16 @@
1
1
  # deps-conflict-resolver
2
2
 
3
+ [![npm version](https://img.shields.io/npm/v/deps-conflict-resolver.svg)](https://www.npmjs.com/package/deps-conflict-resolver)
4
+ [![CI](https://github.com/ben-lau/deps-conflict-resolver/actions/workflows/ci.yml/badge.svg)](https://github.com/ben-lau/deps-conflict-resolver/actions/workflows/ci.yml)
5
+ [![codecov](https://codecov.io/gh/ben-lau/deps-conflict-resolver/branch/main/graph/badge.svg)](https://codecov.io/gh/ben-lau/deps-conflict-resolver)
6
+
7
+ > [English Documentation](./README.en.md)
8
+
3
9
  一个支持 Webpack 和 Vite 的插件,自动解析 peer 依赖冲突,通过创建别名来支持不同版本的依赖共存。
4
10
 
5
11
  ## 功能特性
6
12
 
7
- - 🔍 **递归依赖分析**:深度分析依赖树中的所有子依赖、孙依赖
13
+ - 🔍 **递归依赖分析**:深度遍历依赖树中的所有子依赖、孙依赖,并按实际安装路径区分嵌套实例
8
14
  - 🎯 **智能冲突检测**:自动识别 peer 依赖与主工程的版本冲突
9
15
  - 📦 **自动别名安装**:为冲突的依赖创建别名并自动安装合适的版本
10
16
  - 🔄 **模块解析重定向**:在运行时自动将模块引用重定向到正确的别名版本
@@ -93,24 +99,24 @@ const resolved = resolver.resolveModule('vue', '/path/to/importer.js');
93
99
 
94
100
  ## 配置选项
95
101
 
96
- | 选项 | 类型 | 默认值 | 说明 |
97
- | ------------------- | ------------------------------------- | --------------- | ------------------------------------------------------------------------ |
98
- | `dependencies` | `string[]` | - | **必填**,需要分析的依赖包名列表 |
99
- | `projectRoot` | `string` | `process.cwd()` | 项目根目录路径 |
100
- | `autoInstall` | `boolean` | `true` | 是否自动安装缺失的别名依赖 |
101
- | `packageManager` | `'auto' \| 'npm' \| 'yarn' \| 'pnpm'` | `'auto'` | 包管理器类型,`'auto'` 自动检测 |
102
- | `registry` | `string` | 自动检测 | NPM 注册表地址,不指定则自动从 .npmrc 读取 |
103
- | `debug` | `boolean` | `false` | 是否启用调试日志 |
104
- | `aliasPrefix` | `string` | `'aliased-'` | 别名前缀 |
105
- | `excludeRedirects` | `Record<string, string[]>` | `{}` | 从重定向列表中排除特定包。键为原始包名,值为要排除的 importer 包名列表。示例:`{ vue: ['vue-demi', 'pinia'] }` |
106
- | `includeRedirects` | `Record<string, string[]>` | `{}` | 强制将指定包加入重定向列表,优先于 `excludeRedirects` 执行。适用于 semver 范围写得过宽(如 `>=2.5.0`)但运行时仍依赖旧版本的包。示例:`{ vue: ['@rili/ui', '@kmt/meeting-setting'] }` |
102
+ | 选项 | 类型 | 默认值 | 说明 |
103
+ | ------------------ | ------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
104
+ | `dependencies` | `string[]` | - | **必填**,需要分析的依赖包名列表 |
105
+ | `projectRoot` | `string` | `process.cwd()` | 项目根目录路径 |
106
+ | `autoInstall` | `boolean` | `true` | 是否自动安装缺失的别名依赖 |
107
+ | `packageManager` | `'auto' \| 'npm' \| 'yarn' \| 'pnpm'` | `'auto'` | 包管理器类型,`'auto'` 自动检测 |
108
+ | `registry` | `string` | 自动检测 | NPM 注册表地址;显式指定时同时用于版本查询和别名安装 |
109
+ | `debug` | `boolean` | `false` | 是否启用调试日志 |
110
+ | `aliasPrefix` | `string` | `'aliased-'` | 别名前缀 |
111
+ | `excludeRedirects` | `Record<string, string[]>` | `{}` | 从重定向列表中排除特定包。键为原始包名,值为要排除的 importer 包名列表。示例:`{ vue: ['vue-demi', 'pinia'] }` |
112
+ | `includeRedirects` | `Record<string, string[]>` | `{}` | 强制将指定包加入重定向列表,优先于 `excludeRedirects` 执行。适用于 semver 范围写得过宽(如 `>=2.5.0`)但运行时仍依赖旧版本的包。示例:`{ vue: ['@rili/ui', '@kmt/meeting-setting'] }` |
107
113
 
108
114
  ### Vite 插件专属选项
109
115
 
110
- | 选项 | 类型 | 默认值 | 说明 |
111
- | --------------- | --------- | ------- | -------------------------- |
112
- | `enableInDev` | `boolean` | `true` | 是否在开发模式(dev)下启用 |
113
- | `enableInBuild` | `boolean` | `true` | 是否在构建模式(build)下启用 |
116
+ | 选项 | 类型 | 默认值 | 说明 |
117
+ | --------------- | --------- | ------ | ----------------------------- |
118
+ | `enableInDev` | `boolean` | `true` | 是否在开发模式(dev)下启用 |
119
+ | `enableInBuild` | `boolean` | `true` | 是否在构建模式(build)下启用 |
114
120
 
115
121
  ### 自动检测
116
122
 
@@ -126,9 +132,11 @@ const resolved = resolver.resolveModule('vue', '/path/to/importer.js');
126
132
 
127
133
  1. 项目级 `.npmrc` 文件
128
134
  2. 用户级 `~/.npmrc` 文件
129
- 3. yarn 项目的 `.yarnrc.yml` 文件
135
+ 3. pnpm 的用户级 `.pnpmrc` 或 yarn 项目的 `.yarnrc.yml` 文件
130
136
  4. 默认使用 `https://registry.npmjs.org`
131
137
 
138
+ 显式设置 `registry` 时会覆盖上述自动检测结果:解析器从该地址查询可用版本,包管理器安装别名时也使用同一地址。
139
+
132
140
  ## 工作原理
133
141
 
134
142
  ### 1. 依赖分析
@@ -152,7 +160,7 @@ package-a
152
160
 
153
161
  ### 3. 版本解析
154
162
 
155
- 从 npm 注册表获取可用版本列表,找到满足所有 peer 依赖范围的最佳版本:
163
+ 先检查项目或 workspace 中已经安装、且包名和版本都匹配的 npm alias。可复用的 alias 会直接离线使用,不访问 registry,也不会重复安装;只有未匹配的请求才从 registry 获取版本列表,并找到满足所有 peer 依赖范围的最佳版本:
156
164
 
157
165
  - `vue@^2.0.0` → 选择 `vue@2.7.14`
158
166
  - `vue-router@^3.0.0` → 选择 `vue-router@3.6.5`
@@ -180,12 +188,14 @@ import Vue from 'vue'; // → 解析到 vue (3.x)
180
188
 
181
189
  ### 行为边界
182
190
 
183
- - **冲突检测范围**:只检测用户指定的 `dependencies` 的第一层 `peerDependencies` 与主工程的版本冲突。子依赖的 `peerDependencies` 不触发别名安装。
184
- - **重定向范围**:声明冲突 peer 的包及其所有子依赖(`dependencies` + `peerDependencies` 递归)都会被收入重定向候选列表。冲突包自身(如 `vue`、`vue-router`)在收集时会被自动排除,避免主工程的同名引用被错误重定向。
191
+ - **冲突检测范围**:只检测用户指定的 `dependencies` 的第一层 `peerDependencies` 与主工程的版本冲突。子依赖的 `peerDependencies` 会参与依赖图构建和运行时重定向判断,但不会单独触发别名安装。标记为 `optional: true` 的第一层 peer 会完全跳过,不产生冲突、missing 警告或 alias。
192
+ - **重定向范围**:冲突 peer 的声明包及其 `dependencies`/`peerDependencies` 会递归加入重定向候选列表;冲突目标包自身(如 `vue`、`vue-router`)会被排除,避免主工程引用被误重定向。
193
+ - **嵌套版本**:依赖图以规范化的实际安装目录为节点,并从所属包目录解析子依赖。同名但不同版本的嵌套实例会保留为不同节点,生成的重定向规则优先按 importer 路径匹配;因此 `excludeRedirects` 也会作用于具体实例及其子树,而不是简单按包名全局去重。
185
194
  - **`excludeRedirects`**:从重定向候选列表中剔除指定包,适用于运行时实际使用宿主 Vue 3 版本的共享包(如 `vue-demi`、`pinia`)。
186
195
  - **`includeRedirects`**:将指定包强制加入重定向列表,适用于 semver 范围写得过宽(如 `vue: ">=2.5.0"` 同时满足 Vue 2/3),但运行时仍需要使用旧版本的包。`includeRedirects` 在 `excludeRedirects` 之前应用。
187
- - **别名安装**:只为"主工程已声明且版本冲突"的依赖自动安装别名。未声明的 peer 依赖只会输出警告,不自动安装。
188
- - **依赖图去重**:依赖树遍历按包名去重(同名包只分析一次)。在极少数情况下,如同一包名存在多个不同版本的嵌套安装,只有第一个被解析到的版本会被分析。这对重定向结果的影响极小,因为重定向判断只基于包名匹配,不涉及版本。
196
+ - **别名安装与复用**:只为“主工程已声明且版本冲突”的依赖自动安装别名;未声明的 peer 依赖只输出警告,不自动安装。已安装且身份/版本匹配的 local 或 workspace alias 会复用(无需 registry 和安装);声明但尚未安装的 workspace alias 不算可复用。已有目录身份或版本不匹配时会报告 alias collision,并保持原目录不变,不原地覆盖。
197
+ - **Registry**:`registry` 显式配置同时约束远程版本查询和包管理器安装;未配置时才按项目/用户配置自动检测。
198
+ - **初始化失败策略**:核心 `createResolver()` 与 Vite 插件会把初始化错误交给调用方;Webpack 插件保持 fail-open,初始化或模块解析失败只记录错误并继续编译(该轮不会应用 alias)。Webpack watch 每次 `watchRun` 会先失效旧 generation,再等待新分析;新一轮失败时仍可在后续 watch 周期重试。
189
199
 
190
200
  ## 高级用法
191
201
 
@@ -196,13 +206,13 @@ depsConflictResolverVitePlugin({
196
206
  dependencies: ['legacy-lib'],
197
207
  hooks: {
198
208
  // 分析完成后
199
- onAnalysisComplete: result => {
209
+ onAnalysisComplete: (result) => {
200
210
  console.log('Found conflicts:', result.peerConflicts);
201
211
  },
202
212
 
203
- // 安装完成后
204
- onInstallComplete: installed => {
205
- console.log('Installed aliases:', installed);
213
+ // 安装尝试完成后
214
+ onInstallComplete: (mappings) => {
215
+ console.log('Alias mappings after install attempt:', mappings);
206
216
  },
207
217
 
208
218
  // 自定义模块解析
@@ -217,6 +227,8 @@ depsConflictResolverVitePlugin({
217
227
  });
218
228
  ```
219
229
 
230
+ `onInstallComplete` 在安装尝试结束后触发;其参数是本轮分析得到的 alias mappings,并不表示每个 mapping 都已成功安装(已复用、已安装和失败项需结合日志或安装结果判断)。
231
+
220
232
  ### 精细控制重定向范围(includeRedirects + excludeRedirects)
221
233
 
222
234
  当项目同时包含 Vue 2 依赖和 Vue 3 依赖时,自动检测可能无法准确区分。可以用这两个选项手动调节:
@@ -244,7 +256,7 @@ new DepsConflictResolverWebpackPlugin({
244
256
 
245
257
  ### 复用已有别名
246
258
 
247
- 如果项目中已经安装了合适版本的别名(如 `vue2@npm:vue@2.6.14`),插件会自动检测并复用,不会重复安装。
259
+ 如果项目中已经安装了合适版本的别名(如 `vue2@npm:vue@2.6.14`),插件会在访问 registry 前自动检测并复用,不会重复安装;workspace alias 只有在实际安装且包名/版本验证通过时才会复用。若现有目录不匹配,插件会报告冲突并保留原目录。
248
260
 
249
261
  ## API 参考
250
262
 
@@ -271,21 +283,39 @@ new DepsConflictResolverWebpackPlugin({
271
283
 
272
284
  ```bash
273
285
  # 安装依赖
274
- npm install
286
+ pnpm install
275
287
 
276
288
  # 开发模式
277
- npm run dev
289
+ pnpm dev
278
290
 
279
291
  # 构建
280
- npm run build
292
+ pnpm build
281
293
 
282
294
  # 运行测试
283
- npm test
295
+ pnpm test
284
296
 
285
297
  # 类型检查
286
- npm run typecheck
298
+ pnpm typecheck
299
+
300
+ # 代码检查
301
+ pnpm lint
302
+
303
+ # 代码格式化
304
+ pnpm fmt
287
305
  ```
288
306
 
307
+ ## 发布流程
308
+
309
+ 本项目使用 [release-please](https://github.com/googleapis/release-please) 自动化发版:
310
+
311
+ 1. 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范提交代码到 `main` 分支
312
+ 2. release-please 自动创建/更新 Release PR,包含版本号和 CHANGELOG
313
+ 3. 审核并合并 Release PR
314
+ 4. 自动创建 GitHub Release + tag
315
+ 5. 手动执行 `npm publish` 发布到 npm
316
+
317
+ 详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
318
+
289
319
  ## 许可证
290
320
 
291
321
  MIT
@@ -111,6 +111,12 @@ interface AliasMapping {
111
111
  * 注意:冲突包自身(如 vue、vue-router)已在收集时被排除,避免主工程引用被误重定向
112
112
  */
113
113
  allDependents: string[];
114
+ /**
115
+ * Normalized installed package directories whose importers use this alias.
116
+ * When present, runtime matching is scoped to these package instances and
117
+ * does not fall back to the legacy name-only `allDependents` rule.
118
+ */
119
+ importerPaths?: string[];
114
120
  }
115
121
  /**
116
122
  * 依赖分析结果
@@ -111,6 +111,12 @@ interface AliasMapping {
111
111
  * 注意:冲突包自身(如 vue、vue-router)已在收集时被排除,避免主工程引用被误重定向
112
112
  */
113
113
  allDependents: string[];
114
+ /**
115
+ * Normalized installed package directories whose importers use this alias.
116
+ * When present, runtime matching is scoped to these package instances and
117
+ * does not fall back to the legacy name-only `allDependents` rule.
118
+ */
119
+ importerPaths?: string[];
114
120
  }
115
121
  /**
116
122
  * 依赖分析结果