command_kit-completion 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ed090b5e927e5c88118a00518943d89d5dc405896469291c0bcd50ec44ea243
+  data.tar.gz: 3786b5ae7c7fa784ace3c2f173ce1b5121529674bbcb5899e45bf0bf5b6e79da
+SHA512:
+  metadata.gz: e23917b5fb372dfaeed9316015b0e7a21f7e748c8afa8d8737e82008c8c8a45c365ae97dbf093537766bd67ce30a61487e9d062744b77ad1fcf72cf177a9f7db
+  data.tar.gz: 8de5d327ece13f2c287663a18c62859635f5dd13ae29c5052f405898cafbacc17c2619d27e7d3877492f86b285c18274b5916b7c2005f7b88a6475faf261ced4

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.md
+LICENSE.txt

data/.github/workflows/ruby.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 3.0
+          - 3.1
+          - 3.2
+          - jruby
+          - truffleruby
+    name: OS ${{ matrix.os }} / Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install Ruby dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle
+/.yardoc/
+/Gemfile.lock
+/coverage/
+/example-completion.sh
+/doc/
+/pkg/
+/vendor/cache/*.gem

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "CommandKit Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,8 @@
+### 0.1.0 / 2023-12-18
+
+* Initial release:
+  * Supports automatically generating completion rules from a [command_kit] CLI
+    class's options and sub-commands.
+  * Supports loading additional completion rules from a YAML file.
+
+[command_kit]: https://github.com/postmodern/command_kit.rb#readme

data/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+
+  gem 'rspec', '~> 3.0'
+  gem 'simplecov', '~> 0.20', require: false
+
+  gem 'kramdown'
+  gem 'redcarpet',       platform: :mri
+  gem 'yard', '~> 0.9'
+  gem 'yard-spellcheck', require: false
+  gem 'dead_end'
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2023 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,48 @@
+# command_kit-completion
+
+[![CI](https://github.com/postmodern/command_kit-completion/actions/workflows/ruby.yml/badge.svg)](https://github.com/postmodern/command_kit-completion/actions/workflows/ruby.yml)
+[![Code Climate](https://codeclimate.com/github/postmodern/command_kit-completion.svg)](https://codeclimate.com/github/postmodern/command_kit-completion)
+[![Gem Version](https://badge.fury.io/rb/wordlist.svg)](https://badge.fury.io/rb/wordlist)
+
+* [Source](https://github.com/postmodern/command_kit-completion#readme)
+* [Issues](https://github.com/postmodern/command_kit-completion/issues)
+* [Documentation](https://rubydoc.info/gems/command_kit-complete)
+
+## Description
+
+Adds a rake task that generates shell completion rules for a [command_kit] CLI.
+The rake task loads the CLI class and uses the [completely] library to generate
+the shell completion rules.
+
+## Features
+
+* Supports automatically generating completion rules from a [command_kit] CLI
+  class's options and sub-commands.
+* Supports loading additional completion rules from a YAML file.
+
+## Examples
+
+```ruby
+require 'command_kit/completion/task'
+CommandKit::Completion::Task.new(
+  class_file:  './examples/cli',
+  class_name:  'Foo::CLI',
+  output_file: 'completion.sh'
+)
+```
+
+## Requirements
+
+* [Ruby] >= 3.0.0
+* [command_kit] ~> 0.1
+* [completely] ~> 0.6
+
+## License
+
+Copyright (c) 2023 Hal Brodigan
+
+See {file:LICENSE.txt} for details.
+
+[Ruby]: https://www.ruby-lang.org/
+[command_kit]: https://github.com/postmodern/command_kit.rb#readme
+[completely]: https://rubygems.org/gems/completely

data/Rakefile

@@ -0,0 +1,30 @@
+require 'rubygems'
+
+begin
+  require 'bundler/setup'
+rescue LoadError => e
+  abort e.message
+end
+
+require 'rake'
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :test    => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+task :doc => :yard
+
+namespace :example do
+  require 'command_kit/completion/task'
+  CommandKit::Completion::Task.new(
+    class_file:  './examples/cli',
+    class_name:  'Foo::CLI',
+    output_file: 'example-completion.sh'
+  )
+end

data/command_kit-completion.gemspec

@@ -0,0 +1,59 @@
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'command_kit/completion/version'
+                  CommandKit::Completion::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = if gemspec['files'] then glob[gemspec['files']]
+              else                     `git ls-files`.split($/)
+              end
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = Array(gemspec['requirements'])
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/examples/cli/config/get.rb

@@ -0,0 +1,47 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    class Config < CommandKit::Command
+      #
+      # The `config get` sub-command.
+      #
+      class Get < CommandKit::Command
+
+        usage '[options] NAME'
+
+        argument :name, required: false,
+                        desc:     'Configuration variable name'
+
+        description 'Gets a configuration variable'
+
+        CONFIG = {
+          'name'  => 'John Smith',
+          'email' => 'john.smith@example.com'
+        }
+
+        #
+        # Runs the `config get` sub-command.
+        #
+        # @param [String, nil] name
+        #   The optional name argument.
+        #
+        def run(name=nil)
+          if name
+            unless CONFIG.has_key?(name)
+              print_error "unknown config variable: #{name}"
+              exit(1)
+            end
+
+            puts CONFIG.fetch(name)
+          else
+            CONFIG.each do |name,value|
+              puts "#{name}:\t#{value}"
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

data/examples/cli/config/set.rb

@@ -0,0 +1,44 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    class Config < CommandKit::Command
+      #
+      # The `config set` sub-command.
+      #
+      class Set < CommandKit::Command
+
+        usage '[options] NAME'
+
+        argument :name, required: true,
+                        desc:     'Configuration variable name to set'
+
+        argument :value, required: true,
+                         desc:     'Configuration variable value to set'
+
+        description 'Sets a configuration variable'
+
+        CONFIG = {
+          'name'  => 'John Smith',
+          'email' => 'john.smith@example.com'
+        }
+
+        #
+        # Runs the `config get` sub-command.
+        #
+        # @param [String] name
+        #   The name argument.
+        #
+        def run(name,value)
+          unless CONFIG.has_key?(name)
+            print_error "unknown config variable: #{name}"
+            exit(1)
+          end
+
+          puts "Configuration variable #{name} was #{CONFIG.fetch(name)}, but is now #{value}"
+        end
+
+      end
+    end
+  end
+end

data/examples/cli/config.rb

@@ -0,0 +1,23 @@
+require 'command_kit/command'
+require 'command_kit/commands'
+
+require_relative 'config/get'
+require_relative 'config/set'
+
+module Foo
+  class CLI
+    #
+    # The `config` sub-command.
+    #
+    class Config < CommandKit::Command
+
+      include CommandKit::Commands
+
+      command Get
+      command Set
+
+      description 'Get or set the configuration'
+
+    end
+  end
+end

data/examples/cli/list.rb

@@ -0,0 +1,35 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    #
+    # The `list` sub-command.
+    #
+    class List < CommandKit::Command
+
+      usage '[options] [NAME]'
+
+      argument :name, required: false,
+                      desc:     'Optional name to list'
+
+      description 'Lists the contents'
+
+      ITEMS = %w[foo bar baz]
+
+      #
+      # Runs the `list` sub-command.
+      #
+      # @param [String, nil] name
+      #   The optional name argument.
+      #
+      def run(name=nil)
+        if name
+          puts ITEMS.grep(name)
+        else
+          puts ITEMS
+        end
+      end
+
+    end
+  end
+end

data/examples/cli/update.rb

@@ -0,0 +1,47 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    #
+    # The `update` sub-command.
+    #
+    class Update < CommandKit::Command
+
+      usage '[options] [NAME]'
+
+      option :quiet, short: '-q',
+                     desc:  'Suppresses logging messages'
+
+      argument :name, required: false,
+                      desc:     'Optional name to update'
+
+      description 'Updates an item or all items'
+
+      ITEMS = %w[foo bar baz]
+
+      #
+      # Runs the `update` sub-command.
+      #
+      # @param [String, nil] name
+      #   The optional name argument.
+      #
+      def run(name=nil)
+        if name
+          unless ITEMS.include?(name)
+            print_error "unknown item: #{name}"
+            exit(1)
+          end
+
+          puts "Updating #{name} ..." unless options[:quiet]
+          sleep 1
+          puts "Item #{name} updated." unless options[:quiet]
+        else
+          puts "Updating ..." unless options[:quiet]
+          sleep 2
+          puts "All items updated." unless options[:quiet]
+        end
+      end
+
+    end
+  end
+end

data/examples/cli.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../../lib',__FILE__))
+
+require 'command_kit/commands'
+
+require_relative 'cli/config'
+require_relative 'cli/list'
+require_relative 'cli/update'
+
+module Foo
+  #
+  # The main CLI command.
+  #
+  class CLI
+
+    include CommandKit::Commands
+
+    class << self
+      # The global configuration file setting.
+      #
+      # @return [String, nil]
+      attr_accessor :config_file
+    end
+
+    command_name 'foo'
+
+    # Commands must be explicitly registered, unless
+    # CommandKit::Commands::AutoLoad.new(...) is included.
+    command Config
+    command List
+    command Update
+
+    # Commands may have aliases
+    command_aliases['ls'] = 'list'
+    command_aliases['up'] = 'update'
+
+    # Global options may be defined which are parsed before the sub-command's
+    # options are parsed and the sub-command is executed.
+    option :config_file, short: '-C',
+                         value: {
+                           type: String,
+                           usage: 'FILE'
+                         },
+                         desc: 'Global option to set the config file' do |file|
+                           CLI.config_file = file
+                         end
+
+  end
+end
+
+if $0 == __FILE__
+  # Normally you would invoke Foo::CLI.start from a bin/ script.
+  Foo::CLI.start
+end

data/gemspec.yml

@@ -0,0 +1,27 @@
+name: command_kit-completion
+summary: Generate shell completions for command_kit commands
+description:
+  Adds a rake task that generates shell completion rules for a command_kit CLI.
+  The rake task loads the CLI class and uses the 'completely' library to
+  generate shell completion rules.
+
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://github.com/postmodern/command_kit-completion#readme
+
+metadata:
+  documentation_uri: https://rubydoc.info/gems/command_kit-completion
+  source_code_uri:   https://github.com/postmodern/command_kit-completion
+  bug_tracker_uri:   https://github.com/postmodern/command_kit-completion/issues
+  changelog_uri:     https://github.com/postmodern/command_kit-completion/blob/main/ChangeLog.md
+  rubygems_mfa_required: 'true'
+
+required_ruby_version: ">= 3.0.0"
+
+dependencies:
+  command_kit: ~> 0.1
+  completely: ~> 0.6
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/command_kit/completion/task.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'rake/tasklib'
+
+require 'command_kit/options'
+require 'command_kit/commands'
+require 'completely'
+require 'yaml'
+
+module CommandKit
+  module Completion
+    class Task < Rake::TaskLib
+
+      # The file that the command_kit CLI is defined in.
+      #
+      # @return [String]
+      attr_reader :class_file
+
+      # The class name of the command_kit CLI.
+      #
+      # @return [String]
+      attr_reader :class_name
+
+      # The output file to write the shell completions to.
+      #
+      # @return [String]
+      attr_reader :output_file
+
+      # Optional input YAML file to read additional shell completions from.
+      #
+      # @return [String, nil]
+      attr_reader :input_file
+
+      # Specifies whether the shell completion logic should be wrapped in a
+      # function.
+      #
+      # @return [Boolean]
+      attr_reader :wrap_function
+
+      # Optional function name to wrap the shell completions within.
+      #
+      # @return [String, nil]
+      attr_reader :function_name
+
+      #
+      # Initializes the `command_kit:completion` task.
+      #
+      # @param [String] class_file
+      #   The file that contains the comand_kit CLI.
+      #
+      # @param [String] class_name
+      #   The class name of the command_kit CLI.
+      #
+      # @param [String] output_file
+      #   The output file to write the completions rules to.
+      #
+      # @param [String, nil] input_file
+      #   The optional YAML input file of additional completion rules.
+      #   See [completely examples] for YAML syntax.
+      #
+      #   [completely examples]: https://github.com/DannyBen/completely?tab=readme-ov-file#using-the-completely-command-line
+      #
+      def initialize(class_file: ,
+                     class_name: ,
+                     output_file: ,
+                     input_file:    nil,
+                     wrap_function: false,
+                     function_name: nil)
+        @class_file  = class_file
+        @class_name  = class_name
+        @output_file = output_file
+
+        @input_file    = input_file
+        @wrap_function = wrap_function
+        @function_name = function_name
+
+        define
+      end
+
+      #
+      # Defines the `command_kit:completion` task.
+      #
+      def define
+        task(@output_file) do
+          completions  = Completely::Completions.new(completion_rules)
+          shell_script = if @wrap_function
+                           completions.wrap_function(*@function_name)
+                         else
+                           completions.script
+                         end
+
+          File.write(@output_file,shell_script)
+        end
+
+        desc 'Generates the shell completions'
+        task 'command_kit:completion' => @output_file
+
+        task :completion => 'command_kit:completion'
+      end
+
+      #
+      # Loads the {#class_name} from the {#class_file}.
+      #
+      # @return [Class]
+      #
+      def load_class
+        require(@class_file)
+        Object.const_get(@class_name)
+      end
+
+      # Mapping of command usage strings to completely `<keyword>`s.
+      USAGE_COMPLETIONS = {
+        'FILE' => '<file>',
+        'DIR'  => '<directory>',
+        'HOST' => '<hostname>',
+        'USER' => '<user>'
+      }
+
+      #
+      # Generates the completion rules for the given [command_kit] command
+      # class.
+      #
+      # [command_kit]: https://github.com/postmodern/command_kit.rb#readme
+      #
+      # @param [Class] command_class
+      #   The command class.
+      #
+      # @return [Hash{String => Array<String>}]
+      #   The completion rules for the command class and any sub-commands.
+      #
+      def completion_rules_for(command_class)
+        command_name = command_class.command_name
+        completions  = {command_name => []}
+
+        # options
+        if command_class.include?(CommandKit::Options)
+          # add all long option flags
+          command_class.options.each_value do |option|
+            completions[command_name] << option.long
+
+            if option.value
+              if (option_value_completion = USAGE_COMPLETIONS[option.value.usage])
+                # add a special rule if the option's value USAGE maps to a
+                # 'completely' completion keyword (ex: `FILE` -> `<file>`).
+                completions["#{command_name}*#{option.long}"] = [
+                  option_value_completion
+                ]
+              end
+            end
+          end
+        end
+
+        # sub-commands
+        if command_class.include?(CommandKit::Commands)
+          command_class.commands.each do |subcommand_name,subcommand|
+            # add all sub-command names
+            completions[command_name] << subcommand_name
+
+            # generate completions for the sub-command and merge them in
+            completion_rules_for(subcommand.command).each do |subcommand_string,subcommand_completions|
+              completions["#{command_name} #{subcommand_string}"] = subcommand_completions
+            end
+          end
+
+          completions[command_name].concat(command_class.command_aliases.keys)
+        end
+
+        # filter out any command's that have no options/sub-commands
+        completions.reject! do |command_string,command_completions|
+          command_completions.empty?
+        end
+
+        return completions
+      end
+
+      #
+      # Builds the completion rules for the command_kit CLI command, and merges
+      # in any additional completion rules from the input file.
+      #
+      # @return [Hash{String => Array<String>}]
+      #
+      def completion_rules
+        completion_rules = completion_rules_for(load_class)
+
+        if @input_file
+          # load the additional rules from the input file
+          additional_completion_rules = YAML.load_file(@input_file)
+
+          # merge the additional completion rules
+          additional_completion_rules.each do |command_string,completions|
+            if completion_rules[command_string]
+              completion_rules[command_string].concat(completions)
+            else
+              completion_rules[command_string] = completions
+            end
+          end
+        end
+
+        return completion_rules
+      end
+
+    end
+  end
+end

data/lib/command_kit/completion/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CommandKit
+  module Completion
+    # command_kit-completion version
+    VERSION = '0.1.0'
+  end
+end

data/spec/fixtures/additional_rules.yml

@@ -0,0 +1,3 @@
+---
+foo update:
+  - $(foo list)

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'rspec'
+require 'simplecov'
+SimpleCov.start

data/spec/task_spec.rb

@@ -0,0 +1,474 @@
+require 'spec_helper'
+require 'command_kit/completion/task'
+
+require 'tempfile'
+require 'command_kit/command'
+require 'command_kit/commands'
+
+describe CommandKit::Completion::Task do
+  let(:class_file)  { './examples/cli' }
+  let(:class_name)  { 'Foo::CLI' }
+  let(:tempfile)    { Tempfile.new(['command_kit-completion','.sh']) }
+  let(:output_file) { tempfile.path }
+
+  let(:fixtures_dir) { File.join(__dir__,'fixtures') }
+
+  subject do
+    described_class.new(
+      class_file:  class_file,
+      class_name:  class_name,
+      output_file: output_file
+    )
+  end
+
+  describe "#define" do
+    before { subject }
+
+    it "must define a task for the output file" do
+      expect(Rake::Task[output_file]).to_not be_nil
+    end
+
+    it "must define a 'command_kit:completion' task" do
+      expect(Rake::Task['command_kit:completion']).to_not be_nil
+    end
+
+    it "must define a 'completion' task" do
+      expect(Rake::Task['completion']).to_not be_nil
+    end
+  end
+
+  describe "#initialize" do
+    it "must set #class_file" do
+      expect(subject.class_file).to eq(class_file)
+    end
+
+    it "must set #class_name" do
+      expect(subject.class_name).to eq(class_name)
+    end
+
+    it "must set #output_file" do
+      expect(subject.output_file).to eq(output_file)
+    end
+
+    it "must default #input_file to nil" do
+      expect(subject.input_file).to be(nil)
+    end
+
+    it "must default #wrap_function to false" do
+      expect(subject.wrap_function).to be(false)
+    end
+
+    it "must default #function_name to nil" do
+      expect(subject.function_name).to be(nil)
+    end
+  end
+
+  describe "#load_class" do
+    it "must return the Class object for #class_name in #class_file" do
+      expect(subject.load_class).to be(Foo::CLI)
+    end
+  end
+
+  describe "#completion_rules_for" do
+    context "when given a simple CommandKit::Command class" do
+      class TestBasicCommand < CommandKit::Command
+
+        command_name 'test'
+
+        option :foo, desc: 'Foo option'
+
+        option :bar, value: {
+                       type: String
+                     },
+                     desc: 'Bar option'
+
+      end
+
+      let(:command_class) { TestBasicCommand }
+
+      it "must return a Hash of completion rules for the command" do
+        expect(subject.completion_rules_for(command_class)).to eq(
+          {
+            "test" => %w[--foo --bar]
+          }
+        )
+      end
+
+      context "when one of the options accepts a FILE value" do
+        class TestCommandWithFILEOption < CommandKit::Command
+
+          command_name 'test'
+
+          option :foo, desc: 'Foo option'
+
+          option :bar, value: {
+                         type:  String,
+                         usage: 'FILE'
+                       },
+                       desc: 'Bar option'
+
+        end
+
+        let(:command_class) { TestCommandWithFILEOption }
+
+        it "must add a separate completion rule for the option using the <file> keyword" do
+          expect(subject.completion_rules_for(command_class)).to eq(
+            {
+              "test" => %w[--foo --bar],
+              'test*--bar' => %w[<file>]
+            }
+          )
+        end
+      end
+
+      context "when one of the options accepts a DIR value" do
+        class TestCommandWithDIROption < CommandKit::Command
+
+          command_name 'test'
+
+          option :foo, desc: 'Foo option'
+
+          option :bar, value: {
+                         type:  String,
+                         usage: 'DIR'
+                       },
+                       desc: 'Bar option'
+
+        end
+
+        let(:command_class) { TestCommandWithDIROption }
+
+        it "must add a separate completion rule for the option using the <directory> keyword" do
+          expect(subject.completion_rules_for(command_class)).to eq(
+            {
+              "test" => %w[--foo --bar],
+              'test*--bar' => %w[<directory>]
+            }
+          )
+        end
+      end
+
+      context "when one of the options accepts a HOST value" do
+        class TestCommandWithHOSTOption < CommandKit::Command
+
+          command_name 'test'
+
+          option :foo, desc: 'Foo option'
+
+          option :bar, value: {
+                         type:  String,
+                         usage: 'HOST'
+                       },
+                       desc: 'Bar option'
+
+        end
+
+        let(:command_class) { TestCommandWithHOSTOption }
+
+        it "must add a separate completion rule for the option using the <hostname> keyword" do
+          expect(subject.completion_rules_for(command_class)).to eq(
+            {
+              "test" => %w[--foo --bar],
+              'test*--bar' => %w[<hostname>]
+            }
+          )
+        end
+      end
+
+      context "when one of the options accepts a USER value" do
+        class TestCommandWithUSEROption < CommandKit::Command
+
+          command_name 'test'
+
+          option :foo, desc: 'Foo option'
+
+          option :bar, value: {
+                         type:  String,
+                         usage: 'USER'
+                       },
+                       desc: 'Bar option'
+
+        end
+
+        let(:command_class) { TestCommandWithUSEROption }
+
+        it "must add a separate completion rule for the option using the <user> keyword" do
+          expect(subject.completion_rules_for(command_class)).to eq(
+            {
+              "test" => %w[--foo --bar],
+              'test*--bar' => %w[<user>]
+            }
+          )
+        end
+      end
+
+      context "but the command class does not include CommandKit::Options" do
+        class TestCommandWithoutOptions
+          include CommandKit::CommandName
+          include CommandKit::Usage
+          include CommandKit::Arguments
+
+          command_name 'test'
+        end
+
+        let(:command_class) { TestCommandWithoutOptions }
+
+        it "must return an empty Hash" do
+          expect(subject.completion_rules_for(command_class)).to eq({})
+        end
+      end
+    end
+
+    context "when the command class includes CommandKit::Commands" do
+      class TestCommandWithSubCommands < CommandKit::Command
+        include CommandKit::Commands
+
+        option :global_option, short: '-g',
+                               desc:  'A global option'
+
+        class Foo < CommandKit::Command
+
+          option :foo_opt1, desc: 'Foo option 1'
+
+          option :foo_opt2, value: {
+                              type: String
+                            },
+                            desc: 'Foo option 2'
+
+        end
+
+        class Bar < CommandKit::Command
+
+          option :bar_opt1, desc: 'Bar option 1'
+
+          option :bar_opt2, value: {
+                              type: String
+                            },
+                            desc: 'Bar option 2'
+
+        end
+
+        command_name 'test'
+        command Foo
+        command Bar
+
+      end
+
+      let(:command_class) { TestCommandWithSubCommands }
+
+      it "must add completion rules for the other commands" do
+        expect(subject.completion_rules_for(command_class)).to eq(
+          {
+            "test"     => %w[--global-option help foo bar],
+            "test foo" => %w[--foo-opt1 --foo-opt2],
+            "test bar" => %w[--bar-opt1 --bar-opt2]
+          }
+        )
+      end
+
+      context "when the command has command aliases" do
+        class TestCommandWithSubCommandsAndCommandAliases < CommandKit::Command
+          include CommandKit::Commands
+
+          option :global_option, short: '-g',
+                                 desc:  'A global option'
+
+          class Foo < CommandKit::Command
+
+            option :foo_opt1, desc: 'Foo option 1'
+
+            option :foo_opt2, value: {
+                                type: String
+                              },
+                              desc: 'Foo option 2'
+
+          end
+
+          class Bar < CommandKit::Command
+
+            option :bar_opt1, desc: 'Bar option 1'
+
+            option :bar_opt2, value: {
+                                type: String
+                              },
+                              desc: 'Bar option 2'
+
+          end
+
+          command_name 'test'
+          command Foo
+          command Bar
+
+          command_aliases['foo2'] = 'foo'
+          command_aliases['bar2'] = 'bar'
+
+        end
+
+        let(:command_class) { TestCommandWithSubCommandsAndCommandAliases }
+
+        it "must include the command aliases in the completion rules" do
+          expect(subject.completion_rules_for(command_class)).to eq(
+            {
+              "test"     => %w[--global-option help foo bar foo2 bar2],
+              "test foo" => %w[--foo-opt1 --foo-opt2],
+              "test bar" => %w[--bar-opt1 --bar-opt2]
+            }
+          )
+        end
+      end
+
+      context "but when one of the commands does not define any options" do
+        class TestCommandWithSubCommandsWithNoOptions < CommandKit::Command
+          include CommandKit::Commands
+
+          option :global_option, short: '-g',
+                                 desc:  'A global option'
+
+          class Foo < CommandKit::Command
+
+            option :foo_opt1, desc: 'Foo option 1'
+
+            option :foo_opt2, value: {
+                                type: String
+                              },
+                              desc: 'Foo option 2'
+
+          end
+
+          class Bar < CommandKit::Command
+          end
+
+          command_name 'test'
+          command Foo
+          command Bar
+
+        end
+
+        let(:command_class) { TestCommandWithSubCommandsWithNoOptions }
+
+        it "must omit the command from the completion rules" do
+          expect(subject.completion_rules_for(command_class)).to eq(
+            {
+              "test"     => %w[--global-option help foo bar],
+              "test foo" => %w[--foo-opt1 --foo-opt2]
+            }
+          )
+        end
+      end
+
+      context "and when one of the sub-commands also includes CommandKit::Commands" do
+        class TestCommandWithSubSubCommands < CommandKit::Command
+          include CommandKit::Commands
+
+          option :global_option, short: '-g',
+                                 desc:  'A global option'
+
+          class Foo < CommandKit::Command
+
+            option :foo_opt1, desc: 'Foo option 1'
+
+            option :foo_opt2, value: {
+                                type: String
+                              },
+                              desc: 'Foo option 2'
+
+          end
+
+          class Bar < CommandKit::Command
+
+            include CommandKit::Commands
+
+            option :bar_opt1, desc: 'Bar option 1'
+
+            option :bar_opt2, value: {
+                                type: String
+                              },
+                              desc: 'Bar option 2'
+
+            class Baz < CommandKit::Command
+
+              option :baz_opt1, desc: 'Baz option 1'
+
+              option :baz_opt2, value: {
+                                  type: String
+                                },
+                                desc: 'Baz option 2'
+
+            end
+
+            class Qux < CommandKit::Command
+
+              option :qux_opt1, desc: 'Qux option 1'
+
+              option :qux_opt2, value: {
+                                  type: String
+                                },
+                                desc: 'Qux option 2'
+
+            end
+
+            command Baz
+            command Qux
+
+          end
+
+          command_name 'test'
+          command Foo
+          command Bar
+
+        end
+
+        let(:command_class) { TestCommandWithSubSubCommands }
+
+        it "must recursively include completion rules for the sub-sub-commands" do
+          expect(subject.completion_rules_for(command_class)).to eq(
+            {
+              "test"     => %w[--global-option help foo bar],
+              "test foo" => %w[--foo-opt1 --foo-opt2],
+              "test bar" => %w[--bar-opt1 --bar-opt2 help baz qux],
+              "test bar baz" => %w[--baz-opt1 --baz-opt2],
+              "test bar qux" => %w[--qux-opt1 --qux-opt2]
+            }
+          )
+        end
+      end
+    end
+  end
+
+  describe "#completion_rules" do
+    it "must load the class from #class_file and return the generated completion rules for it" do
+      expect(subject.completion_rules).to eq(
+        {
+          "foo" => %w[--config-file help config list update ls up],
+          "foo config" => %w[help get set],
+          "foo update" => %w[--quiet],
+          "foo*--config-file" => %w[<file>]
+        }
+      )
+    end
+
+    context "when #input_file is set" do
+      let(:input_file) { File.join(fixtures_dir,'additional_rules.yml') }
+
+      subject do
+        described_class.new(
+          class_file:  class_file,
+          class_name:  class_name,
+          output_file: output_file,
+          input_file:  input_file
+        )
+      end
+
+      it "must merge the additional completion rules with the generated ones" do
+        expect(subject.completion_rules).to eq(
+          {
+            "foo" => %w[--config-file help config list update ls up],
+            "foo config" => %w[help get set],
+            "foo update" => ['--quiet', '$(foo list)'],
+            "foo*--config-file" => %w[<file>]
+          }
+        )
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: command_kit-completion
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Postmodern
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-12-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: command_kit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: completely
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Adds a rake task that generates shell completion rules for a command_kit
+  CLI. The rake task loads the CLI class and uses the 'completely' library to generate
+  shell completion rules.
+email: postmodern.mod3@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- ChangeLog.md
+- LICENSE.txt
+- README.md
+files:
+- ".document"
+- ".github/workflows/ruby.yml"
+- ".gitignore"
+- ".rspec"
+- ".yardopts"
+- ChangeLog.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- command_kit-completion.gemspec
+- examples/cli.rb
+- examples/cli/config.rb
+- examples/cli/config/get.rb
+- examples/cli/config/set.rb
+- examples/cli/list.rb
+- examples/cli/update.rb
+- gemspec.yml
+- lib/command_kit/completion/task.rb
+- lib/command_kit/completion/version.rb
+- spec/fixtures/additional_rules.yml
+- spec/spec_helper.rb
+- spec/task_spec.rb
+homepage: https://github.com/postmodern/command_kit-completion#readme
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://rubydoc.info/gems/command_kit-completion
+  source_code_uri: https://github.com/postmodern/command_kit-completion
+  bug_tracker_uri: https://github.com/postmodern/command_kit-completion/issues
+  changelog_uri: https://github.com/postmodern/command_kit-completion/blob/main/ChangeLog.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Generate shell completions for command_kit commands
+test_files: []