# changelog

Changelog & release-automation pack built on the Conventional Commits spec. Parses commit messages into type/scope/subject/body/breaking-change, groups them into a Keep-a-Changelog-style changelog...


**Release automation over [Conventional Commits](https://www.conventionalcommits.org).** Feed it a
list of commit messages and it parses each one, groups them into a Keep-a-Changelog-style changelog,
computes the next SemVer version, and drafts human release notes — deterministically, no git binary
required (you supply the messages, e.g. from `git log --pretty=%B%n%H`).

It is an *intelligent microservice*: every tool has a pure heuristic/template core that runs offline;
`releaseNotes` can optionally polish its prose via a model and silently falls back to the template.
Results are tagged `{ mode: 'heuristic' | 'llm' }` where a model can contribute.

## Tools

| Tool | Input | Output |
|---|---|---|
| `conventionalParse` | `{ commit }` | `{ type, scope, subject, body, breaking, section, conventional, trailers }` |
| `categorize` | `{ commit }` or `{ commits }` | section for one commit, or a breakdown across many |
| `semverBump` | `{ current, commits }` | `{ level, effectiveLevel, next, hasBreaking, hasFeat }` |
| `generate` | `{ commits, current?, version?, date?, repoUrl?, options? }` | grouped changelog (structured + markdown) |
| `releaseNotes` | `{ commits, current?, options? }` | summary + highlights + full markdown |
| `contributors` | `{ commits }` | commit-count leaderboard (authors + `Co-authored-by`) |

## Bump rules

- Any **breaking change** (`!` in the header or a `BREAKING CHANGE:` footer) → **major**.
- Any `feat` → **minor**. Otherwise (`fix`/`perf`/`refactor`/…) → **patch**.
- `options.preMajor` (default `true`): below `1.0.0` a breaking change bumps **minor** instead of major
  (feat still → minor, fix still → patch), matching `semantic-release` (SemVer §4).

## Usage

```js
import changelog from './index.js';

changelog.adapters.semverBump({
  current: '1.4.2',
  commits: ['feat(api): add search', 'fix: null guard', 'refactor!: drop legacy flag'],
});
// -> { level:'major', next:'2.0.0', hasBreaking:true, hasFeat:true }

changelog.adapters.generate({
  current: '1.0.0',
  commits: ['feat(ui): dark mode', 'fix(auth): expiry bug', 'chore: bump deps'],
});
// -> { version:'1.1.0', sections:[{title:'Features',...},{title:'Bug Fixes',...}], markdown:'## 1.1.0 ...' }
```

## DRY boundary

Pure release/versioning tooling over commit **text**. It does not run git, diff files, or measure code
(see **`code-metrics`**). No overlap with any existing pack. Self-contained (Node built-ins +
`../_shared/llm.js` only).


---
Source: shared/engines/adapters/domain/changelog/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/changelog