@push.rocks/smartchangelog

Parse and query changelog.md files that follow the push.rocks release format.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @push.rocks/smartchangelog

What it does

@push.rocks/smartchangelog parses the changelog.md files written by gitzone. The current format has a ## <date> - <version> heading per release, ### sub-sections such as Breaking Changes, Features, Fixes, Documentation and Maintenance, and unreleased changes under ## Pending:

# Changelog

## Pending

### Fixes

- update pnpm tooling configuration (tooling)

## 2026-09-15 - 6.1.0

### Features

- ship the whole install flow as release assets (install)
  - install.sh now verifies the downloaded binary against SHA256SUMS.txt

### Fixes

- remove NUPST from the system on uninstall (uninstall)

Older releases use the legacy labelled heading with a summary line, which stays supported because published changelogs contain both formats:

## 2026-04-16 - 5.10.0 - feat(cli,snmp)
fix APC runtime unit defaults and add interactive action editing

- correct APC PowerNet runtime handling

Grouped historical headings are supported as well:

## 2020-06-01 - 4.0.3-4.0.5 - core
## 2018-07-23 — 2019-12-15 - 2.0.0, 3.0.1, 3.0.9 - version-only releases

Parsing rules:

• ## Pending is not a released version. It is exposed as changelog.pending and never appears in entries, getLatestVersion() or the version queries.
• Every other ## heading must be a version heading. A heading that cannot be parsed (for example ## [Unreleased] or ## 2026-07-18 - next) throws instead of being skipped, so no release disappears silently.
• Indented list items become details of the list item above them; indented plain lines continue the list item above them until a blank line.
• Content other than list items (paragraphs, code blocks) is kept in markdownBlock only.

Usage

import { SmartChangelog } from '@push.rocks/smartchangelog';

const markdown = `# Changelog

## 2026-09-15 - 6.1.0

### Features

- ship the whole install flow as release assets (install)
  - install.sh now verifies the downloaded binary against SHA256SUMS.txt

## 2026-04-16 - 5.10.0 - feat(cli,snmp)
fix APC runtime unit defaults and add interactive action editing

- correct APC PowerNet runtime handling
`;

const changelog = SmartChangelog.fromMarkdown(markdown);
const latestVersion = changelog.getLatestVersion(); // '6.1.0'
const entry = changelog.getEntryForVersion('6.1.0');
const upgradeNotes = changelog.getEntriesBetween('5.8.0', '6.1.0');

console.log(entry?.sections.map((section) => section.heading)); // ['Features']
console.log(entry?.sections[0].items[0].details); // ['install.sh now verifies ...']
console.log(upgradeNotes.map((note) => note.toCliString({ bulletLimit: 5 })).join('\n\n'));

toCliString() renders the version (followed by - <label> for legacy headings), the summary, the items and then each non-empty sub-section as <heading>: with its items and indented details. bulletLimit limits the number of top-level items; the rest is announced as - ...and N more.

API

• SmartChangelog.fromMarkdown(markdown) parses a whole changelog
• smartChangelog.entries / smartChangelog.getEntries() released entries in document order
• smartChangelog.pending the ## Pending section as IChangelogPending, or undefined
• smartChangelog.getLatestVersion()
• smartChangelog.getEntryForVersion(version)
• smartChangelog.getEntriesBetween(currentVersion, targetVersion) entries after currentVersion up to and including targetVersion
• ChangelogEntry.fromMarkdownBlock(markdownBlock) parses one ## version block and throws on an unsupported heading
• entry.date, entry.versionSpec, entry.label (legacy headings only, otherwise undefined), entry.summary
• entry.items list items before the first ### sub-section, as IChangelogItem ({ text, details })
• entry.sections the ### sub-sections, as IChangelogSection ({ heading, items })
• entry.bullets every list item and detail, flattened in document order
• entry.includesVersion(version)
• entry.intersectsRange(currentVersion, targetVersion)
• entry.toCliString({ bulletLimit })
• parseVersionSpec(spec), compareVersions(left, right), normalizeVersionString(version)

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.