monox

v0.4.12

Published

4 months ago

Lightweight monorepo build tool written in Rust

MonoX

🚀 基于 Rust 的轻量级 monorepo 构建工具

MonoX 是一个专为 monorepo 项目设计的智能构建工具，通过依赖关系分析和任务调度优化，帮助您高效管理多包项目的构建过程。

✨ 核心特性

🔍 智能依赖分析 - 自动解析包依赖关系，构建有向无环图
📦 单包分析 - 支持分析指定包及其依赖链，精确定位构建范围
📦 多包操作 - 支持同时操作多个指定包
⚡ 并发任务执行 - 同阶段包并发构建，最大化 CPU 利用率
🛡️ 安全性检查 - 循环依赖检测、版本冲突检查、过期依赖扫描
📊 实时进度显示 - 美观的进度条和任务状态展示
🌍 完整国际化支持 - 中文/英文双语界面，动态语言切换
🎯 灵活配置 - 通过 monox.toml 自定义任务和执行策略
🔧 多包管理器支持 - 支持 pnpm、npm、yarn
🎨 智能用户界面 - 非verbose模式实时刷新UI，verbose模式详细日志
⚙️ 高级执行控制 - 超时控制、错误处理、并发限制

🚀 快速开始

安装

# 从 npm 安装（推荐）
npm install -g monox
# 或者
pnpm add -g monox
# 或者
yarn global add monox

# 从源码构建（需要 Rust 环境）
git clone https://github.com/monoxon/monox.git
cd monox
cargo build --release

# 将可执行文件添加到 PATH
cp target/release/monox /usr/local/bin/

初始化配置

在您的 monorepo 项目根目录运行：

monox init

这将创建一个 monox.toml 配置文件。

基本使用

analyze - 依赖分析

# 分析项目依赖关系和构建阶段
monox analyze

# 分析指定包及其依赖链（单包分析）
monox analyze --package @your-org/package-name

# 查看单包的详细依赖信息
monox analyze --package @your-org/package-name --detail --verbose

# JSON 格式输出
monox analyze --format json

run - 执行任务

# 构建所有包（按依赖顺序）
monox run --all --command build

# 运行指定包及其依赖
monox run @your-org/package-name --command build

# 运行多个指定包（多包执行）
monox run --packages "@your-org/pkg1,@your-org/pkg2,@your-org/pkg3" --command build

# 详细模式显示执行过程
monox run --all --command build --verbose

exec - 执行预定义任务

# 执行预定义任务
monox exec build-all

# 执行配置文件中定义的多包任务
monox exec build-frontend

# 详细模式
monox exec test-all --verbose

check - 健康检查

# 检查项目健康状态
monox check --circular --versions --outdated

# 详细的循环依赖路径信息
monox check --circular --detail --verbose

# JSON 格式输出检查结果
monox check --versions --format json

fix - 问题修复

# 同步项目依赖至项目使用最高版本
monox fix

# 预演模式（不实际修改）
monox fix --dry-run

update - 依赖更新

# 更新所有包的依赖版本（仅更新 package.json）
monox update --all

# 更新指定包的依赖版本
monox update --package @your-org/package-name

# 仅执行安全更新
monox update --all --security

# 预演模式，显示待更新内容
monox update --all --dry-run

# 更新到最新版本（忽略 semver 约束）
monox update --all --latest

# 包含开发依赖和对等依赖
monox update --all --dev --peer

# 跳过确认提示
monox update --all --yes

# JSON 格式输出
monox update --all --format json

# 注意: update 命令仅更新 package.json 中的版本号
# 需要手动运行包管理器安装命令来下载依赖

📋 命令参考

全局选项

-v, --verbose           显示详细执行过程
--no-color              禁用彩色输出
--no-progress           禁用进度显示
-j, --max-concurrency   设置最大并发数
--timeout               设置任务超时时间（秒）
--retry                 设置重试次数
--continue-on-failure   失败时继续执行
-C, --workspace-root    指定工作区根目录
-l, --language          设置界面语言 (en_us, zh_cn)

主要命令

`analyze` - 依赖分析

monox analyze                              # 分析并显示构建阶段
monox analyze --format json               # 输出 JSON 格式
monox analyze --verbose                    # 显示详细依赖关系
monox analyze --package <package-name>    # 分析指定单个包及其依赖链
monox analyze --package <package-name> --detail  # 单包分析显示详细信息
monox analyze --packages "pkg1,pkg2,pkg3" # 分析多个指定包及其依赖关系

`run` - 执行命令

monox run <package> --command <cmd>         # 运行指定包的命令
monox run --all --command <cmd>             # 运行所有包的命令
monox run --packages "pkg1,pkg2" --command <cmd>  # 运行多个指定包的命令
monox run --all --command build -v          # 详细模式显示执行过程

`exec` - 执行预定义任务

monox exec <task-name>           # 执行 monox.toml 中定义的任务
monox exec build-all --verbose   # 详细模式执行任务

`check` - 健康检查

monox check --circular           # 检查循环依赖
monox check --versions           # 检查版本冲突
monox check --outdated           # 检查过期依赖
monox check --circular --detail  # 显示详细循环路径

`fix` - 问题修复

monox fix --versions             # 修复版本不一致
monox fix --dry-run             # 预演模式，不实际修改

`update` - 依赖更新

# 更新所有包的依赖版本号（仅更新 package.json）
monox update --all

# 更新指定包的依赖版本号
monox update --package @your-org/package-name

# 仅执行安全更新
monox update --all --security

# 预演模式，显示待更新内容
monox update --all --dry-run

# 更新到最新版本（忽略 semver 约束）
monox update --all --latest

# 包含开发依赖和对等依赖
monox update --all --dev --peer

# 跳过确认提示
monox update --all --yes

# JSON 格式输出
monox update --all --format json

# 注意: 仅更新 package.json 版本号，需手动安装依赖

`init` - 初始化

monox init                      # 初始化配置文件

⚙️ 配置文件

monox.toml 配置示例

[workspace]
root = "."
package_manager = "pnpm"  # pnpm | npm | yarn
ignore = [                # 排除扫描的目录或文件模式
    "dist",
    "build",
    ".git",
    "*.tmp"
]

# 预定义任务
[[tasks]]
name = "build-all"
pkg_name = "*"
desc = "构建所有包"
command = "build"

[[tasks]]
name = "test-system"
pkg_name = "@your-org/system"
desc = "测试系统核心包"
command = "test"

# 多包任务示例
[[tasks]]
name = "build-frontend"
desc = "构建所有前端相关包"
command = "build"
packages = ["@your-org/web-ui", "@your-org/mobile-app", "@your-org/shared-components"]

[[tasks]]
name = "test-backend"
desc = "测试后端服务"
command = "test"
packages = ["@your-org/api-server", "@your-org/auth-service", "@your-org/database-lib"]

# 执行配置
[execution]
max_concurrency = 4        # 最大并发数
task_timeout = 300         # 任务超时（秒）
retry_count = 0            # 重试次数
continue_on_failure = false # 失败时是否继续

# 输出配置
[output]
show_progress = true       # 显示进度条
verbose = false           # 详细输出
colored = true            # 彩色输出

# 国际化配置
[i18n]
language = "zh_cn"        # 界面语言 (en_us, zh_cn)

配置参数说明

[workspace] - 工作空间

root: 工作目录根路径，默认 "."
package_manager: 包管理器类型，支持 "pnpm"、"npm"、"yarn"
ignore: 排除扫描的目录或文件模式，支持 glob 通配符。注意：node_modules 目录始终被排除，无需配置

[[tasks]] - 任务定义

name: 任务名称，用于 monox exec <name>
pkg_name: 包名，"*" 表示所有包（可选，可用 packages 替代）
packages: 包名数组，用于多包操作（可选，替代 pkg_name）
desc: 任务描述（可选）
command: 执行的命令

注意：每个任务必须指定 pkg_name 或 packages 字段之一。

[execution] - 执行控制

max_concurrency: 最大并发任务数，默认为 CPU 核心数
task_timeout: 单个任务超时时间（秒），默认 300
retry_count: 失败重试次数，默认 0
continue_on_failure: 失败时是否继续，默认 false

[output] - 输出控制

show_progress: 是否显示进度条，默认 true
verbose: 是否详细输出，默认 false
colored: 是否彩色输出，默认 true

[i18n] - 国际化

language: 界面语言，支持 "en_us"（英语）和 "zh_cn"（简体中文）

🌍 国际化支持

MonoX 提供完整的双语支持，所有用户界面文本都已国际化：

语言选择优先级

命令行参数 --language 或 -l
配置文件 monox.toml 中的设置
系统默认（英语）

使用示例

# 使用中文界面
monox analyze -l zh_cn

# 使用英文界面
monox run --all --command build --language en_us

支持的语言

zh_cn: 简体中文 - 完整本地化支持
en_us: 美式英语 - 标准英文界面

📦 单包分析功能

MonoX 支持对指定包进行精确的依赖分析，这在大型 monorepo 项目中特别有用：

功能特点

精确范围：只分析目标包及其直接依赖链，不包含无关包
构建优化：显示构建目标包所需的最小依赖集合
快速诊断：快速了解特定包的依赖状况
多格式输出：支持表格和 JSON 格式输出

使用示例

# 基本单包分析
monox analyze --package @your-org/components

# 输出示例：
# ◇ 分析结果
# ● 总包数: 1
# ▪ 构建阶段数: 3
# ◦ 有工作区依赖的包: 1
#
# ▪ 构建阶段
# ─────────────────────────
# 阶段 1 (1 个包):
#   ● @your-org/utils
#
# 阶段 2 (1 个包):
#   ● @your-org/core
#
# 阶段 3 (1 个包):
#   ● @your-org/components

# 详细信息模式
monox analyze --package @your-org/components --detail

# JSON 格式输出（便于脚本处理）
monox analyze --package @your-org/components --format json

🎨 用户界面特性

两种输出模式

刷新模式（默认）

实时更新的进度条和状态显示
动态 Spinner 动画
多包并行执行状态追踪
完成后保留满进度条显示

[MONOX] ⠧ ████████████░░░░░░░░ 阶段 3/5
[MONOX] 正在处理包: (2/5)
[MONOX]   ○ package-a
[MONOX]   ▸ package-b    ← 正在运行  
[MONOX]   ○ package-c
[MONOX]   ● package-d    ← 已完成
[MONOX]   ○ package-e

详细模式（--verbose）

完整的执行日志输出
每个任务的开始/完成时间
详细的错误信息和堆栈
性能统计信息

[MONOX] ▪ 开始任务: build 在 @your-org/utils
[MONOX] ● 任务 build 在 @your-org/utils 中完成，耗时 1250ms
[MONOX] ▪ 开始任务: build 在 @your-org/core

国际化界面

所有提示信息支持中英文
数字和时间格式本地化
错误信息完整翻译

📊 使用场景

典型工作流

项目初始化

monox init
# 编辑 monox.toml 配置文件

依赖分析

# 分析整个工作区
monox analyze --verbose

# 分析特定包及其依赖链
monox analyze --package @your-org/core --detail

健康检查

monox check --circular --versions --outdated
# 确保项目状态良好

构建执行

monox run --all --command build --verbose
# 按依赖顺序构建所有包

测试运行

monox exec test-all
# 执行预定义的测试任务

单包分析和调试

# 分析特定包的依赖关系
monox analyze --package @your-org/core

# 查看单包的详细依赖信息
monox analyze --package @your-org/core --detail --verbose

# 以 JSON 格式输出单包分析结果
monox analyze --package @your-org/core --format json

# 分析多个包（分别执行）
monox analyze --package @your-org/utils
monox analyze --package @your-org/components

调试和诊断

# 详细模式：查看构建过程和进度
monox run --all --command build --verbose

# 组合使用：最完整的信息输出
monox analyze --verbose --detail

🔧 技术特性

核心引擎

依赖分析器: 基于 petgraph 的图算法，支持循环检测和拓扑排序
任务执行器: 异步并发执行，智能调度和资源管理
缓存系统: 智能缓存提升重复操作性能

用户体验

智能UI: 非详细模式下动态刷新界面，详细模式下完整日志输出
进度追踪: 实时进度条、任务状态、执行时间统计
错误处理: 友好的错误信息、国际化错误消息、失败重试机制

架构设计

模块化: 清晰的模块边界和职责分离
类型安全: 充分利用 Rust 类型系统保证安全性
异步优先: 基于 tokio 的高性能异步运行时

🤝 贡献

欢迎贡献代码！请查看 CONTRIBUTING.md 了解开发指南。

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

📦 多包操作功能

MonoX 支持对多个指定包进行高效操作：

功能特点

灵活包选择：通过命令行或配置文件指定多个包
智能依赖分析：自动分析指定包之间的依赖关系
优化执行顺序：按正确的依赖顺序执行包
共享基础设施：复用单包分析和执行基础设施

使用示例

命令行多包操作

# 分析多个指定包
monox analyze --packages "@your-org/ui-lib,@your-org/web-app,@your-org/mobile-app" --detail

# 构建多个指定包
monox run --packages "@your-org/ui-lib,@your-org/web-app,@your-org/mobile-app" --command build

# 测试多个包（详细模式）
monox run --packages "pkg1,pkg2,pkg3" --command test --verbose

# 参数优先级：--all > --packages > --package
monox run --all --command build  # 最高优先级，构建所有包

配置文件多包任务

# 在 monox.toml 中定义多包任务
[[tasks]]
name = "build-frontend"
desc = "构建所有前端相关包"
command = "build"
packages = ["@your-org/web-ui", "@your-org/mobile-app", "@your-org/shared-components"]

[[tasks]]
name = "test-backend"
desc = "测试后端服务"
command = "test"
packages = ["@your-org/api-server", "@your-org/auth-service", "@your-org/database-lib"]

# 执行多包任务
monox exec build-frontend
monox exec test-backend --verbose

技术实现

多包分析：analyze_packages() 方法支持同时分析多个包
智能去重：自动去除重复包并优化依赖解析
阶段化执行：基于依赖分析结果进行智能调度
完全向后兼容：现有单包功能保持不变

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

MonoX

✨ 核心特性

🚀 快速开始

安装

初始化配置

基本使用

analyze - 依赖分析

run - 执行任务

exec - 执行预定义任务

check - 健康检查

fix - 问题修复

update - 依赖更新

📋 命令参考

全局选项

主要命令

analyze - 依赖分析

run - 执行命令

exec - 执行预定义任务

check - 健康检查

fix - 问题修复

update - 依赖更新

init - 初始化

⚙️ 配置文件

monox.toml 配置示例

配置参数说明

[workspace] - 工作空间

[[tasks]] - 任务定义

[execution] - 执行控制

[output] - 输出控制

[i18n] - 国际化

🌍 国际化支持

语言选择优先级

使用示例

支持的语言

📦 单包分析功能

功能特点

使用示例

🎨 用户界面特性

两种输出模式

刷新模式（默认）

详细模式（--verbose）

国际化界面

📊 使用场景

典型工作流

单包分析和调试

调试和诊断

🔧 技术特性

核心引擎

用户体验

架构设计

🤝 贡献

📄 许可证

🔗 相关链接

📦 多包操作功能

功能特点

使用示例

命令行多包操作

配置文件多包任务

技术实现

`analyze` - 依赖分析

`run` - 执行命令

`exec` - 执行预定义任务

`check` - 健康检查

`fix` - 问题修复

`update` - 依赖更新

`init` - 初始化