dry-cli-autocomplete 0.1.3

data/lib/dry/cli/autocomplete/emitters/zsh.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "dry/inflector"
+
+module Dry
+  class CLI
+    module Autocomplete
+      module Emitters
+        # Turns a CompletionSpec into a native zsh `#compdef` script.
+        #
+        # This is not a bashcompinit shim. Options go through `_arguments`
+        # carrying their `desc` as help text, subcommands go through
+        # `_describe`, declared enum values become a `(a b c)` action, and a
+        # file argument becomes `_files`. That per-option help is the thing
+        # zsh users lose with a shim, and the reason this emitter exists.
+        # See SPECIFICATION.md §4.1.
+        #
+        # Shares no code with the bash emitter by design: a fourth shell
+        # should be a new class here, never another branch inside one of
+        # these two.
+        class Zsh
+          def self.call(spec)
+            new(spec).call
+          end
+
+          def initialize(spec)
+            @spec = spec
+          end
+
+          def call
+            "#{body.join("\n")}\n"
+          end
+
+          private
+
+          attr_reader :spec
+
+          def body
+            header_lines + path_walk_lines + dispatch_lines + footer_lines
+          end
+
+          def header_lines
+            [
+              "#compdef #{spec.program_name}",
+              "",
+              "# Generated by dry-cli-autocomplete. Regenerate after changing commands.",
+              "",
+              "#{function_name}() {",
+              '  local curcontext="$curcontext" state line ret=1',
+              "  local -a commands",
+              "  typeset -A opt_args",
+              ""
+            ]
+          end
+
+          # Resolves which node the cursor sits under by consuming words the
+          # registry knows, exactly as the bash emitter does. words[1] is the
+          # program itself under zsh, so the scan starts at 2.
+          def path_walk_lines
+            lines = [
+              '  local path_key="" i=2',
+              "  while (( i < CURRENT )); do",
+              '    case "$path_key:${words[i]}" in'
+            ]
+            edge_arms.each { |arm| lines << "      #{arm}" }
+            lines + [
+              "      (*) break ;;",
+              "    esac",
+              "    (( i += 1 ))",
+              "  done",
+              ""
+            ]
+          end
+
+          def dispatch_lines
+            lines = ['  case "$path_key" in']
+            spec.nodes.each { |node| lines.concat(node_arm_lines(node)) }
+            lines + ["  esac", ""]
+          end
+
+          # A #compdef file dropped on $fpath is autoloaded by the completion
+          # system with its own name on the function stack, and is expected to
+          # do the completion. The same text sourced from a profile, which is
+          # what `eval "$(mycli completion zsh)"` does, runs with no completion
+          # in progress: calling the function there reaches for _describe
+          # before the completion system has defined it, and zsh reports a
+          # command-not-found from inside a file the user never wrote.
+          #
+          # Naming the function after the program, which is the convention a
+          # compdef file follows anyway, lets one line tell the two apart.
+          def footer_lines
+            [
+              "  return ret",
+              "}",
+              "",
+              "if [ \"$funcstack[1]\" = \"#{function_name}\" ]; then",
+              "  #{function_name} \"$@\"",
+              "else",
+              "  compdef #{function_name} #{spec.program_name}",
+              "fi"
+            ]
+          end
+
+          def node_arm_lines(node)
+            inner = arguments_call_lines(node) + describe_call_lines(node)
+            return [] if inner.empty?
+
+            ["    (#{single_quote(path_key(node.path))})", *inner.map { |line| "      #{line}" }, "      ;;"]
+          end
+
+          # One `_arguments` call carrying every option and positional this
+          # node declares. `-s` allows clustered single-letter flags.
+          def arguments_call_lines(node)
+            specs = node.options.flat_map { |option| option_specs(option) } +
+                    node.arguments.map { |argument| argument_spec(argument) }
+            return [] if specs.empty?
+
+            ["_arguments -s \\", *specs[0..-2].map { |s| "  #{s} \\" }, "  #{specs.last} && ret=0"]
+          end
+
+          def describe_call_lines(node)
+            return [] if node.children.empty?
+
+            entries = node.children.map do |child|
+              single_quote("#{escape_describe(child)}:#{escape_describe(child_desc(node, child))}")
+            end
+
+            ["commands=(", *entries.map { |e| "  #{e}" }, ")",
+             "_describe -t commands #{single_quote(describe_tag(node))} commands && ret=0"]
+          end
+
+          # Each alias gets its own spec rather than a {-f,--force} group:
+          # the grouped form needs its description outside the quotes, and
+          # one entry per flag is easier to read in the generated file.
+          def option_specs(option)
+            names = ["--#{option.name}"] + Array(option.aliases)
+            names.map { |name| single_quote("#{name}#{bracketed(option.desc)}#{option_action(option)}") }
+          end
+
+          # A boolean flag takes no value. Anything else gets one field
+          # naming what it wants and one supplying the completions for it.
+          def option_action(option)
+            return "" if option.boolean
+
+            ":#{escape_spec(option.name)}:#{value_action(option.values)}"
+          end
+
+          # A positional takes `:message:action`, with no bracketed
+          # description: zsh shows the message itself while completing, so
+          # the command's own wording goes there when it has any.
+          def argument_spec(argument)
+            action = argument.file ? "_files" : value_action(argument.values)
+            message = argument.desc.to_s.empty? ? argument.name : argument.desc
+            single_quote("*:#{escape_describe(message)}:#{action}")
+          end
+
+          def value_action(values)
+            return "" if values.nil? || values.empty?
+
+            "(#{values.map { |value| escape_spec(value) }.join(' ')})"
+          end
+
+          def bracketed(desc)
+            return "" if desc.nil? || desc.empty?
+
+            "[#{escape_bracket(desc)}]"
+          end
+
+          def child_desc(node, child)
+            found = spec.nodes.find { |candidate| candidate.path == node.path + [child] }
+            found&.desc.to_s
+          end
+
+          def describe_tag(node)
+            node.path.empty? ? "command" : "#{node.path.join(' ')} command"
+          end
+
+          def path_key(path) = path.join(" ")
+
+          # zsh reads `]` as the end of a description and `:` as the start of
+          # the next spec field, so both have to be escaped inside one.
+          def escape_bracket(str) = str.to_s.gsub("\\", "\\\\\\\\").gsub("]", "\\\\]").gsub(":", "\\\\:")
+
+          def escape_spec(str) = str.to_s.gsub("\\", "\\\\\\\\").gsub(":", "\\\\:").gsub(/([()\[\] ])/, '\\\\\1')
+
+          def escape_describe(str) = str.to_s.gsub("\\", "\\\\\\\\").gsub(":", "\\\\:")
+
+          def single_quote(str) = "'#{str.to_s.gsub("'", "'\\\\''")}'"
+
+          # `_mycli`, not `_mycli_completions`: zsh autoloads a compdef file by
+          # the name of the function it defines, so matching that convention is
+          # what makes the footer's fpath check work.
+          def function_name = "_#{shell_identifier}"
+
+          # A program installed as `my-tool` cannot name a shell function
+          # directly. See SPECIFICATION.md §4.2.
+          def shell_identifier
+            Dry::Inflector.new.underscore(spec.program_name.to_s).gsub(/[^A-Za-z0-9_]/, "_")
+          end
+
+          def edge_arms
+            spec.nodes.flat_map do |node|
+              node.children.map do |child|
+                "(#{single_quote("#{path_key(node.path)}:#{child}")}) " \
+                  "path_key=#{single_quote(path_key(node.path + [child]))} ;;"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/cli/autocomplete/spec_builder.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Autocomplete
+      # Walks a Dry::CLI registry through its public API and returns a
+      # shell-agnostic description of every completion: one CompletionSpec
+      # carrying one Node per reachable, non-hidden command or group.
+      #
+      # Touches nothing beyond the registry and the command classes it
+      # already holds, so it stays cheap enough to run on every shell start.
+      # See SPECIFICATION.md §2.2 and §2.3.
+      class SpecBuilder
+        # `::Data`, with the leading colons, and never a bare `Data`. This file
+        # is lexically inside `module Dry`, so an unqualified constant is looked
+        # up there first: a bare `Struct` here meant `Dry::Struct` in any host
+        # that had dry-struct loaded, which took different arguments and broke
+        # on the host's machine while this gem's own suite stayed green. No
+        # `Dry::Data` exists today, but the same trap is one released gem away,
+        # and dry_struct_host_spec.rb is what keeps watch.
+        #
+        # Data rather than Struct because these are descriptions, built once and
+        # rendered: frozen is what they should be, a missing field raises rather
+        # than arriving as a silent nil, and `:values` stops colliding with a
+        # method Struct defines and Data does not.
+        CompletionSpec = ::Data.define(:program_name, :nodes)
+        Node = ::Data.define(:path, :desc, :options, :arguments, :children)
+        OptionSpec = ::Data.define(
+          :name, :type, :values, :aliases, :default, :desc, :required, :boolean, :array
+        )
+        ArgumentSpec = ::Data.define(:name, :values, :desc, :required, :file)
+
+        # A bare heuristic, used only when a host does not declare `file:`
+        # explicitly on the argument. See SPECIFICATION.md §4.3.
+        FILE_ARGUMENT_HEURISTIC = /file|path/i
+
+        def self.call(registry, program_name:)
+          new(registry, program_name).call
+        end
+
+        def initialize(registry, program_name)
+          @registry = registry
+          @program_name = program_name
+        end
+
+        def call
+          CompletionSpec.new(program_name: program_name, nodes: walk([]))
+        end
+
+        private
+
+        attr_reader :registry, :program_name
+
+        def walk(path, nodes = [])
+          result = registry.get(path)
+          visible = visible_children(result)
+
+          nodes << build_node(path, result, visible)
+          visible.each_key { |name| walk(path + [name], nodes) }
+          nodes
+        end
+
+        def visible_children(result)
+          result.children.reject { |_name, node| node.hidden }
+        end
+
+        def build_node(path, result, visible)
+          command = result.command
+
+          Node.new(
+            path: path,
+            desc: command&.description,
+            options: command ? command.options.map { |option| build_option(option) } : [],
+            arguments: command ? command.arguments.map { |argument| build_argument(argument) } : [],
+            children: visible.keys
+          )
+        end
+
+        def build_option(option)
+          OptionSpec.new(
+            name: option.name.to_s, type: option.type, values: option.values,
+            aliases: option.aliases, default: option.default, desc: option.options[:desc],
+            required: option.required? || false, boolean: option.boolean?, array: option.array?
+          )
+        end
+
+        def build_argument(argument)
+          ArgumentSpec.new(
+            name: argument.name.to_s, values: argument.values, desc: argument.options[:desc],
+            required: argument.required? || false, file: file_argument?(argument)
+          )
+        end
+
+        def file_argument?(argument)
+          explicit = argument.options[:file]
+          return !!explicit unless explicit.nil?
+
+          argument.name.to_s.match?(FILE_ARGUMENT_HEURISTIC)
+        end
+      end
+    end
+  end
+end

data/lib/dry/cli/autocomplete/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Dry
+  # Reopened rather than defined: dry-cli declares `class CLI`, not a module,
+  # and getting that wrong raises TypeError the moment both are loaded.
+  #
+  # Declared here without requiring dry-cli, because the gemspec loads this
+  # file at build time when the dependency may not be installed. dry-cli's CLI
+  # inherits from Object, so an empty reopening is compatible either way.
+  class CLI
+    module Autocomplete
+      VERSION = "0.1.3"
+    end
+  end
+end

data/lib/dry/cli/autocomplete.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "autocomplete/version"
+
+module Dry
+  class CLI
+    # Generates static shell completion scripts from a Dry::CLI registry.
+    #
+    # The generator reads the registry and never forces anything beyond it:
+    # commands, subcommands, options, their declared enum values, and which
+    # arguments look like file paths. Nothing it produces requires loading a
+    # host's data, because the script is regenerated on every shell start via
+    # `eval "$(mycli completion bash)"` and a slow generator is a slow shell.
+    module Autocomplete
+      class Error < StandardError; end
+    end
+  end
+end

data/lib/dry-cli-autocomplete.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "dry/cli/autocomplete"

data/sig/dry/cli/autocomplete.rbs

@@ -0,0 +1,8 @@
+module Dry
+  class CLI
+    module Autocomplete
+      VERSION: String
+      # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    end
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: dry-cli-autocomplete
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- Konstantin Gredeskoul
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: dry-inflector
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Supports auto-completion for dry-cli powered Ruby CLI tools, including
+  sub-commands, in BASH and ZSH.
+email:
+- kigster@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".secrets.baseline"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- SPECIFICATION.md
+- docs/img/badge.svg
+- justfile
+- lefthook.yml
+- lib/dry-cli-autocomplete.rb
+- lib/dry/cli/autocomplete.rb
+- lib/dry/cli/autocomplete/command.rb
+- lib/dry/cli/autocomplete/emitters/bash.rb
+- lib/dry/cli/autocomplete/emitters/zsh.rb
+- lib/dry/cli/autocomplete/spec_builder.rb
+- lib/dry/cli/autocomplete/version.rb
+- sig/dry/cli/autocomplete.rbs
+homepage: https://github.com/kigster/dry-cli-autocomplete
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kigster/dry-cli-autocomplete
+  source_code_uri: https://github.com/kigster/dry-cli-autocomplete
+  changelog_uri: https://github.com/kigster/dry-cli-autocomplete/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: A missing auto-complete addition for dry-cli powered Ruby CLI tools for BASH
+  & ZSH
+test_files: []