or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

changelog-generation.mdconfiguration.mdgit-operations.mdgithub-integration.mdindex.mdrepository-analysis.mdversion-management.md
tile.json

changelog-generation.mddocs/

Changelog Generation

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;
}

Error Handling

The markdown generation process handles various edge cases:

  • Empty commit lists: Generates minimal changelog structure
  • Missing repository information: Falls back to plain text references
  • Invalid commit formats: Skips non-conventional commits silently
  • GitHub API failures: Continues without username resolution
  • Emoji conversion errors: Preserves original text format