usage-spec-click 1.0.0__tar.gz

usage_spec_click-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+aube-lock.yaml
+.npmrc
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/

usage_spec_click-1.0.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: usage-spec-click
+Version: 1.0.0
+Summary: Generates usage spec for CLIs written with click
+License-Expression: MIT
+Keywords: cli,click,kdl,shell-completion,usage
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: usage-spec
+Provides-Extra: dev
+Requires-Dist: click>=8.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# usage-spec-click
+
+Generates [usage spec](https://usage.jdx.dev) for CLIs written with [click](https://click.palletsprojects.com/).
+
+## Install
+
+```sh
+pip install usage-spec-click
+```
+
+## Usage
+
+```python
+import click
+from click_usage import generate
+
+@click.command()
+@click.version_option("1.0.0")
+@click.option("-v", "--verbose", is_flag=True, help="Enable verbose output")
+@click.option("-f", "--file", type=str, help="Input file")
+@click.option("--color/--no-color", default=False, help="Color output")
+def cli(verbose, file, color):
+    pass
+
+print(generate(cli, "mycli"))
+```
+
+## API
+
+### `generate(cmd, bin_name=None)`
+
+Generates a usage spec in KDL format from a click `Command` or `Group`.
+
+### `generate_kdl(cmd, bin_name=None)`
+
+Alias for `generate()`.
+
+### `generate_json(cmd, bin_name=None)`
+
+Generates a usage spec in JSON format.
+
+### `convert_root(cmd, bin_name=None)`
+
+Converts a click `Command` or `Group` to the `Spec` data structure.
+
+## Supported Features
+
+| click Feature | Usage Spec Mapping |
+|---|---|
+| `cmd.name` | `name` / `bin` |
+| `@click.version_option()` | `version` |
+| `cmd.short_help` / `cmd.help` | `about` / `long_about` |
+| `@click.option()` | `flag` |
+| `required=True` | `flag required=#true` |
+| `is_flag=True` | Boolean flag (no arg) |
+| `--flag/--no-flag` | `negate` |
+| `count=True` | `count=#true` |
+| `multiple=True` | `var=#true` |
+| `type=click.Choice()` | `choices` |
+| `default=...` | `default` |
+| `hidden=True` | `hide=#true` |
+| `deprecated="..."` | `deprecated` |
+| `envvar="..."` | `env` |
+| `@click.argument()` | `arg` |
+| `@click.group()` subcommands | `cmd` (recursive) |
+| Groups without positional args | `subcommand_required=#true` |
+| `cmd.hidden` | Commands hidden from listing |
+
+## License
+
+MIT

usage_spec_click-1.0.0/README.md

@@ -0,0 +1,71 @@
+# usage-spec-click
+
+Generates [usage spec](https://usage.jdx.dev) for CLIs written with [click](https://click.palletsprojects.com/).
+
+## Install
+
+```sh
+pip install usage-spec-click
+```
+
+## Usage
+
+```python
+import click
+from click_usage import generate
+
+@click.command()
+@click.version_option("1.0.0")
+@click.option("-v", "--verbose", is_flag=True, help="Enable verbose output")
+@click.option("-f", "--file", type=str, help="Input file")
+@click.option("--color/--no-color", default=False, help="Color output")
+def cli(verbose, file, color):
+    pass
+
+print(generate(cli, "mycli"))
+```
+
+## API
+
+### `generate(cmd, bin_name=None)`
+
+Generates a usage spec in KDL format from a click `Command` or `Group`.
+
+### `generate_kdl(cmd, bin_name=None)`
+
+Alias for `generate()`.
+
+### `generate_json(cmd, bin_name=None)`
+
+Generates a usage spec in JSON format.
+
+### `convert_root(cmd, bin_name=None)`
+
+Converts a click `Command` or `Group` to the `Spec` data structure.
+
+## Supported Features
+
+| click Feature | Usage Spec Mapping |
+|---|---|
+| `cmd.name` | `name` / `bin` |
+| `@click.version_option()` | `version` |
+| `cmd.short_help` / `cmd.help` | `about` / `long_about` |
+| `@click.option()` | `flag` |
+| `required=True` | `flag required=#true` |
+| `is_flag=True` | Boolean flag (no arg) |
+| `--flag/--no-flag` | `negate` |
+| `count=True` | `count=#true` |
+| `multiple=True` | `var=#true` |
+| `type=click.Choice()` | `choices` |
+| `default=...` | `default` |
+| `hidden=True` | `hide=#true` |
+| `deprecated="..."` | `deprecated` |
+| `envvar="..."` | `env` |
+| `@click.argument()` | `arg` |
+| `@click.group()` subcommands | `cmd` (recursive) |
+| Groups without positional args | `subcommand_required=#true` |
+| `cmd.hidden` | Commands hidden from listing |
+
+## License
+
+MIT

usage_spec_click-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "usage-spec-click"
+version = "1.0.0"
+description = "Generates usage spec for CLIs written with click"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+keywords = ["click", "usage", "cli", "kdl", "shell-completion"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+dependencies = ["usage-spec", "click>=8.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "click>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/click_usage"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

usage_spec_click-1.0.0/src/click_usage/__init__.py

@@ -0,0 +1,39 @@
+"""Usage spec integration for click."""
+
+from __future__ import annotations
+
+import click
+
+from usage_spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices, render_kdl, validate_kdl, render_json, generate as core_generate
+
+from .convert import convert_root
+
+__all__ = [
+    "convert_root",
+    "generate",
+    "generate_kdl",
+    "generate_json",
+    "render_kdl",
+    "Spec",
+    "SpecArg",
+    "SpecFlag",
+    "SpecCommand",
+    "SpecChoices",
+]
+
+
+def generate(cmd: click.BaseCommand, bin_name: str | None = None) -> str:
+    """Generate usage spec in KDL format from a click Command/Group."""
+    spec = convert_root(cmd, bin_name)
+    return core_generate(spec, format="kdl", comment="@generated by usage-spec-click from click metadata")
+
+
+def generate_kdl(cmd: click.BaseCommand, bin_name: str | None = None) -> str:
+    """Generate usage spec in KDL format (alias for generate)."""
+    return generate(cmd, bin_name)
+
+
+def generate_json(cmd: click.BaseCommand, bin_name: str | None = None) -> str:
+    """Generate usage spec in JSON format from a click Command/Group."""
+    spec = convert_root(cmd, bin_name)
+    return core_generate(spec, format="json")

usage_spec_click-1.0.0/src/click_usage/convert.py

@@ -0,0 +1,216 @@
+"""Convert click commands to usage spec."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+from usage_spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices
+
+
+def _convert_arg(arg: click.Argument) -> SpecArg:
+    variadic = arg.nargs == -1
+    required = arg.required
+
+    from enum import Enum
+    _has_real_default = arg.default is not None and not isinstance(arg.default, Enum)
+
+    result = SpecArg(
+        name=arg.name or arg.human_readable_name.lower(),
+        help=getattr(arg, "help", "") or "",
+        required=required,
+        var=variadic,
+        hide=getattr(arg, "hidden", False),
+        default=[str(arg.default)] if _has_real_default else [],
+        choices=None,
+    )
+
+    if isinstance(arg.type, click.Choice):
+        result.choices = SpecChoices(values=list(arg.type.choices))
+
+    return result
+
+
+def _extract_short_long(opts: list[str]) -> tuple[str, str]:
+    short = ""
+    long = ""
+    for opt in opts:
+        if opt.startswith("--"):
+            long = opt[2:]
+        elif opt.startswith("-"):
+            short = opt[1:]
+    return short, long
+
+
+def _convert_flag(opt: click.Option) -> SpecFlag:
+    short, long = _extract_short_long(opt.opts)
+
+    is_bool = opt.is_bool_flag or (opt.is_flag and not opt.multiple and not opt.count)
+
+    # Detect negation from secondary opts (--flag/--no-flag pattern)
+    negate = ""
+    if opt.secondary_opts:
+        for sec in opt.secondary_opts:
+            if sec.startswith("--no-"):
+                # negate points to the negative form itself
+                negate = sec
+                break
+
+    flag = SpecFlag(
+        short=short,
+        long=long,
+        help=opt.help or "",
+        help_long="",
+        required=opt.required,
+        hide=opt.hidden,
+        global_=False,
+        count=opt.count,
+        var=opt.multiple,
+        negate=negate,
+        deprecated=str(opt.deprecated) if isinstance(opt.deprecated, str) else "",
+        default=[],
+        default_bool=None,
+        env=str(opt.envvar) if isinstance(opt.envvar, str) else (opt.envvar[0] if opt.envvar and isinstance(opt.envvar, (list, tuple)) else ""),
+        arg=None,
+    )
+
+    # Non-boolean options have an argument
+    if not is_bool and not opt.count:
+        arg_name = (long or short).replace("-", "_").upper()
+        flag.arg = SpecArg(
+            name=arg_name,
+            help="",
+            required=opt.required,
+            var=opt.multiple,
+            hide=False,
+            default=[],
+            choices=None,
+        )
+
+        if isinstance(opt.type, click.Choice):
+            flag.arg.choices = SpecChoices(values=list(opt.type.choices))
+
+    # Default values - click uses Sentinel enum for unset defaults
+    from enum import Enum
+    _has_real_default = opt.default is not None and not isinstance(opt.default, Enum)
+
+    if _has_real_default and not (is_bool and opt.default is False):
+        if is_bool or opt.count:
+            if opt.default is True:
+                flag.default_bool = True
+        else:
+            flag.default = [str(opt.default)]
+
+    return flag
+
+
+def _convert_command(cmd: click.BaseCommand) -> SpecCommand:
+    is_group = isinstance(cmd, click.Group)
+
+    sc = SpecCommand(
+        name=cmd.name or "",
+        help=cmd.short_help or cmd.help or "",
+        help_long=cmd.short_help and cmd.help and cmd.help or "",
+        hide=cmd.hidden,
+        deprecated=str(cmd.deprecated) if isinstance(cmd.deprecated, str) else "",
+        aliases=[],
+        subcommand_required=False,
+        flags=[],
+        args=[],
+        cmds=[],
+    )
+
+    for param in cmd.params:
+        if isinstance(param, click.Option):
+            # Skip help and version flags
+            name = param.name or ""
+            if name in ("help", "version"):
+                continue
+            sc.flags.append(_convert_flag(param))
+        elif isinstance(param, click.Argument):
+            sc.args.append(_convert_arg(param))
+
+    # Subcommands for Groups
+    if is_group:
+        group = cmd  # type: click.Group
+        # Try eager commands dict first, then lazy loading
+        if group.commands:
+            for sub_name, sub_cmd in group.commands.items():
+                if sub_cmd.hidden:
+                    continue
+                sc.cmds.append(_convert_command(sub_cmd))
+        else:
+            # Lazy loading via list_commands + get_command
+            ctx = click.Context(cmd)
+            for sub_name in group.list_commands(ctx):
+                sub_cmd = group.get_command(ctx, sub_name)
+                if sub_cmd and not sub_cmd.hidden:
+                    sc.cmds.append(_convert_command(sub_cmd))
+
+        # subcommand_required: group with no positional args
+        if sc.cmds and not sc.args:
+            sc.subcommand_required = True
+
+    return sc
+
+
+def _extract_version_from_callback(opt: click.Option) -> str:
+    """Extract version string from click.version_option callback closure."""
+    cb = opt.callback
+    if not cb or not cb.__closure__:
+        return ""
+    for cell in cb.__closure__:
+        val = cell.cell_contents
+        if isinstance(val, str) and val and val[0].isdigit():
+            return val
+    return ""
+
+
+def convert_root(cmd: click.BaseCommand, bin_name: str | None = None) -> Spec:
+    """Convert a click Command or Group to a Spec object."""
+    name = bin_name or cmd.name or ""
+
+    spec = Spec(
+        name=name,
+        bin=name,
+        version="",
+        about=cmd.short_help or cmd.help or "",
+        long=cmd.short_help and cmd.help and cmd.help or "",
+        usage="",
+        flags=[],
+        args=[],
+        cmds=[],
+    )
+
+    for param in cmd.params:
+        if isinstance(param, click.Option):
+            pname = param.name or ""
+            # Version flag detection
+            if pname == "version":
+                version = _extract_version_from_callback(param)
+                if version:
+                    spec.version = version
+                continue
+            if pname == "help":
+                continue
+            spec.flags.append(_convert_flag(param))
+        elif isinstance(param, click.Argument):
+            spec.args.append(_convert_arg(param))
+
+    # Subcommands
+    is_group = isinstance(cmd, click.Group)
+    if is_group:
+        group = cmd  # type: click.Group
+        if group.commands:
+            for sub_name, sub_cmd in group.commands.items():
+                if sub_cmd.hidden:
+                    continue
+                spec.cmds.append(_convert_command(sub_cmd))
+        else:
+            ctx = click.Context(cmd)
+            for sub_name in group.list_commands(ctx):
+                sub_cmd = group.get_command(ctx, sub_name)
+                if sub_cmd and not sub_cmd.hidden:
+                    spec.cmds.append(_convert_command(sub_cmd))
+
+    return spec

usage_spec_click-1.0.0/tests/test_click.py

@@ -0,0 +1,813 @@
+"""Tests for click usage spec integration."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import click
+from click_usage import generate, generate_kdl, generate_json, convert_root
+from usage_spec import validate_kdl
+
+
+class TestSimpleCommand:
+    def test_generates_spec_for_basic_cli(self):
+        @click.command()
+        @click.option("-v", "--verbose", is_flag=True, help="Enable verbose output")
+        @click.option("-c", "--config", type=str, help="Config file path")
+        def cli(verbose, config):
+            pass
+
+        output = generate(cli, "mycli")
+
+        assert "name mycli" in output
+        assert "bin mycli" in output
+        assert 'flag "-v --verbose"' in output
+        assert 'help="Enable verbose output"' in output
+        assert 'flag "-c --config"' in output
+        assert 'help="Config file path"' in output
+
+    def test_includes_generated_comment_header(self):
+        @click.command()
+        def cli():
+            pass
+
+        output = generate(cli)
+        assert "// @generated by usage-spec-click from click metadata" in output
+
+    def test_uses_custom_bin_name(self):
+        @click.command()
+        def cli():
+            pass
+
+        output = generate(cli, "my-app")
+        assert "bin my-app" in output
+
+
+class TestVersion:
+    def test_extracts_version_from_version_option(self):
+        @click.command()
+        @click.version_option("2.0.0")
+        def cli():
+            pass
+
+        spec = convert_root(cli)
+        assert spec.version == "2.0.0"
+
+    def test_skips_version_field_when_not_set(self):
+        @click.command()
+        def cli():
+            pass
+
+        output = generate(cli)
+        assert "version " not in output
+
+
+class TestAboutDescription:
+    def test_extracts_short_help_as_about(self):
+        @click.command(short_help="A simple CLI tool")
+        def cli():
+            pass
+
+        spec = convert_root(cli)
+        assert spec.about == "A simple CLI tool"
+
+    def test_extracts_help_as_about_when_no_short_help(self):
+        @click.command(help="Just a description")
+        def cli():
+            pass
+
+        spec = convert_root(cli)
+        assert spec.about == "Just a description"
+
+    def test_sets_long_when_both_help_and_short_help(self):
+        @click.command(short_help="Short help", help="This is a much longer description of the app.")
+        def cli():
+            pass
+
+        spec = convert_root(cli)
+        assert spec.about == "Short help"
+        assert spec.long == "This is a much longer description of the app."
+
+
+class TestNestedSubcommands:
+    def test_renders_subcommands_recursively(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.group()
+        def sub():
+            """A subcommand"""
+
+        @sub.command()
+        def nested():
+            """A nested command"""
+
+        output = generate(cli)
+
+        assert "cmd sub" in output
+        assert "cmd nested" in output
+
+    def test_renders_deeply_nested_command_structure(self):
+        @click.group()
+        def cli():
+            """My application"""
+
+        @cli.group()
+        def db():
+            """Database operations"""
+
+        @db.group()
+        def migrate():
+            """Run migrations"""
+
+        @migrate.command()
+        def up():
+            """Apply migrations"""
+
+        @migrate.command()
+        def down():
+            """Rollback migrations"""
+
+        output = generate(cli)
+
+        assert "cmd db" in output
+        assert "cmd migrate" in output
+        assert "cmd up" in output
+        assert "cmd down" in output
+
+
+class TestOptions:
+    def test_renders_short_and_long_flags(self):
+        @click.command()
+        @click.option("-v", "--verbose", is_flag=True, help="Be verbose")
+        @click.option("-o", "--output", type=str, help="Output dir")
+        def cli(verbose, output):
+            pass
+
+        output = generate(cli)
+
+        assert 'flag "-v --verbose"' in output
+        assert 'flag "-o --output"' in output
+
+    def test_marks_required_options(self):
+        @click.command()
+        @click.option("--env", required=True, help="Target environment")
+        def cli(env):
+            pass
+
+        output = generate(cli)
+
+        assert "required=#true" in output
+
+    def test_renders_default_values(self):
+        @click.command()
+        @click.option("--format", default="json", help="Output format")
+        def cli(format):
+            pass
+
+        spec = convert_root(cli)
+        format_flag = next(f for f in spec.flags if f.long == "format")
+        assert format_flag.default == ["json"]
+
+    def test_preserves_string_zero_as_default(self):
+        @click.command()
+        @click.option("--port", default="0", type=str, help="Port number")
+        def cli(port):
+            pass
+
+        output = generate(cli)
+        assert "default=0" in output
+
+    def test_renders_boolean_default_true(self):
+        @click.command()
+        @click.option("--color", is_flag=True, default=True, help="Enable color")
+        def cli(color):
+            pass
+
+        spec = convert_root(cli)
+        color_flag = next(f for f in spec.flags if f.long == "color")
+        assert color_flag.default_bool is True
+
+    def test_skips_false_default_for_boolean_flags(self):
+        @click.command()
+        @click.option("--force", is_flag=True, default=False, help="Force the operation")
+        def cli(force):
+            pass
+
+        spec = convert_root(cli)
+        force_flag = next(f for f in spec.flags if f.long == "force")
+        assert force_flag.default == []
+        assert force_flag.default_bool is None
+
+    def test_renders_choices(self):
+        @click.command()
+        @click.option("--format", type=click.Choice(["json", "yaml", "toml"]), help="Output format")
+        def cli(format):
+            pass
+
+        spec = convert_root(cli)
+        format_flag = next(f for f in spec.flags if f.long == "format")
+        assert format_flag.arg is not None
+        assert format_flag.arg.choices is not None
+        assert format_flag.arg.choices.values == ["json", "yaml", "toml"]
+
+    def test_hides_hidden_options(self):
+        @click.command()
+        @click.option("--secret", type=str, help="Secret option", hidden=True)
+        def cli(secret):
+            pass
+
+        spec = convert_root(cli)
+        secret_flag = next(f for f in spec.flags if f.long == "secret")
+        assert secret_flag.hide is True
+
+    def test_handles_count_options(self):
+        @click.command()
+        @click.option("-v", "--verbose", count=True, help="Verbosity level")
+        def cli(verbose):
+            pass
+
+        spec = convert_root(cli)
+        verbose_flag = next(f for f in spec.flags if f.long == "verbose")
+        assert verbose_flag.count is True
+
+    def test_handles_multiple_options(self):
+        @click.command()
+        @click.option("--include", type=str, multiple=True, help="Include patterns")
+        def cli(include):
+            pass
+
+        spec = convert_root(cli)
+        include_flag = next(f for f in spec.flags if f.long == "include")
+        assert include_flag.var is True
+        assert include_flag.arg is not None
+        assert include_flag.arg.var is True
+
+    def test_renders_deprecated_options(self):
+        @click.command()
+        @click.option("--old-flag", type=str, help="Old flag", deprecated="Use --new-flag instead")
+        def cli(old_flag):
+            pass
+
+        spec = convert_root(cli)
+        old_flag = next(f for f in spec.flags if f.long == "old-flag")
+        assert old_flag.deprecated == "Use --new-flag instead"
+
+    def test_renders_long_only_flags(self):
+        @click.command()
+        @click.option("--verbose", is_flag=True, help="Be verbose")
+        def cli(verbose):
+            pass
+
+        output = generate(cli)
+        assert "flag --verbose" in output
+
+    def test_renders_short_only_flags(self):
+        @click.command()
+        @click.option("-v", is_flag=True, help="Be verbose")
+        def cli(verbose):
+            pass
+
+        output = generate(cli)
+        assert "flag -v" in output
+
+
+class TestBooleanFlags:
+    def test_does_not_render_arg_for_boolean_flags(self):
+        @click.command()
+        @click.option("--force", is_flag=True, help="Force the operation")
+        def cli(force):
+            pass
+
+        spec = convert_root(cli)
+        force_flag = next(f for f in spec.flags if f.long == "force")
+        assert force_flag.arg is None
+
+
+class TestNegatedOptions:
+    def test_renders_negate_for_toggle_flags(self):
+        @click.command()
+        @click.option("--color/--no-color", default=False, help="Color output")
+        def cli(color):
+            pass
+
+        spec = convert_root(cli)
+        color_flag = next(f for f in spec.flags if f.long == "color")
+        assert color_flag.negate == "--no-color"
+
+    def test_negated_boolean_options_do_not_have_arg(self):
+        @click.command()
+        @click.option("--color/--no-color", default=False, help="Color output")
+        def cli(color):
+            pass
+
+        spec = convert_root(cli)
+        color_flag = next(f for f in spec.flags if f.long == "color")
+        assert color_flag.arg is None
+
+
+class TestEnvironmentVariables:
+    def test_renders_env_for_options_with_envvar(self):
+        @click.command()
+        @click.option("--color", type=str, help="Color output", envvar="MYCLI_COLOR")
+        def cli(color):
+            pass
+
+        spec = convert_root(cli)
+        color_flag = next(f for f in spec.flags if f.long == "color")
+        assert color_flag.env == "MYCLI_COLOR"
+
+    def test_has_no_env_when_envvar_not_set(self):
+        @click.command()
+        @click.option("--color", type=str, help="Color output")
+        def cli(color):
+            pass
+
+        spec = convert_root(cli)
+        color_flag = next(f for f in spec.flags if f.long == "color")
+        assert color_flag.env == ""
+
+
+class TestSkipsBuiltinFlags:
+    def test_does_not_render_help_flag(self):
+        @click.command()
+        @click.option("--custom", type=str, help="A custom flag")
+        def cli(custom):
+            pass
+
+        spec = convert_root(cli)
+        flag_names = [f.long for f in spec.flags]
+        assert "help" not in flag_names
+        assert "custom" in flag_names
+
+
+class TestPositionalArguments:
+    def test_converts_required_arguments(self):
+        @click.command()
+        @click.argument("file")
+        def cli(file):
+            pass
+
+        output = generate(cli)
+        assert "arg <file>" in output
+
+    def test_converts_optional_arguments(self):
+        @click.command()
+        @click.argument("name", required=False)
+        def cli(name):
+            pass
+
+        output = generate(cli)
+        assert "arg [name]" in output
+
+    def test_converts_variadic_arguments(self):
+        @click.command()
+        @click.argument("files", nargs=-1)
+        def cli(files):
+            pass
+
+        spec = convert_root(cli)
+        files_arg = next(a for a in spec.args if a.name == "files")
+        assert files_arg.var is True
+
+    def test_converts_mixed_required_and_optional_args(self):
+        @click.command()
+        @click.argument("source")
+        @click.argument("dest", required=False)
+        def cli(source, dest):
+            pass
+
+        spec = convert_root(cli)
+        assert spec.args[0].name == "source"
+        assert spec.args[0].required is True
+        assert spec.args[1].name == "dest"
+        assert spec.args[1].required is False
+
+    def test_converts_choices_on_arguments(self):
+        @click.command()
+        @click.argument("env", type=click.Choice(["dev", "staging", "prod"]))
+        def cli(env):
+            pass
+
+        spec = convert_root(cli)
+        env_arg = next(a for a in spec.args if a.name == "env")
+        assert env_arg.choices is not None
+        assert env_arg.choices.values == ["dev", "staging", "prod"]
+
+    def test_converts_default_on_arguments(self):
+        @click.command()
+        @click.argument("file", default="input.txt")
+        def cli(file):
+            pass
+
+        spec = convert_root(cli)
+        file_arg = next(a for a in spec.args if a.name == "file")
+        assert file_arg.default == ["input.txt"]
+
+
+class TestCommands:
+    def test_renders_subcommands(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.command()
+        def add():
+            """Add a file"""
+
+        @cli.command()
+        def remove():
+            """Remove files"""
+
+        output = generate(cli)
+
+        assert "cmd add" in output
+        assert "cmd remove" in output
+
+    def test_handles_hidden_commands(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.command(hidden=True)
+        def secret():
+            """Secret command"""
+
+        spec = convert_root(cli)
+        assert len(spec.cmds) == 0
+
+    def test_renders_command_with_multiple_flags(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.command()
+        @click.option("-o", "--output", type=str, help="Output directory")
+        @click.option("--minify", is_flag=True, help="Minify output")
+        @click.option("--watch", is_flag=True, help="Watch for changes")
+        def build(output, minify, watch):
+            """Build the project"""
+
+        spec = convert_root(cli)
+        build_cmd = next(c for c in spec.cmds if c.name == "build")
+        assert build_cmd is not None
+        assert len(build_cmd.flags) == 3
+        flag_longs = [f.long for f in build_cmd.flags]
+        assert "output" in flag_longs
+        assert "minify" in flag_longs
+        assert "watch" in flag_longs
+
+    def test_renders_command_aliases(self):
+        @click.group()
+        def cli():
+            pass
+
+        # Standard click doesn't natively support command aliases,
+        # but custom Group implementations may provide them via an `aliases` attribute.
+        # For the standard click case, commands simply have no aliases.
+        @cli.command()
+        def install():
+            """Install packages"""
+
+        spec = convert_root(cli)
+        install_cmd = next(c for c in spec.cmds if c.name == "install")
+        assert install_cmd.aliases == []
+
+    def test_renders_subcommand_with_summary_and_description(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.command(short_help="Brief", help="Detailed explanation")
+        def sub():
+            pass
+
+        spec = convert_root(cli)
+        sub_cmd = next(c for c in spec.cmds if c.name == "sub")
+        assert sub_cmd.help == "Brief"
+        assert sub_cmd.help_long == "Detailed explanation"
+
+
+class TestSubcommandRequired:
+    def test_sets_subcommand_required_for_non_runnable_groups(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.group()
+        def config():
+            """Manage config"""
+
+        @config.command()
+        def get():
+            """Get a value"""
+
+        @config.command()
+        def set_():
+            """Set a value"""
+
+        output = generate(cli)
+
+        # config subcommand has subcommands but no positional args
+        assert "subcommand_required=#true" in output
+
+    def test_does_not_set_subcommand_required_for_leaf_commands(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.command()
+        def start():
+            """Start"""
+
+        spec = convert_root(cli)
+        start_cmd = next(c for c in spec.cmds if c.name == "start")
+        assert not start_cmd.cmds  # leaf has no subcommands
+        assert start_cmd.subcommand_required is False
+
+
+class TestLongHelp:
+    def test_renders_long_about_for_command_with_short_and_long_help(self):
+        @click.command(short_help="Short help", help="This is a much longer description of the app.")
+        def cli():
+            pass
+
+        output = generate(cli)
+        assert 'about "Short help"' in output
+        assert "long_about" in output
+
+    def test_uses_description_as_about_when_no_short_help(self):
+        @click.command(help="Just a description")
+        def cli():
+            pass
+
+        spec = convert_root(cli)
+        assert spec.about == "Just a description"
+        assert spec.long == ""
+
+
+class TestSpecialCharacterEscaping:
+    def test_handles_special_chars_in_flag_help(self):
+        @click.command()
+        @click.option("--format", type=str, help="Output format:\n  json\n  yaml")
+        def cli(format):
+            pass
+
+        output = generate(cli)
+        assert "help=" in output
+        kdl_content = output.split("\n", 1)[1] if output.startswith("//") else output
+        validate_kdl(kdl_content)
+
+    def test_handles_newlines_in_command_help(self):
+        @click.command(short_help="Short", help="First line.\nSecond line.\n\nThird paragraph.")
+        def cli():
+            pass
+
+        output = generate(cli)
+        assert "long_about" in output
+        kdl_content = output.split("\n", 1)[1] if output.startswith("//") else output
+        validate_kdl(kdl_content)
+
+
+class TestKDLRoundTrip:
+    def test_generates_valid_kdl_for_basic_command(self):
+        @click.command()
+        @click.option("-v", "--verbose", is_flag=True, help="Be verbose")
+        @click.option("-f", "--file", type=str, help="Input file")
+        def cli(verbose, file):
+            pass
+
+        output = generate(cli)
+        kdl_content = output.split("\n", 1)[1] if output.startswith("//") else output
+        validate_kdl(kdl_content)
+
+    def test_generates_valid_kdl_for_nested_commands(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.group()
+        def config():
+            """Config"""
+
+        @config.command()
+        def get():
+            """Get value"""
+
+        output = generate(cli)
+        kdl_content = output.split("\n", 1)[1] if output.startswith("//") else output
+        validate_kdl(kdl_content)
+
+    def test_generates_valid_kdl_for_command_with_flags_and_args(self):
+        @click.command()
+        @click.option("-v", "--verbose", is_flag=True, help="Be verbose")
+        @click.argument("file")
+        def cli(verbose, file):
+            pass
+
+        output = generate(cli)
+        kdl_content = output.split("\n", 1)[1] if output.startswith("//") else output
+        validate_kdl(kdl_content)
+
+
+class TestGenerateKDL:
+    def test_is_alias_for_generate(self):
+        @click.command()
+        def cli():
+            """A CLI"""
+
+        assert generate_kdl(cli) == generate(cli)
+
+
+class TestConvertRoot:
+    def test_returns_spec_with_correct_structure(self):
+        @click.command()
+        @click.version_option("2.0.0")
+        @click.option("--verbose", is_flag=True, help="Be verbose")
+        def cli(verbose):
+            """A CLI tool"""
+
+        spec = convert_root(cli, "mycli")
+
+        assert spec.name == "mycli"
+        assert spec.bin == "mycli"
+        assert spec.version == "2.0.0"
+        assert spec.about == "A CLI tool"
+        assert len(spec.flags) == 1
+        assert spec.flags[0].long == "verbose"
+
+    def test_includes_arguments_in_spec(self):
+        @click.command()
+        @click.argument("file")
+        @click.argument("output", required=False)
+        def cli(file, output):
+            pass
+
+        spec = convert_root(cli)
+
+        assert len(spec.args) == 2
+        assert spec.args[0].name == "file"
+        assert spec.args[0].required is True
+        assert spec.args[1].name == "output"
+        assert spec.args[1].required is False
+
+
+class TestJSONOutput:
+    def test_generates_json_output_with_correct_structure(self):
+        @click.group()
+        @click.version_option("2.0.0")
+        @click.option("--verbose", is_flag=True, help="Be verbose")
+        def cli(verbose):
+            """A CLI tool"""
+
+        @cli.command()
+        def run():
+            """Run something"""
+
+        j = generate_json(cli, "mycli")
+        parsed = json.loads(j)
+
+        assert parsed["name"] == "mycli"
+        assert parsed["version"] == "2.0.0"
+        assert parsed["about"] == "A CLI tool"
+        assert len(parsed["flags"]) == 1
+        assert len(parsed["cmds"]) == 1
+        assert parsed["cmds"][0]["name"] == "run"
+
+    def test_includes_choices_in_json_output(self):
+        @click.command()
+        @click.option("--env", type=click.Choice(["dev", "prod"]), help="Environment")
+        def cli(env):
+            pass
+
+        j = generate_json(cli)
+        parsed = json.loads(j)
+
+        assert parsed["flags"][0]["arg"]["choices"] == ["dev", "prod"]
+
+    def test_includes_flag_details_in_json(self):
+        @click.command()
+        @click.option("--env", required=True, help="Target environment")
+        @click.option("--color/--no-color", default=False, help="Color output")
+        def cli(env, color):
+            pass
+
+        j = generate_json(cli)
+        parsed = json.loads(j)
+
+        assert len(parsed["flags"]) == 2
+        env_flag = next(f for f in parsed["flags"] if f["name"] == "--env")
+        assert env_flag["required"] is True
+        assert env_flag["arg"] is not None
+
+        color_flag = next(f for f in parsed["flags"] if f["name"] == "--color")
+        assert color_flag["negate"] == "--no-color"
+
+    def test_includes_args_in_json_output(self):
+        @click.command()
+        @click.argument("file")
+        @click.argument("output", required=False)
+        def cli(file, output):
+            pass
+
+        j = generate_json(cli)
+        parsed = json.loads(j)
+
+        assert len(parsed["args"]) == 2
+        assert parsed["args"][0]["name"] == "file"
+        # required=true is default, omitted from JSON
+        assert "required" not in parsed["args"][0]
+        assert parsed["args"][1]["name"] == "output"
+        assert parsed["args"][1]["required"] is False
+
+    def test_handles_custom_bin_name_in_json(self):
+        @click.command()
+        @click.option("--verbose", is_flag=True, help="Be verbose")
+        def cli(verbose):
+            """A tool"""
+
+        j = generate_json(cli, "my-tool")
+        parsed = json.loads(j)
+
+        assert parsed["bin"] == "my-tool"
+
+
+class TestEdgeCases:
+    def test_handles_empty_command_with_no_options_or_args(self):
+        @click.command()
+        def cli():
+            pass
+
+        output = generate(cli)
+        assert "flag" not in output
+        assert "arg " not in output
+        assert "cmd" not in output
+
+    def test_handles_command_with_only_subcommands(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.command()
+        def start():
+            """Start"""
+
+        @cli.command()
+        def stop():
+            """Stop"""
+
+        output = generate(cli)
+
+        assert "cmd start" in output
+        assert "cmd stop" in output
+
+    def test_handles_deeply_nested_command_structure(self):
+        @click.group()
+        def cli():
+            """My application"""
+
+        @cli.group()
+        def db():
+            """Database operations"""
+
+        @db.group()
+        def migrate():
+            """Run migrations"""
+
+        @migrate.command()
+        def up():
+            """Apply migrations"""
+
+        @migrate.command()
+        def down():
+            """Rollback migrations"""
+
+        output = generate(cli)
+
+        assert "cmd db" in output
+        assert 'help="Database operations"' in output
+        assert "cmd migrate" in output
+        assert 'help="Run migrations"' in output
+        assert "cmd up" in output
+        assert "cmd down" in output
+
+
+class TestFullOutputFormat:
+    def test_matches_expected_kdl_output(self):
+        @click.command()
+        @click.version_option("1.0.0")
+        @click.option("-f", "--file", type=str, help="Some input file")
+        @click.option("--verbose", is_flag=True, help="Enable verbose output")
+        def cli(file, verbose):
+            """An example CLI"""
+
+        output = generate(cli, "example")
+
+        assert "name example" in output
+        assert "bin example" in output
+        assert "version 1.0.0" in output
+        assert 'about "An example CLI"' in output
+        assert 'flag "-f --file"' in output
+        assert "flag --verbose" in output