@composy/changelog
v0.0.2
Published
Automated changelog and release notes toolkit for LDesign.
Maintainers
Readme
@composy/changelog
@composy/changelog
是一个面向 Node.js 与 TypeScript 项目的变更日志工具包,覆盖从 Git 提交解析、CHANGELOG 生成、格式化输出,到版本分析、迁移指南、发布集成、Webhook 通知的完整链路。
它既可以作为 CLI 独立使用,也可以作为库嵌入自动化脚本、发布流水线和 monorepo 工具链中。
核心能力
- 解析 Conventional Commits,并提取 scope、PR、Issue、Breaking Change 等结构化信息
- 生成 Markdown、JSON、HTML 三种格式的 changelog
- 支持合并、导入、预览、校验、搜索、差异分析、统计分析
- 提供依赖变更追踪、安全扫描、版本推荐、迁移指南、多语言翻译、AI 增强
- 支持 GitHub、GitLab、Gitee Release 管理以及 Slack、Discord、Teams Webhook 通知
- 提供插件机制,允许在解析、生成、格式化、写入阶段插入自定义逻辑
- 支持 monorepo 包级版本标签和多包 changelog 工作流
包结构
src/
├── bin/ # TypeScript 编写的可执行入口,构建后产出 dist/bin/*
├── cli/ # CLI 模块入口、命令实现、交互流程、配置加载
├── core/ # 核心业务能力:分析、生成、导入、合并、迁移、AI、翻译
├── formatters/ # Markdown / JSON / HTML 输出
├── integrations/ # Release 平台与 Webhook 通知
├── plugins/ # 内置插件与插件入口
├── types/ # 对外类型定义
└── utils/ # 文件、Git、日志、终端交互等公共工具安装
pnpm add -D @composy/changelog也可以全局安装:
pnpm add -g @composy/changelog运行要求:
- Node.js
>= 18 - 推荐
pnpm >= 8 - Git 命令可用
快速开始
1. 初始化配置
ldesign-changelog init2. 诊断当前项目
ldesign-changelog doctor --json --report .changelog-doctor.json3. 预览将要生成的内容
ldesign-changelog preview --from v1.2.0 --to HEAD --stats4. 生成 changelog
ldesign-changelog generate --version 2.0.0 --from v1.2.0 --to HEAD5. 发布并打 tag
ldesign-changelog release --type minor --tag --push常用 CLI 命令
| 命令 | 说明 | 常用参数 |
| ------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
| generate | 生成 changelog | --cwd --version --from --to --output --format --interactive --track-deps |
| doctor | 诊断配置、Git 环境和输出路径 | --cwd --config --json --report --fix-plan --fail-on-warnings |
| preview | 预览 changelog,不写文件 | --cwd --version --from --to --format --stats |
| validate | 校验 changelog 内容或文件 | --cwd --config --strict --json |
| check | 检查现有 CHANGELOG.md 的规范性 | --cwd --config --strict --json |
| import | 导入已有 changelog 文件 | --cwd --format |
| merge | 合并多个 changelog 文件 | --cwd --strategy --deduplicate |
| watch | 监听仓库变更并自动生成 | --cwd --interval |
| stats | 输出提交统计信息 | --cwd --from --to --format |
| search | 在 changelog 中搜索提交 | --cwd --keyword --type --scope |
| diff | 分析两个版本/引用之间的影响范围 | --cwd --detailed |
| analyze | 组合输出版本、风险和统计分析 | --cwd --from --to |
| commit | 交互式生成提交消息 | --cwd --config --all |
| lint | 校验提交消息质量 | --cwd --from --to |
| release | 自动发布流程 | --cwd --type --version --tag --push --github-release |
| migration | 生成迁移指南 | --cwd --format |
| init | 生成配置文件 | --cwd --force |
| interactive | 启动交互式工作流 | --cwd --theme |
查看完整帮助:
ldesign-changelog --help
ldesign-changelog generate --help
ldesign-changelog doctor --help配置说明
支持以下配置文件:
changelog.config.js.changelogrc.json
推荐使用 changelog.config.js,这样可以直接复用环境变量与逻辑分支。
配置加载会把 cwd 规范化为绝对路径。所有子命令都支持
--cwd <dir>;命令行传入后,配置文件查找、Git 读取、输入文件、输出路径和模板路径都会以该目录为基准。配置文件里的相对
template 与 multiLang.glossaryPath 仍按配置文件所在目录解析,便于把模板放在 release/templates
等子目录。
ldesign-changelog generate --cwd packages/button --version 1.2.0
ldesign-changelog doctor --cwd packages/button --fix-plan --fail-on-warnings
ldesign-changelog check --cwd packages/button CHANGELOG.md --strict
ldesign-changelog release --cwd packages/button --dry-run
ldesign-changelog stats --cwd packages/button --format json完整示例
// changelog.config.js
export default {
cwd: process.cwd(),
output: 'CHANGELOG.md',
format: 'markdown',
language: 'zh-CN',
includeAuthors: true,
includePRLinks: true,
includeCommitHash: true,
groupByType: true,
updateMode: 'prepend',
keepHistory: true,
trackDependencies: true,
scanSecurity: true,
types: [
{ type: 'feat', section: '✨ 新功能', priority: 1 },
{ type: 'fix', section: '🐛 Bug 修复', priority: 2 },
{ type: 'perf', section: '⚡ 性能优化', priority: 3 },
{ type: 'refactor', section: '♻️ 代码重构', priority: 4 },
{ type: 'docs', section: '📝 文档更新', priority: 5 },
{ type: 'test', section: '✅ 测试', priority: 6 },
{ type: 'build', section: '📦 构建系统', priority: 7 },
{ type: 'chore', section: '🔧 其他', priority: 8 },
],
formatOptions: {
markdown: {
generateToc: true,
headingLevel: 2,
useEmoji: true,
},
json: {
pretty: true,
indent: 2,
includeMetadata: true,
},
html: {
title: 'Project Changelog',
includeStyles: true,
includeSearch: true,
theme: 'auto',
},
},
ai: {
provider: 'openai',
apiKey: process.env.OPENAI_API_KEY,
model: 'gpt-4o-mini',
temperature: 0.3,
},
multiLang: {
enabled: true,
targetLanguages: ['en-US', 'ja-JP'],
provider: 'ai',
translateCommits: false,
translateSections: true,
outputPattern: 'CHANGELOG.{lang}.md',
},
monorepo: {
enabled: true,
packages: ['packages/*'],
tagPrefix: '@scope/',
mergeChangelogs: false,
outputPattern: '{package}/CHANGELOG.md',
},
}程序化 API
生成 changelog
import { createChangelogGenerator } from '@composy/changelog'
const generator = createChangelogGenerator({
output: 'CHANGELOG.md',
format: 'markdown',
trackDependencies: true,
scanSecurity: true,
})
const content = await generator.generate('2.0.0', 'v1.0.0', 'HEAD')
const markdown = generator.format(content)
await generator.write(content)格式化结构化内容
import {
createHtmlFormatter,
createJsonFormatter,
createMarkdownFormatter,
} from '@composy/changelog/formatters'
const markdownFormatter = createMarkdownFormatter({
includeAuthors: true,
includeCommitHash: true,
})
const jsonFormatter = createJsonFormatter({
options: {
pretty: true,
indent: 2,
},
})
const htmlFormatter = createHtmlFormatter({
includeAuthors: true,
includeCommitHash: true,
})分析能力
import {
createDiffAnalyzer,
createSearchEngine,
createStatsAnalyzer,
createVersionAnalyzer,
} from '@composy/changelog/core'
const statsAnalyzer = createStatsAnalyzer()
const diffAnalyzer = createDiffAnalyzer({ cwd: process.cwd() })
const versionAnalyzer = createVersionAnalyzer({ currentVersion: '1.2.3' })
const stats = statsAnalyzer.analyze(commits)
const impact = await diffAnalyzer.analyze('v1.2.0', 'HEAD')
const risk = diffAnalyzer.evaluateRisk({
filesChanged: 8,
linesAdded: 240,
linesRemoved: 36,
affectedModules: ['core', 'cli'],
commits: [{ breaking: true }],
})
const modules = diffAnalyzer.identifyModules(['src/core/config.ts', 'src/cli/index.ts'])
const suggestion = versionAnalyzer.analyze(commits)导入 / 合并已有 changelog
import { createChangelogImporter, createChangelogMerger } from '@composy/changelog/core'
const importer = createChangelogImporter()
const imported = await importer.import(
{ path: 'CHANGELOG.md', format: 'auto' },
{
preserveDates: true,
preserveVersions: true,
dateFormat: 'YYYY-MM-DD',
versionPrefix: '',
}
)
const merger = createChangelogMerger()
const merged = await merger.merge(
[
{ path: 'packages/core/CHANGELOG.md', packageName: 'core', format: 'auto' },
{ path: 'packages/web/CHANGELOG.md', packageName: 'web', format: 'auto' },
],
{
strategy: 'by-package',
deduplicate: true,
deduplicateKey: 'both',
preservePackagePrefix: true,
outputFormat: 'markdown',
}
)JSON Changelog 合并会按 version
去重:重复执行同一版本不会不断追加重复条目;如果现有 JSON 能解析但不是对象结构,或 versions
不是对象数组,合并会明确失败并恢复原文件。合并成功后使用的旁路 .backup
文件会自动清理;失败时保留备份以便诊断和人工恢复。
发布与通知
import { createReleaseManager, createWebhookNotifier } from '@composy/changelog'
const releaseManager = await createReleaseManager({
token: process.env.GITHUB_TOKEN,
owner: 'ldesign',
repo: 'changelog',
})
const notifier = createWebhookNotifier({
enabled: true,
slack: {
url: process.env.SLACK_WEBHOOK_URL,
channel: '#release',
timeout: 10_000,
retries: 3,
},
teams: {
url: process.env.TEAMS_WEBHOOK_URL,
cardType: 'AdaptiveCard',
events: ['release', 'error'],
},
})timeout 使用毫秒;retries 是包含首次请求在内的总请求次数,必须为正整数,默认值为
1。网络错误、超时、限流和服务端错误会重试,其他 4xx 响应会立即报告失败,避免重复投递无效请求。
输出与构建
当前包使用 tools/tsup-config 对应的共享构建包 @composy/pack 打包:
- 入口:
src/**/*.ts - 产物:ESM + CJS +
.d.ts - 平台:Node.js
- 目标:
node18 - 构建配置:
.ldesign/pack.config.ts显式声明库与 CLI 双配置(external 清单手工维护) - ESLint 与 TypeScript 权威配置:
.ldesign/eslint.config.js、.ldesign/tsconfig.json;根目录入口保留 CLI/IDE 自动发现,TypeScript 根入口提供 pack 所需的包根相对rootDir锚点。
构建结果会为所有 src 源文件生成对应的 JS 产物,和 package.json
中的通配导出保持一致,避免“类型声明存在但运行时代码缺失”的深层导入问题。
开发命令
pnpm install
pnpm type-check
pnpm lint:check
pnpm build
pnpm test:run文档命令:
pnpm docs:dev
pnpm docs:build
pnpm docs:preview质量保障
当前仓库默认开启:
- TypeScript
strict @antfu/eslint-config- ESM 包结构
@composy/pack统一构建工作流
建议在修改核心模块后至少执行:
pnpm type-check
pnpm lint:check
pnpm build文档入口
- 使用指南:
docs/guide/* - API 说明:
docs/api/* - 插件文档:
docs/plugins/* - 配置参考:
docs/reference/* - 示例:
docs/examples/*
License
MIT
通过 @composy/cli 统一接入
通过 @composy/cli 统一接入
- 接入类型:
bin - 统一命令:
ldesign changelog - 命令别名:
cl - 包内原生 bin:
ld-changelog、ldesign-changelog
当前包通过独立 bin 接入,统一命令会转发到包自身 CLI。
pnpm add -D @composy/cli
ldesign changelog --help
ldesign tools run changelog --help