kettle-changelog 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8737c49a9337bff6a8234bea1914fd8a054ca66a9fe1107b020cc80ef52205d2
-  data.tar.gz: e15afde1f514972d8417785a657c1a0b5c618fd3edca8a4e5be3c4f59aa7ff75
+  metadata.gz: af5e98644da17ca48d3b7e227af67da6a5a242e28e6c95d90e388f9584d5ee29
+  data.tar.gz: 202d219a65ec0b49398f87080bb705154e7651b2e69a90c49d044dbddcfc45a0
 SHA512:
-  metadata.gz: 8afab816b2675e3ca97449dd50176be20d4ec15723fa4107ccb98f6a6d0c8779467b823f5f472c569d9b856ba6229217c2e5ca7b5e2d300058453a1d79182197
-  data.tar.gz: fd565677b152771afcc28db39a541c061fe58d026c3dd9f571d97cab4801dd8d7b9365678c7fc8d23f5c5340882cce55c977c69e58ff5c109e1bbb3f85f19e28
+  metadata.gz: c269f93480ff1102fbf2b4972ee97d71724302f9585f3f6b7dd051dcb83db491500aaf7f967a083cdbe4a854db225e538e866b366ab42f0f53d34dd6fa80f1a0
+  data.tar.gz: 728692d54483daf73738e4c033419ba76ebd0713c10830900b07a498eb2ba22f93cae4eb383764ac9cc359088b3ad9175e1529fa5bf41d4be0d64be4bb429052

data/CHANGELOG.md

@@ -30,6 +30,17 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.0.2] - 2026-08-12
+
+- TAG: [v1.0.2][1.0.2t]
+- COVERAGE: 94.03% -- 1055/1122 lines in 6 files
+- BRANCH COVERAGE: 76.79% -- 364/474 branches in 6 files
+- 38.71% documented
+
+### Changed
+
+- Add structural [kc]-keyed upserts for maintenance changelog entries.
+
 ## [1.0.1] - 2026-08-11
 
 - TAG: [v1.0.1][1.0.1t]
@@ -127,7 +138,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-dev/kettle-changelog/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-changelog/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/kettle-dev/kettle-changelog/compare/v1.0.1...v1.0.2
+[1.0.2t]: https://github.com/kettle-dev/kettle-changelog/releases/tag/v1.0.2
 [1.0.1]: https://github.com/kettle-dev/kettle-changelog/compare/v1.0.0...v1.0.1
 [1.0.1t]: https://github.com/kettle-dev/kettle-changelog/releases/tag/v1.0.1
 [1.0.0]: https://github.com/kettle-dev/kettle-changelog/compare/v0.1.0...v1.0.0

data/README.md

@@ -395,7 +395,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.009-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.122-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-changelog/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/exe/kettle-changelog

@@ -63,7 +63,7 @@ end
 
 if ARGV.include?("-h") || ARGV.include?("--help")
   puts <<~USAGE
-    Usage: kettle-changelog [--version VERSION] [--yes] [--update-prep|--reformat|--backfill-released-version VERSION] [--pending-release] [--release-state] [--refresh-cache] [--add-unreleased-entry --section SECTION --entry TEXT] [--json|--events[=TYPES]] [--no-strict] [--no-coverage-threshold]
+    Usage: kettle-changelog [--version VERSION] [--yes] [--update-prep|--reformat|--backfill-released-version VERSION] [--pending-release] [--release-state] [--refresh-cache] [--add-unreleased-entry --section SECTION --entry TEXT] [--upsert-unreleased-entry --section SECTION --key KEY --entry TEXT] [--json|--events[=TYPES]] [--no-strict] [--no-coverage-threshold]
 
     Detects the current version from lib/**/version.rb, the latest live release, and
     the most recent CHANGELOG.md release section, then prompts to confirm the selected plan:
@@ -84,8 +84,11 @@ if ARGV.include?("-h") || ARGV.include?("--help")
       --release-status          Print changelog release state, including latest published release and pending sources
       --refresh-cache           Bypass cached gem.coop version data for this invocation
       --add-unreleased-entry    Add one entry to an existing section under ## [Unreleased]
+      --upsert-unreleased-entry Insert or replace one [kc]-keyed entry under ## [Unreleased]
       --section SECTION         Unreleased section to receive the entry (Added, Changed, Deprecated, Removed, Fixed, Security)
+      --key KEY                 Stable kettle-changelog key for --upsert-unreleased-entry
       --entry TEXT              Changelog entry text; "- " is added when omitted
+      --legacy-prefix TEXT      Legacy entry prefix to replace during a keyed upsert; may be repeated
       --json                    Print query output as JSON
       --events[=TYPES]          Print newline-delimited JSON changelog events
       --no-strict               Allow missing coverage and yard data (warnings only, no errors)
@@ -168,6 +171,7 @@ begin
   release_state_query = ARGV.delete("--release-state") || ARGV.delete("--release-status")
   refresh_cache = ARGV.delete("--refresh-cache")
   add_unreleased_entry = ARGV.delete("--add-unreleased-entry") || ARGV.delete("--add-changelog-entry")
+  upsert_unreleased_entry = ARGV.delete("--upsert-unreleased-entry") || ARGV.delete("--upsert-changelog-entry")
   json_output = ARGV.delete("--json")
   events_output, event_types = extract_events_arg!(ARGV)
   Kettle::Dev::ExitAdapter.abort("--events cannot be combined with --json") if events_output && json_output
@@ -193,8 +197,36 @@ begin
     value
   end
 
+  def extract_option_args!(argv, name)
+    values = []
+    while (value = extract_option_arg!(argv, name))
+      values << value
+    end
+    values
+  end
+
   historical_backfill_version = extract_option_arg!(ARGV, "--backfill-released-version")
 
+  if upsert_unreleased_entry
+    section = extract_option_arg!(ARGV, "--section")
+    key = extract_option_arg!(ARGV, "--key")
+    entry = extract_option_arg!(ARGV, "--entry")
+    legacy_prefixes = extract_option_args!(ARGV, "--legacy-prefix")
+    Kettle::Dev::ExitAdapter.abort("--section is required with --upsert-unreleased-entry") if section.to_s.empty?
+    Kettle::Dev::ExitAdapter.abort("--key is required with --upsert-unreleased-entry") if key.to_s.empty?
+    Kettle::Dev::ExitAdapter.abort("--entry is required with --upsert-unreleased-entry") if entry.to_s.empty?
+
+    result = Kettle::Changelog::KeyedEntryUpserter.new(
+      section: section,
+      key: key,
+      entry: entry,
+      legacy_prefixes: legacy_prefixes
+    ).run
+    message = result.fetch(:changed) ? "CHANGELOG.md keyed entry updated under Unreleased #{section}." : "CHANGELOG.md keyed entry already matches under Unreleased #{section}."
+    puts(json_output ? JSON.pretty_generate(result) : message)
+    exit(0)
+  end
+
   if add_unreleased_entry
     section = extract_option_arg!(ARGV, "--section")
     entry = extract_option_arg!(ARGV, "--entry")

data/lib/kettle/changelog/keyed_entry_upserter.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Changelog
+    class KeyedEntryUpserter
+      SECTIONS = %w[Added Changed Deprecated Removed Fixed Security].freeze
+      KEY_PREFIX = "[kc]"
+
+      def initialize(section:, key:, entry:, legacy_prefixes: [], root: Kettle::Dev::CIHelpers.project_root)
+        @root = root
+        @section = section.to_s
+        @key = key.to_s.strip
+        @entry = entry
+        @legacy_prefixes = Array(legacy_prefixes).map { |prefix| prefix.to_s.strip }.reject(&:empty?)
+        @changelog_path = ENV.fetch("K_CHANGELOG_PATH", File.join(@root, "CHANGELOG.md"))
+      end
+
+      def run
+        validate!
+        source = read_source!
+        matches = find_matches(source)
+        if matches.count { |match| match.fetch(:kind) == :keyed } > 1
+          raise Error, "expected at most one #{key_label} entry in CHANGELOG.md"
+        end
+        if matches.any? { |match| match.fetch(:kind) == :keyed } && matches.any? { |match| match.fetch(:kind) == :legacy }
+          raise Error, "found both keyed and legacy entries for #{key_label} in CHANGELOG.md"
+        end
+
+        body = @entry.respond_to?(:call) ? @entry.call(matches) : @entry
+        rendered = render_entry(body)
+        changed = matches.empty? || matches.any? { |match| normalize_source(match.fetch(:source)) != normalize_source(rendered) } || matches.length > 1
+        write_updated_source(source, rendered, matches) if changed
+
+        matched = if matches.empty?
+          "inserted"
+        elsif matches.first.fetch(:kind) == :legacy
+          "legacy"
+        else
+          "keyed"
+        end
+
+        {
+          changed: changed,
+          key: @key,
+          section: @section,
+          entry: rendered,
+          matched: matched
+        }
+      end
+
+      private
+
+      def validate!
+        raise Error, "unsupported changelog section #{@section.inspect}" unless SECTIONS.include?(@section)
+        raise Error, "changelog key must not be empty" if @key.empty?
+        raise Error, "changelog key must not contain whitespace" if @key.match?(/\s/)
+        raise Error, "missing CHANGELOG.md in #{Kettle::Dev.display_path(@root)}" unless File.file?(@changelog_path)
+      end
+
+      def read_source!
+        File.read(@changelog_path)
+      end
+
+      def require_markly!
+        require "ast/crispr/markdown/markly"
+      rescue LoadError => error
+        raise Error, "kettle-changelog keyed entry updates require ast-crispr-markdown-markly (#{error.message})"
+      end
+
+      def find_matches(source)
+        require_markly!
+        context = Ast::Crispr::Markdown::Markly.document_context(content: source, source_label: @changelog_path)
+        sections = context.structural_owners(owner_scope: :heading_sections)
+        unreleased = find_unreleased_heading!(sections)
+        target = find_unreleased_section!(sections, unreleased)
+        items = context.structural_owners(owner_scope: :list_items).select do |item|
+          item.depth == 1 && within?(item, target)
+        end
+
+        items.filter_map do |item|
+          kind = if keyed_item?(item.source)
+            :keyed
+          elsif legacy_item?(item.source)
+            :legacy
+          end
+          next unless kind
+
+          {
+            kind: kind,
+            source: item.source,
+            start_line: item.location.start_line,
+            end_line: item.location.end_line
+          }
+        end
+      end
+
+      def find_unreleased_heading!(sections)
+        matches = sections.select do |owner|
+          owner.level == 2 && owner.heading_source.to_s.strip == "## [Unreleased]"
+        end
+        raise Error, "expected exactly one ## [Unreleased] section in CHANGELOG.md, found #{matches.length}" unless matches.length == 1
+
+        matches.first
+      end
+
+      def find_unreleased_section!(sections, unreleased)
+        matches = sections.select do |owner|
+          owner.heading_text.to_s.strip == @section &&
+            owner.level == 3 &&
+            owner.location.start_line > unreleased.location.start_line &&
+            owner.location.end_line <= unreleased.location.end_line
+        end
+        raise Error, "expected at least one ### #{@section} section under ## [Unreleased] in CHANGELOG.md, found none" if matches.empty?
+
+        matches.first
+      end
+
+      def within?(item, section)
+        item.location.start_line > section.location.start_line &&
+          item.location.end_line <= section.location.end_line
+      end
+
+      def keyed_item?(source)
+        first_line(source).match?(/\A[-*]\s+\[kc\]\s+#{Regexp.escape(@key)}(?:\s|:)/)
+      end
+
+      def legacy_item?(source)
+        return false if @legacy_prefixes.empty?
+
+        text = first_line(source).sub(/\A[-*]\s+/, "").strip
+        @legacy_prefixes.any? { |prefix| text.start_with?(prefix) }
+      end
+
+      def first_line(source)
+        source.to_s.lines.first.to_s.strip
+      end
+
+      def key_label
+        "#{KEY_PREFIX} #{@key}"
+      end
+
+      def render_entry(body)
+        text = body.to_s.strip
+        raise Error, "changelog entry must not be empty" if text.empty?
+        raise Error, "keyed changelog entry body must not include a list marker" if text.lines.first.to_s.match?(/\A[-*]\s+/)
+
+        first, *rest = text.lines.map(&:rstrip)
+        (["- #{key_label}: #{first}"] + rest).join("\n") + "\n\n"
+      end
+
+      def normalize_source(source)
+        source.to_s.strip
+      end
+
+      def write_updated_source(source, rendered, matches)
+        if matches.empty?
+          File.write(@changelog_path, insert_entry(source, rendered))
+          return
+        end
+
+        lines = source.lines
+        matches.sort_by { |match| match.fetch(:start_line) }.reverse_each.with_index do |match, index|
+          start_index = match.fetch(:start_line) - 1
+          end_index = match.fetch(:end_line)
+          replacement = index.zero? ? rendered.lines : []
+          lines[start_index...end_index] = replacement
+        end
+        File.write(@changelog_path, lines.join)
+      end
+
+      def insert_entry(source, rendered)
+        require_markly!
+        context = Ast::Crispr::Markdown::Markly.document_context(content: source, source_label: @changelog_path)
+        sections = context.structural_owners(owner_scope: :heading_sections)
+        unreleased = find_unreleased_heading!(sections)
+        target = find_unreleased_section!(sections, unreleased)
+        lines = source.lines
+        index = target.location.end_line
+        while index > target.location.start_line && lines.fetch(index - 1).strip.empty?
+          index -= 1
+        end
+
+        previous_line = lines[index - 1].to_s
+        next_line = lines[index].to_s
+        before = previous_line.strip.empty? ? "" : "\n"
+        after = (next_line.empty? || next_line.strip.empty?) ? "" : "\n"
+        lines.insert(index, "#{before}#{rendered.rstrip}\n#{after}")
+        lines.join
+      end
+    end
+  end
+end

data/lib/kettle/changelog/version.rb

@@ -5,7 +5,7 @@ module Kettle
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = "1.0.1"
+      VERSION = "1.0.2"
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

data/lib/kettle/changelog.rb

@@ -10,6 +10,7 @@ module Kettle
 
     autoload :CLI, "kettle/changelog/cli"
     autoload :EntryAdder, "kettle/changelog/entry_adder"
+    autoload :KeyedEntryUpserter, "kettle/changelog/keyed_entry_upserter"
     autoload :TransferMerger, "kettle/changelog/transfer_merger"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-changelog
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Peter H. Boling
@@ -295,6 +295,7 @@ files:
 - lib/kettle/changelog.rb
 - lib/kettle/changelog/cli.rb
 - lib/kettle/changelog/entry_adder.rb
+- lib/kettle/changelog/keyed_entry_upserter.rb
 - lib/kettle/changelog/transfer_merger.rb
 - lib/kettle/changelog/version.rb
 - sig/kettle/changelog.rbs
@@ -303,10 +304,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-changelog.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-changelog/tree/v1.0.1
-  changelog_uri: https://github.com/kettle-dev/kettle-changelog/blob/v1.0.1/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-changelog/tree/v1.0.2
+  changelog_uri: https://github.com/kettle-dev/kettle-changelog/blob/v1.0.2/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-changelog/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-changelog/1.0.1
+  documentation_uri: https://www.rubydoc.info/gems/kettle-changelog/1.0.2
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-changelog/wiki
   news_uri: https://www.railsbling.com/tags/kettle-changelog