tessl/npm-changelogen

Generate Beautiful Changelogs using Conventional Commits

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Changelog Generation

Name: tessl/npm-changelogen
Author: tessl

Core markdown generation functionality for creating formatted changelogs from parsed commits with customizable templates, formatting, and emoji support. This module transforms conventional commits into beautiful, readable changelog markdown.

Capabilities

Generate Markdown

Generates a formatted changelog in markdown format from parsed conventional commits.

/**
 * Generate markdown changelog from parsed commits
 * @param commits - Array of parsed conventional commits
 * @param config - Resolved changelog configuration with formatting options
 * @returns Promise resolving to formatted markdown string
 */
function generateMarkDown(
  commits: GitCommit[],
  config: ResolvedChangelogConfig
): Promise<string>;

Usage Examples:

import { 
  generateMarkDown, 
  parseCommits, 
  loadChangelogConfig,
  getGitDiff 
} from "changelogen";

// Basic changelog generation
const config = await loadChangelogConfig(process.cwd(), {
  from: "v1.0.0",
  to: "HEAD"
});

const rawCommits = await getGitDiff(config.from, config.to);
const commits = parseCommits(rawCommits, config);
const markdown = await generateMarkDown(commits, config);

console.log(markdown);

// Custom configuration
const customConfig = await loadChangelogConfig(process.cwd(), {
  from: "v1.0.0",
  to: "HEAD",
  noAuthors: true,
  hideAuthorEmail: true,
  types: {
    feat: { title: "🚀 Features", semver: "minor" },
    fix: { title: "🐛 Bug Fixes", semver: "patch" },
    docs: { title: "📝 Documentation", semver: "patch" }
  }
});

const customMarkdown = await generateMarkDown(commits, customConfig);

Generated Markdown Structure:

## v1.2.0

[compare changes](https://github.com/user/repo/compare/v1.1.0...v1.2.0)

### 🚀 Enhancements

- **scope**: Add new feature ([abc123](https://github.com/user/repo/commit/abc123))
- Fix important bug ([#123](https://github.com/user/repo/pull/123))

### 🩹 Fixes

- **api**: Fix API endpoint issue ([def456](https://github.com/user/repo/commit/def456))

#### ⚠️ Breaking Changes

- **api**: Change authentication method ([#456](https://github.com/user/repo/pull/456))

### ❤️ Contributors

- John Doe ([@johndoe](https://github.com/johndoe))
- Jane Smith <jane@example.com>

Parse Changelog Markdown

Parses existing changelog markdown files to extract release information.

/**
 * Parse existing changelog markdown into structured release data
 * @param contents - Raw changelog markdown content
 * @returns Object containing array of parsed releases
 */
function parseChangelogMarkdown(
  contents: string
): { releases: { version?: string; body: string }[] };

Usage Examples:

import { parseChangelogMarkdown } from "changelogen";
import { readFileSync } from "fs";

// Parse existing changelog
const changelogContent = readFileSync("CHANGELOG.md", "utf8");
const parsed = parseChangelogMarkdown(changelogContent);

console.log(`Found ${parsed.releases.length} releases`);

// Get specific version
const v120Release = parsed.releases.find(r => r.version === "1.2.0");
if (v120Release) {
  console.log("v1.2.0 release notes:", v120Release.body);
}

// List all versions
const versions = parsed.releases
  .map(r => r.version)
  .filter(Boolean);
console.log("Available versions:", versions);

Formatting Features

Commit Type Grouping

Commits are automatically grouped by type with customizable titles and emojis:

// Default type configuration
const defaultTypes = {
  feat: { title: "🚀 Enhancements", semver: "minor" },
  perf: { title: "🔥 Performance", semver: "patch" },
  fix: { title: "🩹 Fixes", semver: "patch" },
  refactor: { title: "💅 Refactors", semver: "patch" },
  docs: { title: "📖 Documentation", semver: "patch" },
  build: { title: "📦 Build", semver: "patch" },
  types: { title: "🌊 Types", semver: "patch" },
  chore: { title: "🏡 Chore" },
  examples: { title: "🏀 Examples" },
  test: { title: "✅ Tests" },
  style: { title: "🎨 Styles" },
  ci: { title: "🤖 CI" }
};

Reference Formatting

References are automatically formatted as clickable links based on repository provider:

Hash references: abc123 → [abc123](https://github.com/user/repo/commit/abc123)
Issue references: #123 → [#123](https://github.com/user/repo/issues/123)
Pull request references: #456 → [#456](https://github.com/user/repo/pull/456)

Breaking Changes

Breaking changes are automatically detected and prominently displayed:

Commits with ! after type/scope: feat!: breaking change
Commits with BREAKING CHANGE: in body
Separate "⚠️ Breaking Changes" section in changelog

Author Attribution

Automatic contributor detection and attribution:

GitHub username resolution via email lookup
Co-author support from Co-authored-by: lines
Configurable author exclusion and email hiding
Fallback to email addresses when GitHub usernames unavailable

Emoji and Gitmoji Support

Full support for emoji in commit messages:

Unicode emojis: 🚀 feat: new feature
Text format: :rocket: feat: new feature
Automatic conversion via convert-gitmoji

Template Customization

Customizable templates for different changelog elements:

interface Templates {
  commitMessage?: string;    // Default: "chore(release): v{{newVersion}}"
  tagMessage?: string;       // Default: "v{{newVersion}}"
  tagBody?: string;          // Default: "v{{newVersion}}"
}

Scope Mapping

Configure scope transformations to standardize or rename scopes:

const config = {
  scopeMap: {
    "cli": "command-line",
    "ui": "interface",
    "db": "database"
  }
};

Configuration Options

interface ChangelogFormatting {
  // Commit type configuration
  types: Record<string, { title: string; semver?: SemverBumpType } | boolean>;
  
  // Scope name mapping
  scopeMap: Record<string, string>;
  
  // Author configuration
  noAuthors: boolean;
  excludeAuthors: string[];
  hideAuthorEmail?: boolean;
  
  // Template configuration
  templates: {
    commitMessage?: string;
    tagMessage?: string;
    tagBody?: string;
  };
  
  // Version information
  newVersion?: string;
  from: string;
  to: string;
}