denisa/clq

clq — 变更日志验证与查询工具

!GitHub Release Date

https://github.com/denisa/clq/actions/workflows/ci.yaml/badge.svg?branch=main](https://github.com/denisa/clq/actions/workflows/ci.yaml?query=branch%3Amain)  https://github.com/denisa/clq/actions/workflows/linter.yaml/badge.svg](https://github.com/denisa/clq/actions/workflows/linter.yaml)

概述

clq是一款用于变更日志（Changelog）验证与查询的工具，旨在确保变更日志符合规范格式，并支持通过查询语言提取关键信息（如版本号、变更内容等）。它支持两种验证模式，可集成到开发流程中，帮助团队维护规范的变更日志，确保语义化版本控制的准确性。

核心功能与特性

• 双重验证模式：支持"特性模式"（开发阶段验证格式合规性）和"发布模式"（发布前检查，确保最新版本非未发布或已撤销状态）。
• 自定义变更映射：通过JSON文件定义变更类型（如Added、Changed）与语义化版本变更（major/minor/patch）的映射关系，支持自定义规则。
• 查询语言支持：提供简单和复杂查询能力，可提取版本号、发布日期、变更描述等信息，支持JSON和Markdown输出格式。
• 多文件处理：支持处理标准输入或多个文件，输出时自动添加文件名前缀。
• Docker化部署：提供轻量Docker镜像，支持无安装直接使用，兼容Whalebrew工具。

使用场景与适用范围

• 开发阶段：在特性分支中验证变更日志格式，确保符合语***范。
• 发布前检查：通过发布模式验证，确保即将发布的版本信息完整且有效。
• CI/CD集成：作为GitHub Action（clq-action）集成到工作流，自动化变更日志验证。
• 版本信息提取：通过查询功能快速获取最新版本号、变更内容等，用于文档生成或版本管理。

使用方法与配置说明

基本用法

clq始终先验证完整变更日志，遇到首个错误即停止。若提供查询，验证后返回查询结果。支持标准输入（无参数或参数为"-"）或多个文件。

• 退出码：0表示所有文件验证通过，非0表示存在验证错误。
• 输出：查询结果输出到标准输出，验证错误输出到标准错误。
• 多文件处理：标准输出和错误的每行均前缀文件名。

命令选项

text
Usage: clq { options } path_to_changelog.md

选项：
  -changeMap name
      定义变更类型到语义化版本变更映射的文件路径
  -output format
      查询结果输出格式，支持json和md（markdown），默认json
  -query string
      用于提取变更日志信息的查询语句
  -release
      启用发布模式验证
  -with-filename
      始终在输出行添加文件名前缀

使用示例

• 验证文件：
  clq CHANGELOG.md
  验证CHANGELOG.md的格式合规性。

• 发布模式验证：
  clq -release CHANGELOG.md
  验证文件并确保最新版本非"[Unreleased]"或"[YANKED]"状态，建议发布前或合并到主分支前使用。

• 查询最新版本：
  clq -query releases[0].version CHANGELOG.md
  验证完整变更日志并返回最新版本号。

Docker执行

提供轻量Docker镜像，标签为发布版本，次要标签以"-slim"结尾（如1.2.3-slim）。

单文件验证

bash
docker run -i denisa/clq < CHANGELOG.md

多文件处理

建议使用多次单独调用或安装原生二进制文件。也可通过Whalebrew简化使用：

1. 安装Whalebrew：
   whalebrew install denisa/clq

2. 验证一个或多个文件：
   clq CHANGELOG.md 或 clq */CHANGELOG.md

其他镜像版本

项目还提供标签以"-alpine"结尾的镜像（如1.2.3-alpine），体积较大，主要用于https://github.com/denisa/clq-action%E3%80%82

GitHub Action集成

详见https://github.com/denisa/clq-action%E6%96%87%E6%A1%A3%EF%BC%8C%E5%8F%AF%E5%B0%86clq%E9%9B%86%E6%88%90%E5%88%B0GitHub%E5%B7%A5%E4%BD%9C%E6%B5%81%E4%B8%AD%E3%80%82

支持的变更日志语法

CHANGELOG       = 引言部分, 发布记录;
引言部分        = 标题, {  markdown段落  };
标题            = "# ", 行内内容, 行结束符;
发布记录        = [ 未发布版本 ], { 已发布版本 };
未发布版本      = 未发布版本标题, { 变更内容 };
已发布版本      = 已发布版本标题, { 变更内容 };
未发布版本标题  = "## [Unreleased]", 行结束符;
已发布版本标题  = "## [", 语义化版本, "] - ", ISO日期, [ " [YANKED]" ], [ 标签 ], 行结束符;
标签            = 行内内容（但不是"[YANKED]"）;
变更内容        = 变更类型, { 变更描述 };
变更类型        = "### ", ( "Added" | "Changed" | "Deprecated" | "Removed" | "Fixed" | "Security" ), 行结束符;
变更描述        = "- ", 行内内容, 行结束符;
语义化版本      = 参见 https://semver.org;
ISO日期         = 年, "-", 月, "-" 日;
年              = 数字, 数字, 数字, 数字;
月              = 数字, 数字;
日              = 数字, 数字;
行结束符        = "U+000A" | "U+000D" | "U+000DU+000A";
数字            = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";

注意：

• 最新版本排在最前。
• 与官方规范的唯一差异是发布条目支持可选标签，便于团队标记特殊版本（如季度演示版本：## [1.5.2] - 2019.10.02 Espelho）。

验证规则

特性模式（默认）

验证变更日志是否符合语法，并确保：

• 发布按时间倒序排列（最新在前）。
• 版本号严格递减。
• 版本变更由变更类型根据默认或自定义映射规则合理触发。

默认变更映射规则

• major版本触发：
  • Added（新增功能）
  • Removed（移除功能）
• minor版本触发：
  • Changed（现有功能变更）
  • Deprecated（即将移除的功能）
• patch版本触发：
  • Fixed（错误修复）
  • Security（安全漏洞修复）

自定义变更映射

通过-changeMap选项指定JSON文件自定义规则。例如，将Added仅触发minor版本变更：

json
[
  {
    "name": "Added",
    "increment": "minor"
  },
  {
    "name": "Changed",
    "increment": "minor"
  },
  {
    "name": "Deprecated",
    "increment": "minor"
  },
  {
    "name": "Fixed",
    "increment": "patch"
  },
  {
    "name": "Removed",
    "increment": "major"
  },
  {
    "name": "Security",
    "increment": "patch"
  }
]

发布模式（-release选项）

在特性模式基础上，进一步验证变更日志的首个条目为实际发布版本（非未发布或已撤销状态）。

注意：目前可能不支持预发布版本。

表情符号支持

变更映射文件可通过emoji属性为变更类型分配表情符号。示例：

json
[
  {
    "name": "Added",
    "increment": "minor",
    "emoji": "✨"
  },
  {
    "name": "Changed",
    "increment": "major",
    "emoji": "💥"
  },
  {
    "name": "Deprecated",
    "increment": "minor",
    "emoji": "👎"
  },
  {
    "name": "Fixed",
    "increment": "patch",
    "emoji": "🐛"
  },
  {
    "name": "Removed",
    "increment": "major",
    "emoji": "🗑️"
  },
  {
    "name": "Security",
    "increment": "patch",
    "emoji": "🔒"
  }
]

实验性扩展

可通过变更映射文件定义其他变更类型（如翻译或新增类型），或为"build"类型的语义化版本分配变更类型（但此类变更不能作为版本递增的唯一依据）。示例：

• 法语翻译
• 文档变更使用build类型

查询表达式语言

查询由一系列"查询元素"组成，用于遍历变更日志结构获取目标字段。首个查询元素必须是变更日志的字段。

语法

QUERY            = ( 简单查询 | 复杂查询 );
简单查询         = { 数组字段, "." }, 字段;
复杂查询         = { 数组字段, "." }, 数组字段, ["/"];
数组字段         = 字段, "[", [选择器], "]";
字段             = 见下文文档模型部分;
选择器           = 数字+;
数字             = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";

• 简单查询：返回单个字段值，无格式。
• 复杂查询：返回所选对象的所有值，按-output指定格式输出。以"/"结尾时包含子元素；无选择器时返回对象集合。

示例（基于以下变更日志）

markdown
# Change log

## [Unreleased]

### Added

- waldo
- fred

## [1.0.0] - 2020-06-20

### Removed

- foo
- bar

• releases[1].version → 1.0.0
• releases[1] → {"version":"1.0.0", "date":"2020-06-20"}
• releases[0].changes[] → [{"title":"Added"}]
• releases[0].changes[]/ → [{"title":"Added", "descriptions":["waldo", "fred"]}]

文档模型

changelog（变更日志）

• releases[]：所有发布记录，可通过索引（从0开始）访问单个发布。
• title：变更日志标题。

release（发布）

• changes[]：该发布的所有变更，不可索引。
• date：发布日期，未发布时为空。
• label：可选发布标签。
• status：状态，可选值：prereleased、released、unreleased、yanked。
• title：版本、日期和可选标签组成的标题。
• version：版本号。

change（变更）

• descriptions[]：所有变更描述，不可索引。
• title：变更类型（如Added、Changed）。

参考资料

• Keep a Changelog
• 语义化版本
• CommonMark 规范