gem_kit-release 0.1.0

data/lib/gem_kit/release/deprecate.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "rubygems/deprecate"
+
+module GemKit
+  module Release
+    # A deprecation is a dated promise: it names the replacement *and* the
+    # version the old name stops existing in. Built on Gem::Deprecate, which
+    # gets the message format and the skip_during escape hatch right, plus one
+    # addition — a registry, so the set of outstanding promises is data the
+    # release tooling can enforce rather than prose someone has to remember.
+    #
+    # Deprecate a method:
+    #
+    #   class Session
+    #     extend GemKit::Release::Deprecate
+    #
+    #     def old_reset = new_reset
+    #     deprecate :old_reset, "Session#new_reset", "5.0"
+    #   end
+    #
+    # Deprecate a whole constant that has moved or been renamed — leave the old
+    # name in place as a subclass of the new one, then declare it:
+    #
+    #   class Completion < Brute::Completion::OpenRouter
+    #     extend GemKit::Release::Deprecate
+    #     superseded_by "Brute::Completion::OpenRouter", "5.0"
+    #   end
+    #
+    # Both warn on use, naming the caller. Gem::Deprecate.skip_during silences
+    # them, so a test suite can exercise the old path in quiet.
+    module Deprecate
+      extend Gem::Deprecate
+
+      # One outstanding deprecation. `removed_in` is the deadline the release
+      # gate reads.
+      Entry = Struct.new(:name, :replacement, :removed_in, :declared_at, keyword_init: true) do
+        def to_s
+          "#{name} -> #{replacement == :none ? "(no replacement)" : replacement}"
+        end
+      end
+
+      class << self
+        # Every deprecation declared in the loaded library, in declaration order.
+        def registry
+          @registry ||= []
+        end
+
+        def register(name:, replacement:, removed_in:, declared_at: nil)
+          entry = Entry.new(
+            name:        name.to_s,
+            replacement: replacement,
+            removed_in:  Gem::Version.new(removed_in.to_s),
+            declared_at: declared_at || location(1),
+          )
+          registry << entry
+          entry
+        end
+
+        # The deprecations that come due at `version` — every deadline that has
+        # arrived or passed. Releasing `version` with any of these still in the
+        # tree breaks the promise the warning made.
+        def pending(version)
+          target = Gem::Version.new(version.to_s)
+          registry.select { |entry| entry.removed_in <= target }
+        end
+
+        # Deprecations still inside their grace period at `version`.
+        def upcoming(version)
+          target = Gem::Version.new(version.to_s)
+          registry.reject { |entry| entry.removed_in <= target }
+        end
+
+        # Single funnel for every warning: Gem::Deprecate.skip_during works
+        # across all of them, and specs have one place to listen.
+        def warn(message)
+          Kernel.warn(message) unless Gem::Deprecate.skip
+        end
+
+        # The Gem::Deprecate-shaped message. `origin` must be computed at the
+        # call site — one frame deeper and it names this file rather than the
+        # code that needs changing.
+        def message(target, replacement, removed_in, origin)
+          [
+            "NOTE: #{target} is deprecated",
+            replacement == :none ? " with no replacement" : "; use #{replacement} instead",
+            ". It will be removed in #{removed_in}",
+            "\n#{target} called from #{origin}.",
+          ].join
+        end
+
+        def location(depth)
+          caller_locations(depth + 1, 1)&.first&.then { |l| "#{l.path}:#{l.lineno}" }
+        end
+      end
+
+      # Deprecate one method. Mirrors Gem::Deprecate#rubygems_deprecate, but the
+      # deadline is explicit — a deprecation added late in a cycle usually wants
+      # the major after next, and guessing that is not the tool's business.
+      def deprecate(name, replacement, removed_in)
+        label = singleton_class? ? "#{attached_object}.#{name}" : "#{self}##{name}"
+        Deprecate.register(name: label, replacement: replacement, removed_in: removed_in,
+                           declared_at: Deprecate.location(1))
+
+        class_eval do
+          old = "_deprecated_#{name}"
+          alias_method old, name
+          define_method name do |*args, &block|
+            target = is_a?(Module) ? "#{self}.#{name}" : "#{self.class}##{name}"
+            origin = Gem.location_of_caller.join(":")
+            Deprecate.warn(Deprecate.message(target, replacement, removed_in, origin))
+            send(old, *args, &block)
+          end
+          ruby2_keywords name if respond_to?(:ruby2_keywords, true)
+        end
+      end
+
+      # Deprecate the constant this is called in — the renamed-or-moved case.
+      # Named `superseded_by` rather than `deprecate_constant` because Module
+      # already has a method by that name and shadowing it would be rude.
+      def superseded_by(replacement, removed_in)
+        Deprecate.register(name: name || to_s, replacement: replacement, removed_in: removed_in,
+                           declared_at: Deprecate.location(1))
+
+        return unless respond_to?(:new)
+
+        define_singleton_method(:new) do |*args, **options, &block|
+          origin = Gem.location_of_caller.join(":")
+          Deprecate.warn(Deprecate.message(name || to_s, replacement, removed_in, origin))
+          super(*args, **options, &block)
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/deprecate" do
+  Deprecate = GemKit::Release::Deprecate unless defined?(Deprecate)
+
+  captured = []
+  # Capture what Deprecate.warn emits and keep the shared registry clean —
+  # these specs declare throwaway deprecations.
+  isolated = lambda do |&block|
+    saved    = Deprecate.registry.dup
+    original = Deprecate.method(:warn)
+    captured.clear
+    Deprecate.define_singleton_method(:warn) { |message| captured << message }
+    begin
+      block.call
+    ensure
+      Deprecate.define_singleton_method(:warn, original)
+      Deprecate.registry.replace(saved)
+    end
+  end
+
+  it "warns on a deprecated method, naming replacement, version and caller" do
+    isolated.call do
+      klass = Class.new do
+        extend Deprecate
+        def new_name = :result
+        def old_name = new_name
+        deprecate :old_name, "Thing#new_name", "9.0"
+      end
+
+      klass.new.old_name.should == :result   # still works
+      captured.size.should == 1
+      captured.first.should.match(/is deprecated/)
+      captured.first.should.match(/use Thing#new_name instead/)
+      captured.first.should.match(/removed in 9\.0/)
+      captured.first.should.match(/called from /)
+    end
+  end
+
+  it "names the caller, not the deprecation machinery" do
+    isolated.call do
+      klass = Class.new do
+        extend Deprecate
+        def old_name = :result
+        deprecate :old_name, "Thing#new_name", "9.0"
+      end
+
+      # These specs live in this file's __END__, so "the caller" is a line in
+      # deprecate.rb either way — pin the exact line to tell them apart.
+      klass.new.old_name; call_line = __LINE__
+      captured.first.should.match(/called from .*deprecate\.rb:#{call_line}\./)
+    end
+  end
+
+  it "labels a class-method deprecation by the class, not its singleton" do
+    isolated.call do
+      Class.new do
+        def self.to_s = "Demo"
+        def self.old_thing = :ok
+        class << self
+          extend Deprecate
+          deprecate :old_thing, "Other.new_thing", "9.0"
+        end
+      end
+
+      Deprecate.registry.last.name.should == "Demo.old_thing"
+    end
+  end
+
+  it "warns on a superseded constant but keeps it working" do
+    isolated.call do
+      modern = Class.new { def initialize(x); @x = x; end; attr_reader :x }
+      legacy = Class.new(modern) do
+        extend Deprecate
+        def self.name = "Old::Name"
+        superseded_by "New::Name", "9.0"
+      end
+
+      legacy.new(42).x.should == 42          # still works
+      captured.size.should == 1
+      captured.first.should.match(/Old::Name is deprecated; use New::Name instead/)
+    end
+  end
+
+  it "supports :none for a deprecation with no replacement" do
+    isolated.call do
+      klass = Class.new do
+        extend Deprecate
+        def gone = :ok
+        deprecate :gone, :none, "9.0"
+      end
+
+      klass.new.gone
+      captured.first.should.match(/with no replacement/)
+    end
+  end
+
+  it "registers each declaration with its deadline and source" do
+    isolated.call do
+      Class.new do
+        extend Deprecate
+        def gone = nil
+        deprecate :gone, "Other#kept", "9.0"
+      end
+
+      entry = Deprecate.registry.last
+      entry.replacement.should == "Other#kept"
+      entry.removed_in.should == Gem::Version.new("9.0")
+      entry.declared_at.should.match(/deprecate\.rb:\d+/)
+    end
+  end
+
+  it "splits the registry into pending and upcoming at a version" do
+    isolated.call do
+      Deprecate.registry.clear
+      Deprecate.register(name: "A", replacement: "A2", removed_in: "5.0")
+      Deprecate.register(name: "B", replacement: "B2", removed_in: "6.0")
+
+      Deprecate.pending("5.0.0").map(&:name).should == ["A"]
+      Deprecate.upcoming("5.0.0").map(&:name).should == ["B"]
+      Deprecate.pending("4.9.0").should.be.empty
+      Deprecate.pending("6.1.0").map(&:name).should == ["A", "B"]
+    end
+  end
+
+  it "stays quiet inside Gem::Deprecate.skip_during" do
+    saved = Deprecate.registry.dup
+    begin
+      klass = Class.new do
+        extend Deprecate
+        def quiet = :ok
+        deprecate :quiet, "Other#loud", "9.0"
+      end
+
+      warned   = []
+      original = Kernel.method(:warn)
+      Kernel.define_singleton_method(:warn) { |*args| warned << args.join }
+      begin
+        Gem::Deprecate.skip_during { klass.new.quiet.should == :ok }
+      ensure
+        Kernel.define_singleton_method(:warn, original)
+      end
+
+      warned.should.be.empty
+    ensure
+      Deprecate.registry.replace(saved)
+    end
+  end
+end

data/lib/gem_kit/release/gate.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module GemKit
+  module Release
+    # The checks, in one place. Both the bump and the release ask the same two
+    # questions of a target version, and neither should be hand-rolling them:
+    #
+    #   Is anything promised to disappear in this version still here?
+    #   Does the changelog document this version?
+    #
+    # Every method returns a list of human-readable problems. Empty means pass,
+    # which makes the callers trivial and lets CI use the same object.
+    class Gate
+      attr_reader :project
+
+      def initialize(project)
+        @project = project
+      end
+
+      # Deprecations whose deadline has arrived at `version`. This is the check
+      # that has to run *before* a bump: bumping onto a deadline is what breaks
+      # the promise, so the bump is the last moment anyone can be stopped.
+      def deprecation_problems(version)
+        project.load!
+
+        Deprecate.pending(version).map do |entry|
+          "#{entry.removed_in.to_s.ljust(8)} #{entry}#{entry.declared_at ? "\n#{" " * 9}#{entry.declared_at}" : ""}"
+        end
+      end
+
+      # Deprecations still inside their grace period — worth printing on the
+      # way past, not worth blocking on.
+      def upcoming_deprecations(version)
+        project.load!
+        Deprecate.upcoming(version)
+      end
+
+      # Changelog format, plus "is there an entry for this version?" when one
+      # is given. Without a version this is the format check alone, which is
+      # the useful thing to run on every push.
+      def changelog_problems(version = nil)
+        changelog = Changelog.new(
+          File.exist?(project.changelog_path) ? File.read(project.changelog_path) : nil,
+          path: project.changelog_path,
+        )
+
+        version ? changelog.release_problems(version) : changelog.problems
+      end
+
+      # Everything standing between the project and releasing `version`.
+      def release_problems(version = project.version)
+        problems = []
+
+        changelog_problems(version).each { |problem| problems << problem }
+        deprecation_problems(version).each do |problem|
+          problems << "deprecation due in #{version}: #{problem}"
+        end
+
+        problems
+      end
+
+      # Everything standing between the project and *bumping to* `version`.
+      # Only the deprecation deadline applies — the changelog for a version
+      # cannot exist before the version does.
+      def bump_problems(version)
+        deprecation_problems(version).map { |problem| "deprecation due in #{version}: #{problem}" }
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/gate" do
+  require "tmpdir"
+
+  # A Project stub: the Gate only asks it for a changelog path and a version,
+  # and to load the library (a no-op here — the specs drive the registry).
+  stub_project = lambda do |changelog_path, version: "1.0.0"|
+    Struct.new(:changelog_path, :version) do
+      def load! = true
+    end.new(changelog_path, Gem::Version.new(version))
+  end
+
+  clean_changelog = <<~MD
+    # Changelog
+
+    ## [Unreleased]
+
+    ## [1.0.0] - 2026-01-01
+
+    ### Added
+
+    - A thing.
+  MD
+
+  # Run a block with the deprecation registry isolated.
+  isolated = lambda do |&block|
+    saved = GemKit::Release::Deprecate.registry.dup
+    GemKit::Release::Deprecate.registry.clear
+    begin
+      block.call
+    ensure
+      GemKit::Release::Deprecate.registry.replace(saved)
+    end
+  end
+
+  it "passes when the changelog documents the version and nothing is due" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "CHANGELOG.md")
+      File.write(path, clean_changelog)
+
+      isolated.call do
+        GemKit::Release::Gate.new(stub_project.call(path)).release_problems("1.0.0").should == []
+      end
+    end
+  end
+
+  it "reports a missing changelog section for the version" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "CHANGELOG.md")
+      File.write(path, clean_changelog)
+
+      isolated.call do
+        problems = GemKit::Release::Gate.new(stub_project.call(path)).release_problems("2.0.0")
+        problems.first.should.match(/no section for 2\.0\.0/)
+      end
+    end
+  end
+
+  it "reports a deprecation whose deadline has arrived" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "CHANGELOG.md")
+      File.write(path, clean_changelog)
+
+      isolated.call do
+        GemKit::Release::Deprecate.register(name: "Old", replacement: "New", removed_in: "1.0")
+        gate = GemKit::Release::Gate.new(stub_project.call(path))
+
+        gate.release_problems("1.0.0").first.should.match(/deprecation due in 1\.0\.0: .*Old -> New/)
+        gate.bump_problems("1.0.0").size.should == 1
+      end
+    end
+  end
+
+  it "does not block a bump on a deadline that has not arrived" do
+    Dir.mktmpdir do |dir|
+      isolated.call do
+        GemKit::Release::Deprecate.register(name: "Old", replacement: "New", removed_in: "2.0")
+        gate = GemKit::Release::Gate.new(stub_project.call(File.join(dir, "CHANGELOG.md")))
+
+        gate.bump_problems("1.1.0").should == []
+        gate.upcoming_deprecations("1.1.0").map(&:name).should == ["Old"]
+      end
+    end
+  end
+
+  it "checks changelog format alone when given no version" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "CHANGELOG.md")
+      File.write(path, "## [1.0.0] - 2026-01-01\n\n### Added\n\n- x\n")
+
+      isolated.call do
+        GemKit::Release::Gate.new(stub_project.call(path)).changelog_problems
+          .first.should.match(/must start with the title/)
+      end
+    end
+  end
+
+  it "reports a changelog that does not exist" do
+    Dir.mktmpdir do |dir|
+      isolated.call do
+        GemKit::Release::Gate.new(stub_project.call(File.join(dir, "CHANGELOG.md")))
+          .changelog_problems.first.should.match(/does not exist/)
+      end
+    end
+  end
+end

data/lib/gem_kit/release/project.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "rubygems"
+
+module GemKit
+  module Release
+    # What the tooling needs to know about the project it is running in.
+    #
+    # Almost all of it is already declared in the project's .gemspec — name,
+    # version, and (through `require_relative`) where the version constant
+    # lives. So the normal case is no configuration at all: point it at a
+    # directory and it works out the rest.
+    #
+    #   project = GemKit::Release::Project.detect
+    #   project.name        # => "brute"
+    #   project.version     # => Gem::Version.new("4.1.0")
+    #   project.version_file # => ".../lib/brute/version.rb"
+    #
+    # Anything that cannot be inferred is an override:
+    #
+    #   GemKit::Release.configure do |config|
+    #     config.changelog = "HISTORY.md"
+    #     config.test_command = "bin/test"
+    #   end
+    class Project
+      class NotFound < StandardError; end
+
+      # Overridable settings. Each is nil until set, and nil means "infer".
+      Config = Struct.new(:changelog, :version_file, :require_path, :test_command,
+                          :changelog_writer, keyword_init: true)
+
+      def self.detect(dir = Dir.pwd, config: GemKit::Release.config)
+        gemspec = Dir[File.join(dir, "*.gemspec")].sort.first
+        raise NotFound, "no .gemspec in #{dir}" if gemspec.nil?
+
+        new(gemspec, config: config)
+      end
+
+      attr_reader :root, :gemspec_path, :config
+
+      def initialize(gemspec_path, config: GemKit::Release.config)
+        @gemspec_path = File.expand_path(gemspec_path)
+        @root         = File.dirname(@gemspec_path)
+        @config       = config
+      end
+
+      # The evaluated gemspec. Loaded from the project root, because a gemspec
+      # typically require_relative's its own version file.
+      def spec
+        @spec ||= Dir.chdir(root) { Gem::Specification.load(gemspec_path) } or
+          raise NotFound, "could not load #{gemspec_path}"
+      end
+
+      def name = spec.name
+
+      def version = Gem::Version.new(spec.version.to_s)
+
+      # The next major version — the default deadline for a deprecation.
+      def next_major_version
+        Gem::Version.new(version.segments.first.to_s).bump.to_s
+      end
+
+      def changelog_path
+        File.expand_path(config.changelog || "CHANGELOG.md", root)
+      end
+
+      # lib/gem_kit/release/version.rb for "gem_kit-release", lib/brute/version.rb
+      # for "brute" — the convention every `bundle gem` project follows.
+      def version_file
+        File.expand_path(config.version_file || File.join("lib", *name.split("-"), "version.rb"), root)
+      end
+
+      # An ERB template beside the version file, if the project generates it.
+      def version_template
+        candidate = "#{version_file}.erb"
+        candidate if File.exist?(candidate)
+      end
+
+      # What to require so that deprecation declarations register themselves.
+      # "gem_kit-release" -> "gem_kit/release".
+      def require_path
+        config.require_path || name.tr("-", "/")
+      end
+
+      # Load the library, so Deprecate's registry reflects this project.
+      def load!
+        $LOAD_PATH.unshift(File.join(root, "lib")) unless $LOAD_PATH.include?(File.join(root, "lib"))
+        require require_path
+        true
+      rescue LoadError => error
+        warn "gem_kit-release: could not require #{require_path.inspect} (#{error.message});" \
+             " deprecations will not be detected"
+        false
+      end
+
+      def test_command = config.test_command || "bin/test"
+
+      def changelog_writer = config.changelog_writer || "claude"
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/project" do
+  require "tmpdir"
+
+  # A throwaway gem laid out the conventional way.
+  with_project = lambda do |name: "demo", version: "1.2.3", &block|
+    Dir.mktmpdir do |dir|
+      path = name.split("-")
+      FileUtils.mkdir_p(File.join(dir, "lib", *path))
+      File.write(File.join(dir, "lib", *path, "version.rb"), <<~RUBY)
+        module #{path.map { |p| p.split("_").map(&:capitalize).join }.join("::")}
+          VERSION = "#{version}"
+        end
+      RUBY
+      File.write(File.join(dir, "#{name}.gemspec"), <<~RUBY)
+        require_relative "lib/#{path.join("/")}/version"
+        Gem::Specification.new do |spec|
+          spec.name = "#{name}"
+          spec.version = "#{version}"
+          spec.authors = ["x"]
+          spec.summary = "x"
+          spec.files = []
+        end
+      RUBY
+      block.call(dir)
+    end
+  end
+
+  it "detects the gemspec and reads name and version from it" do
+    with_project.call do |dir|
+      project = GemKit::Release::Project.detect(dir)
+      project.name.should == "demo"
+      project.version.should == Gem::Version.new("1.2.3")
+    end
+  end
+
+  it "raises when there is no gemspec" do
+    Dir.mktmpdir do |dir|
+      lambda { GemKit::Release::Project.detect(dir) }.should.raise(GemKit::Release::Project::NotFound)
+    end
+  end
+
+  it "infers the version file from the gem name, hyphens as directories" do
+    with_project.call(name: "gem_kit-release") do |dir|
+      GemKit::Release::Project.detect(dir).version_file
+        .should == File.join(dir, "lib/gem_kit/release/version.rb")
+    end
+  end
+
+  it "infers the require path from the gem name" do
+    with_project.call(name: "gem_kit-release") do |dir|
+      GemKit::Release::Project.detect(dir).require_path.should == "gem_kit/release"
+    end
+  end
+
+  it "defaults the changelog to CHANGELOG.md in the project root" do
+    with_project.call do |dir|
+      GemKit::Release::Project.detect(dir).changelog_path.should == File.join(dir, "CHANGELOG.md")
+    end
+  end
+
+  it "bumps to the next major for the default deprecation deadline" do
+    with_project.call(version: "4.1.0") do |dir|
+      GemKit::Release::Project.detect(dir).next_major_version.should == "5"
+    end
+  end
+
+  it "finds an ERB version template when the project generates its version file" do
+    with_project.call do |dir|
+      GemKit::Release::Project.detect(dir).version_template.should.be.nil
+      File.write(File.join(dir, "lib/demo/version.rb.erb"), "x")
+      GemKit::Release::Project.detect(dir).version_template
+        .should == File.join(dir, "lib/demo/version.rb.erb")
+    end
+  end
+
+  it "takes overrides from the config" do
+    with_project.call do |dir|
+      config = GemKit::Release::Project::Config.new(changelog: "HISTORY.md", test_command: "rake")
+      project = GemKit::Release::Project.detect(dir, config: config)
+      project.changelog_path.should == File.join(dir, "HISTORY.md")
+      project.test_command.should == "rake"
+    end
+  end
+end