cli-kit 4.0.0 → 5.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 523252459712e507c4579e244e6330eb3e8a5d8c71334d4e41553903ab651cd6
-  data.tar.gz: 459cb0a684e2890718d0cffdd74cd8540bd91a1995dfe1db593df9a189da20d7
+  metadata.gz: af93e4820420cf1704d8cca5d63107f7bd83961100daa6db8e7f8548680cd10e
+  data.tar.gz: 4894fe464e5be800e850a9543978bb80f3353837ed8e52b63a8cd60f1167f951
 SHA512:
-  metadata.gz: 8579924711573ce6338b52dc44c47ad40c12f925bbd6f3ad6cee5be9f44b2b4f315e6d272adc309788b0418ee6806567660f0386d7e91d9d09a524beeb0a4a1f
-  data.tar.gz: b5507292ba97fd6f13b83b6426e81e4500e0ef1480387164c936164b7593bf7daac98e39cbb835362f198c39e562f2d12adf92384365a9c99a7f0ed42c158a45
+  metadata.gz: 5d47834888929cf73123f2ecb5ca47676f530fbc51355f54b1dd4ef098f6f1afa5f0603d4e6c468326d114324ff467487085dced9cd24bf67ac87890ec4eadb8
+  data.tar.gz: f49180d83cf371a0e5f8870c95a5dcfdb44add7ab4938ba6cb24adb1de034a2526c9505b5eba1cd731d28e8b2089fbce748dec6c5191dcdc140a44713f6f6c79

data/.github/dependabot.yml

@@ -8,3 +8,6 @@ updates:
     time: "07:00"
     timezone: America/Toronto
   open-pull-requests-limit: 99
+  groups:
+    dev-dependencies:
+      dependency-type: "development"

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:
@@ -10,17 +11,30 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '2.7'
         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:
+        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']
+        ruby-version: ['3.1', '3.2', '3.3']
 
     runs-on: ${{ matrix.os }}
+    env:
+      BUNDLE_WITHOUT: typecheck
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby

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
+    - lib/cli/kit/levenshtein.rb # Vendored
+  NewCops: disable
 
 Style/ClassAndModuleChildren:
   Exclude:
@@ -36,3 +43,27 @@ 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
+
+# We make frequent use Open3 methods to run other programs. When passing long command lines, it's useful and informative
+# to place the argument to an option on the same line as its option, eg:
+# Open3.capture3(
+#   'curl',
+#   '-H', 'X-Header: value',
+#   '-o', 'file.txt',
+#   '-L',
+#   'https://example.com/',
+# )
+Layout/MultilineMethodArgumentLineBreaks:
+  Enabled: false
+Layout/MultilineArrayLineBreaks:
+  Enabled: false
+Layout/MultilineHashKeyLineBreaks:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.3.0

data/Gemfile

@@ -4,14 +4,23 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
+  gem 'cli-ui'
   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.4.0', require: false
   gem 'minitest', '>= 5.0.0', require: false
   gem 'minitest-reporters', require: false
 end

data/Gemfile.lock

@@ -1,62 +1,135 @@
 PATH
   remote: .
   specs:
-    cli-kit (4.0.0)
-      cli-ui (>= 1.1.4)
+    cli-kit (5.0.1)
+      cli-ui (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ansi (1.5.0)
     ast (2.4.2)
-    builder (3.2.4)
+    benchmark (0.4.0)
+    builder (3.3.0)
     byebug (11.1.3)
-    cli-ui (1.5.1)
-    method_source (1.0.0)
-    minitest (5.14.4)
-    minitest-reporters (1.4.3)
+    cli-ui (2.3.0)
+    docile (1.4.1)
+    erubi (1.13.1)
+    json (2.10.1)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
+    logger (1.6.6)
+    method_source (1.1.0)
+    minitest (5.25.4)
+    minitest-reporters (1.7.1)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
-    mocha (1.13.0)
-    parallel (1.21.0)
-    parser (3.0.2.0)
+    mocha (2.4.5)
+      ruby2_keywords (>= 0.0.5)
+    netrc (0.11.0)
+    parallel (1.26.3)
+    parser (3.3.7.1)
       ast (~> 2.4.1)
-    rainbow (3.0.0)
-    rake (13.0.6)
-    regexp_parser (2.1.1)
-    rexml (3.2.5)
-    rubocop (1.22.3)
+      racc
+    prism (1.3.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    rbi (0.3.0)
+      prism (~> 1.0)
+      rbs (>= 3.4.4)
+      sorbet-runtime (>= 0.5.9204)
+    rbs (3.8.1)
+      logger
+    regexp_parser (2.10.0)
+    rubocop (1.73.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
-      parser (>= 3.0.0.0)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.12.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.38.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)
-    ruby-progressbar (1.11.0)
-    unicode-display_width (2.1.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.38.1)
+      parser (>= 3.3.1.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    rubocop-shopify (2.16.0)
+      rubocop (~> 1.62)
+    rubocop-sorbet (0.9.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    sorbet (0.5.11915)
+      sorbet-static (= 0.5.11915)
+    sorbet-runtime (0.5.11915)
+    sorbet-static (0.5.11915-universal-darwin)
+    sorbet-static (0.5.11915-x86_64-linux)
+    sorbet-static-and-runtime (0.5.11915)
+      sorbet (= 0.5.11915)
+      sorbet-runtime (= 0.5.11915)
+    spoom (1.5.4)
+      erubi (>= 1.10.0)
+      prism (>= 0.28.0)
+      rbi (>= 0.2.3)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      thor (>= 0.19.2)
+    tapioca (0.16.11)
+      benchmark
+      bundler (>= 2.2.25)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (~> 0.2)
+      sorbet-static-and-runtime (>= 0.5.11087)
+      spoom (>= 1.2.0)
+      thor (>= 1.2.0)
+      yard-sorbet
+    thor (1.3.2)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    yard (0.9.37)
+    yard-sorbet (0.9.0)
+      sorbet-runtime
+      yard
 
 PLATFORMS
-  ruby
+  arm64-darwin-21
+  universal-darwin
+  x64-mingw-ucrt
+  x64-mingw32
+  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.4.0)
   rake (~> 13.0)
   rubocop
+  rubocop-rake
   rubocop-shopify
+  rubocop-sorbet
+  simplecov
+  sorbet-static-and-runtime
+  tapioca
 
 BUNDLED WITH
-   2.2.24
+   2.4.9

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,28 @@
+#!/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

@@ -7,8 +7,11 @@ require 'cli/kit/version'
 Gem::Specification.new do |spec|
   spec.name          = 'cli-kit'
   spec.version       = CLI::Kit::VERSION
-  spec.authors       = ['Burke Libbey', 'Aaron Olson', 'Lisa Ugray']
-  spec.email         = ['burke.libbey@shopify.com', 'aaron.olson@shopify.com', 'lisa.ugray@shopify.com']
+  spec.authors       = ['Burke Libbey', 'Aaron Olson', 'Lisa Ugray', 'Don Kelly']
+  spec.email         = [
+    'burke.libbey@shopify.com', 'aaron.olson@shopify.com', 'lisa.ugray@shopify.com',
+    'don.kelly@shopify.com',
+  ]
 
   spec.summary       = 'Terminal UI framework extensions'
   spec.description   = 'Terminal UI framework extensions'
@@ -16,13 +19,15 @@ 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.required_ruby_version = '>= 3.0'
 
   spec.add_development_dependency('bundler', '~> 2.1')
   spec.add_development_dependency('minitest', '~> 5.0')

data/dev.yml

@@ -1,7 +1,42 @@
 up:
-  - ruby: 2.7.0
+  - homebrew:
+      - fswatch
+  - ruby
   - bundler
 
 commands:
-  test: bin/testunit
-  style: "bundle exec rubocop -D"
+  add-back-ruby:
+    run: bundle lock --add-platform ruby && git commit -a -m 'Add back ruby platform' && git push
+    aliases: [abr]
+  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,12 +8,16 @@ CLI::UI::StdoutRouter.enable
 
 include(CLI::Kit)
 
-registry = CommandRegistry.new(default: 'hello', contextual_resolver: nil)
-registry.add(Class.new(BaseCommand) do
-  def call(_args, _name)
-    puts 'hello, world!'
-  end
-end, 'hello')
+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
+  end,
+  'hello',
+)
 
 executor      = Executor.new(log_file: '/tmp/example.log')
 error_handler = ErrorHandler.new(log_file: '/tmp/example.log', exception_reporter: nil)