gem_kit-release 0.1.0 → 0.2.1

data/lib/gem_kit/release/cli.rb

@@ -1,66 +1,184 @@
 # frozen_string_literal: true
 
-require "dry/cli"
+require "thor"
 
-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"
+# `require`, not `require_relative`: gem_kit is a separate gem, and inside an
+# installed gem_kit-release there is no ../gem_kit to reach. It works in the
+# monorepo, where both gems share one lib/, which is exactly why this is worth
+# a comment.
+require "gem_kit"
+require_relative "version"
+require_relative "changelog"
+require_relative "project"
+require_relative "version_file"
+require_relative "gate"
+require_relative "commands/command"
+require_relative "commands/bump"
+require_relative "commands/changelog"
+require_relative "commands/deprecations"
+require_relative "commands/release"
+require_relative "commands/tag"
+require_relative "generators/setup"
 
 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.
+    # The command line behind `gem kit`, on Thor.
+    #
+    # Thor gives us the parts a hand-rolled parser always ends up needing
+    # badly: per-command help built from the `desc`/`method_option`
+    # declarations, a subcommand listing, and — the reason for choosing it over
+    # a plain option parser — Thor::Group and Thor::Actions, the same generator
+    # machinery Rails' `rails generate` is built on. `gem kit setup` is a
+    # generator, so it gets create/identical/conflict reporting and the
+    # overwrite prompt without writing any of it.
     #
     #   gem kit                    the listing
-    #   gem kit bump --help        that command's arguments, options, examples
+    #   gem kit help bump          that command's options
     #
-    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
+    # Each command here is a thin front for a plain object under CLI::; the
+    # work itself is in Gate, VersionFile, Changelog and Deprecate.
+    class CLI < Thor
+      class_option :gem, type: :string,
+                         desc: "Which gem, in a repository holding more than one gemspec"
+
+      # Thor asks; without it every invocation warns.
+      def self.exit_on_failure? = true
+
+      # `gem kit` with no arguments lists the commands rather than erroring.
+      def self.banner(command, _namespace = nil, _subcommand = false)
+        "gem kit #{command.usage}"
       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
+      # Short forms for the three typed most often.
+      map "log"  => :changelog,
+          "deps" => :deprecations,
+          "init" => :setup
+
+      register(Generators::Setup, "setup", "setup",
+               "Copy DEPRECATIONS.md and RELEASE.md into this project")
+
+      desc "bump [SEGMENT]", "Move the gem version, refusing to bump onto a deprecation deadline"
+      long_desc <<~TXT
+        Rewrites the gem's version file — by rendering its .erb template if there is
+        one, otherwise by substituting the version literal in place.
+
+        Refuses to bump onto a deprecation deadline. A deprecation names the version
+        the old name stops existing in; bumping to that version while the old name is
+        still in the tree breaks that promise. Remove the deprecated code first, or
+        pass --force, which says what it is overriding.
+      TXT
+      method_option :force, type: :boolean, default: false, aliases: "-f",
+                            desc: "Bump even when a deprecation comes due"
+      def bump(segment = "patch")
+        Commands::Bump.new(options).call(segment)
+      end
+
+      desc "changelog [VERSION]", "Lint CHANGELOG.md, or have an AI CLI write this version's entry"
+      long_desc <<~TXT
+        Checks CHANGELOG.md against Keep a Changelog: the title, that every heading is
+        `## [Unreleased]` or `## [1.2.3] - YYYY-MM-DD`, that versions are valid, dated,
+        unique and ordered newest-first, and that ### sections are one of Added,
+        Changed, Deprecated, Removed, Fixed, Security — none of them empty.
+
+        Given a version, it also asks whether that version has a non-empty section of
+        its own sitting at the top of the released list.
+
+        With --write, hands the job to the CLI named by config.changelog_writer
+        (default: claude). Review what it writes.
+      TXT
+      method_option :write, type: :boolean, default: false, aliases: "-w",
+                            desc: "Ask the configured AI CLI to write this version's entry"
+      def changelog(version = nil)
+        Commands::Changelog.new(options).call(version)
+      end
+
+      desc "deprecations [VERSION]", "List the deprecations this gem has not yet honoured"
+      long_desc <<~TXT
+        A deprecation names its replacement and the version the old name stops
+        existing in. This lists the promises still outstanding, with the source
+        location of each declaration.
+
+        Given a version, it lists only what comes due there and fails if anything
+        does, which is what makes it usable as a gate in CI.
+      TXT
+      def deprecations(version = nil)
+        Commands::Deprecations.new(options).call(version)
       end
+
+      desc "release", "Gate, build and push this gem"
+      long_desc <<~TXT
+        Two gates, both before `gem build` runs:
+
+        the changelog must have a non-empty, correctly formatted section for this
+        version, sitting at the top of the released list; and nothing promised to
+        disappear in this version may still be in the tree.
+
+        Then builds the gemspec and pushes it. Requires RubyGems push credentials.
+        --dry-run runs the gates and stops, which is what belongs in CI.
+      TXT
+      method_option :dry_run, type: :boolean, default: false, aliases: "-n",
+                              desc: "Run the gates and stop"
+      method_option :tag, type: :boolean, default: false, aliases: "-t",
+                          desc: "Tag the release after pushing"
+      def release
+        Commands::Release.new(options).call
+      end
+
+      desc "tag", "Tag the current version in git"
+      long_desc <<~TXT
+        Creates the annotated tag <prefix><version> — v4.1.0 by default — for the
+        version in the gem's version file, refusing if that tag already exists.
+
+        The tag is what the next changelog is written against, so a missing one makes
+        the following release harder to describe.
+      TXT
+      method_option :push, type: :boolean, default: false, aliases: "-p",
+                           desc: "Push the tag to origin"
+      method_option :prefix, type: :string,
+                             desc: "Tag name prefix (default: v, or <gem>-v in a multi-gem repository)"
+      def tag
+        Commands::Tag.new(options).call
+      end
+    end
+
+    # The extension seam. A plugin gem adds commands to `gem kit` by reopening
+    # the CLI through this, which is a documented entry point rather than a
+    # class_eval someone reverse-engineered:
+    #
+    #   # lib/gem_kit/plugin.rb, in a gem of your own
+    #   require "gem_kit/release/cli"
+    #
+    #   GemKit::Release.plugin do
+    #     desc "lint", "Check this gem for the things gems get wrong"
+    #     def lint = GemKit::Plugin::Lint.new(options).call
+    #   end
+    #
+    # The block is evaluated on the Thor class, so everything Thor offers is
+    # in scope: `desc`, `long_desc`, `method_option`, `map`, and `register` for
+    # a Thor::Group generator. Commands added this way are indistinguishable
+    # from the built-in ones — they appear in `gem kit`, take `--gem`, and get
+    # a help page.
+    #
+    # Loading is the plugin's own business: ship a lib/rubygems_plugin.rb that
+    # requires your file, and RubyGems will load it on every `gem` invocation,
+    # the same way this gem gets loaded.
+    def self.plugin(&block)
+      CLI.class_eval(&block)
+      CLI
+    end
+
+    # 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)
+      CLI.start(arguments)
+      0
+    rescue Failure => failure
+      err.puts(failure.message)
+      1
+    rescue SystemExit => exit_exception
+      # Thor exits on an unknown command or a missing required argument.
+      exit_exception.status
     end
   end
 end
@@ -71,51 +189,89 @@ 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
+  it "lists every command with its description" do
     with_gem do |dir|
-      status, _out, err = invoke([], 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/)
+      %w[setup bump changelog deprecations release tag].each { |name| out.should.match(/#{name}/) }
+      out.should.match(/Move the gem version/)
     end
   end
 
-  it "names the commands `gem kit <subcommand>`, not the running program" do
+  it "names the commands `gem kit <command>`, 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
+      _status, out, _err = invoke([], dir)
 
-  it "restores $PROGRAM_NAME afterwards" do
-    with_gem do |dir|
-      before = $PROGRAM_NAME
-      invoke([], dir)
-      $PROGRAM_NAME.should == before
+      out.should.match(/gem kit bump/)
+      out.should.not.match(/^\s+rspec /)
     end
   end
 
-  it "prints a subcommand's arguments, options and examples for --help" do
+  it "prints a command's options and long description for help" do
     with_gem do |dir|
-      _status, out, _err = invoke(["bump", "--help"], dir)
+      _status, out, _err = invoke(["help", "bump"], dir)
 
       out.should.match(/gem kit bump/)
       out.should.match(/SEGMENT/)
       out.should.match(/--force/)
-      out.should.match(/Examples:/)
+      out.should.match(/deprecation deadline/)
     end
   end
 
-  it "fails on an unknown subcommand" do
+  it "fails on an unknown command" do
     with_gem do |dir|
       invoke(["nonsense"], dir).first.should.not == 0
     end
   end
+
+  # What a plugin gem does. The command has to be indistinguishable from a
+  # built-in one, or the seam is not worth documenting.
+  it "takes a command from a plugin" do
+    GemKit::Release.plugin do
+      desc "hello NAME", "Say hello from a plugin"
+      def hello(name) = $stdout.puts("hello #{name} (#{options[:gem] || "no --gem"})")
+    end
+
+    begin
+      with_gem do |dir|
+        status, out, _err = invoke(["hello", "world"], dir)
+        status.should == 0
+        out.should.match(/hello world/)
+
+        # The class options reach it too.
+        _status, out, _err = invoke(["hello", "world", "--gem", "demo"], dir)
+        out.should.match(/hello world \(demo\)/)
+
+        # And it is listed and documented like the rest.
+        _status, listing, _err = invoke([], dir)
+        listing.should.match(/gem kit hello NAME/)
+        listing.should.match(/Say hello from a plugin/)
+      end
+    ensure
+      GemKit::Release::CLI.remove_command("hello")
+    end
+  end
+
+  it "hands the plugin the whole Thor DSL, generators included" do
+    generator = Class.new(Thor::Group) do
+      include Thor::Actions
+      def self.banner = "gem kit scaffold"
+      def report = $stdout.puts("scaffolded")
+    end
+    Object.const_set(:PluginScaffoldGenerator, generator) unless defined?(PluginScaffoldGenerator)
+
+    GemKit::Release.plugin do
+      register(PluginScaffoldGenerator, "scaffold", "scaffold", "Scaffold something")
+    end
+
+    begin
+      with_gem do |dir|
+        status, out, _err = invoke(["scaffold"], dir)
+        status.should == 0
+        out.should.match(/scaffolded/)
+      end
+    ensure
+      GemKit::Release::CLI.remove_command("scaffold")
+    end
+  end
 end

data/lib/gem_kit/release/{cli → commands}/bump.rb

@@ -4,29 +4,16 @@ require_relative "command"
 
 module GemKit
   module Release
-    module CLI
+    module Commands
       # 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)
+        def call(segment = "patch")
           current = project.version.to_s
 
           begin
@@ -65,7 +52,7 @@ end
 
 __END__
 
-describe "gem_kit/release/cli/bump" do
+describe "gem_kit/release/commands/bump" do
   require_relative "../../../../spec/support/gem_kit_release_spec"
   extend GemKitReleaseSpec
 

data/lib/gem_kit/release/{cli → commands}/changelog.rb

@@ -4,27 +4,15 @@ require_relative "command"
 
 module GemKit
   module Release
-    module CLI
+    module Commands
       # 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)
+        def call(version = nil)
           return write_entry if options[:write]
 
           problems = version ? gate.release_problems(version) : gate.changelog_problems
@@ -84,7 +72,7 @@ end
 
 __END__
 
-describe "gem_kit/release/cli/changelog" do
+describe "gem_kit/release/commands/changelog" do
   require_relative "../../../../spec/support/gem_kit_release_spec"
   extend GemKitReleaseSpec
 

data/lib/gem_kit/release/{cli → commands}/command.rb

@@ -1,30 +1,34 @@
 # 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
+    # Raised instead of exiting, so the caller decides what a failure means:
+    # the Thor CLI turns it into a non-zero status, and the specs assert on it.
+    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
+    module Commands
+      # Shared base for the commands behind `gem kit`. Each is thin — ask a
+      # library object a question, report — and knows nothing about Thor. The
+      # work stays in Gate, VersionFile, Changelog and Deprecate; the parsing,
+      # the help pages and the generator machinery stay in Thor.
+      class Command
         RED   = "\e[0;31m"
         RESET = "\e[0m"
 
+        attr_reader :options
+
+        def initialize(options = {})
+          @options = options
+        end
+
         # The gem in the working directory. Everything is inferred from its
         # .gemspec, so there is nothing to configure in the common case.
+        # `--gem` picks one out of a repository holding several.
         def project
-          @project ||= Project.detect
-        rescue Project::NotFound => error
+          @project ||= Project.detect(Dir.pwd, name: options[:gem])
+        rescue Project::NotFound, Project::Ambiguous => error
           fail_with(error.message)
         end
 

data/lib/gem_kit/release/{cli → commands}/deprecations.rb

@@ -4,23 +4,15 @@ require_relative "command"
 
 module GemKit
   module Release
-    module CLI
+    module Commands
       # 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, **)
+        def call(version = nil)
           project.load!
           registry = Deprecate.registry
 
@@ -34,7 +26,7 @@ module GemKit
             return render(registry)
           end
 
-          due = Deprecate.pending(version)
+          due = GemKit::Deprecate.pending(version)
           if due.empty?
             say("No deprecations come due at #{version}. (#{registry.size} outstanding overall.)")
             return
@@ -49,7 +41,7 @@ end
 
 __END__
 
-describe "gem_kit/release/cli/deprecations" do
+describe "gem_kit/release/commands/deprecations" do
   require_relative "../../../../spec/support/gem_kit_release_spec"
   extend GemKitReleaseSpec
 

data/lib/gem_kit/release/{cli → commands}/release.rb

@@ -4,21 +4,14 @@ require_relative "command"
 
 module GemKit
   module Release
-    module CLI
+    module Commands
       # 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)
+        def call
           version  = project.version.to_s
           problems = gate.release_problems(version)
 
@@ -42,7 +35,7 @@ module GemKit
 
           say("Released #{project.name} #{version}")
 
-          Tag.new.call if options[:tag]
+          Tag.new(options).call if options[:tag]
         end
       end
     end
@@ -51,7 +44,7 @@ end
 
 __END__
 
-describe "gem_kit/release/cli/release" do
+describe "gem_kit/release/commands/release" do
   require_relative "../../../../spec/support/gem_kit_release_spec"
   extend GemKitReleaseSpec
 

data/lib/gem_kit/release/{cli → commands}/tag.rb

@@ -4,24 +4,16 @@ require_relative "command"
 
 module GemKit
   module Release
-    module CLI
+    module Commands
       # 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}"
+        def call
+          tag = "#{options[:prefix] || project.tag_prefix}#{project.version}"
 
           Dir.chdir(project.root) do
             fail_with("not a git repository") unless system("git rev-parse --git-dir >/dev/null 2>&1")
@@ -45,7 +37,7 @@ end
 
 __END__
 
-describe "gem_kit/release/cli/tag" do
+describe "gem_kit/release/commands/tag" do
   require_relative "../../../../spec/support/gem_kit_release_spec"
   extend GemKitReleaseSpec
 
@@ -67,6 +59,28 @@ describe "gem_kit/release/cli/tag" do
     end
   end
 
+  # Two gems at the same version in one repository would otherwise fight over
+  # a single `v0.1.0`.
+  it "namespaces the tag by gem when the repository holds several" do
+    with_gem do |dir|
+      as_repo.call(dir)
+      File.write(File.join(dir, "other.gemspec"), <<~RUBY)
+        Gem::Specification.new do |spec|
+          spec.name = "other"
+          spec.version = "1.2.3"
+          spec.authors = ["x"]
+          spec.summary = "x"
+          spec.files = []
+        end
+      RUBY
+
+      invoke(["tag", "--gem", "demo"], dir).first.should == 0
+      invoke(["tag", "--gem", "other"], dir).first.should == 0
+
+      `git -C #{dir} tag -l`.split.sort.should == ["demo-v1.2.3", "other-v1.2.3"]
+    end
+  end
+
   it "honours a custom prefix" do
     with_gem do |dir|
       as_repo.call(dir)