coze-studio/frontend/infra/utils/monorepo-kits

@coze-arch/monorepo-kits

一个用于管理 monorepo 项目的工具包，提供了基于 Rush 框架的项目查找、依赖分析和配置管理功能。

🚀 功能概述

@coze-arch/monorepo-kits 是专为 monorepo 项目设计的工具库，提供了一套完整的包管理、依赖分析和配置查询解决方案。通过统一的 API 接口，帮助开发者更高效地管理复杂的 monorepo 项目结构。

✨ 主要功能

📦 子包管理

• 依赖递归查找: 自动查找包的所有子依赖关系
• 路径解析: 获取包在文件系统中的实际位置
• 配置查询: 读取包的 package.json 配置信息
• 缓存优化: 智能缓存机制提升查找性能

⚙️ Rush 配置管理

• 配置加载: 自动加载和管理 Rush 配置
• 单例模式: 避免重复加载配置文件
• 类型安全: 完整的 TypeScript 类型支持

🔍 项目查找

• 依赖分析: 查找包的直接和间接依赖关系
• 项目定位: 快速定位指定包的项目配置
• 关系查询: 分析包之间的依赖关系图

📚 API 文档

子包管理

lookupSubPackages(packageName: string): string[]

递归查找指定包的所有子依赖包。

import { lookupSubPackages } from '@coze-arch/monorepo-kits';

const deps = lookupSubPackages('@coze/ui-components');
console.log(deps); // ['@coze/icons', '@coze/themes', ...]

getPackageLocation(packageName: string): string

获取指定包的文件系统路径。

import { getPackageLocation } from '@coze-arch/monorepo-kits';

const location = getPackageLocation('@coze/ui-components');
console.log(location); // '/path/to/packages/ui-components'

getPackageJson(packageName: string): RushConfigurationProject['packageJson']

获取指定包的 package.json 配置信息。

import { getPackageJson } from '@coze-arch/monorepo-kits';

const pkg = getPackageJson('@coze/ui-components');
console.log(pkg.version); // '1.0.0'

Rush 配置管理

getRushConfiguration(): RushConfiguration

获取 Rush 配置实例（单例模式）。

import { getRushConfiguration } from '@coze-arch/monorepo-kits';

const rushConfig = getRushConfiguration();
console.log(rushConfig.projects.length); // 项目总数

项目查找

lookupTo(to: string): string[]

查找指定包的直接依赖项。

import { lookupTo } from '@coze-arch/monorepo-kits';

const dependencies = lookupTo('@coze/ui-components');
console.log(dependencies); // 依赖的包名数组

lookupOnly(packageName: string): RushConfigurationProject

查找并返回指定包的完整项目配置对象。

import { lookupOnly } from '@coze-arch/monorepo-kits';

const project = lookupOnly('@coze/ui-components');
console.log(project.projectFolder); // 项目文件夹路径

🛠 安装使用

安装

# 在 monorepo 内部作为工具库使用
npm install @coze-arch/monorepo-kits

基本使用

import {
  lookupSubPackages,
  getPackageLocation,
  getRushConfiguration,
  lookupOnly
} from '@coze-arch/monorepo-kits';

// 查找包的所有依赖
const allDeps = lookupSubPackages('your-package');

// 获取包的位置
const location = getPackageLocation('your-package');

// 获取项目配置
const project = lookupOnly('your-package');

// 获取 Rush 配置
const rushConfig = getRushConfiguration();

🏗 项目结构

src/
├── index.ts          # 主入口文件，导出所有公共 API
├── sub-packages.ts   # 子包管理和依赖查找功能
├── rush-config.ts    # Rush 配置管理
└── lookup.ts         # 项目查找相关功能

🎯 使用场景

1. 依赖分析工具

// 分析包的依赖关系
const analyzeDependencies = (packageName: string) => {
  const allDeps = lookupSubPackages(packageName);
  const directDeps = lookupTo(packageName);

  return {
    total: allDeps.length,
    direct: directDeps.length,
    indirect: allDeps.length - directDeps.length
  };
};

2. 构建脚本集成

// 在构建脚本中获取包信息
const buildPackage = (packageName: string) => {
  const location = getPackageLocation(packageName);
  const pkg = getPackageJson(packageName);

  console.log(`Building ${pkg.name}@${pkg.version} at ${location}`);
  // ... 执行构建逻辑
};

3. 自动化工具开发

// 为自动化工具提供项目信息
const getProjectInfo = (packageName: string) => {
  const project = lookupOnly(packageName);
  const dependencies = lookupSubPackages(packageName);

  return {
    name: project.packageName,
    path: project.projectFolder,
    dependencies,
    config: project.packageJson
  };
};

🚀 特性优势

• 🎯 专为 Monorepo 设计: 针对大型 monorepo 项目优化
• ⚡ 高性能: 智能缓存机制，避免重复计算
• 🛡 类型安全: 完整的 TypeScript 类型定义
• 🔧 易于集成: 简洁的 API 设计，易于集成到现有工具链
• 📦 轻量级: 最小化依赖，专注核心功能

📄 依赖信息

• 主要依赖: @rushstack/rush-sdk@5.100.2
• 开发依赖: ESLint、TypeScript、Vitest 等工具链
• 运行环境: Node.js 18+

🤝 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个项目。

📝 许可证

Apache-2.0 License

---

作者: fanwenjie.fe@bytedance.com

如需了解更多信息，请查看项目文档或联系维护团队。