gem_kit-release 0.1.0

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module GemKit
+  module Release
+    module CLI
+      # Without a version: everything outstanding. With one: only what comes
+      # due there, failing if anything does — which is what makes it usable as
+      # a CI gate.
+      class Deprecations < Command
+        desc "List the deprecations this gem has not yet honoured"
+
+        argument :version,
+                 type: :string, required: false,
+                 desc: "List only what comes due at this version, and fail if any does"
+
+        example [
+          "                   # everything outstanding, by removal version",
+          "5.0.0              # only what comes due at 5.0.0; fails if any does",
+        ]
+
+        def call(version: nil, **)
+          project.load!
+          registry = Deprecate.registry
+
+          if registry.empty?
+            say("No deprecations declared.")
+            return
+          end
+
+          if version.nil?
+            say("#{registry.size} outstanding deprecation(s) (current version #{project.version}):")
+            return render(registry)
+          end
+
+          due = Deprecate.pending(version)
+          if due.empty?
+            say("No deprecations come due at #{version}. (#{registry.size} outstanding overall.)")
+            return
+          end
+
+          refuse("#{due.size} deprecation(s) come due at #{version} and must be removed first:", lines(due))
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/cli/deprecations" do
+  require_relative "../../../../spec/support/gem_kit_release_spec"
+  extend GemKitReleaseSpec
+
+  it "says so when nothing is declared" do
+    with_gem do |dir|
+      status, out, _err = invoke(["deprecations"], dir)
+      status.should == 0
+      out.should.match(/No deprecations declared/)
+    end
+  end
+
+  it "lists everything outstanding with its deadline" do
+    with_gem do |dir|
+      status, out, _err = invoke(["deprecations"], dir,
+                                 deprecations: [["Old", "New", "2.0"], ["Older", "Newer", "3.0"]])
+
+      status.should == 0
+      out.should.match(/2 outstanding deprecation\(s\) \(current version 1\.2\.3\)/)
+      out.should.match(/2\.0\s+Old -> New/)
+      out.should.match(/3\.0\s+Older -> Newer/)
+    end
+  end
+
+  it "fails for a version with deprecations due, naming only those" do
+    with_gem do |dir|
+      status, _out, err = invoke(["deprecations", "2.0.0"], dir,
+                                 deprecations: [["Old", "New", "2.0"], ["Later", "Newer", "3.0"]])
+
+      status.should == 1
+      err.should.match(/1 deprecation\(s\) come due at 2\.0\.0/)
+      err.should.match(/Old -> New/)
+      err.should.not.match(/Later/)
+    end
+  end
+
+  it "passes for a version with nothing due, but says what remains" do
+    with_gem do |dir|
+      status, out, _err = invoke(["deprecations", "1.5.0"], dir, deprecations: [["Old", "New", "2.0"]])
+
+      status.should == 0
+      out.should.match(/No deprecations come due at 1\.5\.0\. \(1 outstanding overall\.\)/)
+    end
+  end
+
+  it "is reachable by its alias" do
+    with_gem do |dir|
+      invoke(["deps"], dir).first.should == 0
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module GemKit
+  module Release
+    module CLI
+      # Gate, build, push. The gates run before anything is built, because a
+      # half-done release is worse than a refused one.
+      class Release < Command
+        desc "Gate, build and push this gem"
+
+        option :dry_run, type: :boolean, default: false, desc: "Run the gates and stop"
+        option :tag,     type: :boolean, default: false, desc: "Tag the release after pushing"
+
+        example [
+          "--dry-run          # run the gates; what belongs in CI",
+          "--tag              # release, then tag it",
+        ]
+
+        def call(**options)
+          version  = project.version.to_s
+          problems = gate.release_problems(version)
+
+          refuse("Refusing to release #{project.name} #{version}:", problems) unless problems.empty?
+
+          if options[:dry_run]
+            say("#{project.name} #{version} is ready to release.")
+            return
+          end
+
+          gemspec = File.basename(project.gemspec_path)
+          package = "#{project.name}-#{version}.gem"
+
+          Dir.chdir(project.root) do
+            say("Building #{gemspec}…")
+            fail_with("gem build failed") unless system("gem", "build", gemspec)
+
+            say("Pushing #{package}…")
+            fail_with("gem push failed") unless system("gem", "push", package)
+          end
+
+          say("Released #{project.name} #{version}")
+
+          Tag.new.call if options[:tag]
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/cli/release" do
+  require_relative "../../../../spec/support/gem_kit_release_spec"
+  extend GemKitReleaseSpec
+
+  it "--dry-run passes when the changelog documents the version" do
+    with_gem do |dir|
+      status, out, _err = invoke(["release", "--dry-run"], dir)
+      status.should == 0
+      out.should.match(/demo 1\.2\.3 is ready to release/)
+    end
+  end
+
+  it "refuses without a changelog entry, before building anything" do
+    with_gem(changelog: :none) do |dir|
+      status, _out, err = invoke(["release"], dir)
+
+      status.should == 1
+      err.should.match(/Refusing to release demo 1\.2\.3/)
+      err.should.match(/does not exist/)
+      Dir[File.join(dir, "*.gem")].should.be.empty
+    end
+  end
+
+  it "refuses when a deprecation is due in this version, before building anything" do
+    with_gem do |dir|
+      status, _out, err = invoke(["release"], dir, deprecations: [["Old", "New", "1.0"]])
+
+      status.should == 1
+      err.should.match(/deprecation due in 1\.2\.3: .*Old -> New/)
+      Dir[File.join(dir, "*.gem")].should.be.empty
+    end
+  end
+
+  it "does not gate on a deprecation that is not yet due" do
+    with_gem do |dir|
+      invoke(["release", "--dry-run"], dir, deprecations: [["Old", "New", "9.0"]]).first.should == 0
+    end
+  end
+
+  it "reports a directory with no gemspec" do
+    Dir.mktmpdir do |dir|
+      invoke(["release", "--dry-run"], dir).first.should == 1
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "erb"
+
+require_relative "command"
+
+module GemKit
+  module Release
+    module CLI
+      # Copies the two documents that describe this toolchain into the project,
+      # rendered for its name and version.
+      #
+      # They are copies rather than links because a policy nobody can read in
+      # their own repo is a policy nobody follows, and because the examples are
+      # worth more when they use the project's real version numbers.
+      class Setup < Command
+        TEMPLATES = File.expand_path("../templates", __dir__)
+
+        DOCUMENTS = %w[DEPRECATIONS.md RELEASE.md].freeze
+
+        desc "Copy DEPRECATIONS.md and RELEASE.md into this project"
+
+        option :force, type: :boolean, default: false, desc: "Overwrite documents that already exist"
+
+        example [
+          "                   # write the documents that are missing",
+          "--force            # refresh them all, e.g. after a major version",
+        ]
+
+        def call(**options)
+          written, skipped = [], []
+
+          DOCUMENTS.each do |document|
+            destination = File.join(project.root, document)
+
+            if File.exist?(destination) && !options[:force]
+              skipped << document
+              next
+            end
+
+            File.write(destination, render_document(document))
+            written << document
+          end
+
+          written.each { |document| say("Wrote #{document}") }
+
+          unless skipped.empty?
+            say("Left alone (already present): #{skipped.join(", ")}")
+            say("Pass --force to overwrite.")
+          end
+
+          say("Link them from your README and AGENTS.md so they are found.") unless written.empty?
+        end
+
+        private
+
+          # Values the templates may use. Kept small and obvious — a template
+          # needing more than this is documenting the tool, not the project.
+          def render_document(document)
+            name         = project.name
+            version      = project.version.to_s
+            next_major   = project.next_major_version
+            changelog    = File.basename(project.changelog_path)
+            version_file = relative(project.version_file)
+            test         = project.test_command
+            today        = Time.now.strftime("%Y-%m-%d")
+
+            template = File.read(File.join(TEMPLATES, "#{document}.erb"))
+            ERB.new(template, trim_mode: "-").result(binding)
+          end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/cli/setup" do
+  require_relative "../../../../spec/support/gem_kit_release_spec"
+  extend GemKitReleaseSpec
+
+  it "writes both documents into the project root" do
+    with_gem do |dir|
+      status, out, _err = invoke(["setup"], dir)
+
+      status.should == 0
+      out.should.match(/Wrote DEPRECATIONS\.md/)
+      out.should.match(/Wrote RELEASE\.md/)
+      File.exist?(File.join(dir, "DEPRECATIONS.md")).should.be.true
+      File.exist?(File.join(dir, "RELEASE.md")).should.be.true
+    end
+  end
+
+  it "renders them for this project's name and versions" do
+    with_gem(version: "4.1.0") do |dir|
+      invoke(["setup"], dir)
+
+      deprecations = File.read(File.join(dir, "DEPRECATIONS.md"))
+      deprecations.should.match(/A deprecation in demo is a \*\*dated promise\*\*/)
+      deprecations.should.match(/4\.1\.0, so the usual deadline is 5/)
+      deprecations.should.not.match(/<%=/)
+
+      release = File.read(File.join(dir, "RELEASE.md"))
+      release.should.match(/demo/)
+      release.should.not.match(/<%=/)
+    end
+  end
+
+  it "leaves existing documents alone and says so" do
+    with_gem do |dir|
+      File.write(File.join(dir, "RELEASE.md"), "mine\n")
+
+      status, out, _err = invoke(["setup"], dir)
+
+      status.should == 0
+      out.should.match(/Left alone \(already present\): RELEASE\.md/)
+      File.read(File.join(dir, "RELEASE.md")).should == "mine\n"
+    end
+  end
+
+  it "--force overwrites them" do
+    with_gem do |dir|
+      File.write(File.join(dir, "RELEASE.md"), "mine\n")
+
+      invoke(["setup", "--force"], dir).first.should == 0
+      File.read(File.join(dir, "RELEASE.md")).should.not == "mine\n"
+    end
+  end
+
+  it "is reachable by its alias" do
+    with_gem do |dir|
+      invoke(["init"], dir).first.should == 0
+      File.exist?(File.join(dir, "RELEASE.md")).should.be.true
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module GemKit
+  module Release
+    module CLI
+      # The tag matters beyond bookkeeping: it is what the next changelog is
+      # written against, so a missing one makes the following release harder to
+      # describe.
+      class Tag < Command
+        desc "Tag the current version in git"
+
+        option :push,   type: :boolean, default: false, desc: "Push the tag to origin"
+        option :prefix, type: :string,  default: "v",   desc: "Tag name prefix"
+
+        example [
+          "                   # tag v4.1.0",
+          "--push             # ...and push it",
+          "--prefix release-  # tag release-4.1.0",
+        ]
+
+        def call(**options)
+          tag = "#{options.fetch(:prefix, "v")}#{project.version}"
+
+          Dir.chdir(project.root) do
+            fail_with("not a git repository") unless system("git rev-parse --git-dir >/dev/null 2>&1")
+            fail_with("tag #{tag} already exists") unless `git tag -l #{tag}`.strip.empty?
+            fail_with("could not create tag #{tag}") unless system("git", "tag", "-a", tag, "-m", tag)
+
+            say("Tagged #{tag}")
+
+            if options[:push]
+              fail_with("could not push #{tag}") unless system("git", "push", "origin", tag)
+              say("Pushed #{tag}")
+            else
+              say("Push it with: git push origin #{tag}")
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/cli/tag" do
+  require_relative "../../../../spec/support/gem_kit_release_spec"
+  extend GemKitReleaseSpec
+
+  # git needs an identity and at least one commit before it will tag.
+  as_repo = lambda do |dir|
+    system("git init -q #{dir}")
+    system("git -C #{dir} -c user.name=t -c user.email=t@t commit -q --allow-empty -m init")
+  end
+
+  it "tags the current version and says how to push it" do
+    with_gem do |dir|
+      as_repo.call(dir)
+
+      status, out, _err = invoke(["tag"], dir)
+      status.should == 0
+      out.should.match(/Tagged v1\.2\.3/)
+      out.should.match(/git push origin v1\.2\.3/)
+      `git -C #{dir} tag -l`.strip.should == "v1.2.3"
+    end
+  end
+
+  it "honours a custom prefix" do
+    with_gem do |dir|
+      as_repo.call(dir)
+
+      invoke(["tag", "--prefix", "release-"], dir).first.should == 0
+      `git -C #{dir} tag -l`.strip.should == "release-1.2.3"
+    end
+  end
+
+  it "refuses to retag an existing version" do
+    with_gem do |dir|
+      as_repo.call(dir)
+      invoke(["tag"], dir)
+
+      status, _out, err = invoke(["tag"], dir)
+      status.should == 1
+      err.should.match(/tag v1\.2\.3 already exists/)
+    end
+  end
+
+  it "reports a directory that is not a git repository" do
+    with_gem do |dir|
+      status, _out, err = invoke(["tag"], dir)
+      status.should == 1
+      err.should.match(/not a git repository/)
+    end
+  end
+end

data/lib/gem_kit/release/cli.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+require_relative "cli/command"
+require_relative "cli/bump"
+require_relative "cli/changelog"
+require_relative "cli/deprecations"
+require_relative "cli/release"
+require_relative "cli/setup"
+require_relative "cli/tag"
+
+module GemKit
+  module Release
+    # The command registry. dry-cli gives us the parts a hand-rolled parser
+    # always ends up needing badly: per-command help pages built from the
+    # `argument`/`option`/`example` declarations, value validation, and a
+    # listing of the subcommands.
+    #
+    #   gem kit                    the listing
+    #   gem kit bump --help        that command's arguments, options, examples
+    #
+    module CLI
+      extend Dry::CLI::Registry
+
+      register "setup",        Setup,        aliases: ["init"]
+      register "bump",         Bump
+      register "changelog",    Changelog,    aliases: ["log"]
+      register "deprecations", Deprecations, aliases: ["deps"]
+      register "release",      Release
+      register "tag",          Tag
+
+      # How the commands are reached, which is not something dry-cli can work
+      # out: it takes the program name from $PROGRAM_NAME, and ours is `gem`.
+      PROGRAM_NAME = "gem kit"
+
+      # Run one invocation. Returns an exit status rather than exiting, so the
+      # `gem kit` bridge can hand it to terminate_interaction and the specs can
+      # assert on it.
+      def self.run(arguments, out: $stdout, err: $stderr)
+        with_program_name do
+          Dry::CLI.new(self).call(arguments: arguments, out: out, err: err)
+        end
+        0
+      rescue Failure => failure
+        err.puts(failure.message)
+        1
+      rescue SystemExit => exit_exception
+        # dry-cli exits on an unknown command or a bad argument value.
+        exit_exception.status
+      end
+
+      # dry-cli renders usage as `File.basename($PROGRAM_NAME) <command>`, so
+      # every help page would otherwise say `gem bump` — or, under the test
+      # runner, `-e`. Basename of "gem kit" is "gem kit", which is exactly the
+      # string we want.
+      def self.with_program_name
+        original = $PROGRAM_NAME
+        $PROGRAM_NAME = PROGRAM_NAME
+        yield
+      ensure
+        $PROGRAM_NAME = original
+      end
+    end
+  end
+end
+
+__END__
+
+describe "gem_kit/release/cli" do
+  require_relative "../../../spec/support/gem_kit_release_spec"
+  extend GemKitReleaseSpec
+
+  # With no subcommand dry-cli treats it as a usage error: the listing goes to
+  # stderr and the status is non-zero, the way `git` alone behaves.
+  it "lists every subcommand with its description" do
+    with_gem do |dir|
+      status, _out, err = invoke([], dir)
+
+      status.should.not == 0
+      %w[setup bump changelog deprecations release tag].each do |name|
+        err.should.match(/#{name}/)
+      end
+      err.should.match(/Move the gem version/)
+    end
+  end
+
+  it "names the commands `gem kit <subcommand>`, not the running program" do
+    with_gem do |dir|
+      _status, _out, err = invoke([], dir)
+
+      err.should.match(/gem kit bump \[SEGMENT\]/)
+      err.should.not.match(/^\s+-e /)
+    end
+  end
+
+  it "restores $PROGRAM_NAME afterwards" do
+    with_gem do |dir|
+      before = $PROGRAM_NAME
+      invoke([], dir)
+      $PROGRAM_NAME.should == before
+    end
+  end
+
+  it "prints a subcommand's arguments, options and examples for --help" do
+    with_gem do |dir|
+      _status, out, _err = invoke(["bump", "--help"], dir)
+
+      out.should.match(/gem kit bump/)
+      out.should.match(/SEGMENT/)
+      out.should.match(/--force/)
+      out.should.match(/Examples:/)
+    end
+  end
+
+  it "fails on an unknown subcommand" do
+    with_gem do |dir|
+      invoke(["nonsense"], dir).first.should.not == 0
+    end
+  end
+end