feat(completion): add jq-backed zsh completion support. fixes #319

[jameswilson]

Summary

This PR adds richer Zsh completion support for drupalorg by using drupalorg list --format=json when jq is available.

What Changed

• rename the existing Bash completion file to drupalorg-cli-completion.bash for clarity that it is Bash-only.
• add a dedicated drupalorg-cli-completion.zsh script for Zsh completions.
• load command metadata from JSON and cache it for the current shell session
• supported completions:
  • top-level commands and namespaces: eg drupalorg <TAB>, drupalorg issue:<TAB>
  • command aliases such as is: eg drupalorg i<TAB>
  • long and short options/flags: eg drupalorg is -<TAB>, drupalorg is --<TAB>
  • positional argument placeholders such as <nid> and [branch]: eg drupalorg is <TAB>
• fallback to simpler command/namespace completion behavior when jq is unavailable
• add README documentation for installing and using the Zsh completion script
• add a self-contained regression test for the Zsh completion helpers

Testing

• zsh tests/zsh-completion-tests.zsh

Related issues

• Document installing Zsh completion #319
• Autocompletion error #181

[jameswilson]

Note: this PR is a workaround for an upstream-releated issue when using drupalorg completion from within a Zsh environment.

drupalorg completion zsh
Detected shell "zsh", which is not supported by Symfony shell completion (supported shells: "").

[Copilot]

Pull request overview

Adds a dedicated Zsh completion script for drupalorg that can optionally use jq + drupalorg list --format=json to provide richer completions, alongside updated docs and a small Zsh regression test.

Changes:

• Added drupalorg-cli-completion.zsh with JSON/jq-backed completion (commands, namespaces, aliases, options, argument placeholders) plus a non-jq fallback.
• Renamed/introduced a Bash-only completion script as drupalorg-cli-completion.bash.
• Documented Zsh completion installation in README.md and added tests/zsh-completion-tests.zsh.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.

File	Description
drupalorg-cli-completion.zsh	Implements jq-backed Zsh completion with in-session caching and a raw fallback mode.
tests/zsh-completion-tests.zsh	Regression tests for core Zsh completion helper behavior and session caching.
drupalorg-cli-completion.bash	Bash completion script (still minimal) under a clearer Bash-specific filename.
README.md	Updates Bash completion path and adds Zsh completion installation/usage guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Option tokens that include an inline value (e.g. --format=json) won't match _DRUPALORG_COMMAND_OPTION_CANONICAL, so the completer may (a) re-suggest already-used options and (b) fail to detect that an option requires a value. Normalise long options by stripping any =... suffix (and consider handling short options with attached values) before looking up the canonical option key.

Suggested change

	local option_key=${_DRUPALORG_COMMAND_OPTION_CANONICAL["$command_name:$option_token"]-}
	local normalized_option_token=$option_token
	# Normalise long options with inline values, e.g. "--format=json" -> "--format".
	if [[ $normalized_option_token == --*=* ]]; then
	normalized_option_token=${normalized_option_token%%=*}
	fi
	local option_key=${_DRUPALORG_COMMAND_OPTION_CANONICAL["$command_name:$normalized_option_token"]-}

[Copilot]

The Bash completion instructions don’t mention the bash-completion dependency that provides _init_completion. To prevent the common _init_completion: command not found failure on macOS, document that users may need to install and source bash-completion (or note the minimal completion script requires it).