Changelog Tools

This package provides changelog-oriented tools for use in CLI, Node and browser scripts.

Features:

• Parse CHANGELOG.md files compatible with https://keepachangelog.com/en/1.1.0/ into JSON structure
• Filter output based on semver range, or custom filter conditions
• Combine multiple versions into a single structure, grouped by type of change (Added, Fixed etc.)
• Compatible with both browser and node environments
• Add new entries into changelog with CLI

The parsing algorithm was initially based on the changelog-parser package, but it was updated to provide a more object-oriented approach.

CLI API

parse

changelog-tools parse path-to-changelog.md

Parses the changelog and returns it in JSON format

Parameters

| Param | Alias | Default | Description | | --------------- | ----- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --help | -h | | | | --version | -v | | | | --new-line | -n | AUTO | AUTO\|LF\|CRLF\|CR - Define what should be newline character for output data. AUTO will try to detect the line endings from the document. | | --consolidate | -c | false | Merge multiple versions into one entry, groupiung the same ypes of changes together | | --semver | -s | '' | filter versions by semver range syntax. E.g. -s '>=1.0.0' | | --filter | -f | | Filter entries based on provided statement. Use this to access version data. Statement needs to return a boolean. Example: -f 'this.version === "1.0.0"' |

Examples

Parse changelog and output a JSON structure representing the document.

changelog-tools CHANGELOG.md

Find all versions in the changelog between 1.0.0 and 1.1.0 and group Added, Fixed etc entries together.

changelog-tools -cs '~1.0.0' CHANGELOG.md

add

changelog-tools add path-to-changelog.md -t 'Title of new version' [-o output file]

Adds a new version to the changelog.

Parameters

| Param | Alias | Default | Description | | ----------------- | ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | --help | -h | | | | --version | -v | | | | --new-line | -n | AUTO | AUTO\|LF\|CRLF\|CR - Define what should be newline character for output data. AUTO will try to detect the line endings from the document. | | --title | -t | | (Required) Title of the version to add (e.g. -t '1.0.0 (2020-01-01) - My Version Title') | | --added | -a | | ### Added entries (e.g. -a 'new feature' -a 'new feature 2') | | --changed | -c | | ### Changed entries (e.g. -c 'format 1' -c 'api description') | | --deprecated | -d | | ### Deprecated entries (e.g. -d 'old feature' -d 'old feature 2'). | | --removed | -r | | ### Removed entries (e.g. -r 'old feature' -r 'old feature 2') | | --fixed | -f | | ### Fixed entries (e.g. -f 'bug 1' -f 'bug 2') | | --new-changelog | | | Raw changelog text (including ### section headers) to be parsed and merged with other sections (e.g. --new-changelog "### Added\n* Something new") | | --list-bullet | -l | | Character to be used for list items (e.g. -l '*') | | --output | -o | stdout | Output file |

Examples

Add a new version with a single 'Added' entry

changelog-tools add CHANGELOG.md -t 'v1.5.0 - 2022-01-01' -a 'New command `add`'

output on CLI:

# Changelog Tools

## v1.5.0 - 2022-01-01
### Added
- New command `add`

<!-- ... previous versions -->

Add a new version with a single 'Added' entry and save it to the same file as input

changelog-tools add CHANGELOG.md -t 'v1.5.0 - 2022-01-01' -a 'New command `add`' -o CHANGELOG.md

JavaScript (Node and browser)

Loading parser class

CommonJS:

const { ChangelogParser } = require("changelog-tools");

ES Modules:

import { ChangelogParser } from "changelog-tools";

Creating parser

// Empty parser:
const changelogParser = new ChangelogParser();

// Parser with preloaded changelog text:
const changelogParser = new ChangelogParser({
  text: changelogContent
});

Parsing

// If text was already preloaded
const changelog = changelogParser.parse();

// With new changelog content:
const changelog = changelogParser.parse(changelogContent);

.parse() method will return an instance of the Changelog class.

An example structure of this object can be seen below:

{
  "title": "Changelog title",
  "description": "This is a sample changelog",
  "versions": [
    {
      "version": "1.1.0",
      "line": 4,
      "date": "2022-12-20",
      "title": "v1.1.0 - 2022-12-20",
      "parsed": {
        "_": ["Removed 1", "Changed 2"],
        "Removed": ["Removed 1"],
        "Changed": ["Changed 2"]
      },
      "body": "### Removed \n\n- Removed 1\n\n### Changed\n\n-Changed 2"
    },
    {
      "version": "1.0.0",
      "line": 12,
      "date": "2022-12-12",
      "title": "v1.0.0 - 2022-12-12",
      "parsed": {
        "_": ["Added 1", "Changed 1"],
        "Added": ["Added 1"],
        "Changed": ["Changed 1"]
      },
      "body": "### Added \n\n- Added 1\n\n### Changed\n\n-Changed 1"
    }
  ]
}

Filtering results

const filteredChangelog = changelog.filter((v) => v.version === '1.0.0' || v.title.includes('Unversioned'))

.filter() method will also return an instance of the Changelog class.

Consolidate versions from the changelog

const changeSummary = changelog.consolidate();

This is best used to summarize all changes from multiple versions. E.g. the script below will gather all changes from versions 1.1.X.

const changeSummary = changelog.filter((v) => v.version.startsWith('1.1')).consolidate();

The result will be provided as an object like below:

{
  "Added": [
    {
      "text": "Added 2",
      "version": "0.0.3"
    },
    {
      "text": "Added 1",
      "version": "0.0.1"
    }
  ],
  "Removed": [
    {
      "text": "Removed 1",
      "version": "0.0.2"
    }
  ]
}

Examples

See the ./examples folder to check for examples of use cases.