ML Changelogger

An intelligent changelog generator that analyzes Git commits using AI (OpenAI) and creates professional changelogs in various formats.

Features

• AI-Powered Analysis: Uses OpenAI GPT-4o-mini for intelligent analysis of Git commits
• Multi-Language Support: Supports English and German with localized date formatting
• Multiple Output Formats: Console, Markdown (.md), and HTML
• Automatic Categorization: Commits are automatically categorized into features, improvements, bugfixes, and internal changes
• Daily Grouping: Commits are grouped by date with automatically generated daily summaries
• Flexible Configuration: API key, default language, and default commit count can be saved
• Interactive Setup Wizard: Easy initial configuration with --init or --setup flag

Requirements

• Node.js (v20 or higher)
• Git Repository
• OpenAI API Key

Installation

1. Clone or download the repository
2. Install dependencies:

npm install

Initial Setup

The easiest way to configure the tool is using the interactive setup wizard:

npm run start -- --init
# or
npm run start -- --setup

The setup wizard will guide you through:

• Default Language: Choose between English (en) or German (de)
• OpenAI API Key: Enter your API key (or press Enter to keep existing)
• Default Commit Count: Set how many commits should be analyzed by default

If you already have settings configured, you can press Enter to keep existing values when prompted.

API Key Setup

You can provide the OpenAI API key in three ways:

Option 1: As Environment Variable

export OPENAI_API_KEY="your-api-key"

Option 2: In .env File

Create a .env file in the project directory:

OPENAI_API_KEY=your-api-key

Option 3: Save Permanently

npm run start -- --set-key your-api-key

Option 4: Interactive Setup

Use the setup wizard (recommended for first-time setup):

npm run start -- --init

Usage

Basic Usage

Simply start the tool and follow the interactive prompts:

npm run start

If you have configured a default commit count (via --init setup), it will be used as the default value when prompted. You can still override it by using the -n option.

Command Line Options

npm run start -- [Options]

Available Options:

| Option | Short | Description | Example | |--------|-------|-------------|---------| | --number <int> | -n | Number of commits to analyze | -n 10 | | --format <items> | -f | Output formats (comma-separated) | -f console,markdown,html | | --output <file> | -o | Output filename (without extension) | -o my-changelog | | --lang <iso> | -l | Language (en, de) | -l de | | --set-lang <iso> | | Set default language permanently | --set-lang de | | --key <string> | -k | OpenAI API Key (temporary) | -k your-key | | --set-key <key> | | Save API key permanently | --set-key your-key | | --clear-key | | Delete saved API key | --clear-key | | --init | | Run interactive setup wizard | --init | | --setup | | Run interactive setup wizard (alias for --init) | --setup |

Examples

Simple Call (Interactive)

npm run start

Analyze 10 Commits and Save as Markdown

npm run start -- -n 10 -f markdown

Generate German Changelog in All Formats

npm run start -- -n 5 -f console,markdown,html -l de

Set Default Language to German

npm run start -- --set-lang de

Run Initial Setup Wizard

npm run start -- --init

Changelog with Custom Filename

npm run start -- -n 15 -f markdown,html -o release-v1.0.0

Output Formats

Console

Colored output directly in the console with categories.

Markdown (.md)

Standard Markdown format, ideal for GitHub, GitLab, or other platforms.

HTML (.html)

Standalone HTML file with embedded styles, perfect for sharing or publishing.

Categories

Commits are automatically categorized into the following:

• New Features - New functionality
• Improvements (UI/UX) - Improvements to user interface or experience
• Bug Fixes - Bug fixes
• Technical Details (Internal) - Internal technical changes

Languages

Currently supported languages:

• en - English
• de - German

The language affects:

• The tool's user interface
• The generated changelog texts (titles, descriptions, daily summaries)
• Date formatting: German language uses DD.MM.YYYY format, English uses YYYY-MM-DD format

Configuration

Saved Settings

The tool saves configurations in a local config file:

• API Key (optional, can also be set via environment variable)
• Default Language (en or de)
• Default Commit Count (used as default when -n is not specified)

View Configuration

The configuration is automatically saved in ~/.config/ml-changelogger/config.json.

Updating Settings

You can update your settings in two ways:

1. Interactive Setup (Recommended): Run the setup wizard again

   npm run start -- --init

   You can press Enter to keep existing values for any setting you don't want to change.

2. Command Line: Use individual commands

   npm run start -- --set-key your-new-key
   npm run start -- --set-lang de

Example Output

Markdown Format

# Changelog

## [02.12.2025]

This update enhances the ml-changelogger project by introducing multi-language support...

### New Features

- **Add Multi-Language Support**: This commit introduces internationalization (i18n)...
- **Initial Project Setup**: This commit includes the setup of the project...

### Bug Fixes

- **Fix Import Paths**: Corrected module import paths in CLI...

Development

Project Structure

ml-changelogger/
├── bin/
│   └── cli.js              # Main CLI entrypoint
├── src/
│   ├── locales/
│   │   ├── en.json         # English translations
│   │   ├── de.json         # German translations
│   │   └── services/
│   │       ├── ai.js       # OpenAI Service
│   │       └── git.js      # Git Service
│   └── utils/
│       ├── config.js       # Configuration management
│       └── exporter.js     # Export functions
├── tests/
│   ├── unit/               # Unit tests for individual modules
│   │   ├── ai.test.js      # AI Service tests
│   │   ├── config.test.js  # Configuration tests
│   │   ├── exporter.test.js # Export function tests
│   │   └── git.test.js     # Git Service tests
│   ├── integration/        # Integration tests
│   │   └── full-flow.test.js # End-to-end workflow tests
│   └── utils/              # Test utilities and mocks
│       ├── mocks.js        # Mock implementations
│       └── test-data.js    # Test data generators
├── vitest.config.js        # Vitest configuration
├── package.json
└── README.md

Testing

The project uses Vitest as the test framework for comprehensive test coverage of all modules.

Running Tests

Run all tests in watch mode (recommended during development):

npm test

Run tests once (for CI/CD):

npm run test:run

Test Structure

The tests are divided into three categories:

Unit Tests (tests/unit/):

• ai.test.js - Tests the AI Service (OpenAI integration, commit analysis, categorization)
• config.test.js - Tests configuration management (saving/loading settings)
• exporter.test.js - Tests export functions (Markdown, HTML, Console format)
• git.test.js - Tests the Git Service (commit log, diff extraction)

Integration Tests (tests/integration/):

• full-flow.test.js - Tests the complete workflow from Git log to export generation

Test Utilities (tests/utils/):

• mocks.js - Mock implementations for external dependencies
• test-data.js - Helper functions for generating test data

Test Configuration

The test configuration is located in vitest.config.js. Vitest is configured so that:

• Globals are enabled (no explicit imports of describe, it, expect needed)
• Node.js environment is used
• All external dependencies (OpenAI, simple-git, fs) are mocked

Best Practices

• All new features should include corresponding tests
• Unit tests should be isolated and not perform real API calls or filesystem operations
• Integration tests verify the complete workflow with mocked dependencies
• Mock data is centrally managed in tests/utils/test-data.js

Troubleshooting

"No API Key found"

• Make sure the API key is set (see API Key Setup)
• Run the setup wizard: npm run start -- --init

"Git repository not found"

• Make sure you run the tool in a Git repository

"Cannot find module"

• Run npm install to install all dependencies

Setup Issues

• If the setup wizard doesn't start with --init or --setup, make sure you're using the latest version
• You can always update individual settings using the command line options (see Command Line Options)

License

ISC

Contributing

Contributions are welcome! Please create a Pull Request or open an Issue.

Support

For questions or problems, please open an Issue in the repository.