Changelog-tools NPM

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'`)
`--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"
    }
  ]
}