cli-kit 4.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 523252459712e507c4579e244e6330eb3e8a5d8c71334d4e41553903ab651cd6
-  data.tar.gz: 459cb0a684e2890718d0cffdd74cd8540bd91a1995dfe1db593df9a189da20d7
+  metadata.gz: e576da52278c6b0596840691bffbb12546b54bf2238145455a45333d6101f773
+  data.tar.gz: 24243f1a2d66ad3b12fb2728b73b608038950d958ffc31dc0ab7951c3714533a
 SHA512:
-  metadata.gz: 8579924711573ce6338b52dc44c47ad40c12f925bbd6f3ad6cee5be9f44b2b4f315e6d272adc309788b0418ee6806567660f0386d7e91d9d09a524beeb0a4a1f
-  data.tar.gz: b5507292ba97fd6f13b83b6426e81e4500e0ef1480387164c936164b7593bf7daac98e39cbb835362f198c39e562f2d12adf92384365a9c99a7f0ed42c158a45
+  metadata.gz: 8e7f4f5c4cc6620a2d98eca89e85ad57e6a9a0bd94ec704503ac0c9ba84f631984beb7c71c60e8b24ddbd2c4cf88b30cc298d3b05009f565450348a5b82c8d7f
+  data.tar.gz: ac1c63ad107ca13fda07413a17054a17bb69ec6ae793f2a0abb97a5c2616c15fe7aaeaf7c3328b7ce035136dd72007df51fe7f5aab15e0c90199ede7ddd8d1e0

data/.github/workflows/cla.yml

@@ -0,0 +1,22 @@
+name: Contributor License Agreement (CLA)
+
+on:
+  pull_request_target:
+    types: [opened, synchronize]
+  issue_comment:
+    types: [created]
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    if: |
+      (github.event.issue.pull_request 
+        && !github.event.issue.pull_request.merged_at
+        && contains(github.event.comment.body, 'signed')
+      ) 
+      || (github.event.pull_request && !github.event.pull_request.merged)
+    steps:
+      - uses: Shopify/shopify-cla-action@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cla-token: ${{ secrets.CLA_TOKEN }}

data/.github/workflows/ruby.yml

@@ -3,6 +3,7 @@ name: Ruby
 on: [push, pull_request]
 
 jobs:
+
   style:
     runs-on: ubuntu-latest
     steps:
@@ -14,11 +15,24 @@ jobs:
         bundler-cache: true
     - name: Check style
       run: bundle exec rake style
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '2.7'
+        bundler-cache: true
+    - name: Typecheck
+      run: bundle exec srb tc
+
   test:
     strategy:
       matrix:
-        os: [macos-latest, ubuntu-latest, windows-latest]
-        ruby-version: ['2.6', '2.7']
+        os: [macos-latest, ubuntu-latest]
+        ruby-version: ['2.7', '3.0']
 
     runs-on: ${{ matrix.os }}
     steps:
@@ -30,3 +44,21 @@ jobs:
         bundler-cache: true
     - name: Run tests
       run: bundle exec rake test
+
+  test-windows:
+    strategy:
+      matrix:
+        ruby-version: ['2.7', '3.0']
+
+    runs-on: windows-latest
+    env:
+      BUNDLE_WITHOUT: typecheck
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Run tests
+      run: bundle exec rake test

data/.gitignore

@@ -4,6 +4,8 @@ build
 .DS_Store
 .bundle
 
+/coverage
+
 .starscope.db
 cscope.out
 tags

data/.rubocop.sorbet.yml

@@ -0,0 +1,47 @@
+Sorbet:
+  Enabled: true
+
+Sorbet/ValidSigil:
+  Enabled: true
+  Exclude:
+    - lib/cli/kit/sorbet_runtime_stub.rb
+
+Sorbet/FalseSigil:
+  Enabled: false
+
+Sorbet/TrueSigil:
+  Enabled: true
+  Include:
+    - "**/*.rb"
+    - "**/*.rbi"
+    - "**/*.rake"
+    - "**/*.ru"
+  Exclude:
+    - lib/cli/kit/sorbet_runtime_stub.rb
+    - "test/**/*"
+    - "lib/cli/kit/support/test_helper.rb"
+
+Sorbet/EnforceSigilOrder:
+  Enabled: true
+
+Sorbet/EnforceSignatures:
+  Enabled: true
+  Exclude:
+    - lib/cli/kit/sorbet_runtime_stub.rb
+    - "test/**/*"
+    - bin/testunit
+    - "lib/cli/kit/support/test_helper.rb"
+
+Sorbet/SignatureBuildOrder:
+  Enabled: true
+
+Sorbet/KeywordArgumentOrdering:
+  Enabled: true
+
+Sorbet/ConstantsFromStrings:
+  Enabled: true
+  Exclude:
+    - "examples/**/*"
+
+Sorbet/ForbidIncludeConstLiteral:
+  Enabled: false

data/.rubocop.yml

@@ -1,11 +1,18 @@
 inherit_gem:
   rubocop-shopify: rubocop-cli.yml
 
+inherit_from:
+  - .rubocop.sorbet.yml
+
+require:
+  - rubocop-sorbet
+
 AllCops:
   Exclude:
     - gen/template/**/*
     - vendor/**/*
-  TargetRubyVersion: 2.5
+  TargetRubyVersion: 2.7
+  NewCops: disable
 
 Style/ClassAndModuleChildren:
   Exclude:
@@ -36,3 +43,11 @@ Style/MultilineBlockChain:
 
 Style/StringLiterals:
   EnforcedStyle: single_quotes
+
+# We heavily manage output on purpose
+Style/GlobalStdStream:
+  Enabled: false
+
+# Sometimes (often) explicit is good
+Style/EmptyElse:
+  Enabled: false

data/Gemfile

@@ -4,14 +4,23 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
+  gem 'cli-ui', git: 'https://github.com/Shopify/cli-ui', ref: '0eefd57248f42ec163639884e77a071d82bfbda8'
   gem 'rubocop'
+  gem 'rubocop-rake'
   gem 'rubocop-shopify'
+  gem 'rubocop-sorbet'
   gem 'byebug'
   gem 'method_source'
+  gem 'simplecov'
+end
+
+group :typecheck do
+  gem 'sorbet-static-and-runtime'
+  gem 'tapioca', require: false
 end
 
 group :test do
-  gem 'mocha', '~> 1.13.0', require: false
+  gem 'mocha', '~> 2.0.1', require: false
   gem 'minitest', '>= 5.0.0', require: false
   gem 'minitest-reporters', require: false
 end

data/Gemfile.lock

@@ -1,3 +1,10 @@
+GIT
+  remote: https://github.com/Shopify/cli-ui
+  revision: 0eefd57248f42ec163639884e77a071d82bfbda8
+  ref: 0eefd57248f42ec163639884e77a071d82bfbda8
+  specs:
+    cli-ui (1.5.1)
+
 PATH
   remote: .
   specs:
@@ -11,52 +18,121 @@ GEM
     ast (2.4.2)
     builder (3.2.4)
     byebug (11.1.3)
-    cli-ui (1.5.1)
+    diff-lcs (1.5.0)
+    docile (1.4.0)
+    json (2.6.2)
     method_source (1.0.0)
-    minitest (5.14.4)
-    minitest-reporters (1.4.3)
+    minitest (5.16.3)
+    minitest-reporters (1.5.0)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
-    mocha (1.13.0)
-    parallel (1.21.0)
-    parser (3.0.2.0)
+    mocha (2.0.2)
+      ruby2_keywords (>= 0.0.5)
+    netrc (0.11.0)
+    parallel (1.22.1)
+    parser (3.1.2.1)
       ast (~> 2.4.1)
-    rainbow (3.0.0)
+    rainbow (3.1.1)
     rake (13.0.6)
-    regexp_parser (2.1.1)
+    rbi (0.0.16)
+      ast
+      parser (>= 2.6.4.0)
+      sorbet-runtime (>= 0.5.9204)
+      unparser
+    regexp_parser (2.6.0)
     rexml (3.2.5)
-    rubocop (1.22.3)
+    rubocop (1.39.0)
+      json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 3.0.0.0)
+      parser (>= 3.1.2.1)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.12.0, < 2.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.12.0)
-      parser (>= 3.0.1.1)
-    rubocop-shopify (2.3.0)
-      rubocop (~> 1.22)
+    rubocop-ast (1.23.0)
+      parser (>= 3.1.1.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-shopify (2.10.1)
+      rubocop (~> 1.35)
+    rubocop-sorbet (0.6.11)
+      rubocop (>= 0.90.0)
     ruby-progressbar (1.11.0)
-    unicode-display_width (2.1.0)
+    ruby2_keywords (0.0.5)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    sorbet (0.5.10554)
+      sorbet-static (= 0.5.10554)
+    sorbet-runtime (0.5.10554)
+    sorbet-static (0.5.10554-universal-darwin-14)
+    sorbet-static (0.5.10554-universal-darwin-15)
+    sorbet-static (0.5.10554-universal-darwin-16)
+    sorbet-static (0.5.10554-universal-darwin-17)
+    sorbet-static (0.5.10554-universal-darwin-18)
+    sorbet-static (0.5.10554-universal-darwin-19)
+    sorbet-static (0.5.10554-universal-darwin-20)
+    sorbet-static (0.5.10554-universal-darwin-21)
+    sorbet-static (0.5.10554-universal-darwin-22)
+    sorbet-static (0.5.10554-x86_64-linux)
+    sorbet-static-and-runtime (0.5.10554)
+      sorbet (= 0.5.10554)
+      sorbet-runtime (= 0.5.10554)
+    spoom (1.1.12)
+      sorbet (>= 0.5.9204)
+      sorbet-runtime (>= 0.5.9204)
+      thor (>= 0.19.2)
+    tapioca (0.10.3)
+      bundler (>= 1.17.3)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (~> 0.0.0, >= 0.0.16)
+      sorbet-static-and-runtime (>= 0.5.9892)
+      spoom (~> 1.1.0, >= 1.1.11)
+      thor (>= 1.2.0)
+      yard-sorbet
+    thor (1.2.1)
+    unicode-display_width (2.3.0)
+    unparser (0.6.5)
+      diff-lcs (~> 1.3)
+      parser (>= 3.1.0)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
+    yard-sorbet (0.7.0)
+      sorbet-runtime (>= 0.5)
+      yard (>= 0.9)
 
 PLATFORMS
+  arm64-darwin-21
   ruby
+  universal-darwin
+  x86_64-linux
 
 DEPENDENCIES
   bundler (~> 2.1)
   byebug
   cli-kit!
+  cli-ui!
   method_source
   minitest (>= 5.0.0)
   minitest-reporters
-  mocha (~> 1.13.0)
+  mocha (~> 2.0.1)
   rake (~> 13.0)
   rubocop
+  rubocop-rake
   rubocop-shopify
+  rubocop-sorbet
+  simplecov
+  sorbet-static-and-runtime
+  tapioca
 
 BUNDLED WITH
    2.2.24

data/README.md

@@ -26,9 +26,52 @@ select how the project consumes `cli-kit` and `cli-ui`.  The available options a
 
 You're now ready to write your very first `cli-kit` application!
 
+## Upgrading to version 5
+
+Version 5 includes breaking changes and significant new features. Notably:
+
+* `autocall` is completely removed;
+* A help system and command-line option parsing system is added.
+
+Migrating away from `autocall` is as simple as replacing `autocall(:X) { y }` with `X = y`.
+
+Using the new help system is not yet well-documented, but some hints can be found in the
+`gen/ilb/gen/commands` directory of this repo. Existing commands in existing apps should continue to
+work.
+
+To use the new help system, commands should all define `invoke` instead of `call`. `invoke` takes
+`name` as before, but the first argument is now an instance of `Opts`, defined in the command class,
+which must be a subclass of `CLI::Kit::Opts`. For example:
+
+```ruby
+class MyCommand < CLI::Kit::BaseCommand
+  class Opts < CLI::Kit::Opts
+    def force
+      flag(short: '-f', long: '--force', description: 'Force the operation')
+    end
+  end
+  def invoke(op, _name)
+    if op.force
+      puts 'Forcing the operation'
+    else
+      puts 'Not forcing the operation'
+    end
+  end
+end
+```
+
+This particular structure was chosen to allow the code to by fully typed using sorbet, as `invoke`
+can be tagged with `sig { params(op: Opts, _name: String).void }`, and the `#force` method visibly
+exists.
+
+`-h/--help` is installed as a default flag, and running this command with `--help` is handled before
+reaching `#invoke`, to print a help message (for which several other class methods on `BaseCommand`
+provide text: `command_name`, `desc`, `long_desc`, `usage`, `example`, and `help_sections`). See
+`gen/lib/gen/commands/new.rb` for an example.
+
 ## How do `cli-kit` Applications Work?
 
-The executable for your `cli-kit` app is stored in the "exe" directory.  To execute the app, simply
+The executable for your `cli-kit` app is stored in the "exe" directory. To execute the app, simply
 run:
 ```bash
 ./exe/myproject
@@ -38,7 +81,7 @@ run:
 * `/exe/` - Location of the executables for your application.
 * `/lib/` - Location of the resources for your app (modules, classes, helpers, etc).
     * `myproject.rb` - This file is the starting point for where to look for all other files. It
-    configures autoload and autocall for the app.
+    configures autoload for the app.
     * `myproject/` - Stores the various commands/entry points.
         * `entry_point.rb` - This is the file that is first called from the executable. It handles 
         loading and commands.
@@ -113,4 +156,4 @@ powerful command-line user interface elements. For more details on how to use `c
 
 ## Examples
 
-- [A Simple To-Do App](https://github.com/Shopify/cli-kit-example)
+- [A Simple To-Do App](https://github.com/Shopify/cli-kit-example)

data/Rakefile

@@ -2,6 +2,7 @@ $LOAD_PATH.unshift(File.expand_path('../lib', __FILE__))
 require 'rake/testtask'
 require 'rubocop/rake_task'
 require 'bundler/gem_tasks'
+require 'sorbet-runtime' unless ENV['BUNDLE_WITHOUT'] == 'typecheck'
 
 TEST_ROOT = File.expand_path('../test', __FILE__)
 

data/bin/onchange

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# typed: ignore
+# frozen_string_literal: true
+
+require('open3')
+
+extra_fswatch_args, cmd_args = if (rest_index = ARGV.index('--'))
+  [ARGV[0...rest_index], ARGV[rest_index + 1..-1]]
+else
+  [[], ARGV]
+end
+
+if cmd_args.size == 1 && cmd_args =~ /[&;|]/
+  cmd_args = ['bash', '-c', cmd_args[0]]
+end
+
+system(*cmd_args)
+
+fswatch_args = [
+  '-e', 'coverage',
+  '-e', '/\.git',
+  '--one-per-batch',
+  *extra_fswatch_args,
+  '.',
+]
+
+Open3.popen3('fswatch', *fswatch_args) do |stdin, stdout, _stderr, _wait_thr|
+  stdin.close
+  stdout.each { |_| system(*cmd_args) }
+end

data/bin/tapioca

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'tapioca' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('../bundle', __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('tapioca', 'tapioca')

data/bin/testunit

@@ -2,6 +2,7 @@
 
 require 'rubygems'
 require 'bundler/setup'
+require 'sorbet-runtime' unless ENV['BUNDLE_WITHOUT'] == 'typecheck'
 
 root = File.expand_path('../..', __FILE__)
 CLI_TEST_ROOT = root + '/test'

data/cli-kit.gemspec

@@ -16,13 +16,13 @@ Gem::Specification.new do |spec|
   spec.license       = 'MIT'
 
   spec.files = %x(git ls-files -z).split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
+    f.match(%r{^(sorbet|test|spec|features)/})
   end
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency('cli-ui', '>= 1.1.4')
+  spec.add_runtime_dependency('cli-ui', '~> 2.0')
 
   spec.add_development_dependency('bundler', '~> 2.1')
   spec.add_development_dependency('minitest', '~> 5.0')

data/dev.yml

@@ -1,7 +1,39 @@
 up:
-  - ruby: 2.7.0
+  - homebrew:
+      - fswatch
+  - ruby: 3.0.4
   - bundler
 
 commands:
-  test: bin/testunit
-  style: "bundle exec rubocop -D"
+  console: irb -I./lib -rcli/kit
+  check:
+    run: 'srb && rake style test'
+    aliases: [ck]
+  test:
+    run: rake test
+    aliases: [t]
+  style:
+    run: rake style
+    aliases: [st]
+  typecheck:
+    run: srb
+    aliases: [tc]
+  watch:
+    aliases: [w]
+    subcommands:
+      style:
+        run: bin/onchange rake style
+        aliases: [st]
+      test:
+        run: bin/onchange rake test
+        aliases: [t]
+      typecheck:
+        run: bin/onchange srb
+        aliases: [tc]
+      check:
+        run: bin/onchange 'srb && rake style test'
+        aliases: [ck]
+fastcheck:
+  Test: bundle exec rake test
+  Style: bundle exec rake style
+  Typecheck: bundle exec srb tc

data/examples/minimal/example.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# typed: true
 
 require 'cli/ui'
 require 'cli/kit'
@@ -7,8 +8,9 @@ CLI::UI::StdoutRouter.enable
 
 include(CLI::Kit)
 
-registry = CommandRegistry.new(default: 'hello', contextual_resolver: nil)
+registry = CommandRegistry.new(default: 'hello')
 registry.add(Class.new(BaseCommand) do
+  sig { params(_args: T::Array[String], _name: String).void }
   def call(_args, _name)
     puts 'hello, world!'
   end

data/examples/single-file/example.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# typed: true
 
 require 'cli/ui'
 require 'cli/kit'
@@ -6,62 +7,51 @@ require 'cli/kit'
 CLI::UI::StdoutRouter.enable
 
 module Example
-  extend CLI::Kit::Autocall
-
   TOOL_NAME = 'example'
   ROOT      = File.expand_path('../..', __FILE__)
   LOG_FILE  = '/tmp/example.log'
 
   module Commands
-    extend CLI::Kit::Autocall
+    Registry = CLI::Kit::CommandRegistry.new(default: 'hello')
 
-    Registry = CLI::Kit::CommandRegistry.new(
-      default: 'hello',
-      contextual_resolver: nil
-    )
+    class << self
+      sig { params(const: Symbol, cmd: String, path: String, lamda_const: T.proc.returns(Example::Command)).void }
+      def register(const, cmd, path, lamda_const)
+        autoload(const, path)
+        Registry.add(lamda_const, cmd)
+      end
 
-    def self.register(const, cmd, path = nil, &block)
-      path ? autoload(const, path) : autocall(const, &block)
-      Registry.add(->() { const_get(const) }, cmd)
+      # register(:Hello, 'hello', 'a/b/hello', -> { Commands::Hello })
     end
 
-    # register(:Hello, 'hello', 'a/b/hello')
-
-    register(:Hello, 'hello') do
-      Class.new(Example::Command) do
-        def call(_args, _name)
-          puts 'hello, world!'
-        end
+    class Hello < Example::Command
+      sig { override.params(_args: T::Array[String], _name: String).void }
+      def call(_args, _name)
+        puts 'hello, world!'
       end
     end
   end
 
-  autocall(:EntryPoint) do
-    Module.new do
-      def self.call(args)
+  module EntryPoint
+    class << self
+      sig { params(args: T::Array[String]).void }
+      def call(args)
         cmd, command_name, args = Example::Resolver.call(args)
         Example::Executor.call(cmd, command_name, args)
       end
     end
   end
 
-  autocall(:Config)  { CLI::Kit::Config.new(tool_name: TOOL_NAME) }
-  autocall(:Command) { CLI::Kit::BaseCommand }
+  Config = CLI::Kit::Config.new(tool_name: TOOL_NAME)
+  Command = CLI::Kit::BaseCommand
 
-  autocall(:Executor) { CLI::Kit::Executor.new(log_file: LOG_FILE) }
-  autocall(:Resolver) do
-    CLI::Kit::Resolver.new(
-      tool_name: TOOL_NAME,
-      command_registry: Example::Commands::Registry
-    )
-  end
+  Executor = CLI::Kit::Executor.new(log_file: LOG_FILE)
+  Resolver = CLI::Kit::Resolver.new(
+    tool_name: TOOL_NAME,
+    command_registry: Example::Commands::Registry,
+  )
 
-  autocall(:ErrorHandler) do
-    CLI::Kit::ErrorHandler.new(
-      log_file: LOG_FILE,
-      exception_reporter: nil
-    )
-  end
+  ErrorHandler = CLI::Kit::ErrorHandler.new(log_file: LOG_FILE)
 end
 
 if __FILE__ == $PROGRAM_NAME