README

A minimal PHP library for validating and converting changelog formats between JSON and Markdown.

Installation

Install via Composer:

composer require --dev adachsoft/changelog-linter

Usage

CLI Commands

Validate changelog.json

vendor/bin/changelog validate --path=changelog.json [--lenient]

Generate Markdown from JSON

vendor/bin/changelog generate-md --input=changelog.json --output=CHANGELOG.md

Generate JSON from Markdown

vendor/bin/changelog generate-json --input=CHANGELOG.md --output=changelog.json [--lenient] [--with-created-at]

Options:

• --lenient: enables tolerant parsing/validation mode for Markdown → JSON. Unknown sections are skipped, version headers may include v prefix, and Unreleased is recognized.
• --with-created-at: when set for generate-json, adds createdAt to each version (preserving existing values for existing versions).

Composer Scripts

The package provides convenient composer scripts:

composer run changelog:validate    # Validate changelog.json
composer run changelog:generate    # Generate Markdown from JSON
composer run changelog:from-md     # Generate JSON from Markdown

Configuration (changelog-linter.json)

Optional configuration file located at the repository root.

{
  "markdown": {
    "version_header_prefix": "v",
    "allow_prologue": true
  },
  "json": {
    "created_at_field_name": "createdAt",
    "created_at_format": "Y-m-d H:i:s"
  }
}

• markdown.version_header_prefix: Prefix in version headings in Markdown (default: "v").
• markdown.allow_prologue: Allow any text between the title and first version (default: true).
• json.created_at_field_name: Field name for creation timestamp in JSON (default: "createdAt").
• json.created_at_format: Datetime format for createdAt (default: "Y-m-d H:i:s").

Behavior of generate-json:

• If output JSON exists and you pass --with-created-at, the tool preserves existing createdAt for already known versions and sets createdAt only for new versions.
• If you do not pass --with-created-at, no createdAt is added (schema allows it to be omitted).

File Formats

changelog.json (JSON Schema excerpt)

Root-level fields:

• title (string, optional)
• intro (string, optional)
• unreleased (object with changes, optional)
• versions (array of version objects; required)

Version object:

• version (string, X.Y.Z)
• date (string, YYYY-MM-DD)
• createdAt (string, YYYY-MM-DD HH:MM:SS; optional)
• changes (object): allowed keys: added, changed, fixed, removed, deprecated, security

Example changelog.json

{
  "title": "Changelog",
  "intro": "All notable changes to this project will be documented in this file.",
  "unreleased": {
    "changes": {
      "added": ["Upcoming feature"]
    }
  },
  "versions": [
    {
      "version": "0.3.0",
      "date": "2025-11-10",
      "changes": {
        "added": ["Support for title/intro/unreleased", "New sections: Deprecated/Security"],
        "changed": ["createdAt optional in schema"],
        "security": []
      }
    }
  ]
}

CHANGELOG.md (Markdown)

# Changelog

## [Unreleased]
### Added
- Upcoming feature

## [v0.3.0] - 2025-11-10
### Added
- Support for title/intro/unreleased
- New sections: Deprecated/Security

### Changed
- createdAt optional in schema

Validation Rules

The validator checks for:

• Valid JSON format
• Required fields
• Semantic versioning format (X.Y.Z)
• Valid date format (YYYY-MM-DD)
• Optional createdAt format (YYYY-MM-DD HH:ii:ss) when present
• Versions sorted in descending order
• No duplicate versions
• Valid change section keys (added, changed, fixed, removed, deprecated, security)

Development

Running Tests

composer test

Code Style

composer cs:check    # Check code style
composer cs:fix      # Fix code style

Static Analysis

composer stan

Requirements

• PHP >= 8.2
• Composer

Dependencies

• justinrainbow/json-schema: JSON Schema validation
• twig/twig: Markdown generation templates
• adachsoft/collection: Immutable collections
• phpunit/phpunit: Testing framework