npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@composy/changelog

v0.0.2

Published

Automated changelog and release notes toolkit for LDesign.

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 init

2. 诊断当前项目

ldesign-changelog doctor --json --report .changelog-doctor.json

3. 预览将要生成的内容

ldesign-changelog preview --from v1.2.0 --to HEAD --stats

4. 生成 changelog

ldesign-changelog generate --version 2.0.0 --from v1.2.0 --to HEAD

5. 发布并打 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