dry-cli-autocomplete 0.1.3

data/SPECIFICATION.md

@@ -0,0 +1,246 @@
+# `dry-cli-autocomplete`: Specification
+
+Generate static shell completion scripts for any `Dry::CLI` application, from the command registry alone.
+
+The intended use is one line in a shell profile:
+
+```bash
+eval "$(mycli completion bash)"    # ~/.bashrc
+eval "$(mycli completion zsh)"     # ~/.zshrc
+```
+
+The script is regenerated when the shell starts, so a new command in the host application completes as soon as it ships. Pressing TAB runs nothing: the shell matches against a word list the script already carries.
+
+## Research
+
+Research discovered a completion gems [https://github.com/rngtng/dry-cli-completion](https://github.com/rngtng/dry-cli-completion) however it lacks in a several areas (see below).
+
+## Motivation
+
+## 1. Why this exists when `dry-cli-completion` already does
+
+`rngtng/dry-cli-completion` (MIT, v2.0.0) works and is the obvious starting point. Read it before writing anything. It falls short in four specific ways, each of which is an acceptance criterion below.
+
+**1.1 A node carrying both a command and children loses its children.** `Input#extract_commands` branches `if sub_node.command ... elsif sub_node.children`. An application that registers an overview command at a group's bare name, so that `mycli db --help` can explain what the group is for, gets:
+
+```ruby
+register "db", DbOverview      # node now has a command
+register "db migrate", Migrate # ...and children, which are never walked
+```
+
+Completion for `mycli db <TAB>` offers `--help` and nothing else. The subcommands are invisible. This is not exotic: it is what any application does when it wants group-level help.
+
+**1.2 File arguments are dropped silently.** `Input#input_line` opens with `return if name.include?("<file>")`. A command whose argument name matches `/path/` produces no entry at all, and the generated script contains no `compgen -f`, no `-o default`, no `_filedir`. So `mycli deploy <TAB>` on a path argument completes nothing, which is the single most common thing a user wants.
+
+**1.3 There is no light entry point.** `command.rb` opens with `require "dry/cli/completion"`, which loads the generator, which loads `completely`. A host that only wants to register the command pays for the whole tree at boot. Measured: `require "dry/cli"` is 160ms, adding the completion gem makes it 190ms. Thirty milliseconds on every invocation of a command run once per shell.
+
+**1.4 zsh is a bashcompinit shim.** It emits `autoload -Uz +X bashcompinit && bashcompinit` and then bash. It works, but zsh users get no per-option descriptions and none of the native behaviour they expect.
+
+There is also a dependency argument. `completely` pulls `colsole`, `docopt_ng` and `mister_bin`, and `mister_bin` is itself a CLI framework. Four gems, one of them a second CLI framework, to emit a shell script. This gem generates the script itself and depends on `dry-cli` and `dry-inflector` only.
+
+## 2. Design decisions, and the measurements behind them
+
+These were settled by profiling a real dry-cli application (`tax_engine`, 27 commands, 33 options, 7 arguments). Reproduce them before overturning any of this.
+
+| Measurement                                               |           Time |
+| --------------------------------------------------------- | -------------: |
+| Bare `ruby -e ''`                                         |          100ms |
+| `require "dry/cli"`                                       |          160ms |
+| `require "dry/cli"` + `dry-cli-completion` + `completely` |          190ms |
+| `require "tax_engine"` (a gem with 2.5M lines of data)    |          520ms |
+| First touch of that host's data store                     |         +239ms |
+| **Registry walk and full completion spec build**          |    **0.067ms** |
+| Generated bash script for 27 commands                     | 257 lines, 9KB |
+
+### 2.1 Static generation, never a runtime callback
+
+Cobra and clap route every TAB press to a hidden `__complete` subcommand. That is correct for a Go or Rust binary that starts in 10ms. It is wrong here: a Ruby host costs 100ms at absolute best and 520ms in the case measured above. Half a second of dead air per keystroke is unusable, and no amount of lazy loading gets under the host's own require cost.
+
+So the generated script carries every completion it will ever offer, and TAB spawns no process. **Do not add a `__complete` command.** It was considered, costed at about 90 lines, and rejected on this measurement.
+
+### 2.2 The generator reads the registry and never forces anything beyond it
+
+The full walk plus spec build takes 0.067ms because it only touches objects dry-cli already holds. The moment an option's `values:` calls into a host's data, that cost lands at class-definition time on *every* invocation of the host, not just completion. In the profiled host that would have added 239ms of YAML parsing to shell startup.
+
+Enum values *declared on an option* are free and must be included:
+
+```ruby
+option :format, values: %w[json yaml table]   # completes json yaml table
+argument :component, values: %w[major minor]  # completes major minor
+```
+
+Values a host would have to compute are out of scope. There is no API for them. A host that wants them declares them as a constant on the option, where dry-cli validates the input and the generator sees it for free.
+
+### 2.3 Optimising the generator is pointless
+
+At 0.067ms, the work this gem does is 0.01% of the cheapest possible invocation. Native extensions were considered and rejected: they cannot reduce interpreter startup, which is where all the time goes, and they would put a compiled artifact in the dependency chain of every consumer. Keep it plain Ruby.
+
+### 2.4 Nothing loads until the command runs
+
+The host registers a command whose file pulls in no emitters:
+
+```ruby
+require "dry/cli/autocomplete/command"
+register "completion", Dry::CLI::Autocomplete::Command[MyCLI]
+```
+
+`command.rb` must define the command class and nothing else, and `require` the generator inside `#call`. This is the mistake in §1.3 and it cannot be retrofitted politely, so build it this way from the first commit. Verified working: after registering the shim, `defined?(Dry::CLI::Autocomplete::Generator)` is nil and `$LOADED_FEATURES` shows nothing, until the command is invoked.
+
+## 3. Reading a registry
+
+Everything needed is public API. **Do not use `instance_variable_get(:@node)`**, which is what the existing gem does. `Registry#get` returns a lookup result exposing `command`, `children` and `names`.
+
+This walk is proven against a foreign registry:
+
+```ruby
+def walk(registry, path = [], acc = [])
+  result = registry.get(path)
+  acc << [path, result.command, (result.children || {}).keys]
+  (result.children || {}).each_key { |name| walk(registry, path + [name], acc) }
+  acc
+end
+```
+
+Available per command: `.options` and `.arguments`. Per option: `name`, `type`, `values`, `aliases`, `default`, `desc`, `required?`, `boolean?`, `array?`. Per argument: `name`, `values`, `desc`, `required?`. Per node: `children`, `command`, `aliases`, `hidden`.
+
+Registering with `hidden: true` keeps a command out of `--help`; **the generator must skip hidden commands too**.
+
+Run against a registry with three commands, one of them nested, this produces:
+
+```
+(root)       -> version deploy db
+version      -> --format json plain
+deploy       -> --force -f staging production
+db           -> migrate
+db migrate   -> --step <file>
+```
+
+Note what that output demonstrates: the `-f` alias, enum values on both an option and an argument, a nested group with no command of its own, and a file argument detected.
+
+## 4. What the generated scripts must do
+
+### 4.1 Both shells, natively
+
+**bash** emits a `complete -F _mycli_completions mycli` function using `compgen -W` over the word list for the current command path, plus `compgen -f` where an argument takes a file.
+
+**zsh** emits a real `#compdef` script using `_arguments` and `_describe`, carrying each option's `desc` as help text. It is not a bashcompinit shim. This is the largest single piece of work in the gem, roughly 120 lines, and it is the reason the gem exists rather than a patch to the existing one.
+
+### 4.2 Program names that are not identifiers
+
+A host may be installed as `my-tool`. Shell function names cannot contain a dash, so derive the identifier with `Dry::Inflector#underscore` rather than a hand-rolled `gsub`. `Dry::CLI::Inflector` ships with dry-cli but only has `dasherize` and is marked `@api private`; do not use it.
+
+### 4.3 File arguments
+
+An argument whose name suggests a path should complete filenames. Matching on the name (`/file|path/`) is a heuristic and a poor one. Prefer letting the host be explicit, and fall back to the heuristic only when nothing is declared. Whatever the mechanism, the generated script must contain real file completion, which is the gap in §1.2.
+
+## 5. Testing
+
+**Never test only against one CLI.** A generator tested against a single registry bakes in that registry's shape. The suite must carry at least three fixture registries, and at least one must come from outside this project. Candidates: the examples in dry-cli's own repository, and Hanami's CLI.
+
+Each fixture must exercise: a nested group with a command at its bare name (§1.1), a file argument (§1.2), an option with `values`, a boolean flag, an option with an alias, and a hidden command.
+
+Validate generated output by running the shells, not by matching strings: `bash -n script` and `zsh -n script` both parse without executing. Golden-file the scripts so a change in output is visible in review.
+
+Pin the laziness contract with a spec, because it erodes silently:
+
+```ruby
+it "loads no emitter until the command runs" do
+  expect(defined?(Dry::CLI::Autocomplete::Generator)).to be_nil
+end
+```
+
+## 6. Acceptance criteria
+
+1. A node with both a command and children completes its children *and* its own options.
+1. Commands with file arguments produce real file completion in the generated script.
+1. `require "dry/cli/autocomplete/command"` loads no generator and no emitter.
+1. zsh output is a native `#compdef` script with per-option descriptions, not a bashcompinit shim.
+1. `bash -n` and `zsh -n` accept the generated scripts.
+1. Hidden commands do not appear.
+1. Program names containing dashes produce valid shell identifiers.
+1. Generating completions touches nothing outside the registry.
+1. Runtime dependencies are `dry-cli` and `dry-inflector`, and nothing else.
+1. The suite passes against at least one registry not written for this project.
+
+## 7. Out of scope
+
+- A `__complete` hidden command or any per-TAB process. See §2.1.
+- Values that require the host to load data. See §2.2.
+- Native extensions. See §2.3.
+- fish, PowerShell, nushell. Worth adding later; the emitter interface should make a fourth shell a new class rather than a new branch, but do not build them now.
+
+## 8. Scope estimate
+
+About 470 lines, most of it the zsh emitter and the specs.
+
+| Part                               | Lines |
+| ---------------------------------- | ----: |
+| Registry walk and spec builder     |    60 |
+| bash emitter                       |    60 |
+| zsh emitter                        |   120 |
+| Command shim and installation help |    30 |
+| Specs, including foreign fixtures  |   200 |
+
+Suggested order: walk, then bash, then zsh. The bash emitter proves the spec builder against a real shell quickly, and the zsh emitter is where the estimate is most likely to be wrong.
+
+## 9. Work units
+
+### 1. Registry walk and spec builder
+
+This section did not exist when the folder entered Building; an implementer found nothing here to build against and split it before writing any code, per the instruction that governs exactly this case. Four units, non-overlapping in the files they own, matching §8's table. #1 has no dependency on the others; #2 and #3 depend only on #1's *interface* below, not its code, so they can be built concurrently with each other and with WU1. WU4 integrates all three and is the last to land.
+
+Owns:
+
+- `lib/dry/cli/autocomplete/spec_builder.rb`,
+- `spec/dry/cli/autocomplete/spec_builder_spec.rb`,
+- `spec/support/fixtures/**`.
+
+Builds the fixture registries the whole suite depends on (§5: at least three, at least one from outside this project) and the walker (§3) that turns a registry into the `CompletionSpec` shape defined below. Owns file-argument *detection* (§4.3): the heuristic and any explicit declaration are resolved here, so emitters only ever read a plain `file?` flag and never re-derive it.
+
+Done when: builds a correct spec for every fixture; hidden commands are absent from it; a node with both a command and children reports both (§1.1 acceptance criterion); nothing outside the registry is touched (no file reads, no host constants beyond what `values:` already declared).
+
+### 2. `BASH` emitter
+
+Owns:
+
+- `lib/dry/cli/autocomplete/emitters/bash.rb`,
+- `spec/dry/cli/autocomplete/emitters/bash_spec.rb`.
+
+Consumes a `CompletionSpec` (build one by hand in specs against the documented shape; do not import WU1's fixtures until WU1 has landed) and emits the `complete -F` script per §4.1: `compgen -W` over each node's word list, `compgen -f` where `file?` is set.
+
+Done when: golden-file tests cover a fixture with a nested group, a file argument, an aliased option, and a hidden command absent from output; every golden file passes `bash -n`.
+
+### 3. `ZSH` emitter
+
+Owns:
+
+- `lib/dry/cli/autocomplete/emitters/zsh.rb`
+- spec/dry/cli/autocomplete/emitters/zsh_spec.rb\`.
+
+Same `CompletionSpec` input as WU2. Emits a native `#compdef` script using `_arguments`/`_describe` (§4.1), carrying each option's `desc`. Not a bashcompinit shim.
+
+Done when: golden-file tests as WU2, output validated with `zsh -n`, and per-option descriptions are visible in the generated `_describe` calls.
+
+### 4. Generator and command shim
+
+Owns:
+
+- `lib/dry/cli/autocomplete/generator.rb`,
+- `lib/dry/cli/autocomplete/command.rb`,
+- `spec/dry/cli/autocomplete/generator_spec.rb`,
+- `spec/dry/cli/autocomplete/command_spec.rb`.
+
+The generator is the small piece that ties a registry to an emitter: given a registry and a shell name, run WU1's spec builder, hand the result to WU2 or WU3's emitter, return the script. `command.rb` is the shim (§2.4): defines the command class, derives the program's shell-identifier with `Dry::Inflector#underscore` (§4.2, never a hand-rolled `gsub`), and `require`s `generator` only inside `#call`.
+
+Done when: the laziness spec from §5 passes (`defined?(Dry::CLI::Autocomplete::Generator)` is `nil` after requiring only `dry/cli/autocomplete/command`); dashed program names produce valid identifiers; the command actually produces working output end-to-end through a real emitter (a stub is fine mid-flight, but the unit is not done while one remains in the diff).
+
+### Interface contract between the units
+
+`SpecBuilder.call(registry, program_name:)` returns a `CompletionSpec`:
+
+- `program_name` — String, the shell-identifier-safe name (already run through `Dry::Inflector#underscore` by whichever unit constructs it — WU4's command shim owns this call, so WU1's builder just accepts the string it's given).
+- `nodes` — Array of `{path: Array<String>, options: [...], arguments: [...], children: Array<String>}`, one entry per node in the registry, hidden nodes excluded.
+- Each option: `{name:, type:, values:, aliases:, default:, desc:, required:, boolean:, array:}`.
+- Each argument: `{name:, values:, desc:, required:, file:}` — `file:` is the resolved boolean described under WU1 above.
+
+`Emitter.call(spec)` (both `Emitters::Bash` and `Emitters::Zsh`) takes one `CompletionSpec` and returns one String: the complete generated script. Neither emitter takes a registry, and neither knows what dry-cli's own API looks like.

data/docs/img/badge.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="99" height="20">
+  <linearGradient id="b" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <mask id="a">
+    <rect width="99" height="20" rx="3" fill="#fff"/>
+  </mask>
+  <g mask="url(#a)">
+    <path fill="#555" d="M0 0h63v20H0z"/>
+    <path fill="#4c1" d="M63 0h36v20H63z"/>
+    <path fill="url(#b)" d="M0 0h99v20H0z"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+    <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
+    <text x="31.5" y="14">coverage</text>
+    <text x="80" y="15" fill="#010101" fill-opacity=".3">98%</text>
+    <text x="80" y="14">98%</text>
+  </g>
+</svg>

data/justfile

@@ -0,0 +1,110 @@
+# Tell 'just' to run bash, source our setup script, then execute the recipe
+set shell := ["bash", "-c"]
+
+version := `grep VERSION lib/dry/cli/autocomplete/version.rb | awk '{print $3}' | tr -d '"' | tr -d '\n'`
+rbenv   := 'eval "$(rbenv init - bash 2>/dev/null || true)"; bundle exec '
+repo    := 'git@github.com:kigster/dry-cli-autocomplete.git'
+
+gem_name := 'dry-cli-autocomplete'
+gem_file := 'pkg/' + gem_name + '-' + version + '.gem'
+gem_url  := 'https://rubygems.org/gems/' + gem_name
+
+[no-exit-message]
+recipes:
+    just --choose
+
+# Sync all dependencies
+install:
+    bin/setup
+
+build: install
+
+# Lint and reformat files
+lint:
+    {{ rbenv }} rubocop
+
+# Lint and reformat files (-a) — pass -A as an argument
+format *args:
+    {{ rbenv }} rubocop -a {{ args }}
+    /usr/bin/find . -name '*.md' -exec mdformat --wrap no {} \; -print
+
+# Run all the tests
+test *args: 
+    export ENVIRONMENT=test; {{ rbenv }} rspec {{args}}
+
+# Run tests with coverage
+test-coverage *args:
+    export ENVIRONMENT=test; export COVERAGE=true; {{ rbenv }} rspec {{ args }}
+
+ci: lint test-coverage 
+
+alias check-all := ci
+
+clean:
+    #!/usr/bin/env bash
+    @find . -name .DS_Store -delete -print || true
+    @rm -rf tmp/*
+
+# Run all lefthook pre-commit hooks
+lefthook:
+    {{ rbenv }} lefthook run pre-commit --all-files
+
+# Print current gem version
+version:
+    @echo "{{ version }}"
+
+# Clobber
+clobber: 
+    {{ rbenv }} rake clobber
+
+# Generate documentation
+doc: 
+    #!/usr/bin/env bash
+    {{ rbenv }} rake doc
+
+# `gem push` rather than `rake release`: release also guards the tree, tags and
+# pushes git — which `just release` does deliberately and separately — and it
+# gives no way to pass a 2FA code, so it always stopped to prompt.
+#
+# The code comes from 1Password unless one is passed in:
+#
+#   just publish            # read the code from 1Password
+#   just publish 123456     # use this code
+#
+# `just publish-all` in inquirex-tools passes one, because a TOTP is single-use:
+# four gems reading the same 30-second window would have the second push
+# rejected as a replay.
+#
+# Build the .gem and push it to RubyGems, non-interactively
+publish otp="": build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    eval "$(rbenv init - bash 2>/dev/null || true)"
+
+    mkdir -p pkg
+    gem build {{ gem_name }}.gemspec --output "{{ gem_file }}"
+
+    # `|| true` is load-bearing: under `set -e` a failed `op read` — not signed
+    # in to 1Password, item renamed, op not installed — would abort the recipe
+    # before the prompting fallback below could run.
+    otp="{{ otp }}"
+
+    if [[ -n "${otp}" ]]; then
+      gem push "{{ gem_file }}" --otp "${otp}"
+    else
+      echo "rubygems: no OTP available — gem push will prompt if 2FA is required."
+      gem push "{{ gem_file }}"
+    fi
+
+    # Only reachable when the push succeeded: `set -e` aborts the recipe on a
+    # non-zero `gem push`, so the page never opens for a release that failed.
+    echo "published {{ gem_name }} {{ version }} → {{ gem_url }}"
+    open "{{ gem_url }}" 2>/dev/null || xdg-open "{{ gem_url }}" 2>/dev/null || true
+
+# Tag v{{ version }}, publish the GH release, & refresh the Homebrew tap.
+release:
+    git fetch --tags
+    git tag -f "v{{ version }}"
+    git push -f --tags
+    gh release delete -y "v{{ version }}" --repo {{ repo }} 2>/dev/null || true
+    gh release create "v{{ version }}" --generate-notes --repo {{ repo }}

data/lefthook.yml

@@ -0,0 +1,34 @@
+output:
+  - summary
+  - failure
+
+pre-commit:
+  parallel: true
+  jobs:
+    - name: lint
+      run: bundle exec rubocop --force-exclusion --parallel {staged_files}
+      stage_fixed: true
+
+    - name: check for conflict markers and whitespace issues
+      run: git --no-pager diff --check
+
+    # If tests take >1 second, move this (or just the long-running tests) to pre-push.
+    - name: run tests
+      run: just test
+
+    - name: fix rubocop formatting issues
+      run: bundle exec rubocop -a {staged_files}
+      glob: "*.{rb,Gemfile,gemspec}"
+      stage_fixed: true
+
+    - name: spell check
+      run: codespell {staged_files}
+      glob: "*.{rb,md,gemspec}"
+
+    - name: format markdown
+      run: mdformat {staged_files}
+      glob: "*.md"
+      stage_fixed: true
+
+    - name: scan for secrets
+      run: detect-secrets-hook --baseline .secrets.baseline

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+module Dry
+  class CLI
+    module Autocomplete
+      # The command a host registers to expose `mycli completion <shell>`.
+      #
+      # This file defines the command class and nothing else. It loads no
+      # spec builder and no emitter, and it must stay that way: a host pays
+      # for whatever this require pulls on *every* invocation, while the
+      # command itself runs about once per shell. The generator is required
+      # inside #call, where the cost is actually incurred. See
+      # SPECIFICATION.md §1.3 and §2.4, and the spec that pins it.
+      class Command < Dry::CLI::Command
+        SHELLS = %w[bash zsh].freeze
+
+        # Binds the command to a registry, and optionally to the name the
+        # host is installed as. Without one, the program name is taken from
+        # $PROGRAM_NAME at call time rather than at registration, since a
+        # gem may be required long before anyone knows how it was invoked.
+        #
+        #   register "completion", Dry::CLI::Autocomplete::Command[MyCLI]
+        def self.[](registry, program_name: nil)
+          Class.new(self) do
+            @registry = registry
+            @program_name = program_name
+          end
+        end
+
+        class << self
+          attr_reader :registry, :program_name
+        end
+
+        desc "Print a shell completion script"
+
+        argument :shell, required: true, values: SHELLS,
+                         desc: "Shell to generate completions for"
+
+        example [
+          "bash > /usr/local/etc/bash_completion.d/#{File.basename($PROGRAM_NAME)}",
+          "zsh  > \"${fpath[1]}/_#{File.basename($PROGRAM_NAME)}\""
+        ]
+
+        def call(shell:, **)
+          require_relative "spec_builder"
+          require_relative "emitters/#{shell}"
+
+          spec = SpecBuilder.call(registry, program_name: program_name)
+          out.puts emitter_for(shell).call(spec)
+        end
+
+        private
+
+        def registry
+          self.class.registry or
+            raise ArgumentError, "no registry bound: register Dry::CLI::Autocomplete::Command[MyCLI]"
+        end
+
+        def program_name
+          self.class.program_name || File.basename($PROGRAM_NAME)
+        end
+
+        def emitter_for(shell)
+          Emitters.const_get(shell.capitalize)
+        end
+
+        # Overridable so specs can capture output without reaching for $stdout.
+        def out = $stdout
+      end
+    end
+  end
+end

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "dry/inflector"
+
+module Dry
+  class CLI
+    module Autocomplete
+      module Emitters
+        # Turns a CompletionSpec into a bash `complete -F` script.
+        # See SPECIFICATION.md §4.1: a static, case-statement walk over
+        # COMP_WORDS resolves which node the cursor is under, then
+        # `compgen -W` fills COMPREPLY from that node's children and
+        # option flags, with `compgen -f` added where an argument is a
+        # file (§4.3).
+        #
+        # Deliberately avoids bash associative arrays (bash 4+ only):
+        # macOS still ships bash 3.2 as /bin/bash, and this script is
+        # meant to be eval'd from exactly that.
+        class Bash
+          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 + option_value_lines + word_lookup_lines + footer_lines
+          end
+
+          def header_lines
+            [
+              "#{function_name}() {",
+              "  local cur prev path word next_path words i",
+              "  COMPREPLY=()",
+              '  cur="${COMP_WORDS[COMP_CWORD]}"',
+              '  prev=""',
+              '  if [ "$COMP_CWORD" -gt 0 ]; then',
+              '    prev="${COMP_WORDS[$((COMP_CWORD - 1))]}"',
+              "  fi",
+              '  path=""',
+              "  i=1"
+            ]
+          end
+
+          def path_walk_lines
+            path_walk_open_lines + path_walk_close_lines
+          end
+
+          def path_walk_open_lines
+            lines = [
+              '  while [ "$i" -lt "$COMP_CWORD" ]; do',
+              '    word="${COMP_WORDS[$i]}"',
+              '    next_path=""',
+              '    case "$path:$word" in'
+            ]
+            edge_arms.each { |arm| lines << "      #{arm}" }
+            lines << "    esac"
+          end
+
+          def path_walk_close_lines
+            [
+              '    if [ -z "$next_path" ]; then',
+              "      break",
+              "    fi",
+              '    path="$next_path"',
+              "    i=$((i + 1))",
+              "  done",
+              ""
+            ]
+          end
+
+          def word_lookup_lines
+            lines = ['  words=""', '  case "$path" in']
+            word_arms.each { |arm| lines << "    #{arm}" }
+            lines + ["  esac", ""]
+          end
+
+          def footer_lines
+            [
+              '  COMPREPLY=($(compgen -W "$words" -- "$cur"))',
+              *file_completion_lines,
+              "}",
+              "complete -F #{function_name} #{spec.program_name}"
+            ]
+          end
+
+          def function_name = "_#{shell_identifier}_completions"
+
+          # 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 path_key(path) = path.join(" ")
+
+          def edge_arms
+            spec.nodes.flat_map do |node|
+              parent_key = path_key(node.path)
+              node.children.map do |child|
+                child_key = path_key(node.path + [child])
+                "\"#{quote(parent_key)}:#{quote(child)}\") next_path=\"#{quote(child_key)}\" ;;"
+              end
+            end
+          end
+
+          def word_arms
+            spec.nodes.filter_map do |node|
+              words = node_words(node)
+              next if words.empty?
+
+              "\"#{quote(path_key(node.path))}\") words=\"#{quote(words.join(' '))}\" ;;"
+            end
+          end
+
+          # Children, flags, and any values a positional declares: all three are
+          # legitimate next words at this point in the line.
+          def node_words(node)
+            node.children +
+              node.options.flat_map { |option| option_words(option) } +
+              node.arguments.flat_map { |argument| Array(argument.values) }
+          end
+
+          def option_words(option) = ["--#{option.name}"] + Array(option.aliases)
+
+          # An option that declares values gets its own arm, keyed on the word
+          # before the cursor. Typing `--format ` then TAB should offer what
+          # --format accepts, not the command list again, so this arm answers
+          # and returns rather than falling through. Long name and every alias
+          # are listed together, since `-f` accepts what `--format` accepts.
+          def option_value_lines
+            arms = spec.nodes.flat_map do |node|
+              node.options.filter_map do |option|
+                values = Array(option.values)
+                next if values.empty?
+
+                key = path_key(node.path)
+                option_words(option).map do |name|
+                  "    \"#{quote(key)}:#{quote(name)}\") " \
+                    "COMPREPLY=($(compgen -W \"#{quote(values.join(' '))}\" -- \"$cur\")); return ;;"
+                end
+              end
+            end.flatten
+
+            return [] if arms.empty?
+
+            ['  case "$path:$prev" in', *arms, "  esac", ""]
+          end
+
+          def file_completion_lines
+            paths = spec.nodes.select { |node| node.arguments.any?(&:file) }.map { |node| path_key(node.path) }
+            return [] if paths.empty?
+
+            lines = ['  case "$path" in']
+            paths.each do |key|
+              lines << "    \"#{quote(key)}\") COMPREPLY+=($(compgen -f -- \"$cur\")) ;;"
+            end
+            lines << "  esac"
+            lines
+          end
+
+          def quote(str) = str.to_s.gsub("\\", "\\\\\\\\").gsub('"', "\\\"")
+        end
+      end
+    end
+  end
+end