Verify generated Carapace specs against the real carapace-spec engine

Author: kdeldycke

changelog.md

@@ -5,7 +5,8 @@
 > [!WARNING]
 > This version is **not released yet** and is under active development.
 
-- Fix Carapace dynamic completion for subcommand parameters, which resolved against the root command and returned the wrong candidates.
+- Fix Carapace dynamic completion: an option's value or a subcommand argument with a custom `shell_complete` now resolves through the generated spec, instead of returning empty or root-level candidates.
+- Verify generated Carapace specs against the real `carapace-spec` engine in the test suite.
 
 ## [`8.1.4` (2026-06-27)](https://github.com/kdeldycke/click-extra/compare/v8.1.3...v8.1.4)
 

click_extra/carapace.py

@@ -171,7 +171,7 @@ def _env_var(prog_name: str) -> str:
     return f"_{prog_name}_COMPLETE".replace("-", "_").upper()
 
 
-def _dynamic_action(command_path: tuple[str, ...]) -> str:
+def _dynamic_action(command_path: tuple[str, ...], option: str | None = None) -> str:
     """A Carapace shell-macro action that calls back into the CLI for completion.
 
     Carapace's default ``$(...)`` macro runs ``sh -c '<script>' -- <words>``,
@@ -181,27 +181,37 @@ def _dynamic_action(command_path: tuple[str, ...]) -> str:
     shell), which prints exactly that. Carapace prefix-filters the result, so the
     callback returns the full candidate set.
 
-    ``command_path`` is the chain of command names from the root program down to
-    the command owning the completed parameter, like ``("weather", "forecast")``.
-    It is baked into ``COMP_WORDS`` so :class:`CarapaceComplete` can rebuild the
-    command line Click needs to resolve the subcommand.
-
-    .. note::
-        Baking the whole path is required, not cosmetic. Carapace's ``traverse``
-        descends into each subcommand with only the remaining words, stripping the
-        parent command names from the ``c.Args`` it hands the macro. So ``$*``
-        carries only the leaf command's own words: for ``weather forecast --city``
-        Carapace passes just ``--city``. Without the baked ``weather forecast``
-        prefix, the callback would reconstruct ``weather --city`` and resolve
-        against the root command, completing the wrong thing. The env var and the
-        invoked binary stay rooted at ``command_path[0]``, the executable Carapace
-        dispatches and the name Click derives its completion variable from.
+    ``COMP_WORDS`` is rebuilt so :class:`CarapaceComplete` hands Click the command
+    line it needs to resolve the completed parameter. Two pieces must be baked in,
+    because Carapace withholds them from ``$*``:
+
+    - ``command_path``: the chain of command names from the root program down to
+      the command owning the parameter, like ``("weather", "forecast")``.
+      Carapace's ``traverse`` descends into each subcommand with only the remaining
+      words, so ``$*`` never carries the parent command names. Without the baked
+      prefix the callback would reconstruct ``weather --city`` and resolve against
+      the root command.
+
+    - ``option``: the spelling of the flag whose value is being completed, for an
+      option (not an argument). Carapace routes a flag's value completion to this
+      per-flag action and keeps the flag in its own ``inFlag`` state rather than
+      ``c.Args``, so ``$*`` does not contain it; Click would not know which value
+      to resolve. It is appended after ``$*`` so it stays the trailing token Click
+      reads as the option awaiting a value.
+
+    So a subcommand option ``--city`` yields ``COMP_WORDS=weather forecast $*
+    --city``, while a subcommand argument yields ``COMP_WORDS=weather forecast
+    $*``. The env var and the invoked binary stay rooted at ``command_path[0]``,
+    the executable Carapace dispatches and the name Click derives its completion
+    variable from.
     """
     root = command_path[0]
-    words = " ".join(command_path)
+    comp_words = " ".join(command_path) + " $*"
+    if option:
+        comp_words += f" {option}"
     return (
         f'$(env "{_env_var(root)}=carapace_complete" '
-        f'"COMP_WORDS={words} $*" {root} 2>/dev/null)'
+        f'"COMP_WORDS={comp_words}" {root} 2>/dev/null)'
     )
 
 
@@ -234,21 +244,26 @@ def _overrides_shell_complete(param_type: click.ParamType) -> bool:
     return type(param_type).shell_complete is not click.ParamType.shell_complete
 
 
-def _param_action(param: Parameter, command_path: tuple[str, ...]) -> list[str]:
+def _param_action(
+    param: Parameter, command_path: tuple[str, ...], option: str | None = None
+) -> list[str]:
     """Resolve the Carapace completion action for one parameter.
 
     An explicit ``shell_complete=`` callback always routes to the dynamic macro;
     otherwise a statically-knowable type is inlined; otherwise a type that
     overrides ``shell_complete`` falls back to the dynamic macro. Anything else
-    yields an empty action (no completion offered).
+    yields an empty action (no completion offered). ``option`` carries the flag
+    spelling when the parameter is an option, so the dynamic macro can name the
+    flag whose value is being completed (see :func:`_dynamic_action`); arguments
+    leave it ``None``.
     """
     if getattr(param, "_custom_shell_complete", None) is not None:
-        return [_dynamic_action(command_path)]
+        return [_dynamic_action(command_path, option)]
     static = _static_action(param.type)
     if static is not None:
         return static
     if _overrides_shell_complete(param.type):
-        return [_dynamic_action(command_path)]
+        return [_dynamic_action(command_path, option)]
     return []
 
 
@@ -398,8 +413,9 @@ def _add_option(
     A boolean flag with a secondary spelling (``--foo`` / ``--no-foo``) is split
     into two independent Carapace flags, since the spec has no negation primitive.
     Only value-taking options contribute a ``completion.flag`` action. Dynamic
-    actions reference ``command_path``, the chain of command names down to this
-    command (see :func:`_dynamic_action`).
+    actions reference ``command_path`` (the chain of command names down to this
+    command) and the option's own spelling, both baked into the callback so Click
+    can resolve the right flag's value (see :func:`_dynamic_action`).
     """
     flags = node.persistentflags if persistent else node.flags
     description = _clean_description(getattr(param, "help", None))
@@ -418,7 +434,8 @@ def _add_option(
         )
 
     if value:
-        action = _param_action(param, command_path)
+        short, long = short_long_opts(param.opts)
+        action = _param_action(param, command_path, option=long or short)
         if action:
             node.completion.flag[_flag_name(param.opts)] = action
 

tests/test_carapace.py

@@ -17,11 +17,18 @@
 from __future__ import annotations
 
 import json
+import os
+import platform
+import stat
+import subprocess
+import sys
+import tarfile
 from pathlib import Path
 
 import click
 import cloup
 import pytest
+import requests
 import yaml
 from click.shell_completion import CompletionItem, get_completion_class
 from cloup.constraints import mutually_exclusive
@@ -218,10 +225,12 @@ def test_dynamic_action_emitted(flag_name):
     macro = action[0]
     assert macro.startswith("$(")
     assert "_WEATHER_COMPLETE=carapace_complete" in macro
-    # The macro bakes the full command path (root + subcommand), not just the
-    # root: Carapace strips parent command names from the words it forwards to
-    # the macro, so the path must be restored here for Click to resolve forecast.
-    assert "COMP_WORDS=weather forecast $*" in macro
+    # The macro bakes the full command path (root + subcommand) AND the option
+    # spelling. Carapace forwards neither to the macro: it strips parent command
+    # names from the words, and routes a flag's value completion to this per-flag
+    # action without putting the flag in those words. Both are restored so Click
+    # resolves the right option's value under the right subcommand.
+    assert f"COMP_WORDS=weather forecast $* --{flag_name}" in macro
 
 
 # -- persistentflags ----------------------------------------------------------
@@ -323,21 +332,26 @@ def test_complete_reuses_click_machinery():
 
 
 def test_subcommand_dynamic_completion_resolves_end_to_end(monkeypatch):
-    """The COMP_WORDS a subcommand's generated macro builds must let the backend
-    resolve that subcommand's callback, not the root command.
-
-    Carapace strips parent command names from the words it forwards to the macro,
-    so for ``weather forecast --city`` it passes only ``--city``. The macro
-    restores the baked path; rebuilding COMP_WORDS the same way and feeding it
-    back must yield the forecast callback's values. Pinning only the root name
-    (the original behavior) would reconstruct ``weather --city``, resolve it
-    against the root, and complete the subcommand list instead.
+    """The COMP_WORDS a subcommand flag's generated macro builds must let the
+    backend resolve that option's value, not the root command.
+
+    When completing a subcommand flag's value, Carapace forwards an empty word
+    list to the macro: it strips the parent command names, and keeps the flag
+    being completed in its own state rather than passing it through. So the macro
+    bakes both the command path and the flag spelling, and ``$*`` expands to
+    nothing. This reconstructs the resulting COMP_WORDS from the generated macro
+    and confirms the backend resolves the forecast callback. The original
+    root-only, flag-less macro would have reconstructed bare ``weather`` and
+    completed the subcommand list instead.
     """
     macro = FORECAST["completion"]["flag"]["city"][0]
-    baked_path = macro.split("COMP_WORDS=", 1)[1].split(" $*", 1)[0]
-    monkeypatch.setenv("COMP_WORDS", f"{baked_path} --city")
+    # The macro's COMP_WORDS template, with $* expanded to the empty word list
+    # Carapace passes for a flag value.
+    template = macro.split("COMP_WORDS=", 1)[1].split('"', 1)[0]
+    monkeypatch.setenv("COMP_WORDS", template.replace("$*", ""))
     comp = CarapaceComplete(weather, {}, "weather", "_WEATHER_COMPLETE")
     args, incomplete = comp.get_completion_args()
+    assert args == ["forecast", "--city"]
     values = {item.value for item in comp.get_completions(args, incomplete)}
     assert values == {"paris", "oslo"}
 
@@ -416,3 +430,162 @@ def test_wrap_install_requires_carapace(runner, greet_script):
     result = runner.invoke(demo, ["wrap", "--install", greet_script], color=False)
     assert result.exit_code == 2
     assert "--install requires --carapace" in result.output
+
+
+# -- Real carapace-spec engine (integration) ----------------------------------
+
+# Pinned carapace-spec release exercised by the integration test below.
+CARAPACE_SPEC_VERSION = "1.7.0"
+
+# platform.machine() (lower-cased) -> carapace-spec release arch token.
+CARAPACE_ARCH = {
+    "aarch64": "arm64",
+    "amd64": "amd64",
+    "arm64": "arm64",
+    "x86_64": "amd64",
+}
+
+# A self-contained weather CLI exercising each dynamic shell_complete shape: a
+# root-level option, a subcommand option, and a subcommand argument. Invoked with
+# --dump-carapace-spec it prints its own spec; otherwise it answers the completion
+# the spec's dynamic macros call back into.
+CARAPACE_RUNNER = '''\
+import sys
+
+import click
+import cloup
+from click.shell_completion import CompletionItem
+
+import click_extra  # noqa: F401  Registers the carapace completion backend.
+
+
+def complete_region(ctx, param, incomplete):
+    return [CompletionItem("north"), CompletionItem("south")]
+
+
+def complete_city(ctx, param, incomplete):
+    return [CompletionItem("paris", help="France"), CompletionItem("oslo")]
+
+
+def complete_zone(ctx, param, incomplete):
+    return [CompletionItem("alpha"), CompletionItem("bravo")]
+
+
+@cloup.group()
+@click.option("--region", shell_complete=complete_region, help="Region.")
+def weather(region):
+    """Weather tools."""
+
+
+@weather.command()
+@click.option("--city", shell_complete=complete_city, help="City.")
+@click.argument("zone", shell_complete=complete_zone)
+def forecast(city, zone):
+    """Forecast for a zone."""
+
+
+if __name__ == "__main__":
+    if "--dump-carapace-spec" in sys.argv:
+        from click_extra.carapace import dump_carapace_spec
+
+        sys.stdout.write(dump_carapace_spec(weather, prog_name="weather"))
+    else:
+        weather(prog_name="weather")
+'''
+
+
+@pytest.mark.network
+@pytest.mark.once
+def test_spec_drives_real_carapace_engine(tmp_path):
+    """Feed a generated spec to the real carapace-spec binary, end-to-end.
+
+    The tests above simulate Carapace at the CarapaceComplete level. This one
+    downloads a pinned carapace-spec release and drives it through each dynamic
+    shape: a root option, a subcommand option, and a subcommand argument. It
+    guards the contract between the emitted macros and Carapace's real
+    traverse/exec/parse behavior, which the simulation cannot see: Carapace strips
+    parent command names from the words it forwards, and withholds the flag being
+    completed entirely, so the macros must bake both back in.
+
+    .. attention::
+        Downloads the carapace-spec binary from GitHub and executes it, hence the
+        ``network`` mark (and ``once``, to run on a single CI runner). The dynamic
+        macro shells out, so the test only runs on POSIX platforms.
+    """
+    system = platform.system().lower()
+    arch = CARAPACE_ARCH.get(platform.machine().lower())
+    if system not in ("linux", "darwin"):
+        pytest.skip(f"dynamic macro is POSIX-shell only, not {system}")
+    if arch is None:
+        pytest.skip(f"no carapace-spec asset for {platform.machine()}")
+
+    # Download the pinned release archive from GitHub.
+    asset = f"carapace-spec_{CARAPACE_SPEC_VERSION}_{system}_{arch}.tar.gz"
+    url = (
+        "https://github.com/carapace-sh/carapace-spec/releases/download/"
+        f"v{CARAPACE_SPEC_VERSION}/{asset}"
+    )
+    with requests.get(url, timeout=60) as response:
+        assert response.ok, f"failed to download {url}"
+        archive_bytes = response.content
+
+    archive = tmp_path / asset
+    archive.write_bytes(archive_bytes)
+
+    # Pull just the carapace-spec binary out of the archive by name. Reading the
+    # member by hand (rather than extractall) sidesteps path-traversal and symlink
+    # members and the cross-version tar extraction-filter churn.
+    with tarfile.open(archive, "r:gz") as tar:
+        member = next(
+            (
+                m
+                for m in tar.getmembers()
+                if m.isfile() and Path(m.name).name == "carapace-spec"
+            ),
+            None,
+        )
+        assert member is not None, tar.getnames()
+        payload = tar.extractfile(member)
+        assert payload is not None
+        binary = tmp_path / "carapace-spec"
+        binary.write_bytes(payload.read())
+    binary.chmod(binary.stat().st_mode | stat.S_IXUSR)
+
+    # Write the CLI and generate its spec through the script's own dump mode.
+    script = tmp_path / "weather_cli.py"
+    script.write_text(CARAPACE_RUNNER)
+    spec = subprocess.run(
+        [sys.executable, str(script), "--dump-carapace-spec"],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout
+    spec_file = tmp_path / "weather.yaml"
+    spec_file.write_text(spec)
+
+    # The dynamic macro execs the program by bare name, so a `weather` shim that
+    # runs the script under this interpreter must be discoverable on PATH.
+    bindir = tmp_path / "bin"
+    bindir.mkdir()
+    shim = bindir / "weather"
+    shim.write_text(f'#!/bin/sh\nexec "{sys.executable}" "{script}" "$@"\n')
+    shim.chmod(0o755)
+    env = {**os.environ, "PATH": f"{bindir}{os.pathsep}{os.environ['PATH']}"}
+
+    def complete(*words):
+        """Ask the real engine to complete `weather <words> <TAB>`."""
+        result = subprocess.run(
+            [str(binary), str(spec_file), "export", "weather", *words],
+            capture_output=True,
+            text=True,
+            env=env,
+        )
+        assert result.returncode == 0, result.stderr
+        return {value["value"] for value in json.loads(result.stdout)["values"]}
+
+    # Each dynamic shape resolves through the real engine.
+    assert complete("--region", "") == {"north", "south"}
+    assert complete("forecast", "--city", "") == {"paris", "oslo"}
+    assert complete("forecast", "") == {"alpha", "bravo"}
+    # Carapace prefix-filters the full candidate set the callback returns.
+    assert complete("forecast", "--city", "p") == {"paris"}