dry-cli-autocomplete 0.1.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5de81918d8ea085c400d5578481fd513b595d21b4e6c46fa2cce70ffbbe051f1
-  data.tar.gz: b57a07d39c36db90a843474694e61c1fcf970f58a2267bc44449ed60017f3369
+  metadata.gz: b392efc439cb2a04ce5858ab9f8931cf3be6c987df699c4ef56e0c20782775d9
+  data.tar.gz: 749295c776797acfd2a82a059d632df3d1f02170e158c4b3e8ad260def61009a
 SHA512:
-  metadata.gz: fd15d74c1ebece2e83817330d91f09f664b301753cbe09f2c5413ee042db260ea04acff53c6b090b1ea275b748f38949fd348f2b4bc847680446e546f57c6c68
-  data.tar.gz: c7bdc08cdeefa48c8ea9f67c9667fb76053b28a75ff96f7d1239ab2f1135d6f22a296a402a64c364fbedb7e8b7ede2b25e2ae8ebaa14087233d51cd6a3f40ca3
+  metadata.gz: b33692dd9535f11c1057a75c5c689dc05d6dff0850094478b7f7cf4867436272855786d6b2c7a1f406ecf029da678be33ff13738d7cbecca69fe1536fde292ef
+  data.tar.gz: 5dacc2b7a57ddc9ca177ec1f0c29a1f9d6514e08f0eeec9ce1863a3c88217583ce6f9013f02d0293671fecdf7657e19d9c8d3a57224e34d71bd9aa7be7ac6f1a

data/.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/bower_components": true,
+    "**/*.code-search": true,
+    "**/.ruby-lsp": true,
+    "**/.rubymate": true
+  },
+  "files.watcherExclude": {
+    ".git/objects/**": true,
+    ".git/subtree-cache/**": true,
+    ".hg/store/**": true,
+    "*/.git/objects/**": true,
+    "*/.git/subtree-cache/**": true,
+    "*/.hg/store/**": true,
+    "**/.trunk/*actions/": true,
+    "**/.trunk/*logs/": true,
+    "**/.trunk/*notifications/": true,
+    "**/.trunk/*out/": true,
+    "**/.trunk/*plugins/": true,
+    "**/.rubymate": true
+  }
+}

data/CHANGELOG.md

@@ -1,14 +1,24 @@
 ## [Unreleased]
 
+- Options complete the way dry-cli parses them. `option :as_of` completed as `--as_of`, which dry-cli accepts but its own help never shows; it is now `--as-of`. A boolean also completes its `--no-` form, and an alias declared without dashes (`aliases: ["f"]`) gains them (`-f`). A name with capitals is downcased as dry-cli registers it: `option :dryRun` completes as `--dryrun`.
+- In zsh, a `type: :flag` option no longer takes a value. `run --quiet x` completed `x` as `--quiet`'s argument, while dry-cli parses it as `quiet: true` and an argument `x`.
+- In zsh, a boolean's two forms exclude each other, so once `--force` is on the line zsh stops offering `--no-force`. The `--no-` form is described as `Turn off --force` rather than repeating the description, which read backwards.
+- `Command[MyCLI]` keeps its description and examples. dry-cli empties both on every subclass, so `mycli completion --help` printed usage alone. The examples now name the bound `program_name:`.
+- `completion` now writes to the stream a host passes to `Dry::CLI#call(out:)`. It used to write to `$stdout` regardless, so a launcher's own STDOUT, and an in-process Aruba run, received nothing. Called directly, outside `Dry::CLI`, it still falls back to `$stdout`.
+
+## [0.5.0] - 2026-09-16
+
+Documentation only; no change to the gem's behaviour.
+
+- The README now matches the generated scripts. The bash example is real output, a zsh excerpt is included, and it documents `file:` on arguments and the name-based file guess, `program_name:`, option and positional values, `eval` for bash, placing the zsh `eval` after `compinit`, and Ruby 4.0.
+- The specification moved to `docs/SPECIFICATION.md` and is marked as describing version 0.1.0. It is no longer part of the YARD docs.
+- The YARD docs title names this gem instead of an unrelated project.
+- Added a warning about AI contributions and an author section to the README.
+
 ## [0.1.3] - 2026-08-23
 
-- The zsh script now registers itself when sourced. `eval "$(mycli completion zsh)"`
-  previously ran the completion function outside a completion context, and zsh
-  answered with `_tags:comptags:36: can only be called from completion function`.
-  The script now calls itself when autoloaded from `$fpath` and calls `compdef`
-  when sourced, so both work.
-- The zsh function is named `_mycli` rather than `_mycli_completions`, matching
-  the name a `#compdef` file is autoloaded under. The bash function is unchanged.
+- The zsh script now registers itself when sourced. `eval "$(mycli completion zsh)"` previously ran the completion function outside a completion context, and zsh answered with `_tags:comptags:36: can only be called from completion function`. The script now calls itself when autoloaded from `$fpath` and calls `compdef` when sourced, so both work.
+- The zsh function is named `_mycli` rather than `_mycli_completions`, matching the name a `#compdef` file is autoloaded under. The bash function is unchanged.
 
 ## [0.1.2] - 2026-08-22
 

data/CLAUDE.md

@@ -6,9 +6,9 @@ Guidance for Claude Code (claude.ai/code) working in this repository.
 
 A Ruby gem that generates static shell completion scripts for any `Dry::CLI` application. A host registers one command; `mycli completion bash` prints a script; the user evaluates it from a shell profile.
 
-**Read `SPECIFICATION.md` first.** It carries the design decisions, the measurements behind them, and the acceptance criteria. This file covers how to work in the repository; that one covers what to build and why.
+**Read `docs/SPECIFICATION.md` first.** It carries the design decisions, the measurements behind them, and the acceptance criteria. This file covers how to work in the repository; that one covers what to build and why.
 
-The gem is a skeleton from `bundle gem` with no implementation yet. Nothing in `lib/` does anything.
+The gem is implemented and released (tags `v0.1.0` through `v0.1.3`). `README.md` documents the host-facing behaviour; keep it in step with `lib/` when behaviour changes.
 
 ## Environment
 
@@ -23,11 +23,12 @@ bundle install
 bundle exec rspec              # the suite
 bundle exec rubocop            # the linter
 bundle exec rubocop -a         # autocorrect
-bundle exec rake               # both, and the default task
+bundle exec rake               # the suite only; it is the default task and what CI runs
+bundle exec rake doc           # YARD documentation
 bin/console                    # IRB with the gem loaded
 ```
 
-The gemspec sets `required_ruby_version >= 3.2.0` and `.rubocop.yml` sets `TargetRubyVersion: 3.2`. Keep the two in step: raising one without the other produces a linter that permits syntax the gemspec claims to support, or the reverse.
+The gemspec sets `required_ruby_version >= 4.0`, `.rubocop.yml` sets `TargetRubyVersion: 4.0`, and CI runs Ruby 4.0.6. Keep them in step: raising one without the other produces a linter that permits syntax the gemspec claims to support, or the reverse.
 
 ## The trap that has already bitten this repository once
 
@@ -43,6 +44,8 @@ module Dry
 
 `lib/dry/cli/autocomplete/version.rb` deliberately does **not** `require "dry/cli"`, because the gemspec loads it at build time when the dependency may not be installed. It reopens `class CLI` on its own. dry-cli's `CLI` inherits from `Object`, so an empty reopening is compatible whichever loads first.
 
+The same lexical scoping bites constants. Every file here sits inside `module Dry`, so a bare `Struct` or `Data` resolves to `Dry::Struct` or `Dry::Data` first when a host has loaded them. Write `::Data` and `::Struct`. `spec/dry/cli/autocomplete/dry_struct_host_spec.rb` loads dry-struct to catch this.
+
 For deriving names at runtime, use `dry-inflector`. `Dry::Inflector.new { |i| i.acronym("CLI") }` handles both the casing above and the `underscore` needed for shell function identifiers. `Dry::CLI::Inflector` ships with dry-cli but only has `dasherize` and is marked `@api private`; do not depend on it.
 
 ## Architecture
@@ -58,31 +61,41 @@ Four pieces, and the boundary between the first and the rest is load-bearing.
 
 Two rules hold this shape together, both measured rather than assumed:
 
-- **The command shim loads no emitter.** A host pays nothing at boot for a command run once per shell. `SPECIFICATION.md` §2.4.
-- **The spec builder touches only the registry.** It must be safe to run at shell startup, because it runs at every shell startup. `SPECIFICATION.md` §2.2.
+- **The command shim loads no emitter.** A host pays nothing at boot for a command run once per shell. `docs/SPECIFICATION.md` §2.4.
+- **The spec builder touches only the registry.** It must be safe to run at shell startup, because it runs at every shell startup. `docs/SPECIFICATION.md` §2.2.
+
+`SpecBuilder` returns frozen `::Data` values: a `CompletionSpec` holding one `Node` per visible command or group, each with `OptionSpec` and `ArgumentSpec` entries. An argument is a file argument when it declares `file: true`, or, with no `file:` key, when its name matches `/file|path/i`.
 
 The emitters take the same description and share no code. A fourth shell should be a new emitter class, never a branch inside an existing one.
 
 ## Conventions
 
-- **The generator is not a hot path.** It runs in 0.067ms against a 27-command registry. Do not optimise it, do not add native extensions, and do not cache anything. The reasoning is in `SPECIFICATION.md` §2.3.
+- **The generator is not a hot path.** It runs in 0.067ms against a 27-command registry. Do not optimise it, do not add native extensions, and do not cache anything. The reasoning is in `docs/SPECIFICATION.md` §2.3.
 - **Read a registry through its methods, not its ivars.** `registry.get(path)` returns a result exposing `command`, `children` and `names`. `instance_variable_get(:@node)` is what the gem this one replaces does, and it will break on a dry-cli release. Do not mistake this for a public API: in 1.4.1 `Registry#get`, all of `CommandRegistry`, every `LookupResult` reader and every `Node` reader carry `@api private`. There is no public way to enumerate a registry, so an upgrade can break the walk and the fixture suite is what catches it.
-- **Test against registries this project did not write.** A generator tested against one CLI encodes that CLI's shape. `SPECIFICATION.md` §5.
-- **Validate generated shell with the shell.** `bash -n` and `zsh -n` parse without executing. A regex over generated output proves nothing about whether it runs.
+- **Test against registries this project did not write.** A generator tested against one CLI encodes that CLI's shape. `docs/SPECIFICATION.md` §5.
+- **Validate generated shell with the shell.** `bash -n` and `zsh -n` parse without executing. A regex over generated output proves nothing about whether it runs. `spec/support/shell_helpers.rb` skips a missing shell locally and fails on CI.
+- **Emitter output is pinned by golden files** in `spec/support/golden/`. A deliberate output change means updating the golden file in the same commit.
+- **The bash emitter targets bash 3.2.** macOS ships it as `/bin/bash`, so no associative arrays.
+- **The zsh script works both from `$fpath` and from `eval`.** Its footer checks `$funcstack[1]` against the function name, so the function must stay named `_<program>`.
 - **Commit messages**: imperative mood, 50-character subject, no full stop. A body only where the change needs explaining, saying what and why.
 - **Writing prose here**: no em dashes, active voice, plain words. Say what a thing does, not how it feels. If a sentence could appear unchanged in another project's README, it says nothing about this one and should go.
 
 ## Repository layout
 
-| Path                                  | What it is                                                                                                        |
-| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `SPECIFICATION.md`                    | What to build, why, and what "done" means                                                                         |
-| `lib/dry/cli/autocomplete.rb`         | Entry point                                                                                                       |
-| `lib/dry/cli/autocomplete/version.rb` | Version, loaded standalone by the gemspec                                                                         |
-| `sig/`                                | RBS signatures, generated by `bundle gem` and not yet real                                                        |
-| `exe/dry-cli-autocomplete`            | Generated by `bundle gem`. **Probably should be deleted**: this is a library, and a host provides the executable. |
-| `.github/workflows/main.yml`          | CI                                                                                                                |
-
-## Before the first release
-
-The gemspec still carries `bundle gem` TODOs that will refuse to build: `spec.summary`, `spec.description`, and `spec.metadata["allowed_push_host"]`. The `dry-` prefix and the `Dry::CLI::Autocomplete` namespace imply an affiliation with dry-rb that does not exist, so say so in the README, or ask them first.
+| Path                                  | What it is                                                                           |
+| ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `docs/SPECIFICATION.md`               | What to build, why, and what "done" means                                            |
+| `README.md`                           | Host-facing documentation                                                            |
+| `CHANGELOG.md`                        | Release notes                                                                        |
+| `lib/dry/cli/autocomplete.rb`         | Entry point for `require "dry/cli/autocomplete"`. Hosts require `command.rb` instead |
+| `lib/dry-cli-autocomplete.rb`         | Bundler-style entry point, requires the one above                                    |
+| `lib/dry/cli/autocomplete/version.rb` | Version, loaded standalone by the gemspec                                            |
+| `sig/`                                | RBS signatures. Only `VERSION` is declared so far                                    |
+| `spec/support/fixtures/`              | Registries the suite walks, including shapes modelled on other CLIs                  |
+| `spec/support/golden/`                | Expected bash and zsh output, compared byte for byte                                 |
+| `.github/workflows/main.yml`          | CI: installs zsh, runs `bundle exec rake`                                            |
+| `.github/workflows/rubocop.yml`       | CI: runs `bundle exec rubocop`                                                       |
+
+## Releasing
+
+Bump `VERSION` in `lib/dry/cli/autocomplete/version.rb`, add a `CHANGELOG.md` entry, then `bundle exec rake release`. The gemspec requires MFA for pushes. The `dry-` prefix and the `Dry::CLI::Autocomplete` namespace imply an affiliation with dry-rb that does not exist; the README says so, and that note should stay.

data/README.md

@@ -5,7 +5,66 @@
 Shell completion for [dry-cli](https://github.com/dry-rb/dry-cli) applications, with no Ruby in the TAB path.
 
 > [!NOTE]
-> For the specification of this gem see [SPECIFICATION](SPECIFICATION.md)
+> For the original specification of this gem see [SPECIFICATION](docs/SPECIFICATION.md)
+
+______________________________________________________________________
+
+> [!WARNING]
+> This gem was written with a collaboration with Claude Code. Most of the ruby was written by a human (myself), reviewed and pushed to GitHub by Claude (anyone loves writing commit descriptions?). The part where Claude authored the most code is the ZSH autocompletion code as I'm less familiar with it than BASH. If you prefer not to use gems that had some AI contributions that were reviewed by a human, do not use this gem.
+
+## Usage
+
+For the impatient:
+
+```bash
+gem install dry-cli dry-cli-autocomplete -N
+```
+
+Register one command:
+
+```ruby
+require "dry/cli"
+require "dry/cli/autocomplete/command"
+
+module MyCLI
+  extend Dry::CLI::Registry
+
+  register "deploy", Deploy
+  register "completion", Dry::CLI::Autocomplete::Command[MyCLI]
+end
+```
+
+Then load the script from your shell's initialization file:
+
+```bash
+eval "$(mycli completion bash)"   # ~/.bashrc
+eval "$(mycli completion zsh)"    # ~/.zshrc, after compinit
+```
+
+### Real Example
+
+[`examples/`](examples/README.md) holds a working CLI with the command registered, to try it end to end.
+
+```bash
+$ cd examples && bundle exec bin/mycli -h
+mycli
+
+Downloads URLs and finds hosts on the local network, several at once.
+
+USAGE
+  mycli COMMAND [OPTIONS]
+
+COMMANDS
+  version, v               Print version
+  download-urls, download  Download URLs, each to its own file
+  find-hosts, hosts        Find hosts on the local network that listen on
+                           common TCP ports
+  completion               Print a shell completion script
+
+OPTIONS
+  -h, --help               Show help
+  -v, --version            Print version
+```
 
 Your CLI knows its own commands, options, aliases and enum values. The shell does not. This gem walks your registry once, prints a bash or zsh script, and you source it from your profile. Pressing TAB then spawns nothing and costs nothing, because every completion the script will ever offer is already inside it.
 
@@ -41,6 +100,28 @@ There is a dependency argument too. `completely` pulls `colsole`, `docopt_ng` an
 Given this registry:
 
 ```ruby
+class Version < Dry::CLI::Command
+  desc "Print the version"
+  option :format, values: %w[json plain], desc: "Output format"
+end
+
+class Deploy < Dry::CLI::Command
+  desc "Deploy the application"
+  option :force, type: :boolean, aliases: ["-f"], desc: "Skip confirmation"
+  argument :environment, values: %w[staging production], required: true, desc: "Target environment"
+end
+
+class DbStatus < Dry::CLI::Command
+  desc "Show pending migrations"
+  option :verbose, type: :boolean, desc: "Print full migration history"
+end
+
+class DbMigrate < Dry::CLI::Command
+  desc "Run pending migrations"
+  option :step, desc: "Migrate to a specific step"
+  argument :file, desc: "Migration file to run"
+end
+
 register "version", Version
 register "deploy", Deploy
 register "db", DbStatus do |prefix|
@@ -49,17 +130,23 @@ end
 register "secret", Secret, hidden: true
 ```
 
-`mycli completion bash` prints a `complete -F` function that dispatches on the command path:
+`mycli completion bash` prints a `complete -F` function. It walks `COMP_WORDS` to find the command path under the cursor, answers option values first, then offers that path's words:
 
 ```bash
 _mycli_completions() {
   # ...walks COMP_WORDS to find the current command path...
+
+  case "$path:$prev" in
+    "version:--format") COMPREPLY=($(compgen -W "json plain" -- "$cur")); return ;;
+  esac
+
   words=""
   case "$path" in
     "") words="version deploy db" ;;
     "version") words="--format" ;;
-    "deploy") words="--force -f" ;;
-    "db") words="migrate --verbose" ;;
+    "deploy") words="--force --no-force -f staging production" ;;
+    "db") words="migrate --verbose --no-verbose" ;;
+    "db migrate") words="--step" ;;
   esac
 
   COMPREPLY=($(compgen -W "$words" -- "$cur"))
@@ -70,17 +157,62 @@ _mycli_completions() {
 complete -F _mycli_completions mycli
 ```
 
-Read what that output proves. `db` offers `migrate` alongside its own `--verbose`, so a group with both a command and children keeps both. `db migrate` gets real file completion. `secret` is absent, because hidden commands stay hidden. The `-f` alias on `deploy` is there because you declared it.
+Read what that output proves:
+
+- `db` offers `migrate` alongside its own `--verbose`, so a group with both a command and children keeps both.
+- `db migrate` gets real file completion.
+- `secret` is absent, because hidden commands stay hidden.
+- The `-f` alias on `deploy` is there because you declared it.
+- `--no-force` is there because `--force` is a boolean, and dry-cli accepts both forms. Options are spelled the way dry-cli parses them, so `option :dry_run` completes as `--dry-run`, and an alias declared as `"f"` completes as `-f`.
+- `mycli version --format <TAB>` offers `json plain`, and nothing else.
+- `mycli deploy <TAB>` offers `staging production`, the values declared on the positional.
+
+The script uses no associative arrays, so it runs under the bash 3.2 that macOS ships as `/bin/bash`.
+
+`mycli completion zsh` prints a native `#compdef` script. Options go through `_arguments` with their `desc` as help text, subcommands go through `_describe` with the command's `desc`, declared values become a value list, and file arguments use `_files`:
+
+```zsh
+    ('deploy')
+      _arguments -s \
+        '--force[Skip confirmation]' \
+        '--no-force[Skip confirmation]' \
+        '-f[Skip confirmation]' \
+        '*:Target environment:(staging production)' && ret=0
+      ;;
+    ('db')
+      _arguments -s \
+        '--verbose[Print full migration history]' \
+        '--no-verbose[Print full migration history]' && ret=0
+      commands=(
+        'migrate:Run pending migrations'
+      )
+      _describe -t commands 'db command' commands && ret=0
+      ;;
+```
 
-`mycli completion zsh` prints a native `#compdef` script built on `_arguments` and `_describe`, carrying each option's `desc` as help text next to it.
+### Enum values
 
-Enum values declared on an option or argument come through at no cost:
+Values declared on an option or argument come through at no cost:
 
 ```ruby
-option :format, values: %w[json yaml table]    # completes json yaml table
+option :format, values: %w[json yaml table]    # completes json yaml table after --format
 argument :component, values: %w[major minor]   # completes major minor
 ```
 
+### File arguments
+
+An argument completes file paths when it declares `file: true`. Without that key, the generator treats any argument whose name contains `file` or `path` as a file argument. Declare `file: false` to opt out of the guess:
+
+```ruby
+argument :output, file: true     # completes paths
+argument :path, file: false      # does not, despite the name
+argument :config_file            # completes paths, by name
+```
+
+### Program names
+
+Shell function names derive from the program name. A program installed as `my-tool` gets `_my_tool_completions` in bash and `_my_tool` in zsh.
+
 ## Installation
 
 ```bash
@@ -105,19 +237,33 @@ end
 
 That require pulls in the command class and nothing else. No emitter loads until someone actually runs `mycli completion`.
 
+The command reads the program name from `$PROGRAM_NAME` when it runs. If your executable can be invoked under a different name, such as through a wrapper or a binstub, pin it:
+
+```ruby
+register "completion", Dry::CLI::Autocomplete::Command[MyCLI, program_name: "mycli"]
+```
+
+The command takes one required argument, `bash` or `zsh`, and prints the script to standard output.
+
 Then have your users write the script once and source it. For bash:
 
 ```bash
 mycli completion bash > /usr/local/etc/bash_completion.d/mycli
 ```
 
+Or evaluate it from `.bashrc`:
+
+```bash
+eval "$(mycli completion bash)"
+```
+
 For zsh, put it anywhere on your `$fpath`:
 
 ```bash
 mycli completion zsh > "${fpath[1]}/_mycli"
 ```
 
-Sourcing it from `.zshrc` works too, if you would rather not manage a file:
+Sourcing it from `.zshrc` works too, if you would rather not manage a file. Place the line after `compinit`, since the script calls `compdef` to register itself:
 
 ```bash
 eval "$(mycli completion zsh)"
@@ -155,19 +301,24 @@ The same table explains two other decisions. The generator will not be optimised
 
 ## Development
 
-Ruby 3.2 or newer. This repository uses rbenv, so activate it first:
+Ruby 4.0 or newer, matching the gemspec and CI. This repository uses rbenv, so activate it first:
 
 ```bash
 eval "$(rbenv init -)"
 bundle install
 bundle exec rspec       # the suite
 bundle exec rubocop     # the linter
-bundle exec rake        # both
+bundle exec rake        # the suite, and the default task
+bundle exec rake doc    # YARD documentation
 bin/console             # IRB with the gem loaded
 ```
 
 Two conventions in the suite are worth knowing before you add to it. Fixtures include registries this project did not write, because a generator tested against one CLI quietly encodes that CLI's shape. And generated scripts are validated by the shells themselves, with `bash -n` and `zsh -n` parsing without executing, since a regex over the output proves nothing about whether it runs.
 
+## Author
+
+- Konstantin Gredeskoul pairing with Claude Code. Every line has been reviewed and co-written by a human. The commits were pushed by Claude to save time writing comment descriptions.
+
 ## Contributing
 
 Bug reports and pull requests are welcome at <https://github.com/kigster/dry-cli-autocomplete>.

data/Rakefile

@@ -29,8 +29,8 @@ end
 task build: :permissions
 
 YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = %w[lib/**/*.rb exe/*.rb - README.md LICENSE.txt CHANGELOG.md SPECIFICATION.md]
-  t.options.unshift("--title", '"FlowEngine — DSL + AST for buildiong complex flows in Ruby."')
+  t.files = %w[lib/**/*.rb - README.md LICENSE.txt CHANGELOG.md]
+  t.options.unshift("--title", '"dry-cli-autocomplete: shell completion for dry-cli"')
   t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
 end
 

data/{SPECIFICATION.md → docs/SPECIFICATION.md}

@@ -1,5 +1,8 @@
 # `dry-cli-autocomplete`: Specification
 
+> [!NOTE]
+> This is the specification for version 0.1.0. Later versions may differ; see `CHANGELOG.md` and `README.md` for current behaviour.
+
 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:

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

@@ -12,7 +12,7 @@ module Dry
       # 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.
+      # docs/SPECIFICATION.md §1.3 and §2.4, and the spec that pins it.
       class Command < Dry::CLI::Command
         SHELLS = %w[bash zsh].freeze
 
@@ -22,10 +22,17 @@ module Dry
         # gem may be required long before anyone knows how it was invoked.
         #
         #   register "completion", Dry::CLI::Autocomplete::Command[MyCLI]
+        #
+        # dry-cli's inherited hook empties a subclass's description and
+        # examples, and this returns a subclass, so both are set again here.
+        # The examples name the bound program, not whatever loaded the gem.
         def self.[](registry, program_name: nil)
           Class.new(self) do
             @registry = registry
             @program_name = program_name
+
+            desc superclass.description
+            example examples_for(program_name || File.basename($PROGRAM_NAME))
           end
         end
 
@@ -33,24 +40,33 @@ module Dry
           attr_reader :registry, :program_name
         end
 
+        def self.examples_for(name)
+          [
+            "bash > /usr/local/etc/bash_completion.d/#{name}",
+            "zsh  > \"${fpath[1]}/_#{name}\""
+          ]
+        end
+
         desc "Print a shell completion script"
 
-        argument :shell, required: true, values: SHELLS,
-                         desc: "Shell to generate completions for"
+        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)}\""
-        ]
+        example examples_for(File.basename($PROGRAM_NAME))
 
         def call(shell:, **)
           require_relative "spec_builder"
           require_relative "emitters/#{shell}"
 
-          spec = SpecBuilder.call(registry, program_name: program_name)
+          spec = SpecBuilder.call(registry, program_name:)
+
           out.puts emitter_for(shell).call(spec)
         end
 
+        # Dry::CLI sets @out from Dry::CLI#call(out:) before it calls a command,
+        # and only when the command has not set @out itself, so never assign it
+        # here. $stdout is for a command called directly, outside Dry::CLI.
+        def out = @out || $stdout
+
         private
 
         def registry
@@ -65,9 +81,6 @@ module Dry
         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

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

@@ -7,7 +7,7 @@ module Dry
     module Autocomplete
       module Emitters
         # Turns a CompletionSpec into a bash `complete -F` script.
-        # See SPECIFICATION.md §4.1: a static, case-statement walk over
+        # See docs/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
@@ -97,7 +97,7 @@ module Dry
           def function_name = "_#{shell_identifier}_completions"
 
           # A program installed as `my-tool` cannot name a shell function
-          # directly. See SPECIFICATION.md §4.2.
+          # directly. See docs/SPECIFICATION.md §4.2.
           def shell_identifier
             Dry::Inflector.new.underscore(spec.program_name.to_s).gsub(/[^A-Za-z0-9_]/, "_")
           end
@@ -127,12 +127,10 @@ module Dry
           # legitimate next words at this point in the line.
           def node_words(node)
             node.children +
-              node.options.flat_map { |option| option_words(option) } +
+              node.options.flat_map(&:flags) +
               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
@@ -145,7 +143,7 @@ module Dry
                 next if values.empty?
 
                 key = path_key(node.path)
-                option_words(option).map do |name|
+                option.flags.map do |name|
                   "    \"#{quote(key)}:#{quote(name)}\") " \
                     "COMPREPLY=($(compgen -W \"#{quote(values.join(' '))}\" -- \"$cur\")); return ;;"
                 end

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

@@ -13,7 +13,7 @@ module Dry
         # `_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.
+        # See docs/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
@@ -132,15 +132,34 @@ module Dry
           # 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.
+          #
+          # A boolean's two forms exclude each other, so once `--force` is on
+          # the line zsh stops offering `--no-force`, and the reverse. The
+          # `--no-` form says what it turns off rather than repeating the
+          # description, which would read backwards.
           def option_specs(option)
-            names = ["--#{option.name}"] + Array(option.aliases)
-            names.map { |name| single_quote("#{name}#{bracketed(option.desc)}#{option_action(option)}") }
+            positives = [option.long, *option.alias_flags]
+            specs = positives.map do |name|
+              single_quote("#{exclusion([option.negation])}#{name}#{bracketed(option.desc)}#{option_action(option)}")
+            end
+            return specs unless option.negation
+
+            specs.insert(1, single_quote("#{exclusion(positives)}#{option.negation}[Turn off #{option.long}]"))
+          end
+
+          # A zsh exclusion list such as `(--no-force)`, or nothing when there
+          # is nothing to exclude.
+          def exclusion(names)
+            names = names.compact
+            names.empty? ? "" : "(#{names.join(' ')})"
           end
 
-          # A boolean flag takes no value. Anything else gets one field
-          # naming what it wants and one supplying the completions for it.
+          # A boolean or a `type: :flag` option takes no value: dry-cli parses
+          # `run --quiet x` as `quiet: true` with `x` as an argument. Anything
+          # else gets one field naming what it wants and one supplying the
+          # completions for it.
           def option_action(option)
-            return "" if option.boolean
+            return "" if option.boolean || option.flag
 
             ":#{escape_spec(option.name)}:#{value_action(option.values)}"
           end
@@ -193,7 +212,7 @@ module Dry
           def function_name = "_#{shell_identifier}"
 
           # A program installed as `my-tool` cannot name a shell function
-          # directly. See SPECIFICATION.md §4.2.
+          # directly. See docs/SPECIFICATION.md §4.2.
           def shell_identifier
             Dry::Inflector.new.underscore(spec.program_name.to_s).gsub(/[^A-Za-z0-9_]/, "_")
           end

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

@@ -9,7 +9,7 @@ module Dry
       #
       # 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.
+      # See docs/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
@@ -25,13 +25,23 @@ module Dry
         # method Struct defines and Data does not.
         CompletionSpec = ::Data.define(:program_name, :nodes)
         Node = ::Data.define(:path, :desc, :options, :arguments, :children)
+        # `long`, `negation` and `alias_flags` are spelled the way dry-cli
+        # 1.4.1 spells them in Option#parser_options and #alias_names, so
+        # both emitters offer exactly what the parser accepts. `flag` is a
+        # `type: :flag` option: like a boolean it takes no value, but dry-cli
+        # gives it no `--no-` form.
         OptionSpec = ::Data.define(
-          :name, :type, :values, :aliases, :default, :desc, :required, :boolean, :array
-        )
+          :name, :type, :values, :aliases, :default, :desc, :required, :boolean, :array,
+          :flag, :long, :negation, :alias_flags
+        ) do
+          # @return [Array<String>] every spelling: the long name, its `--no-`
+          #   form for a boolean, then the aliases
+          def flags = [long, negation, *alias_flags].compact
+        end
         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.
+        # explicitly on the argument. See docs/SPECIFICATION.md §4.3.
         FILE_ARGUMENT_HEURISTIC = /file|path/i
 
         def self.call(registry, program_name:)
@@ -77,13 +87,29 @@ module Dry
         end
 
         def build_option(option)
+          long = "--#{dasherize(option.name)}"
           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?
+            required: option.required? || false, boolean: option.boolean?, array: option.array?,
+            flag: option.respond_to?(:flag?) && option.flag?, long: long,
+            negation: option.boolean? ? long.sub("--", "--no-") : nil,
+            alias_flags: Array(option.aliases).map { |name| alias_flag(name) }.uniq
           )
         end
 
+        # What Dry::CLI::Inflector.dasherize does, without depending on a
+        # module dry-cli marks private: `dry_run` becomes `--dry-run` and `dryRun`
+        # becomes `--dryrun`, as dry-cli registers them.
+        def dasherize(name) = name.to_s.downcase.gsub(/[[:space:]_]/, "-")
+
+        # One letter gets one dash and anything longer two, whatever the host
+        # wrote: `"f"`, `"-f"` and `"--f"` all register as `-f`.
+        def alias_flag(name)
+          bare = name.to_s.sub(/\A-{1,2}/, "")
+          bare.size == 1 ? "-#{bare}" : "--#{bare}"
+        end
+
         def build_argument(argument)
           ArgumentSpec.new(
             name: argument.name.to_s, values: argument.values, desc: argument.options[:desc],

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

@@ -9,7 +9,7 @@ module Dry
   # inherits from Object, so an empty reopening is compatible either way.
   class CLI
     module Autocomplete
-      VERSION = "0.1.3"
+      VERSION = "0.6.0"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-autocomplete
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.6.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -46,12 +46,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".secrets.baseline"
+- ".vscode/settings.json"
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- SPECIFICATION.md
+- docs/SPECIFICATION.md
 - docs/img/badge.svg
 - justfile
 - lefthook.yml
@@ -86,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+rubygems_version: 4.0.22
 specification_version: 4
 summary: A missing auto-complete addition for dry-cli powered Ruby CLI tools for BASH
   & ZSH