Add a test for the new command-line parser normalization step (ed3c5a0) - derivepassphrase.git

tests/test_derivepassphrase_cli/test_all_cli.py
@@ -11,23 +11,29 @@ subcommands.
 
 from __future__ import annotations
 
+import collections
 import contextlib
 import enum
+import functools
+import operator
 import re
+import string
 import types
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypeVar, cast
 
 import exceptiongroup
+import hypothesis
 import pytest
-from typing_extensions import NamedTuple
+from hypothesis import strategies
+from typing_extensions import NamedTuple, overload
 
 from derivepassphrase import _types, cli, ssh_agent
-from derivepassphrase._internals import cli_messages
+from derivepassphrase._internals import cli_machinery, cli_messages
 from tests import machinery
 from tests.machinery import pytest as pytest_machinery
 
 if TYPE_CHECKING:
-    from collections.abc import Generator
+    from collections.abc import Generator, Iterable, Sequence
 
 
 class VersionOutputData(NamedTuple):
@@ -70,6 +76,11 @@ class KnownLineType(str, enum.Enum):
     ENABLED_EXTRAS = _label_text(cli_messages.Label.ENABLED_PEP508_EXTRAS)
 
 
+class ParseStateAndExpectedResult(NamedTuple):
+    starting_state: cli_machinery.ParseState
+    expected_result: cli_machinery.ParseResult
+
+
 class Parametrize(types.SimpleNamespace):
     """Common test parametrizations."""
 
@@ -329,6 +340,964 @@ Supported subcommands: export, spectre ({aliases!s} master-password, mpw),
     """Sample data for [`parse_version_output`][]."""
 
 
+def roman_numerals() -> Generator[str, None, None]:
+    """Generate lowercase roman numerals, up to 3999."""
+    ones = ["", "i", "ii", "iii", "iv", "v", "vi", "vii", "viii", "ix"]
+    tens = ["", "x", "xx", "xxx", "xl", "l", "lx", "lxx", "lxxx", "xc"]
+    huns = ["", "c", "cc", "ccc", "cd", "d", "dc", "dcc", "dccc", "cm"]
+    thou = ["", "m", "mm", "mmm"]
+
+    # Start at "i".
+    for i in range(1, 4000):
+        yield "".join([
+            thou[(i // 1000) % len(thou)],
+            huns[(i // 100) % len(huns)],
+            tens[(i // 10) % len(tens)],
+            ones[(i // 1) % len(ones)],
+        ])
+
+
+def make_dummy_options(
+    name_counter: Iterable[str],
+    short_name_counter: Iterable[str],
+    /,
+) -> Generator[cli_machinery.CLIOption, None, None]:
+    """Generate dummy CLIOption objects.
+
+    Args:
+        name_counter:
+            An iterable for unique names, to be used as long option
+            names.
+        short_name_counter:
+            An iterable of short option "letters", to be used for short
+            option names.
+
+    Yields:
+        CLIOption objects with hitherto unseen option names.  Some
+        options will be eager, some will take an argument, some will do
+        both.
+
+    """
+    has_argument_list: list[bool | tuple[str, ...]] = [
+        False,
+        True,
+        ("arg1", "arg2", "arg3", "arg4", "arg5", "arg6"),
+    ]
+    eager_list = [False, True]
+    for i, (name, letter) in enumerate(zip(name_counter, short_name_counter)):
+        i_has_argument = i // len(eager_list)
+        i_eager = i
+        names = (
+            f"--{name}",
+            f"-{letter}",
+            f"--alias-{name}",
+            f"--alternate-{name}",
+        )
+        help = f"Help for option --{name}."  # noqa: A001
+        has_argument = has_argument_list[
+            i_has_argument % len(has_argument_list)
+        ]
+        eager = eager_list[i_eager % len(eager_list)]
+        yield cli_machinery.CLIOption(
+            names=names, help=help, has_argument=has_argument, eager=eager
+        )
+
+
+def make_dummy_option_groups(
+    name_counter: Iterable[str],
+    short_name_counter: Iterable[str],
+    /,
+) -> Generator[cli_machinery.CLIOptionGroup, None, None]:
+    """Generate dummy CLIOptionGroup objects.
+
+    The option objects are generated via [`make_dummy_options`][].
+    They are grouped such that each option has a unique combination of
+    eagerness and argument requirements.
+
+    Args:
+        name_counter:
+            An iterable for unique names, to be used as long option
+            names.  Passed to [`make_dummy_options`][].
+        short_name_counter:
+            An iterable of short option "letters", to be used for short
+            option names.  Passed to [`make_dummy_options`][].
+
+    Yields:
+        CLIOptionGroup objects.  The embedded CLIOption objects will
+        have hitherto unseen option names.  Some options will be eager,
+        some will take an argument, some will do both.
+
+    """
+    option_states_seen: set[tuple[bool, bool | tuple[str, ...]]] = set()
+    options_collected: list[cli_machinery.CLIOption] = []
+    i = 1
+    for option in make_dummy_options(name_counter, short_name_counter):
+        option_state = (
+            option.eager,
+            option.has_argument
+            if isinstance(option.has_argument, bool)
+            else tuple(option.has_argument),
+        )
+        if option_state in option_states_seen:
+            yield cli_machinery.CLIOptionGroup(
+                options=tuple(options_collected),
+                title=f"Group {i}",
+                epilog=f"Group {i} epilog.",
+            )
+            option_states_seen.clear()
+            options_collected.clear()
+            i += 1
+        options_collected.append(option)
+        option_states_seen.add(option_state)
+    if options_collected:
+        yield cli_machinery.CLIOptionGroup(
+            options=tuple(options_collected),
+            title=f"Group {i}",
+            epilog=f"Group {i} epilog.",
+        )
+
+
+def make_dummy_command_names() -> Generator[str, None, None]:
+    """Generate dummy subcommand names.
+
+    The names are drawn from actual program subcommands.
+
+    Yields:
+        Unique names from actual program subcommands.
+
+    """
+    subpools = [
+        (
+            "add rm status checkout branch switch merge diff log push pull "
+            "revert reset rebase bisect bundle cherry-pick gc clone init "
+            "stash worktree tag remote blame"
+        ),  # git
+        "vault",  # derivepassphrase
+        "all check install test clean",  # make
+        (
+            "bye cd chgrp chmod chown copy cp df exit get help lcd lls "
+            "lmkdir ln lpwd ls lumask mkdir progress put pwd quit "
+            "reget reput rename rm rmdir symlink version"
+        ),  # OpenSSH sftp
+        (
+            "alias bg cd chdir command echo eval exec exit export fc "
+            "fg getopts hash jobs kill pwd read readonly printf set shift "
+            "test times trap type ulimit umask unalias unset wait"
+        ),  # dash/POSIX sh(1)
+        (
+            "bind builtin caller compgen complete compopt declare disown "
+            "enable history let local logout mapfile popd pushd return "
+            "shopt source suspend"
+        ),  # bash
+    ]
+    seen: set[str] = set()
+    for subpool in subpools:
+        for arg in subpool.split():
+            if arg not in seen:
+                seen.add(arg)
+                yield arg
+
+
+OPTION_GROUP_POOL = tuple(
+    make_dummy_option_groups(roman_numerals(), sorted(string.ascii_letters))
+)
+"""A pool of disjoint option group objects from which individual option
+groups can be drawn without consuming too much entropy."""
+OPTION_POOL = tuple(
+    option for group in OPTION_GROUP_POOL for option in group.options
+)
+"""A pool of disjoint option objects from which individual options can be
+drawn without consuming too much entropy."""
+COMMAND_NAMES_POOL = tuple(make_dummy_command_names())
+"""A pool of unique subcommand names from which individual names can be
+drawn without consuming too much entropy."""
+
+
+def _is_short_option(name: str) -> bool:
+    return not name.startswith("--")
+
+
+def _name_complexity(name: str) -> tuple[int, str]:
+    return len(name), name
+
+
+def _option_name_complexity(opt: cli_machinery.CLIOption) -> tuple[int, int]:
+    has_short_option = any(_is_short_option(name) for name in opt.names)
+    return (
+        0 if has_short_option else 1,
+        0 if opt.has_argument else 1,
+    )
+
+
+def _option_group_complexity(group: cli_machinery.CLIOptionGroup) -> int:
+    option_complexities = [
+        _option_name_complexity(opt) for opt in group.options
+    ]
+    penalty_no_short_option = sum(cplx[0] for cplx in option_complexities)
+    penalty_argument = sum(cplx[1] for cplx in option_complexities)
+    size_penalty = (
+        len(option_complexities[0]) * len(option_complexities)
+        if option_complexities
+        else 0
+    )
+    return size_penalty + penalty_no_short_option + penalty_argument
+
+
+def _options_are_unique(
+    groups: Sequence[cli_machinery.CLIOptionGroup],
+    /,
+) -> bool:
+    all_option_names = [
+        name for group in groups for opt in group.options for name in opt.names
+    ]
+    option_names = set(all_option_names)
+    return len(all_option_names) == len(option_names)
+
+
+T = TypeVar("T")
+
+
+@overload
+def _flatten(nested_list: Sequence[list[T]], /) -> list[T]: ...
+
+
+@overload
+def _flatten(nested_list: Sequence[tuple[T, ...]], /) -> tuple[T, ...]: ...
+
+
+@overload
+def _flatten(
+    nested_list: Sequence[collections.deque[T]], /
+) -> collections.deque[T]: ...
+
+
+def _flatten(
+    nested_list: Sequence[list | tuple | collections.deque],
+    /,
+) -> list | tuple | collections.deque:
+    if not nested_list:
+        raise ValueError(  # noqa: TRY003
+            "Cannot flatten empty sequence without constructor factory"  # noqa: EM101
+        )
+    first = nested_list[0]
+    if isinstance(first, list):
+        return functools.reduce(operator.add, nested_list, [])
+    if isinstance(first, tuple):
+        return functools.reduce(operator.add, nested_list, ())
+    if isinstance(first, collections.deque):
+        return functools.reduce(operator.add, nested_list, collections.deque())
+    raise ValueError(  # noqa: TRY003
+        "Cannot flatten things that aren't tuples, lists or deques"  # noqa: EM101
+    )
+
+
+class Strategies(types.SimpleNamespace):
+    """Common hypothesis strategies."""
+
+    WORDS = strategies.text(string.ascii_lowercase, min_size=1)
+    METAVARS = strategies.text(string.ascii_uppercase, min_size=1, max_size=7)
+    COMMAND_NAMES = strategies.sampled_from(
+        sorted(COMMAND_NAMES_POOL, key=len)
+    )
+
+    NUM_NAMES = 4
+    NUM_OPTIONS_PER_GROUP = 2
+
+    @staticmethod
+    def option_pool() -> tuple[cli_machinery.CLIOption, ...]:
+        return OPTION_POOL
+
+    @staticmethod
+    def options() -> strategies.SearchStrategy[cli_machinery.CLIOption]:
+        pool = Strategies.option_pool()
+        return strategies.sampled_from(pool)
+
+    @staticmethod
+    def option_group_pool(
+        *,
+        allow_eager: bool = False,
+    ) -> tuple[cli_machinery.CLIOptionGroup, ...]:
+        pool1 = [
+            cli_machinery.CLIOptionGroup(
+                options=tuple(
+                    opt
+                    for opt in group.options
+                    if not opt.eager or allow_eager
+                ),
+                title=group.title,
+                epilog=group.epilog,
+            )
+            for group in OPTION_GROUP_POOL
+        ]
+        pool2 = [group for group in pool1 if group.options]
+        return tuple(pool2)
+
+    @staticmethod
+    def option_groups(
+        *,
+        allow_eager: bool = False,
+    ) -> strategies.SearchStrategy[cli_machinery.CLIOptionGroup]:
+        pool = Strategies.option_group_pool(allow_eager=allow_eager)
+        return strategies.sampled_from(pool)
+
+    @staticmethod
+    @strategies.composite
+    def terminal_subcommands(
+        draw: strategies.DrawFn,
+        /,
+        *,
+        allow_eager: bool = False,
+        max_option_groups: int = NUM_NAMES,
+        max_positionals: int = NUM_NAMES,
+    ) -> cli_machinery.CLITerminalSubcommand:
+        names = draw(
+            strategies.lists(
+                Strategies.COMMAND_NAMES,
+                min_size=1,
+                max_size=Strategies.NUM_NAMES,
+                unique=True,
+            ),
+            "names",
+        )
+        option_groups = draw(
+            strategies.lists(
+                Strategies.option_groups(allow_eager=allow_eager),
+                min_size=1,
+                max_size=max_option_groups,
+            ).filter(_options_are_unique),
+            "option_groups",
+        )
+        positionals = draw(
+            strategies.lists(
+                Strategies.METAVARS.map(cli_machinery.CLIArgument),
+                max_size=max_positionals,
+                unique_by=lambda arg: arg.name,
+            ),
+            "positionals",
+        )
+        return cli_machinery.CLITerminalSubcommand(
+            names=tuple(names),
+            contents=(tuple(option_groups), tuple(positionals)),
+            prolog=("Subcommand prolog goes here.",),
+            epilog=("Subcommand epilog goes here.",),
+        )
+
+    @staticmethod
+    def clustered_options_with_final_argument(
+        *options: cli_machinery.CLIOption,
+    ) -> strategies.SearchStrategy[list[str]]:
+        if not options:  # pragma: no cover [failsafe]
+            msg = "No options given!"
+            raise ValueError(msg)
+        for opt in options:  # pragma: no cover [failsafe]
+            if not any(_is_short_option(name) for name in opt.names):
+                msg = f"Option object has no short options: {opt!r}"
+                raise ValueError(msg)
+        if not options[-1].has_argument:  # pragma: no cover [failsafe]
+            msg = f"Option does not accept an argument: {opt!r}"
+            raise ValueError(msg)
+
+        def cluster_options(args: tuple[str, ...]) -> list[str]:
+            first = args[0]  # in full
+            middle = "".join(opt[-1:] for opt in args[1:-1])  # no "-"
+            last = args[-1]  # maybe an argument
+            return [f"{first}{middle}{last}"]
+
+        eligible_options = [
+            tuple(name for name in opt.names if _is_short_option(name))
+            for opt in options
+        ]
+        strategies_ = [
+            strategies.just(names[0])
+            if len(names) == 1
+            else strategies.sampled_from(names)
+            for names in eligible_options
+        ]
+        strategies_.append(Strategies.WORDS)
+        return strategies.tuples(*strategies_).map(cluster_options)
+
+    @staticmethod
+    def option_and_argument(
+        opt: cli_machinery.CLIOption,
+        free_arguments_strategy: strategies.SearchStrategy[str] | None = None,
+    ) -> strategies.SearchStrategy[list[str]]:
+        # shrink to less complex option names
+        option_names = sorted(opt.names, key=_name_complexity)
+        option_strategy = strategies.sampled_from(option_names)
+        if not isinstance(opt.has_argument, bool):
+            # shrink to less complex arguments
+            arguments = sorted(opt.has_argument, key=_name_complexity)
+            return strategies.tuples(
+                option_strategy, strategies.sampled_from(arguments)
+            ).map(list)
+        if opt.has_argument:
+            return strategies.tuples(
+                option_strategy,
+                free_arguments_strategy
+                if free_arguments_strategy is not None
+                else Strategies.WORDS,
+            ).map(list)
+        return strategies.tuples(option_strategy).map(list)
+
+    @staticmethod
+    @strategies.composite
+    def maybe_connect_options_and_arguments(
+        draw: strategies.DrawFn,
+        pairs: list[list[str]],
+        /,
+    ) -> list[list[str]]:
+        return [
+            ["=".join(pair)]
+            if len(pair) > 1
+            and pair[0].startswith("--")
+            and draw(strategies.booleans(), f"connect pair {i}")
+            else pair
+            for i, pair in enumerate(pairs)
+        ]
+
+    @staticmethod
+    @strategies.composite
+    def choose_clusters(
+        draw: strategies.DrawFn,
+        snippet: list[str],
+        /,
+    ) -> list[str]:
+        result: list[str] = []
+        for i, token in enumerate(snippet):
+            if i == 0:
+                result.append(token)
+                continue
+            previous_token = snippet[i - 1]
+            if (
+                previous_token.startswith("--")
+                or not previous_token.startswith("-")
+                or token.startswith("--")
+            ):
+                result.append(token)
+            else:
+                # token is an argument, or a short option
+                extend_cluster = draw(
+                    strategies.booleans(), f"cluster[{i - 1}, {i}]"
+                )
+                if extend_cluster:
+                    result[-1] += token[1] if token.startswith("-") else token
+                else:
+                    result.append(token)
+        return result
+
+    @staticmethod
+    def arrange_options(
+        *options: cli_machinery.CLIOption,
+        free_arguments_strategy: strategies.SearchStrategy[str] | None = None,
+    ) -> strategies.SearchStrategy[list[list[str]]]:
+        pairs_strategies = [
+            Strategies.option_and_argument(opt, free_arguments_strategy)
+            for opt in options
+        ]
+        return strategies.tuples(*pairs_strategies).map(list)
+
+    @staticmethod
+    def choose_option(
+        options: Sequence[cli_machinery.CLIOption],
+        /,
+    ) -> strategies.SearchStrategy[cli_machinery.CLIOption]:
+        # shrink to less complex options
+        return strategies.sampled_from(
+            sorted(options, key=_option_name_complexity)
+        )
+
+    @staticmethod
+    def choose_options(
+        *options: cli_machinery.CLIOption,
+        free_arguments_strategy: strategies.SearchStrategy[str] | None = None,
+    ) -> strategies.SearchStrategy[list[list[str]]]:
+        def _option_and_argument(
+            opt: cli_machinery.CLIOption,
+            /,
+        ) -> strategies.SearchStrategy[list[str]]:
+            return Strategies.option_and_argument(opt, free_arguments_strategy)
+
+        return strategies.lists(
+            Strategies.choose_option(options).flatmap(_option_and_argument),
+            max_size=2 * len(options),
+        )
+
+    @staticmethod
+    def any_option_and_argument_pairs(
+        *options: cli_machinery.CLIOption,
+        free_arguments_strategy: strategies.SearchStrategy[str] | None = None,
+        in_order: bool = True,
+    ) -> strategies.SearchStrategy[list[list[str]]]:
+        if not options:  # pragma: no cover [failsafe]
+            msg = "No options given!"
+            raise ValueError(msg)
+        return (
+            Strategies.arrange_options(
+                *options, free_arguments_strategy=free_arguments_strategy
+            )
+            if in_order
+            else Strategies.choose_options(
+                *options, free_arguments_strategy=free_arguments_strategy
+            )
+        )
+
+    @staticmethod
+    @strategies.composite
+    def any_options(
+        draw: strategies.DrawFn,
+        option_and_argument_pairs_strategy: strategies.SearchStrategy[
+            list[list[str]]
+        ],
+        /,
+        *,
+        normalized: bool = True,
+    ) -> list[str]:
+
+        def choose_clusters(
+            tokens: list[str],
+        ) -> strategies.SearchStrategy[list[str]]:
+            return (
+                strategies.just(tokens)
+                if normalized
+                else Strategies.choose_clusters(tokens)
+            )
+
+        raw_option_argument_pairs = draw(
+            option_and_argument_pairs_strategy, "raw option/argument pairs"
+        )
+        connected_option_argument_pairs = (
+            [
+                ["=".join(pair)]
+                if len(pair) > 1 and pair[0].startswith("--")
+                else pair
+                for pair in raw_option_argument_pairs
+            ]
+            if normalized
+            else draw(
+                Strategies.maybe_connect_options_and_arguments(
+                    raw_option_argument_pairs
+                ),
+                "connected option/argument pairs",
+            )
+        )
+        unclustered_arguments = _flatten(connected_option_argument_pairs)
+        return draw(
+            choose_clusters(unclustered_arguments), "clustered command-line"
+        )
+
+    @staticmethod
+    @strategies.composite
+    def composite_subcommands(
+        draw: strategies.DrawFn,
+        subcommands: strategies.SearchStrategy[cli_machinery.CLISubcommand],
+        /,
+        wrapped_subcommand: cli_machinery.CLISubcommand | None = None,
+        *,
+        allow_default_subcommand: bool = True,
+        allow_eager: bool = False,
+        max_option_groups: int = NUM_NAMES,
+        max_subcommands: int = NUM_NAMES,
+    ) -> cli_machinery.CLICompositeSubcommand:
+        k = max_option_groups
+        n = max_subcommands
+        names = draw(
+            strategies.lists(
+                Strategies.COMMAND_NAMES,
+                min_size=1,
+                max_size=Strategies.NUM_NAMES,
+                unique=True,
+            ),
+            "names",
+        )
+        option_groups = draw(
+            strategies.lists(
+                Strategies.option_groups(allow_eager=allow_eager),
+                min_size=1,
+                max_size=k,
+            ).filter(_options_are_unique),
+            "option_groups",
+        )
+
+        def subcommand_names_are_unique(
+            subcommands: list[cli_machinery.CLISubcommand],
+        ) -> bool:
+            names = [name for cmd in subcommands for name in cmd.names]
+            return len(names) == len(set(names))
+
+        subcommand_list_strategy = (
+            strategies.lists(subcommands, max_size=n - 1).map(
+                lambda others: [wrapped_subcommand, *others]
+            )
+            if wrapped_subcommand is not None
+            else strategies.lists(subcommands, min_size=1, max_size=n)
+        )
+        subcommand_list = draw(
+            subcommand_list_strategy.filter(subcommand_names_are_unique),
+            "subcommands",
+        )
+        default_subcommand = (
+            draw(
+                strategies.one_of(
+                    strategies.none(),
+                    strategies.just(subcommand_list[0].names[0]),
+                ),
+                "default_subcommand",
+            )
+            if allow_default_subcommand
+            else None
+        )
+        return cli_machinery.CLICompositeSubcommand(
+            names=tuple(names),
+            contents=(
+                tuple(option_groups),
+                tuple(subcommand_list),
+                default_subcommand,
+            ),
+            prolog=("Subcommand prolog goes here.",),
+            epilog=("Subcommand epilog goes here.",),
+        )
+
+    @staticmethod
+    def subcommands(
+        *,
+        allow_eager: bool = False,
+        max_option_groups: int = NUM_NAMES,
+        max_positionals: int = NUM_NAMES,
+    ) -> strategies.SearchStrategy[cli_machinery.CLISubcommand]:
+        terminals = Strategies.terminal_subcommands(
+            allow_eager=allow_eager,
+            max_option_groups=max_option_groups,
+            max_positionals=max_positionals,
+        )
+        return strategies.recursive(
+            terminals,
+            lambda strat: Strategies.composite_subcommands(
+                strat,
+                allow_default_subcommand=True,
+                allow_eager=allow_eager,
+                max_option_groups=max_option_groups,
+                max_subcommands=max_positionals,
+            ),
+        )
+
+    @staticmethod
+    @strategies.composite
+    def subcommand_and_symbolic_command_line(
+        draw: strategies.DrawFn,
+        /,
+        *,
+        allow_eager: bool = False,
+        max_option_groups: int = NUM_NAMES,
+        max_positionals: int = NUM_NAMES,
+    ) -> tuple[
+        cli_machinery.CLISubcommand,
+        list[
+            tuple[
+                tuple[cli_machinery.CLIOption, ...],
+                tuple[cli_machinery.CLIArgument, ...]
+                | cli_machinery.CLISubcommand,
+            ]
+        ],
+    ]:
+
+        @strategies.composite
+        def options_strategy(
+            draw: strategies.DrawFn,
+            options: Sequence[cli_machinery.CLIOption],
+            /,
+            *,
+            force_clusterable: bool = False,
+        ) -> tuple[cli_machinery.CLIOption, ...]:
+            n = draw(
+                strategies.integers(0, Strategies.NUM_NAMES), "num_options"
+            )
+            if not n:
+                return ()
+            with_args = [opt for opt in options if opt.has_argument]
+            without_args = [opt for opt in options if not opt.has_argument]
+            options_without_arguments = strategies.sampled_from(without_args)
+            options_with_arguments = strategies.sampled_from(with_args)
+            options_maybe_with_arguments = strategies.sampled_from(options)
+            if not force_clusterable:
+                return draw(
+                    strategies.lists(
+                        options_maybe_with_arguments, min_size=n, max_size=n
+                    ).map(tuple),
+                    "options",
+                )
+            last_opt = draw(options_with_arguments, "last_option")
+            preceding_opts = draw(
+                strategies.lists(
+                    options_without_arguments, min_size=n - 1, max_size=n - 1
+                ),
+                "preceding_options",
+            )
+            return (*preceding_opts, last_opt)
+
+        terminal_subcommands = Strategies.terminal_subcommands(
+            allow_eager=allow_eager
+        )
+        subcommand_stack = collections.deque([
+            cast(
+                "cli_machinery.CLISubcommand",
+                draw(terminal_subcommands, "terminal_subcommand"),
+            )
+        ])
+        subcommand_depth = draw(strategies.integers(1, 4), "subcommand_depth")
+        for counter in range(1, subcommand_depth):
+            subcommand_stack.appendleft(
+                draw(
+                    Strategies.composite_subcommands(
+                        terminal_subcommands,
+                        wrapped_subcommand=subcommand_stack[0],
+                        allow_default_subcommand=True,
+                        allow_eager=allow_eager,
+                        max_option_groups=max_option_groups,
+                        max_subcommands=max_positionals,
+                    ),
+                    f"parent_subcommand #{counter}",
+                )
+            )
+        command_line_symbolic_sections: list[
+            tuple[
+                tuple[cli_machinery.CLIOption, ...],
+                tuple[cli_machinery.CLIArgument, ...]
+                | cli_machinery.CLISubcommand,
+            ]
+        ] = []
+        for i, subcommand in enumerate(subcommand_stack):
+            counter = i + 1
+            eligible_options = [
+                opt
+                for group in subcommand.contents[0]
+                for opt in group.options
+            ]
+            section_options = draw(
+                options_strategy(eligible_options),
+                f"options #{counter}",
+            )
+            section: tuple[
+                tuple[cli_machinery.CLIOption, ...],
+                cli_machinery.CLISubcommand
+                | tuple[cli_machinery.CLIArgument, ...],
+            ]
+            if isinstance(subcommand, cli_machinery.CLITerminalSubcommand):
+                arguments = subcommand.contents[1]
+                section = (tuple(section_options), tuple(arguments))
+            else:
+                next_subcommand = subcommand_stack[i + 1]
+                section = (tuple(section_options), next_subcommand)
+            command_line_symbolic_sections.append(section)
+        return (subcommand_stack[0], command_line_symbolic_sections)
+
+    @staticmethod
+    @strategies.composite
+    def parse_states(
+        draw: strategies.DrawFn,
+        /,
+        subcommand_and_symbolic_command_line: tuple[
+            cli_machinery.CLISubcommand,
+            list[
+                tuple[
+                    tuple[cli_machinery.CLIOption, ...],
+                    tuple[cli_machinery.CLIArgument, ...]
+                    | cli_machinery.CLISubcommand,
+                ]
+            ],
+        ]
+        | None = None,
+        *,
+        allow_eager: bool = False,
+        normalized: bool = True,
+        max_option_groups: int = NUM_NAMES,
+        max_positionals: int = NUM_NAMES,
+    ) -> cli_machinery.ParseState:
+        subcommand, command_line_symbolic_sections = (
+            subcommand_and_symbolic_command_line
+            if subcommand_and_symbolic_command_line is not None
+            else draw(
+                Strategies.subcommand_and_symbolic_command_line(
+                    allow_eager=allow_eager,
+                    max_option_groups=max_option_groups,
+                    max_positionals=max_positionals,
+                ),
+                "subcommand/symbolic command-line",
+            )
+        )
+        command_line: list[str] = []
+        for i, section in enumerate(command_line_symbolic_sections):
+            options, subcommand_or_arguments = section
+            command_line.extend(
+                draw(
+                    Strategies.any_options(
+                        Strategies.any_option_and_argument_pairs(
+                            *options,
+                            in_order=True,
+                        ),
+                        normalized=normalized,
+                    ),
+                    f"section {i} options",
+                )
+                if options
+                else []
+            )
+            if isinstance(
+                subcommand_or_arguments,
+                (
+                    cli_machinery.CLITerminalSubcommand,
+                    cli_machinery.CLICompositeSubcommand,
+                ),
+            ):
+                command_line.append(subcommand_or_arguments.names[0])
+            else:
+                arguments_strategies = [
+                    strategies.sampled_from(arg.choices)
+                    if arg.choices is not None
+                    else Strategies.WORDS
+                    for arg in subcommand_or_arguments
+                ]
+                command_line.extend(
+                    draw(
+                        strategies.tuples(*arguments_strategies),
+                        f"section {i} arguments",
+                    )
+                )
+        return cli_machinery.ParseState(
+            tuple(command_line),
+            subcommand,
+        )
+
+    @staticmethod
+    @strategies.composite
+    def normalizable_parser_states(
+        draw: strategies.DrawFn,
+        /,
+        subcommand_and_symbolic_command_line: tuple[
+            cli_machinery.CLISubcommand,
+            list[
+                tuple[
+                    tuple[cli_machinery.CLIOption, ...],
+                    tuple[cli_machinery.CLIArgument, ...]
+                    | cli_machinery.CLISubcommand,
+                ]
+            ],
+        ]
+        | None = None,
+        *,
+        allow_eager: bool = True,
+        max_option_groups: int = NUM_NAMES,
+        max_positionals: int = NUM_NAMES,
+    ) -> ParseStateAndExpectedResult:
+        subcommand, command_line_symbolic_sections = (
+            subcommand_and_symbolic_command_line
+            if subcommand_and_symbolic_command_line is not None
+            else draw(
+                Strategies.subcommand_and_symbolic_command_line(
+                    allow_eager=allow_eager,
+                    max_option_groups=max_option_groups,
+                    max_positionals=max_positionals,
+                ),
+                "subcommand/symbolic command-line",
+            )
+        )
+        command_line: list[str] = []
+        first_section_normalized_command_line: list[str] = []
+        for i, section in enumerate(command_line_symbolic_sections):
+            options, subcommand_or_arguments = section
+            if options:  # pragma: no branch
+                option_and_argument_pairs = draw(
+                    Strategies.any_option_and_argument_pairs(
+                        *options,
+                        in_order=True,
+                    ),
+                    f"section {i} raw option/argument pairs",
+                )
+                drawn_options_and_arguments = (
+                    draw(
+                        Strategies.any_options(
+                            strategies.just(option_and_argument_pairs),
+                            normalized=False,
+                        ),
+                        f"section {i} options",
+                    )
+                    if options
+                    else []
+                )
+                command_line.extend(drawn_options_and_arguments)
+                if i == 0:
+                    assert len(option_and_argument_pairs) == len(options)
+                    for opt, pair in zip(options, option_and_argument_pairs):
+                        opt_name = opt.names[0]
+                        if len(pair) > 1:
+                            arg = pair[1]
+                            first_section_normalized_command_line.append(
+                                f"{opt_name}={arg}"
+                            )
+                        else:
+                            first_section_normalized_command_line.append(
+                                opt_name
+                            )
+                else:
+                    first_section_normalized_command_line.extend(
+                        drawn_options_and_arguments
+                    )
+            if isinstance(
+                subcommand_or_arguments,
+                (
+                    cli_machinery.CLITerminalSubcommand,
+                    cli_machinery.CLICompositeSubcommand,
+                ),
+            ):
+                subcommand_name = subcommand_or_arguments.names[0]
+                command_line.append(subcommand_name)
+                if i == 0:
+                    first_section_normalized_command_line.append("--")
+                first_section_normalized_command_line.append(subcommand_name)
+            else:
+                arguments_strategies = [
+                    strategies.sampled_from(arg.choices)
+                    if arg.choices is not None
+                    else Strategies.WORDS
+                    for arg in subcommand_or_arguments
+                ]
+                argument_values = draw(
+                    strategies.tuples(*arguments_strategies),
+                    f"section {i} arguments",
+                )
+                command_line.extend(argument_values)
+                if i == 0:
+                    first_section_normalized_command_line.append("--")
+                first_section_normalized_command_line.extend(argument_values)
+        old_state = cli_machinery.ParseState(tuple(command_line), subcommand)
+        new_state = cli_machinery.ParseState(
+            tuple(first_section_normalized_command_line), subcommand
+        )
+        result = cli_machinery.ParseSuccess(new_state, None)
+        return ParseStateAndExpectedResult(old_state, result)
+
+
+strategies.register_type_strategy(
+    cli_machinery.CLIOption,
+    Strategies.options(),
+)
+strategies.register_type_strategy(
+    cli_machinery.CLIOptionGroup,
+    Strategies.option_groups(),
+)
+strategies.register_type_strategy(
+    cli_machinery.CLITerminalSubcommand,
+    Strategies.terminal_subcommands(),
+)
+strategies.register_type_strategy(
+    cli_machinery.CLICompositeSubcommand,
+    Strategies.composite_subcommands(Strategies.subcommands()),
+)
+strategies.register_type_strategy(
+    cli_machinery.ParseState,
+    Strategies.parse_states(),
+)
+
+
 def tokenize_version_output_item_listing(
     line: str,
     /,
@@ -575,6 +1544,21 @@ class Test001VersionOutputParser:
         )
 
 
+class Test010CLIMachinery:
+    """Tests for the CLI machinery."""
+
+    @hypothesis.given(data_tuple=Strategies.normalizable_parser_states())
+    def test_normalize_options_stage(
+        self,
+        data_tuple: ParseStateAndExpectedResult,
+    ) -> None:
+        actual_result = cli_machinery.normalize_options(
+            data_tuple.starting_state
+        )
+        assert actual_result.state == data_tuple.expected_result.state
+        assert actual_result == data_tuple.expected_result
+
+
 class TestHelpOutput:
     """Tests for all command-line interfaces' `--help` output."""
 
