@mznjs/mbump 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@
 格式遵循 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)，
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [2.1.0] - 2026-07-04
+
+🚀 新增功能
+
+- feat(cli): 优化路径支持与命令行参数，新增更多路径格式和快捷参数 (README.md, index.ts, parser.ts)
+
+## [2.0.4] - 2026-07-04
+
+🚀 新增功能
+
+- feat(cli): 新增--version/-V参数用于显示版本信息 (index.ts, parser.ts, index.ts)
+
+## [2.0.4-beta.1] - 2026-07-04
+
+♻️ 代码重构
+
+- refactor(cli): 重构参数解析和配置加载逻辑 (index.ts)
+
+## [2.0.4-beta.0] - 2026-07-04
+
+🚀 新增功能
+
+- feat(cli): 新增路径模式支持，允许直接指定项目目录更新版本 (README.md, index.ts, parser.ts, index.ts)
+
+## [2.0.3] - 2026-07-04
+
+♻️ 代码重构
+
+- refactor(config,cli): 重构包路径处理逻辑，新增路径校验 (package.json, index.ts, loader.ts, VersionManager.ts, integration.test.ts)
+
 ## [2.0.2] - 2026-05-26
 
 🔧 工具变更

package/README.md

@@ -18,18 +18,45 @@
 - ✅ 智能配置加载（支持异步/同步）
 - ✅ 未提交更改检测与处理
 - ✅ 详细日志输出模式
+- ✅ **零配置启动** - 无需配置文件即可使用
 
 ## 📦 安装
 
+### 全局安装（推荐）
+
+适合在多个项目中使用，一次安装，全局可用：
+
 ```bash
 npm install -g @mznjs/mbump
 # 或
 pnpm add -g @mznjs/mbump
 ```
 
+**全局安装特性**：
+- ✅ 所有依赖（包括 `tsx`）已移至 `dependencies`，确保全局安装后正常工作
+- ✅ 支持 `.ts` 配置文件的自动编译
+- ✅ 可在任意项目目录下使用
+
+### 本地安装
+
+适合在单个项目中使用，作为开发依赖：
+
+```bash
+npm install @mznjs/mbump -D
+# 或
+pnpm add @mznjs/mbump -D
+```
+
+**本地安装特性**：
+- ✅ 项目级依赖，不影响全局环境
+- ✅ 可在 `package.json` 的 `scripts` 中使用
+- ✅ 推荐在 CI/CD 流程中使用
+
 ## 🚀 快速开始
 
-### 单包项目
+### 单包项目（零配置）
+
+无需任何配置文件，mbump 会自动使用默认配置 `{ default: 'package.json' }`：
 
 ```bash
 # 升级补丁版本
@@ -45,9 +72,59 @@ mbump major
 mbump
 ```
 
+**零配置行为**：
+- ✅ 自动识别当前目录的 `package.json`
+- ✅ 使用 `default` 作为包名
+- ✅ 创建 Git Tag：`v{version}`（如 `v1.0.1`）
+- ✅ 生成 CHANGELOG.md
+
+### 路径模式（直接指定项目目录）
+
+无需配置文件，直接指定项目目录路径，mbump 会自动查找该目录下的 `package.json`：
+
+```bash
+# 更新指定目录下的 package.json（默认 patch）
+mbump ./packages/my-pkg
+
+# 指定版本类型
+mbump ./packages/my-pkg patch
+mbump ./packages/my-pkg minor
+mbump ./packages/my-pkg major
+
+# 使用上级目录
+mbump ../other-project
+
+# 使用绝对路径
+mbump /path/to/project
+mbump C:\projects\my-app
+```
+
+**支持的路径格式**：
+
+| 格式类型 | 示例 | 说明 |
+|----------|------|------|
+| Unix 相对路径 | `./packages/theme` | 以 `./` 开头 |
+| Windows 相对路径 | `.\frontend` | 以 `.\` 开头 |
+| 当前目录 | `.` | 单个点 |
+| 上级目录 | `../other-project` | 以 `../` 或 `..\` 开头 |
+| 简单目录名 | `frontend` | 直接使用目录名（会自动检测） |
+| Unix 绝对路径 | `/usr/local/project` | 以 `/` 开头 |
+| Windows 绝对路径 | `\Windows\System32` | 以 `\` 开头 |
+| Windows 驱动器 | `C:\Projects\app` | 驱动器字母 + `:\` |
+| 用户主目录 | `~/projects/my-app` | 以 `~` 开头 |
+| UNC 网络路径 | `\\server\share\project` | 以 `\\` 开头 |
+
+**路径模式特性**：
+- ✅ 支持多种路径格式（相对路径、绝对路径、驱动器路径、UNC 路径等）
+- ✅ 自动检测路径下是否存在 `package.json`
+- ✅ 使用默认配置 `{ default: 'package.json' }`
+- ✅ 支持所有命令行选项（`--dry-run`, `--verbose`, `--npm` 等）
+- ✅ 适合快速更新独立的子包或临时项目
+- ✅ 智能回退：如果包名在配置中找不到，会自动检查是否为有效目录路径
+
 ### Monorepo 项目
 
-创建配置文件 `.mbump.config.json`:
+创建配置文件 `.mbump.config.json`（或其他支持的格式）：
 
 ```json
 {
@@ -59,6 +136,11 @@ mbump
 }
 ```
 
+**重要特性**：
+- ✅ **默认包始终保留**：即使配置了 `packagePaths`，`default` 键（指向根目录 `package.json`）仍然会被保留
+- ✅ **路径解析基准**：相对路径相对于配置文件所在目录解析，而非当前工作目录
+- ✅ **统一路径处理**：配置中的路径在加载时会自动解析为绝对路径
+
 ```bash
 # 更新所有包（交互式选择每个包的版本）
 mbump all
@@ -66,6 +148,9 @@ mbump all
 # 更新指定包
 mbump components minor
 
+# 更新根目录包
+mbump default patch
+
 # 试运行模式（不实际执行）
 mbump components minor --dry-run
 
@@ -76,10 +161,11 @@ mbump components patch --npm
 ## 💻 命令行参数
 
 ```
-用法: mbump [package] [type] [options]
+用法: mbump [package|path] [type] [options]
 
 参数:
   [package]      要更新的包名称或 "all" 更新所有包
+  [path]         项目目录路径（支持 ./path, ../path, /path, C:\path），自动查找该目录下的 package.json
   [type]         版本升级类型: major, minor, patch, pre-patch, pre-minor, pre-major
 
 选项:
@@ -88,8 +174,9 @@ mbump components patch --npm
   --no-commit, -n        禁用自动git提交
   --no-push, -p          禁用自动推送到远程仓库
   --allow-uncommitted, -u  允许在有未提交更改的情况下继续操作
-  --npm                  启用npm/pnpm包发布功能（默认不发布）
-  --show-config          显示当前加载的完整配置信息
+  --npm, -N              启用npm/pnpm包发布功能（默认不发布）
+  --show-config, -c      显示当前加载的完整配置信息
+  --version, -V          显示当前版本号
   --help, -h             显示此帮助信息
 
 示例:
@@ -100,6 +187,17 @@ mbump components patch --npm
   mbump components patch --npm        # 更新版本并发布到npm/pnpm
   mbump                               # 交互式选择包和版本类型
   mbump --show-config                 # 查看当前配置
+  mbump --version                     # 查看当前版本号
+
+  # 路径模式
+  mbump ./packages/my-pkg             # 更新 ./packages/my-pkg 目录下的 package.json
+  mbump ./packages/my-pkg patch       # 指定版本类型
+  mbump ../other-project minor        # 更新上级目录的项目
+  mbump /path/to/project major        # 使用绝对路径
+  mbump ./packages/my-pkg --dry-run   # 试运行模式
+  mbump .\frontend\                   # Windows 风格路径（PowerShell）
+  mbump frontend                      # 直接使用目录名（自动检测）
+  mbump ~/projects/my-app             # 使用用户主目录路径
 ```
 
 ## ⚙️ 配置文件
@@ -286,7 +384,35 @@ export default () => ({
 
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `packagePaths` | `Record<string, string>` | `{ default: 'package.json' }` | 包路径映射（必需） |
+| `packagePaths` | `Record<string, string>` | `{ default: 'package.json' }` | 包路径映射，相对路径相对于配置文件所在目录解析 |
+
+**packagePaths 配置说明**：
+
+1. **默认配置**：即使不配置 `packagePaths`，系统也会自动使用 `{ default: 'package.json' }`
+2. **默认包保留**：用户配置 `packagePaths` 时，`default` 键始终会被保留，指向根目录的 `package.json`
+3. **路径解析基准**：相对路径相对于配置文件所在目录解析，而非 `process.cwd()`
+4. **示例**：
+   ```typescript
+   // .mbump.config.ts（位于项目根目录）
+   export default {
+     packagePaths: {
+       theme: 'packages/theme/package.json',      // 解析为 /project/packages/theme/package.json
+       web: 'packages/web/package.json',          // 解析为 /project/packages/web/package.json
+       utils: 'plugins/utils/package.json',       // 解析为 /project/plugins/utils/package.json
+       core: 'plugins/core/package.json',         // 解析为 /project/plugins/core/package.json
+     },
+   } satisfies Config
+   ```
+   最终合并后的配置会包含：
+   ```typescript
+   {
+     default: '/project/package.json',           // 自动保留
+     theme: '/project/packages/theme/package.json',
+     web: '/project/packages/web/package.json',
+     utils: '/project/plugins/utils/package.json',
+     core: '/project/plugins/core/package.json',
+   }
+   ```
 
 #### defaults 选项
 
@@ -317,12 +443,12 @@ mbump 根据包的类型采用不同的 Tag 命名策略：
 - **Tag 格式**: `{tagPrefix}{version}`
 - **使用前缀**: 是（默认 `v`）
 - **识别条件**: 包名为 `default` 或包路径为 `package.json`（根目录）
-- **示例**: 
+- **示例**:
   ```bash
   mbump default patch
   # 假设 package.json 中 "name": "@my-org/monorepo"
   # → 创建 Tag: v1.0.1
-  
+
   # 自定义前缀
   mbump default minor
   # 如果配置 git.tagPrefix = "release-"
@@ -332,7 +458,7 @@ mbump 根据包的类型采用不同的 Tag 命名策略：
 #### 子包 (所有非主项目包)
 - **Tag 格式**: `{package-name}@{version}`
 - **不使用前缀**: 直接使用 package.json 中的 `name` 字段
-- **适用场景**: 
+- **适用场景**:
   - 单独更新子包：`mbump components patch`
   - 批量更新所有包：`mbump all`
 - **示例**:
@@ -340,7 +466,7 @@ mbump 根据包的类型采用不同的 Tag 命名策略：
   mbump components patch
   # 假设 components/package.json 中 "name": "@my-org/components"
   # → 创建 Tag: @my-org/components@1.0.1
-  
+
   mbump cli minor
   # 假设 cli/package.json 中 "name": "@my-org/cli"
   # → 创建 Tag: @my-org/cli@2.3.0
@@ -420,6 +546,15 @@ mbump components patch --changelog
 
 #### 单包项目
 
+无需配置文件，直接使用默认配置：
+
+```bash
+# 直接使用，自动识别当前目录的 package.json
+mbump patch
+```
+
+如果需要自定义配置：
+
 ```json
 {
   "packagePaths": {
@@ -768,6 +903,23 @@ mbump 提供了友好的错误提示信息，帮助用户快速理解和解决
 - 检查 `.mbump.config.js` 中的 `packagePaths` 配置
 - 确保包名与配置中的 key 一致
 
+#### 8. 包路径不存在
+
+**错误信息**：
+```
+配置错误：以下包路径指向的文件不存在
+  - components: "packages/components/package.json" -> 解析为 "/path/to/project/packages/components/package.json"（文件不存在）
+
+请检查配置文件中的 packagePaths 是否正确
+```
+
+**原因**：配置文件中指定的 package.json 文件不存在
+
+**解决方案**：
+- 检查路径是否正确
+- 确保文件已创建
+- 相对路径是相对于配置文件所在目录解析的
+
 ### 调试模式
 
 如果遇到未知错误，可以使用 `DEBUG` 环境变量查看详细信息：
@@ -1047,7 +1199,6 @@ setInterval(() => {
 // CI/CD 环境中可以禁用缓存（每次都是全新环境）
 const manager = new VersionManager({
   rootDir,
-  // 未来可以添加配置选项
 })
 ```
 
@@ -1172,7 +1323,6 @@ pnpm test:watch
 beforeEach(() => {
   tempDir = join(os.tmpdir(), `mbump-test-${Date.now()}`)
   mkdirSync(tempDir, { recursive: true })
-  // 初始化 Git 仓库...
 })
 
 afterEach(() => {
@@ -1191,78 +1341,12 @@ afterEach(() => {
 #### 3. 真实场景
 使用真实的 Git 命令和文件系统操作：
 ```typescript
-// 初始化 Git 仓库
 execSync('git init', { cwd: tempDir })
 execSync('git config user.email "test@example.com"', { cwd: tempDir })
-
-// 创建 commits
 execSync('git add . && git commit -m "feat: feature"', { cwd: tempDir })
-
-// 验证 Git Tag
 const tags = execSync('git tag', { cwd: tempDir, encoding: 'utf8' })
 ```
 
-### 测试示例
-
-#### 单包更新测试
-```typescript
-it('应该成功更新单个包的版本号', async () => {
-  createPackageFile('test-package', '1.0.0')
-  createConfigFile({ default: 'package.json' })
-  createInitialCommit()
-
-  const manager = new VersionManager({ rootDir: tempDir })
-  const result = await manager.updateVersion('default', 'minor', {
-    dryRun: false,
-    autoCommit: true,
-    npm: false,
-    changelog: false,
-  })
-
-  expect(result.success).toBe(true)
-  expect(result.updatedPackages[0].newVersion).toBe('1.1.0')
-  
-  const pkgContent = JSON.parse(readFileSync(join(tempDir, 'package.json'), 'utf8'))
-  expect(pkgContent.version).toBe('1.1.0')
-})
-```
-
-#### Git Tag 测试
-```typescript
-it('应该在版本更新后创建 Git Tag', async () => {
-  createPackageFile('test-package', '1.0.0')
-  createConfigFile({ default: 'package.json' })
-  createInitialCommit()
-
-  const manager = new VersionManager({ rootDir: tempDir })
-  await manager.updateVersion('default', 'minor', {
-    dryRun: false,
-    autoCommit: true,
-    npm: false,
-    changelog: false,
-    tag: true,
-  })
-
-  const tags = execSync('git tag', { cwd: tempDir, encoding: 'utf8' }).trim().split('\n')
-  expect(tags).toContain('v1.1.0')
-})
-```
-
-#### 缓存机制测试
-```typescript
-it('应该预加载包信息到缓存', () => {
-  createPackageFile('test-package', '1.0.0')
-  createConfigFile({ default: 'package.json' })
-  createInitialCommit()
-
-  const manager = new VersionManager({ rootDir: tempDir })
-  const stats = manager.getCacheStats()
-  
-  expect(stats.size).toBeGreaterThan(0)
-  expect(stats.packages).toContain(join(tempDir, 'package.json'))
-})
-```
-
 ### 持续集成
 
 测试已集成到 CI/CD 流程中，每次提交都会自动运行：
@@ -1290,155 +1374,6 @@ it('应该预加载包信息到缓存', () => {
 - **conventional**: 根据 commits 自动生成版本类型
 - **as-is**: 保持当前版本不变（仅更新 CHANGELOG）
 
-## 🧪 测试
-
-mbump 拥有完善的测试体系，包括单元测试和集成测试，确保代码质量和功能稳定性。
-
-### 测试覆盖范围
-
-#### 单元测试 (Unit Tests)
-- ✅ **版本计算**：验证 semver 版本递增逻辑
-- ✅ **安全检查**：验证路径遍历防护、命令注入防护
-- ✅ **工具函数**：验证各种辅助函数的正确性
-
-#### 集成测试 (Integration Tests)
-- ✅ **单包版本更新**：验证单个包的版本号更新流程
-- ✅ **批量版本更新**：验证多个包同时更新的场景
-- ✅ **CHANGELOG 生成**：验证 CHANGELOG.md 文件的创建和内容
-- ✅ **Git Tag 管理**：验证 Git 标签的创建、前缀配置等
-- ✅ **Dry-run 模式**：验证试运行模式不修改文件
-- ✅ **缓存机制**：验证配置缓存和包信息缓存
-- ✅ **错误处理**：验证无效包名、版本冲突等异常场景
-
-### 运行测试
-
-```bash
-# 运行所有测试
-pnpm test
-
-# 运行特定测试文件
-pnpm test tests/integration.test.ts
-
-# 监听模式（开发时使用）
-pnpm test:watch
-```
-
-### 测试统计
-
-| 测试类型 | 测试文件数 | 测试用例数 | 通过率 |
-|---------|-----------|-----------|--------|
-| 单元测试 | 2 | 12 | 100% ✅ |
-| 集成测试 | 1 | 16 | 100% ✅ |
-| **总计** | **3** | **28** | **100%** ✅ |
-
-### 集成测试特点
-
-#### 1. 隔离环境
-每个测试在临时目录中执行，避免污染真实项目：
-```typescript
-beforeEach(() => {
-  tempDir = join(os.tmpdir(), `mbump-test-${Date.now()}`)
-  mkdirSync(tempDir, { recursive: true })
-  // 初始化 Git 仓库...
-})
-
-afterEach(() => {
-  rmSync(tempDir, { recursive: true, force: true })
-})
-```
-
-#### 2. 完整工作流
-测试完整的版本更新流程：
-- 创建临时 Git 仓库
-- 创建 package.json 和配置文件
-- 执行版本更新
-- 验证结果（版本号、Git Tag、CHANGELOG）
-- 清理临时文件
-
-#### 3. 真实场景
-使用真实的 Git 命令和文件系统操作：
-```typescript
-// 初始化 Git 仓库
-execSync('git init', { cwd: tempDir })
-execSync('git config user.email "test@example.com"', { cwd: tempDir })
-
-// 创建 commits
-execSync('git add . && git commit -m "feat: feature"', { cwd: tempDir })
-
-// 验证 Git Tag
-const tags = execSync('git tag', { cwd: tempDir, encoding: 'utf8' })
-```
-
-### 测试示例
-
-#### 单包更新测试
-```typescript
-it('应该成功更新单个包的版本号', async () => {
-  createPackageFile('test-package', '1.0.0')
-  createConfigFile({ default: 'package.json' })
-  createInitialCommit()
-
-  const manager = new VersionManager({ rootDir: tempDir })
-  const result = await manager.updateVersion('default', 'minor', {
-    dryRun: false,
-    autoCommit: true,
-    npm: false,
-    changelog: false,
-  })
-
-  expect(result.success).toBe(true)
-  expect(result.updatedPackages[0].newVersion).toBe('1.1.0')
-  
-  const pkgContent = JSON.parse(readFileSync(join(tempDir, 'package.json'), 'utf8'))
-  expect(pkgContent.version).toBe('1.1.0')
-})
-```
-
-#### Git Tag 测试
-```typescript
-it('应该在版本更新后创建 Git Tag', async () => {
-  createPackageFile('test-package', '1.0.0')
-  createConfigFile({ default: 'package.json' })
-  createInitialCommit()
-
-  const manager = new VersionManager({ rootDir: tempDir })
-  await manager.updateVersion('default', 'minor', {
-    dryRun: false,
-    autoCommit: true,
-    npm: false,
-    changelog: false,
-    tag: true,
-  })
-
-  const tags = execSync('git tag', { cwd: tempDir, encoding: 'utf8' }).trim().split('\n')
-  expect(tags).toContain('v1.1.0')
-})
-```
-
-#### 缓存机制测试
-```typescript
-it('应该预加载包信息到缓存', () => {
-  createPackageFile('test-package', '1.0.0')
-  createConfigFile({ default: 'package.json' })
-  createInitialCommit()
-
-  const manager = new VersionManager({ rootDir: tempDir })
-  const stats = manager.getCacheStats()
-  
-  expect(stats.size).toBeGreaterThan(0)
-  expect(stats.packages).toContain(join(tempDir, 'package.json'))
-})
-```
-
-### 持续集成
-
-测试已集成到 CI/CD 流程中，每次提交都会自动运行：
-- ✅ 代码构建
-- ✅ 类型检查
-- ✅ ESLint 检查
-- ✅ 单元测试
-- ✅ 集成测试
-
 ## 🎯 使用场景
 
 ### 场景 1: 日常开发
@@ -1478,7 +1413,23 @@ mbump all patch
 mbump all minor --dry-run
 ```
 
-### 场景 4: CI/CD 自动化
+### 场景 4: 路径模式（快速更新独立子包）
+
+```bash
+# 快速更新指定目录下的 package.json
+mbump ./packages/my-pkg
+
+# 指定版本类型
+mbump ./packages/my-pkg minor
+
+# 更新上级目录的项目
+mbump ../other-project
+
+# 试运行模式
+mbump ./packages/my-pkg --dry-run
+```
+
+### 场景 5: CI/CD 自动化
 
 ```bash
 # 在 CI 环境中自动发布
@@ -1509,10 +1460,11 @@ mbump --show-config
   配置文件: .mbump.config.mjs
 
 📦 包路径:
-  components: package.json
-  cli: packages/cli/package.json
+  default: /path/to/project/package.json
+  components: /path/to/project/packages/components/package.json
+  cli: /path/to/project/packages/cli/package.json
 
-⚙️  默认选项:
+⚙️ 默认选项:
   releaseType: patch
   dryRun: false
   verbose: false
@@ -1699,17 +1651,20 @@ git push --tags
 
 1. **Git 要求**: 确保项目在 Git 仓库中，且已配置用户信息
 2. **未提交更改**: 默认情况下，存在未提交更改时会提示确认
-3. **配置文件**: 至少需要配置 `packagePaths`，其他选项可使用默认值
-4. **Node 版本**: 需要 Node.js >= 18.0.0
-5. **包管理器**: 默认使用 pnpm 发布，可在配置中修改为 npm 或 yarn
-6. **TypeScript 配置**: `.ts` 格式需要安装 `tsx` 依赖
-7. **ES Module**: `.mjs` 格式仅支持异步加载
+3. **零配置支持**: 无需配置文件即可使用，系统自动使用默认配置 `{ default: 'package.json' }`
+4. **路径模式**: 支持 `mbump ./path` 模式，自动查找指定目录下的 `package.json`，适合快速更新独立子包
+5. **Node 版本**: 需要 Node.js >= 18.0.0
+6. **包管理器**: 默认使用 pnpm 发布，可在配置中修改为 npm 或 yarn
+7. **路径解析**: 相对路径相对于配置文件所在目录解析，而非当前工作目录
+8. **默认包保留**: `default` 键始终指向根目录的 `package.json`，即使配置了其他包路径
+9. **全局安装**: 支持 `npm install -g @mznjs/mbump`，所有依赖已移至 `dependencies` 确保全局安装后可用
+10. **配置文件格式**: 支持 `.ts`/`.mjs`/`.js`/`.cjs`/`.json`/`.yaml`/`.yml`/`.toml` 多种格式
+11. **配置文件优先级**: 按以下顺序查找：`.ts` → `.mjs` → `.js` → `.cjs` → `.json` → `.yaml` → `.yml` → `.toml` → `package.json`
 
 ## 📚 更多资源
 
 - [配置示例](./config-examples/) - 各种格式的配置文件示例
 - [CHANGELOG](./CHANGELOG.md) - 版本更新历史
-- [GitHub Issues](https://github.com/mznjs/mbump/issues) - 问题反馈
 
 ## 🤝 贡献指南
 
@@ -1746,5 +1701,3 @@ MIT License
 ---
 
 **mbump** - 让版本管理更简单！🚀
-
-```