gem_kit-release 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d42874e3ef31b2b7ecdad0cdd3acd28a62a2d38c7b3a6476c5a5d449dc27311b
+  data.tar.gz: 639dc539b8171640bd2f2f91d193d8c2f2278724d20a1594f6dafa050bfb9942
+SHA512:
+  metadata.gz: 29e0b353656610e5adcbc79395753e4f7b2476218681da112d73070bd9dd2db2d53f7fb657225c5c11cd0760ca6a77f8942bda25f0931c7ba5cc3d32612207c4
+  data.tar.gz: b8a4daca35ca2dd5c5de72d2b1ff2d288ced5989125368049376aaee6df9ef5e31b5aedb7457667f6d43c248d0cf2337db23071d225b2a5b11633e5288975b59

data/lib/gem_kit/release/changelog.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require "date"
+
+module GemKit
+  module Release
+    # A parser and linter for CHANGELOG.md, which follows
+    # [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+    #
+    # The changelog is the one release artefact nothing else can regenerate, so
+    # it is the one most easily forgotten. Making it machine-checkable turns
+    # "did anyone write the changelog?" into a gate: `gem_kit-release check`
+    # validates the format, and refuses to release a version that has no
+    # section of its own.
+    #
+    #   changelog = GemKit::Release::Changelog.load
+    #   changelog.problems              # => [] when the format is clean
+    #   changelog.release_problems("4.1.0")
+    #
+    # The shape it expects:
+    #
+    #   # Changelog
+    #
+    #   ## [Unreleased]
+    #
+    #   ## [4.1.0] - 2026-08-20
+    #
+    #   ### Added
+    #
+    #   - Something that happened.
+    #
+    class Changelog
+      # The six change types Keep a Changelog defines. Anything else under a
+      # version is a typo or an invention, and both are worth catching.
+      SECTIONS = %w[Added Changed Deprecated Removed Fixed Security].freeze
+
+      UNRELEASED       = "Unreleased"
+      HEADING          = /\A##\s+\[([^\]]+)\](?:\s+-\s+(.*))?\s*\z/
+      SUBHEADING       = /\A###\s+(.*?)\s*\z/
+      BULLET           = /\A[-*]\s+\S/
+      DATE             = /\A\d{4}-\d{2}-\d{2}\z/
+
+      # One `## [...]` section of the file.
+      Release = Struct.new(:version, :date, :line, :subsections, keyword_init: true) do
+        def unreleased? = version == UNRELEASED
+        def empty? = subsections.empty? || subsections.values.all?(&:empty?)
+        def to_s = unreleased? ? "[#{version}]" : "[#{version}] - #{date}"
+      end
+
+      # Load the changelog sitting beside the gem (../../CHANGELOG.md).
+      def self.load(path = File.join(Dir.pwd, "CHANGELOG.md"))
+        new(File.exist?(path) ? File.read(path) : nil, path: path)
+      end
+
+      attr_reader :path, :releases
+
+      # @parameter text [String, nil] the file's contents; nil means "no file".
+      def initialize(text, path: "CHANGELOG.md")
+        @path     = path
+        @text     = text
+        @releases = text ? parse(text) : []
+      end
+
+      def missing? = @text.nil?
+
+      def unreleased = releases.find(&:unreleased?)
+
+      def released = releases.reject(&:unreleased?)
+
+      def find(version)
+        target = Gem::Version.new(version.to_s)
+        released.find { |release| Gem::Version.new(release.version) == target rescue false }
+      end
+
+      # Everything wrong with the file's *format*, as a list of human-readable
+      # problems. Empty means it lints clean.
+      def problems
+        return ["#{path} does not exist"] if missing?
+
+        [*header_problems, *heading_problems, *ordering_problems, *content_problems]
+      end
+
+      # Everything standing between this changelog and releasing `version`.
+      # Format problems count: a file nobody can parse is not documentation.
+      def release_problems(version)
+        return problems unless problems.empty?
+
+        release = find(version)
+        return ["#{path} has no section for #{version} — run gem_kit-release changelog"] if release.nil?
+        return ["#{path} section for #{version} is empty"] if release.empty?
+
+        newest = released.first
+        if newest && newest.version != release.version
+          return ["#{path} lists #{newest.version} above #{version}; the release being cut must come first"]
+        end
+
+        []
+      end
+
+      private
+
+        # Split the file into `## [...]` sections, recording each one's
+        # `### Type` subsections and their top-level bullets.
+        def parse(text)
+          found   = []
+          current = nil
+          heading = nil
+
+          text.each_line.with_index(1) do |line, number|
+            case line
+            when HEADING
+              heading = nil
+              current = Release.new(version: $1, date: $2&.strip, line: number, subsections: {})
+              found << current
+            when SUBHEADING
+              next unless current
+
+              heading = $1
+              (current.subsections[heading] ||= [])
+            when BULLET
+              current.subsections[heading] << line.strip if current && heading
+            end
+          end
+
+          found
+        end
+
+        def header_problems
+          first = @text.each_line.find { |line| !line.strip.empty? }
+          return [] if first&.strip == "# Changelog"
+
+          ["#{path}:1 must start with the title `# Changelog`"]
+        end
+
+        def heading_problems
+          problems = []
+
+          @text.each_line.with_index(1) do |line, number|
+            next unless line.start_with?("## ") && !line.start_with?("###")
+
+            unless line =~ HEADING
+              problems << "#{path}:#{number} malformed version heading: #{line.strip.inspect} " \
+                          "(expected `## [Unreleased]` or `## [1.2.3] - YYYY-MM-DD`)"
+              next
+            end
+
+            version, date = $1, $2&.strip
+            next if version == UNRELEASED
+
+            problems << "#{path}:#{number} #{version} has no date (expected `## [#{version}] - YYYY-MM-DD`)" if date.nil? || date.empty?
+            problems << "#{path}:#{number} #{version} has a malformed date: #{date.inspect}" if date && !date.empty? && date !~ DATE
+            problems << "#{path}:#{number} #{version} is not a valid version number" unless valid_version?(version)
+          end
+
+          problems + subheading_problems
+        end
+
+        def subheading_problems
+          @text.each_line.with_index(1).filter_map do |line, number|
+            next unless line.start_with?("### ")
+            next if line =~ SUBHEADING && SECTIONS.include?($1)
+
+            "#{path}:#{number} unknown section #{line.sub("###", "").strip.inspect} " \
+              "(expected one of: #{SECTIONS.join(", ")})"
+          end
+        end
+
+        def ordering_problems
+          problems = []
+
+          if unreleased && releases.first&.unreleased? == false
+            problems << "#{path}:#{unreleased.line} [Unreleased] must be the first section"
+          end
+
+          seen = {}
+          released.each do |release|
+            if (first = seen[release.version])
+              problems << "#{path}:#{release.line} duplicate section for #{release.version} (also at line #{first})"
+            end
+            seen[release.version] ||= release.line
+          end
+
+          versions = released.select { |release| valid_version?(release.version) }
+          versions.each_cons(2) do |newer, older|
+            next if Gem::Version.new(newer.version) > Gem::Version.new(older.version)
+
+            problems << "#{path}:#{older.line} #{older.version} is listed below #{newer.version}; " \
+                        "releases must run newest to oldest"
+          end
+
+          problems
+        end
+
+        def content_problems
+          released.flat_map do |release|
+            if release.subsections.empty?
+              ["#{path}:#{release.line} #{release} has no #{SECTIONS.join("/")} section"]
+            else
+              release.subsections.filter_map do |heading, bullets|
+                "#{path}:#{release.line} #{release} has an empty `### #{heading}` section" if bullets.empty?
+              end
+            end
+          end
+        end
+
+        def valid_version?(version)
+          Gem::Version.correct?(version)
+        end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/changelog" do
+  # Build a changelog from a body, with the standard title already in place.
+  changelog = lambda do |body|
+    GemKit::Release::Changelog.new("# Changelog\n\n#{body}")
+  end
+
+  good = <<~MD
+    ## [Unreleased]
+
+    ## [4.1.0] - 2026-08-20
+
+    ### Added
+
+    - A thing.
+
+    ## [4.0.0] - 2026-08-01
+
+    ### Removed
+
+    - An older thing.
+  MD
+
+  it "parses sections, dates and bullets" do
+    log = changelog.call(good)
+
+    log.releases.map(&:version).should == ["Unreleased", "4.1.0", "4.0.0"]
+    log.unreleased.should.be.kind_of?(GemKit::Release::Changelog::Release)
+    log.released.first.date.should == "2026-08-20"
+    log.released.first.subsections["Added"].should == ["- A thing."]
+    log.find("4.0.0").subsections["Removed"].size.should == 1
+  end
+
+  it "lints a well-formed file clean and clears it for release" do
+    log = changelog.call(good)
+
+    log.problems.should == []
+    log.release_problems("4.1.0").should == []
+  end
+
+  it "requires the `# Changelog` title" do
+    GemKit::Release::Changelog.new("## [1.0.0] - 2026-01-01\n\n### Added\n\n- x\n")
+      .problems.first.should.match(/must start with the title/)
+  end
+
+  it "reports a missing file" do
+    log = GemKit::Release::Changelog.new(nil, path: "nope.md")
+    log.missing?.should.be.true
+    log.problems.first.should.match(/does not exist/)
+  end
+
+  it "rejects a malformed version heading" do
+    changelog.call("## 1.0.0\n").problems.first.should.match(/malformed version heading/)
+  end
+
+  it "rejects an undated or badly dated release" do
+    changelog.call("## [1.0.0]\n\n### Added\n\n- x\n").problems.first.should.match(/has no date/)
+    changelog.call("## [1.0.0] - 20260101\n\n### Added\n\n- x\n").problems.first.should.match(/malformed date/)
+  end
+
+  it "rejects an unknown section type" do
+    changelog.call("## [1.0.0] - 2026-01-01\n\n### Improved\n\n- x\n")
+      .problems.first.should.match(/unknown section "Improved"/)
+  end
+
+  it "rejects an empty release and an empty subsection" do
+    changelog.call("## [1.0.0] - 2026-01-01\n").problems.first.should.match(/has no Added/)
+    changelog.call("## [1.0.0] - 2026-01-01\n\n### Added\n\n## [0.9.0] - 2026-01-01\n\n### Added\n\n- x\n")
+      .problems.first.should.match(/empty `### Added` section/)
+  end
+
+  it "rejects duplicates and out-of-order releases" do
+    body = "## [1.0.0] - 2026-01-02\n\n### Added\n\n- x\n\n## [1.0.0] - 2026-01-01\n\n### Added\n\n- y\n"
+    changelog.call(body).problems.first.should.match(/duplicate section for 1\.0\.0/)
+
+    body = "## [1.0.0] - 2026-01-01\n\n### Added\n\n- x\n\n## [2.0.0] - 2026-01-02\n\n### Added\n\n- y\n"
+    changelog.call(body).problems.first.should.match(/must run newest to oldest/)
+  end
+
+  it "requires [Unreleased] to come first" do
+    body = "## [1.0.0] - 2026-01-01\n\n### Added\n\n- x\n\n## [Unreleased]\n"
+    changelog.call(body).problems.first.should.match(/\[Unreleased\] must be the first section/)
+  end
+
+  it "blocks a release with no section of its own" do
+    changelog.call(good).release_problems("9.9.9").first.should.match(/no section for 9\.9\.9/)
+  end
+
+  it "blocks a release that is not the newest section" do
+    changelog.call(good).release_problems("4.0.0").first.should.match(/lists 4\.1\.0 above 4\.0\.0/)
+  end
+
+  it "reports format problems ahead of release problems" do
+    changelog.call("## nonsense\n").release_problems("4.1.0").first.should.match(/malformed version heading/)
+  end
+
+  it "loads the repo's own CHANGELOG.md" do
+    GemKit::Release::Changelog.load.missing?.should.be.false
+  end
+end

data/lib/gem_kit/release/cli/bump.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module GemKit
+  module Release
+    module CLI
+      # The deadline check lives here rather than at release time because the
+      # bump is the last moment anyone can be stopped: once the version file
+      # says 5.0.0, every promise to disappear "in 5.0" is already broken.
+      class Bump < Command
+        desc "Move the gem version, refusing to bump onto a deprecation deadline"
+
+        argument :segment,
+                 type: :string, required: false, default: "patch",
+                 values: %w[major minor patch],
+                 desc: "Which segment of the version to move"
+
+        option :force,
+               type: :boolean, default: false,
+               desc: "Bump even when a deprecation comes due"
+
+        example [
+          "minor              # 4.1.0 -> 4.2.0",
+          "major              # refused while a 5.0 deprecation is still in the tree",
+          "major --force      # bump anyway, saying what it overrode",
+        ]
+
+        def call(segment: "patch", **options)
+          current = project.version.to_s
+
+          begin
+            target = VersionFile.bump(current, segment)
+          rescue VersionFile::Error => error
+            fail_with(error.message)
+          end
+
+          problems = gate.bump_problems(target)
+          unless problems.empty?
+            unless options[:force]
+              refuse("Refusing to bump #{current} -> #{target}:",
+                     problems + ["", "Remove them, then bump. Override with --force."])
+            end
+
+            say("--force given; bumping past #{problems.size} deprecation(s) anyway.")
+          end
+
+          version_file.write(target)
+          say("#{current} -> #{target}")
+
+          upcoming = gate.upcoming_deprecations(target)
+          unless upcoming.empty?
+            say("#{upcoming.size} deprecation(s) still outstanding (none due in #{target}).")
+          end
+
+          # The changelog is the one release artefact nothing regenerates, and
+          # the one most easily forgotten — so say so loudly.
+          say
+          say("#{RED}now run: gem kit changelog --write#{RESET}")
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/cli/bump" do
+  require_relative "../../../../spec/support/gem_kit_release_spec"
+  extend GemKitReleaseSpec
+
+  it "moves the version and points at the changelog" do
+    with_gem do |dir|
+      status, out, _err = invoke(["bump", "minor"], dir)
+
+      status.should == 0
+      out.should.match(/1\.2\.3 -> 1\.3\.0/)
+      out.should.match(/now run: gem kit changelog --write/)
+      File.read(File.join(dir, "lib/demo/version.rb")).should.match(/"1\.3\.0"/)
+    end
+  end
+
+  it "defaults to a patch bump" do
+    with_gem do |dir|
+      invoke(["bump"], dir)
+      File.read(File.join(dir, "lib/demo/version.rb")).should.match(/"1\.2\.4"/)
+    end
+  end
+
+  it "refuses to bump onto a deadline, leaving the version file alone" do
+    with_gem do |dir|
+      status, _out, err = invoke(["bump", "major"], dir, deprecations: [["Old", "New", "2.0"]])
+
+      status.should == 1
+      err.should.match(/Refusing to bump 1\.2\.3 -> 2\.0\.0/)
+      err.should.match(/Old -> New/)
+      File.read(File.join(dir, "lib/demo/version.rb")).should.match(/"1\.2\.3"/)
+    end
+  end
+
+  it "--force bumps past a deadline and says so" do
+    with_gem do |dir|
+      status, out, _err = invoke(["bump", "major", "--force"], dir, deprecations: [["Old", "New", "2.0"]])
+
+      status.should == 0
+      out.should.match(/--force given; bumping past 1 deprecation/)
+      File.read(File.join(dir, "lib/demo/version.rb")).should.match(/"2\.0\.0"/)
+    end
+  end
+
+  it "mentions deprecations outstanding but not yet due" do
+    with_gem do |dir|
+      _status, out, _err = invoke(["bump", "minor"], dir, deprecations: [["Old", "New", "9.0"]])
+      out.should.match(/1 deprecation\(s\) still outstanding \(none due in 1\.3\.0\)/)
+    end
+  end
+
+  it "rejects a segment that is not major, minor or patch" do
+    with_gem do |dir|
+      status, _out, _err = invoke(["bump", "epoch"], dir)
+      status.should.not == 0
+      File.read(File.join(dir, "lib/demo/version.rb")).should.match(/"1\.2\.3"/)
+    end
+  end
+
+  it "reports a directory with no gemspec" do
+    Dir.mktmpdir do |dir|
+      status, _out, err = invoke(["bump", "minor"], dir)
+      status.should == 1
+      err.should.match(/no \.gemspec/)
+    end
+  end
+end

data/lib/gem_kit/release/cli/changelog.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module GemKit
+  module Release
+    module CLI
+      # Linting is the default because it is the safe, read-only half. Writing
+      # edits a file and costs money, so it asks for the flag.
+      class Changelog < Command
+        desc "Lint CHANGELOG.md, or have an AI CLI write this version's entry"
+
+        argument :version,
+                 type: :string, required: false,
+                 desc: "Check that this version is ready to release (default: format only)"
+
+        option :write,
+               type: :boolean, default: false,
+               desc: "Ask the configured AI CLI to write this version's entry"
+
+        example [
+          "                   # lint the format",
+          "4.2.0              # ...and check 4.2.0 is ready to release",
+          "--write            # hand the entry to the configured AI CLI",
+        ]
+
+        def call(version: nil, **options)
+          return write_entry if options[:write]
+
+          problems = version ? gate.release_problems(version) : gate.changelog_problems
+
+          if problems.empty?
+            say("#{relative(project.changelog_path)} is #{version ? "ready to release #{version}" : "clean"}.")
+            return
+          end
+
+          refuse("#{problems.size} problem(s) in #{relative(project.changelog_path)}:", problems)
+        end
+
+        private
+
+          def write_entry
+            writer = project.changelog_writer
+            unless system("command -v #{writer} >/dev/null 2>&1")
+              fail_with("#{writer} is not on PATH (set config.changelog_writer)")
+            end
+
+            say("Writing #{relative(project.changelog_path)} for #{project.version}…")
+            fail_with("#{writer} failed") unless system(writer, prompt)
+          end
+
+          def prompt
+            <<~PROMPT
+              Update #{File.basename(project.changelog_path)} for the release of version #{project.version}.
+
+              The changes to document are the commits since the last tag plus any
+              uncommitted work. Read `git log`, `git status` and `git diff` first.
+
+              Rules:
+              - Follow Keep a Changelog (https://keepachangelog.com/en/1.1.0/) exactly.
+                The file must pass `gem kit changelog #{project.version}`; run it when you
+                are done and fix anything it reports.
+              - Add one `## [#{project.version}] - #{Time.now.strftime("%Y-%m-%d")}` section
+                directly below `## [Unreleased]`, and move anything already under
+                [Unreleased] that shipped in this version into it. Leave [Unreleased] in
+                place, empty.
+              - Group entries only under: Added, Changed, Deprecated, Removed, Fixed,
+                Security. Omit the groups with nothing in them.
+              - Write for someone upgrading the gem: what changed in the public API, what
+                they must now do differently. Name the constants and methods involved.
+                Skip internal refactors, test-only changes and typo fixes.
+              - Anything deprecated this cycle goes under Deprecated, naming the
+                replacement and the version it will be removed in (see
+                `gem kit deprecations`).
+              - Match the voice and level of detail of the existing entries.
+              - Edit #{File.basename(project.changelog_path)} only. Do not touch any other
+                file, and do not commit.
+            PROMPT
+          end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/cli/changelog" do
+  require_relative "../../../../spec/support/gem_kit_release_spec"
+  extend GemKitReleaseSpec
+
+  it "lints the format when given no version" do
+    with_gem do |dir|
+      status, out, _err = invoke(["changelog"], dir)
+      status.should == 0
+      out.should.match(/CHANGELOG\.md is clean/)
+    end
+  end
+
+  it "checks a version is ready to release" do
+    with_gem do |dir|
+      invoke(["changelog", "1.2.3"], dir).first.should == 0
+
+      status, _out, err = invoke(["changelog", "9.9.9"], dir)
+      status.should == 1
+      err.should.match(/no section for 9\.9\.9/)
+    end
+  end
+
+  it "reports a malformed changelog with line numbers" do
+    with_gem(changelog: :none) do |dir|
+      File.write(File.join(dir, "CHANGELOG.md"), "# Changelog\n\n## 1.0.0\n")
+
+      status, _out, err = invoke(["changelog"], dir)
+      status.should == 1
+      err.should.match(/malformed version heading/)
+      err.should.match(/CHANGELOG\.md:3/)
+    end
+  end
+
+  it "reports a changelog that does not exist" do
+    with_gem(changelog: :none) do |dir|
+      status, _out, err = invoke(["changelog"], dir)
+      status.should == 1
+      err.should.match(/does not exist/)
+    end
+  end
+
+  it "--write fails clearly when the configured writer is not on PATH" do
+    with_gem do |dir|
+      GemKit::Release.configure { |config| config.changelog_writer = "definitely-not-a-command" }
+      begin
+        status, _out, err = invoke(["changelog", "--write"], dir)
+        status.should == 1
+        err.should.match(/definitely-not-a-command is not on PATH/)
+      ensure
+        GemKit::Release.reset!
+      end
+    end
+  end
+
+  it "--write invokes the configured writer" do
+    with_gem do |dir|
+      # `true` accepts and ignores its argument, so this exercises the whole
+      # path without spending anything.
+      GemKit::Release.configure { |config| config.changelog_writer = "true" }
+      begin
+        status, out, _err = invoke(["changelog", "--write"], dir)
+        status.should == 0
+        out.should.match(/Writing CHANGELOG\.md for 1\.2\.3/)
+      ensure
+        GemKit::Release.reset!
+      end
+    end
+  end
+
+  it "is reachable by its alias" do
+    with_gem do |dir|
+      invoke(["log"], dir).first.should == 0
+    end
+  end
+end

data/lib/gem_kit/release/cli/command.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+require_relative "../../release"
+
+module GemKit
+  module Release
+    module CLI
+      # Raised instead of exiting, so the caller decides what a failure means:
+      # the `gem kit` bridge turns it into terminate_interaction, and the specs
+      # turn it into a status.
+      class Failure < StandardError; end
+
+      # Shared base for the subcommands. Each is thin — declare arguments and
+      # options so dry-cli can render the help page, ask a library object a
+      # question, report. The work stays in Gate, VersionFile, Changelog and
+      # Deprecate.
+      class Command < Dry::CLI::Command
+        RED   = "\e[0;31m"
+        RESET = "\e[0m"
+
+        # The gem in the working directory. Everything is inferred from its
+        # .gemspec, so there is nothing to configure in the common case.
+        def project
+          @project ||= Project.detect
+        rescue Project::NotFound => error
+          fail_with(error.message)
+        end
+
+        def gate
+          @gate ||= Gate.new(project)
+        end
+
+        def version_file
+          VersionFile.new(project.version_file, template: project.version_template)
+        end
+
+        def say(message = "") = $stdout.puts(message)
+
+        def fail_with(message)
+          raise Failure, message
+        end
+
+        # Report a problem list under a heading and stop. One message — a
+        # refusal is not half output and half diagnostics.
+        def refuse(heading, problems)
+          fail_with([heading, "", *problems.map { |problem| "  #{problem}" }].join("\n"))
+        end
+
+        def relative(path) = path.sub("#{project.root}/", "")
+
+        def render(entries)
+          lines(entries).each { |line| say("  #{line}") }
+        end
+
+        # Deprecation entries as display lines: the deadline, the rename, and
+        # where it was declared.
+        def lines(entries)
+          entries.sort_by { |entry| [entry.removed_in, entry.name] }.flat_map do |entry|
+            line = "#{entry.removed_in.to_s.ljust(8)} #{entry}"
+            entry.declared_at ? [line, "#{" " * 8} #{entry.declared_at}"] : [line]
+          end
+        end
+      end
+    end
+  end
+end