changelog-parser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a52b0f653d48af02c20cc4f1287dad6a76bcdc66efb802ba80470b21659a027e
+  data.tar.gz: f77abb93586e09bdf5b11e9e8022ab5d86656ec07ccbfad74fbd73c7f9cbed82
+SHA512:
+  metadata.gz: 1fb1a622fe5b843d14f092acd112824221478ed0ec316b603d99f83e2dede43a31df04833fc226aa00a5574dd509731f3d88a62f19b91eed5cfa298740b6e9cc
+  data.tar.gz: 9d7c22d58a1520b85215c578778754d68d797fee125ee4cedd0e64cdb5caa6534d9935c9c3d19efb49a567b458ce6fa86393046f366cd7c8e0f2649593d80976

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-23
+
+### Added
+
+- Core changelog parsing with auto-format detection
+- Support for Keep a Changelog, markdown headers, and underline formats
+- Custom regex pattern support for non-standard formats
+- CLI with JSON output, version listing, and content extraction

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"changelog-parser" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["andrewnez@gmail.com"](mailto:"andrewnez@gmail.com").

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrew Nesbitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,219 @@
+# Changelog::Parser
+
+A Ruby gem for parsing changelog files into structured data. Supports the Keep a Changelog format, markdown headers, and custom patterns. Zero runtime dependencies.
+
+Inspired by [vandamme](https://github.com/tech-angels/vandamme).
+
+## Installation
+
+```bash
+gem install changelog-parser
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "changelog-parser"
+```
+
+## Usage
+
+### Ruby API
+
+```ruby
+require "changelog/parser"
+
+# Parse a string
+changelog = File.read("CHANGELOG.md")
+parser = Changelog::Parser.new(changelog)
+result = parser.parse
+
+# Or use the class method
+result = Changelog::Parser.parse(changelog)
+
+# Or parse a file directly
+result = Changelog::Parser.parse_file("CHANGELOG.md")
+```
+
+The result is a hash where keys are version strings and values contain the date and content:
+
+```ruby
+{
+  "Unreleased" => { date: nil, content: "### Added\n- New feature" },
+  "1.0.0" => { date: #<Date: 2024-01-15>, content: "### Added\n- Initial release" }
+}
+```
+
+### Accessing versions
+
+```ruby
+parser = Changelog::Parser.new(changelog)
+
+# Get all version strings
+parser.versions
+# => ["Unreleased", "1.0.0"]
+
+# Get a specific version
+parser["1.0.0"]
+# => { date: #<Date: 2024-01-15>, content: "..." }
+
+# Convert to JSON
+parser.to_json
+
+# Convert to HTML (requires a markdown gem)
+parser.to_html
+```
+
+### HTML conversion
+
+The `to_html` method converts markdown content to HTML. It requires one of these optional gems to be installed separately:
+
+- [commonmarker](https://github.com/gjtorikian/commonmarker)
+- [redcarpet](https://github.com/vmg/redcarpet)
+- [kramdown](https://github.com/gettalong/kramdown)
+
+```ruby
+gem "commonmarker" # Add to your Gemfile
+
+parser.to_html
+# => { "1.0.0" => { date: #<Date>, content: "<ul><li>Feature</li></ul>" } }
+```
+
+### Formats
+
+The parser auto-detects the changelog format. You can also specify it explicitly:
+
+```ruby
+# Keep a Changelog: ## [1.0.0] - 2024-01-15
+Changelog::Parser.new(content, format: :keep_a_changelog)
+
+# Markdown headers: ## 1.0.0 or ### v1.0.0 (2024-01-15)
+Changelog::Parser.new(content, format: :markdown)
+
+# Underline style: 1.0.0\n=====
+Changelog::Parser.new(content, format: :underline)
+```
+
+### Custom patterns
+
+For changelogs with non-standard formats, provide a custom regex:
+
+```ruby
+# Custom format: "Version 1.0.0 released 2024-01-15"
+pattern = /^Version ([\d.]+) released (\d{4}-\d{2}-\d{2})/
+parser = Changelog::Parser.new(content, version_pattern: pattern)
+```
+
+The first capture group should be the version string. The second capture group (if present) is parsed as a date.
+
+## CLI
+
+The gem includes a command-line interface:
+
+```bash
+# Parse a changelog and output JSON
+changelog-parser CHANGELOG.md
+
+# Pretty print JSON
+changelog-parser --pretty CHANGELOG.md
+
+# List versions only
+changelog-parser --list CHANGELOG.md
+
+# Get a specific version
+changelog-parser --version 1.0.0 CHANGELOG.md
+
+# Get content only for a version
+changelog-parser --version 1.0.0 --content CHANGELOG.md
+
+# Specify format
+changelog-parser --format keep_a_changelog CHANGELOG.md
+
+# Read from stdin
+cat CHANGELOG.md | changelog-parser -
+
+# Custom regex pattern
+changelog-parser --pattern "^## v([\d.]+)" CHANGELOG.md
+```
+
+### CLI options
+
+```
+-f, --format FORMAT      Changelog format (keep_a_changelog, markdown, underline)
+-v, --version VERSION    Show only a specific version
+-l, --list               List versions only
+-c, --content            Output content only (requires --version)
+-p, --pattern REGEX      Custom version header regex pattern
+-m, --match-group N      Regex capture group for version (default: 1)
+    --pretty             Pretty print JSON output
+-h, --help               Show help message
+    --gem-version        Show gem version
+```
+
+## Supported formats
+
+### Keep a Changelog
+
+The default format follows the [Keep a Changelog](https://keepachangelog.com) specification:
+
+```markdown
+## [Unreleased]
+
+## [1.0.0] - 2024-01-15
+
+### Added
+- New feature
+```
+
+### Markdown headers
+
+Standard markdown headers with optional dates:
+
+```markdown
+## 1.0.0 (2024-01-15)
+
+### v0.9.0
+```
+
+### Underline style
+
+Setext-style headers:
+
+```markdown
+1.0.0
+=====
+```
+
+## Vandamme compatibility
+
+For projects migrating from the [vandamme](https://github.com/tech-angels/vandamme) gem, a compatibility layer is provided:
+
+```ruby
+require "changelog/parser/vandamme"
+
+parser = Vandamme::Parser.new(
+  changelog: content,
+  version_header_exp: /^## ([\d.]+)/,
+  format: :markdown,
+  match_group: 1
+)
+
+# Returns plain strings like vandamme (no date hash)
+parser.parse
+# => { "1.0.0" => "### Added\n- Feature" }
+
+# HTML conversion (requires markdown gem)
+parser.to_html
+# => { "1.0.0" => "<h3>Added</h3><ul><li>Feature</li></ul>" }
+```
+
+## Development
+
+```bash
+bin/setup
+rake test
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/exe/changelog-parser

@@ -0,0 +1,132 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require_relative "../lib/changelog/parser"
+
+options = {
+  format: nil,
+  output: :json,
+  version: nil
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: changelog-parser [options] [file]"
+  opts.separator ""
+  opts.separator "Parse changelog files and extract version information."
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("-f", "--format FORMAT", %i[keep_a_changelog markdown underline],
+          "Changelog format (keep_a_changelog, markdown, underline)") do |f|
+    options[:format] = f
+  end
+
+  opts.on("-v", "--version VERSION", "Show only a specific version") do |v|
+    options[:version] = v
+  end
+
+  opts.on("-l", "--list", "List versions only") do
+    options[:output] = :list
+  end
+
+  opts.on("-c", "--content", "Output content only (requires --version)") do
+    options[:output] = :content
+  end
+
+  opts.on("-p", "--pattern REGEX", "Custom version header regex pattern") do |p|
+    options[:pattern] = Regexp.new(p)
+  end
+
+  opts.on("-m", "--match-group N", Integer, "Regex capture group for version (default: 1)") do |n|
+    options[:match_group] = n
+  end
+
+  opts.on("--pretty", "Pretty print JSON output") do
+    options[:pretty] = true
+  end
+
+  opts.on_tail("-h", "--help", "Show this help message") do
+    puts opts
+    exit
+  end
+
+  opts.on_tail("--gem-version", "Show gem version") do
+    puts Changelog::Parser::VERSION
+    exit
+  end
+end
+
+begin
+  parser.parse!
+rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e
+  warn "Error: #{e.message}"
+  warn parser
+  exit 1
+end
+
+input = if ARGV.empty? || ARGV.first == "-"
+  $stdin.read
+else
+  file = ARGV.first
+  unless File.exist?(file)
+    warn "Error: File not found: #{file}"
+    exit 1
+  end
+  File.read(file)
+end
+
+if input.nil? || input.empty?
+  warn "Error: No input provided"
+  warn parser
+  exit 1
+end
+
+parsed = Changelog::Parser.new(
+  input,
+  format: options[:format],
+  version_pattern: options[:pattern],
+  match_group: options[:match_group] || 1
+)
+
+result = parsed.parse
+
+case options[:output]
+when :list
+  puts result.keys.join("\n")
+when :content
+  unless options[:version]
+    warn "Error: --content requires --version"
+    exit 1
+  end
+  entry = result[options[:version]]
+  if entry
+    puts entry[:content]
+  else
+    warn "Version not found: #{options[:version]}"
+    exit 1
+  end
+when :json
+  output = if options[:version]
+    entry = result[options[:version]]
+    unless entry
+      warn "Version not found: #{options[:version]}"
+      exit 1
+    end
+    { options[:version] => entry }
+  else
+    result
+  end
+
+  # Convert dates to strings for JSON
+  json_output = output.transform_values do |entry|
+    entry.transform_values { |v| v.is_a?(Date) ? v.to_s : v }
+  end
+
+  if options[:pretty]
+    puts JSON.pretty_generate(json_output)
+  else
+    puts JSON.generate(json_output)
+  end
+end

data/lib/changelog/parser/vandamme.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../parser"
+
+module Vandamme
+  class Parser
+    attr_reader :parser
+
+    def initialize(changelog: "", version_header_exp: nil, format: nil, match_group: 1)
+      @parser = Changelog::Parser.new(
+        changelog,
+        version_pattern: version_header_exp,
+        format: format,
+        match_group: match_group
+      )
+    end
+
+    def parse
+      @parser.parse.transform_values { |entry| entry[:content] }
+    end
+
+    def to_html
+      parsed = parse
+      parsed.transform_values { |content| render_html(content) }
+    end
+
+    def render_html(content)
+      return content if content.nil? || content.empty?
+
+      if defined?(Commonmarker)
+        Commonmarker.to_html(content)
+      elsif defined?(CommonMarker)
+        CommonMarker.render_html(content)
+      elsif defined?(Redcarpet)
+        markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML)
+        markdown.render(content)
+      elsif defined?(Kramdown)
+        Kramdown::Document.new(content).to_html
+      else
+        raise Changelog::Parser::Error,
+          "No markdown renderer found. Install commonmarker, redcarpet, or kramdown."
+      end
+    end
+  end
+end

data/lib/changelog/parser/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Changelog
+  class Parser
+    VERSION = "0.1.0"
+  end
+end

data/lib/changelog/parser.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "parser/version"
+
+module Changelog
+  class Parser
+    class Error < StandardError; end
+    class ParseError < Error; end
+
+    # Keep a Changelog format: ## [1.0.0] - 2024-01-15 or ## [Unreleased]
+    KEEP_A_CHANGELOG = /^##\s+\[([^\]]+)\](?:\s+-\s+(\d{4}-\d{2}-\d{2}))?/
+
+    # Markdown headers with version: ## 1.0.0 or ### v1.0.0 (2024-01-15)
+    MARKDOWN_HEADER = /^\#{1,3}\s+v?([\w.+-]+\.[\w.+-]+[a-zA-Z0-9])(?:\s+\((\d{4}-\d{2}-\d{2})\))?/
+
+    # Underline style: 1.0.0\n===== or 1.0.0\n-----
+    UNDERLINE_HEADER = /^([\w.+-]+\.[\w.+-]+[a-zA-Z0-9])\n[=-]+/
+
+    FORMATS = {
+      keep_a_changelog: KEEP_A_CHANGELOG,
+      markdown: MARKDOWN_HEADER,
+      underline: UNDERLINE_HEADER
+    }.freeze
+
+    attr_reader :changelog, :version_pattern, :match_group
+
+    def initialize(changelog, format: nil, version_pattern: nil, match_group: 1)
+      @changelog = changelog.to_s
+      @version_pattern = resolve_pattern(format, version_pattern)
+      @match_group = match_group
+    end
+
+    def parse
+      return {} if changelog.empty?
+
+      versions = {}
+      matches = find_version_matches
+
+      matches.each_with_index do |match, index|
+        version = match[:version]
+        start_pos = match[:end_pos]
+        end_pos = matches[index + 1]&.dig(:start_pos) || changelog.length
+
+        content = changelog[start_pos...end_pos].strip
+        versions[version] = build_entry(match, content)
+      end
+
+      versions
+    end
+
+    def versions
+      parse.keys
+    end
+
+    def [](version)
+      parse[version]
+    end
+
+    def to_h
+      parse
+    end
+
+    def to_json(*)
+      require "json"
+      parse.to_json
+    end
+
+    def to_html
+      parse.transform_values do |entry|
+        {
+          date: entry[:date],
+          content: render_html(entry[:content])
+        }
+      end
+    end
+
+    def render_html(content)
+      return content if content.nil? || content.empty?
+
+      if defined?(Commonmarker)
+        Commonmarker.to_html(content)
+      elsif defined?(CommonMarker)
+        CommonMarker.render_html(content)
+      elsif defined?(Redcarpet)
+        markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML)
+        markdown.render(content)
+      elsif defined?(Kramdown)
+        Kramdown::Document.new(content).to_html
+      else
+        raise Error, "No markdown renderer found. Install commonmarker, redcarpet, or kramdown."
+      end
+    end
+
+    def self.parse(changelog, **options)
+      new(changelog, **options).parse
+    end
+
+    def self.parse_file(path, **options)
+      content = File.read(path)
+      new(content, **options).parse
+    end
+
+    def resolve_pattern(format, custom_pattern)
+      return custom_pattern if custom_pattern
+      return FORMATS.fetch(format) if format
+
+      detect_format
+    end
+
+    def detect_format
+      return KEEP_A_CHANGELOG if changelog.match?(KEEP_A_CHANGELOG)
+      return UNDERLINE_HEADER if changelog.match?(UNDERLINE_HEADER)
+
+      MARKDOWN_HEADER
+    end
+
+    def find_version_matches
+      matches = []
+      scanner = StringScanner.new(changelog)
+
+      while scanner.scan_until(version_pattern)
+        matched = scanner.matched
+        match_data = matched.match(version_pattern)
+
+        matches << {
+          version: match_data[match_group],
+          date: extract_date(match_data),
+          start_pos: scanner.pos - matched.length,
+          end_pos: scanner.pos
+        }
+      end
+
+      matches
+    end
+
+    def extract_date(match_data)
+      return nil if match_data.captures.length < 2
+
+      date_str = match_data[match_group + 1]
+      return nil unless date_str
+
+      Date.parse(date_str) rescue nil
+    end
+
+    def build_entry(match, content)
+      {
+        date: match[:date],
+        content: content
+      }
+    end
+  end
+end
+
+require "strscan"
+require "date"

data/sig/changelog/parser.rbs

@@ -0,0 +1,6 @@
+module Changelog
+  module Parser
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: changelog-parser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrew Nesbitt
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby gem for parsing changelog files. Supports Keep a Changelog format,
+  markdown headers, and custom patterns. Zero runtime dependencies.
+email:
+- andrewnez@gmail.com
+executables:
+- changelog-parser
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE
+- README.md
+- Rakefile
+- exe/changelog-parser
+- lib/changelog/parser.rb
+- lib/changelog/parser/vandamme.rb
+- lib/changelog/parser/version.rb
+- sig/changelog/parser.rbs
+homepage: https://github.com/andrew/changelog-parser
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/andrew/changelog-parser
+  source_code_uri: https://github.com/andrew/changelog-parser
+  changelog_uri: https://github.com/andrew/changelog-parser/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.1
+specification_version: 4
+summary: Parse changelog files into structured data
+test_files: []