usage-spec-argparse 1.0.0__tar.gz

usage_spec_argparse-1.0.0/.gitignore

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

usage_spec_argparse-1.0.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: usage-spec-argparse
+Version: 1.0.0
+Summary: Generates usage spec for CLIs written with argparse
+License-Expression: MIT
+Keywords: argparse,cli,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: usage-spec
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# usage-spec-argparse
+
+Generates [usage spec](https://usage.jdx.dev) for CLIs written with [argparse](https://docs.python.org/3/library/argparse.html).
+
+## Install
+
+```sh
+pip install usage-spec-argparse
+```
+
+## Usage
+
+```python
+import argparse
+from argparse_usage import generate
+
+parser = argparse.ArgumentParser(prog="mycli", description="My CLI tool")
+parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose output")
+parser.add_argument("-f", "--file", help="Input file")
+parser.add_argument("--no-color", action="store_false", help="Disable colored output")
+
+print(generate(parser))
+```
+
+## API
+
+### `generate(parser, bin_name=None)`
+
+Generates a usage spec in KDL format from an `argparse.ArgumentParser`.
+
+### `generate_kdl(parser, bin_name=None)`
+
+Alias for `generate()`.
+
+### `generate_json(parser, bin_name=None)`
+
+Generates a usage spec in JSON format.
+
+### `convert_root(parser, bin_name=None)`
+
+Converts an `argparse.ArgumentParser` to the `Spec` data structure.
+
+## Supported Features
+
+| argparse Feature | Usage Spec Mapping |
+|---|---|
+| `prog` | `name` / `bin` |
+| `--version` action | `version` |
+| `description` | `about` |
+| `epilog` | `long_about` |
+| `add_argument()` (optional) | `flag` |
+| `add_argument()` (positional) | `arg` |
+| `required=True` | `flag required=#true` |
+| `action="store_true"/"store_false"` | Boolean flag (no arg) |
+| `action="store_false"` | `negate` |
+| `action="count"` | `count=#true` |
+| `nargs="?"` | `required=#false` |
+| `nargs="*"/"+"` | `var=#true` |
+| `choices=[...]` | `choices` |
+| `default=...` | `default` |
+| `help=SUPPRESS` | `hide=#true` |
+| `add_subparsers()` | `cmd` (recursive) |
+| Non-runnable subcommand groups | `subcommand_required=#true` |
+
+## License
+
+MIT

usage_spec_argparse-1.0.0/README.md

@@ -0,0 +1,67 @@
+# usage-spec-argparse
+
+Generates [usage spec](https://usage.jdx.dev) for CLIs written with [argparse](https://docs.python.org/3/library/argparse.html).
+
+## Install
+
+```sh
+pip install usage-spec-argparse
+```
+
+## Usage
+
+```python
+import argparse
+from argparse_usage import generate
+
+parser = argparse.ArgumentParser(prog="mycli", description="My CLI tool")
+parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose output")
+parser.add_argument("-f", "--file", help="Input file")
+parser.add_argument("--no-color", action="store_false", help="Disable colored output")
+
+print(generate(parser))
+```
+
+## API
+
+### `generate(parser, bin_name=None)`
+
+Generates a usage spec in KDL format from an `argparse.ArgumentParser`.
+
+### `generate_kdl(parser, bin_name=None)`
+
+Alias for `generate()`.
+
+### `generate_json(parser, bin_name=None)`
+
+Generates a usage spec in JSON format.
+
+### `convert_root(parser, bin_name=None)`
+
+Converts an `argparse.ArgumentParser` to the `Spec` data structure.
+
+## Supported Features
+
+| argparse Feature | Usage Spec Mapping |
+|---|---|
+| `prog` | `name` / `bin` |
+| `--version` action | `version` |
+| `description` | `about` |
+| `epilog` | `long_about` |
+| `add_argument()` (optional) | `flag` |
+| `add_argument()` (positional) | `arg` |
+| `required=True` | `flag required=#true` |
+| `action="store_true"/"store_false"` | Boolean flag (no arg) |
+| `action="store_false"` | `negate` |
+| `action="count"` | `count=#true` |
+| `nargs="?"` | `required=#false` |
+| `nargs="*"/"+"` | `var=#true` |
+| `choices=[...]` | `choices` |
+| `default=...` | `default` |
+| `help=SUPPRESS` | `hide=#true` |
+| `add_subparsers()` | `cmd` (recursive) |
+| Non-runnable subcommand groups | `subcommand_required=#true` |
+
+## License
+
+MIT

usage_spec_argparse-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "usage-spec-argparse"
+version = "1.0.0"
+description = "Generates usage spec for CLIs written with argparse"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+keywords = ["argparse", "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"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/argparse_usage"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

usage_spec_argparse-1.0.0/src/argparse_usage/__init__.py

@@ -0,0 +1,39 @@
+"""Usage spec integration for argparse."""
+
+from __future__ import annotations
+
+import argparse
+
+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(parser: argparse.ArgumentParser, bin_name: str | None = None) -> str:
+    """Generate usage spec in KDL format from an argparse.ArgumentParser."""
+    spec = convert_root(parser, bin_name)
+    return core_generate(spec, format="kdl", comment="@generated by usage-spec-argparse from argparse metadata")
+
+
+def generate_kdl(parser: argparse.ArgumentParser, bin_name: str | None = None) -> str:
+    """Generate usage spec in KDL format (alias for generate)."""
+    return generate(parser, bin_name)
+
+
+def generate_json(parser: argparse.ArgumentParser, bin_name: str | None = None) -> str:
+    """Generate usage spec in JSON format from an argparse.ArgumentParser."""
+    spec = convert_root(parser, bin_name)
+    return core_generate(spec, format="json")

usage_spec_argparse-1.0.0/src/argparse_usage/convert.py

@@ -0,0 +1,226 @@
+"""Convert argparse.ArgumentParser to usage spec."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from usage_spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices
+
+# Action class names that represent boolean flags
+_BOOL_ACTION_NAMES = frozenset({
+    "_StoreTrueAction",
+    "_StoreFalseAction",
+})
+
+# Action class names that represent count flags
+_COUNT_ACTION_NAMES = frozenset({
+    "_CountAction",
+})
+
+# Action class names for subparsers
+_SUBPARSERS_ACTION_NAMES = frozenset({
+    "_SubParsersAction",
+    "SubParsersAction",
+})
+
+# Built-in flag names to skip
+_BUILTIN_FLAG_NAMES = frozenset({"help", "version"})
+
+
+def _is_bool_action(action: argparse.Action) -> bool:
+    return type(action).__name__ in _BOOL_ACTION_NAMES
+
+
+def _is_count_action(action: argparse.Action) -> bool:
+    return type(action).__name__ in _COUNT_ACTION_NAMES
+
+
+def _is_subparsers_action(action: argparse.Action) -> bool:
+    return type(action).__name__ in _SUBPARSERS_ACTION_NAMES
+
+
+def _is_optional(action: argparse.Action) -> bool:
+    return bool(action.option_strings)
+
+
+def _extract_short_long(option_strings: list[str]) -> tuple[str, str]:
+    short = ""
+    long = ""
+    for opt in option_strings:
+        if opt.startswith("--"):
+            long = opt[2:]
+        elif opt.startswith("-"):
+            short = opt[1:]
+    return short, long
+
+
+def _convert_arg(action: argparse.Action) -> SpecArg:
+    nargs = action.nargs
+    # Use argparse's own 'required' attribute for positional args
+    required = getattr(action, "required", True)
+    # Variadic: nargs is '*' or '+' or argparse.REMAINDER
+    variadic = nargs in ("*", "+", argparse.REMAINDER) if nargs else False
+
+    result = SpecArg(
+        name=action.dest or action.metavar or "",
+        help=action.help if action.help != argparse.SUPPRESS else "",
+        required=required,
+        var=variadic,
+        hide=action.help == argparse.SUPPRESS,
+        default=[str(action.default)] if action.default not in (None, argparse.SUPPRESS) else [],
+        choices=None,
+    )
+
+    if action.choices:
+        result.choices = SpecChoices(values=[str(c) for c in action.choices])
+
+    return result
+
+
+def _convert_flag(action: argparse.Action) -> SpecFlag:
+    short, long = _extract_short_long(action.option_strings)
+    is_bool = _is_bool_action(action)
+    is_count = _is_count_action(action)
+    is_store_false = type(action).__name__ == "_StoreFalseAction"
+
+    flag = SpecFlag(
+        short=short,
+        long=long,
+        help=action.help if action.help != argparse.SUPPRESS else "",
+        help_long="",
+        required=bool(action.required) if hasattr(action, "required") else False,
+        hide=action.help == argparse.SUPPRESS,
+        global_=False,
+        count=is_count,
+        var=bool(action.nargs and action.nargs in ("*", "+")),
+        negate=f"--{long}" if is_store_false else "",
+        deprecated="",
+        default=[],
+        default_bool=None,
+        env="",
+        arg=None,
+    )
+
+    # Non-boolean, non-count options have an argument
+    if not is_bool and not is_count:
+        arg_name = (long or short).replace("-", "_").upper()
+        flag.arg = SpecArg(
+            name=arg_name,
+            help="",
+            required=flag.required,
+            var=flag.var,
+            hide=False,
+            default=[],
+            choices=None,
+        )
+
+        if action.choices:
+            flag.arg.choices = SpecChoices(values=[str(c) for c in action.choices])
+
+    # Default values
+    if action.default not in (None, argparse.SUPPRESS, True, False):
+        if is_bool or is_count:
+            pass  # skip for booleans
+        else:
+            flag.default = [str(action.default)]
+    elif action.default is True:
+        flag.default_bool = True
+    # False defaults are omitted for booleans
+
+    return flag
+
+
+def _get_subcommand_helps(parser: argparse.ArgumentParser) -> dict[str, str]:
+    """Extract help texts from subparsers' _choices_actions."""
+    helps: dict[str, str] = {}
+    for action in parser._actions:
+        if _is_subparsers_action(action) and hasattr(action, "_choices_actions"):
+            for ca in action._choices_actions:
+                if ca.dest and ca.help:
+                    helps[ca.dest] = ca.help
+    return helps
+
+
+def _convert_command(parser: argparse.ArgumentParser, help_override: str = "") -> SpecCommand:
+    name = parser.prog
+    # Strip parent prefix from name (e.g. "app sub" -> "sub")
+    if " " in name:
+        name = name.rsplit(" ", 1)[-1]
+
+    # Use help_override from _choices_actions if available, otherwise description
+    cmd_help = help_override or parser.description or ""
+
+    sc = SpecCommand(
+        name=name,
+        help=cmd_help,
+        help_long="",
+        hide=False,
+        deprecated="",
+        aliases=[],
+        subcommand_required=False,
+        flags=[],
+        args=[],
+        cmds=[],
+    )
+
+    sub_helps = _get_subcommand_helps(parser)
+
+    for action in parser._actions:
+        if _is_optional(action):
+            action_name = _extract_short_long(action.option_strings)[1] or _extract_short_long(action.option_strings)[0]
+            if action_name in _BUILTIN_FLAG_NAMES:
+                continue
+            sc.flags.append(_convert_flag(action))
+        elif _is_subparsers_action(action):
+            if hasattr(action, "choices") and action.choices:
+                for sub_name, sub_parser in action.choices.items():
+                    sc.cmds.append(_convert_command(sub_parser, sub_helps.get(sub_name, "")))
+        else:
+            sc.args.append(_convert_arg(action))
+
+    # subcommand_required: has subcommands but no positional args
+    if sc.cmds and not sc.args:
+        sc.subcommand_required = True
+
+    return sc
+
+
+def convert_root(parser: argparse.ArgumentParser, bin_name: str | None = None) -> Spec:
+    """Convert an argparse.ArgumentParser to a Spec object."""
+    name = bin_name or parser.prog
+
+    spec = Spec(
+        name=name,
+        bin=name,
+        version="",
+        about=parser.description or "",
+        long=parser.epilog or "",
+        usage=parser.usage or "",
+        flags=[],
+        args=[],
+        cmds=[],
+    )
+
+    sub_helps = _get_subcommand_helps(parser)
+
+    for action in parser._actions:
+        if _is_optional(action):
+            action_name = _extract_short_long(action.option_strings)[1] or _extract_short_long(action.option_strings)[0]
+            # Extract version string before skipping
+            if action_name == "version" and hasattr(action, "version"):
+                spec.version = action.version or ""
+                continue
+            # Skip built-in flags
+            if action_name in _BUILTIN_FLAG_NAMES:
+                continue
+            spec.flags.append(_convert_flag(action))
+        elif _is_subparsers_action(action):
+            if hasattr(action, "choices") and action.choices:
+                for sub_name, sub_parser in action.choices.items():
+                    spec.cmds.append(_convert_command(sub_parser, sub_helps.get(sub_name, "")))
+        else:
+            # Positional argument
+            spec.args.append(_convert_arg(action))
+
+    return spec

usage_spec_argparse-1.0.0/tests/test_argparse.py

@@ -0,0 +1,593 @@
+"""Tests for argparse usage spec integration."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from argparse_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):
+        p = argparse.ArgumentParser(prog="mycli", description="A simple CLI")
+        p.add_argument("-v", "--verbose", action="store_true", help="Enable verbose output")
+        p.add_argument("-c", "--config", help="Config file path")
+
+        output = generate(p)
+
+        assert "name mycli" in output
+        assert "bin mycli" in output
+        assert 'about "A simple CLI"' 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):
+        p = argparse.ArgumentParser(prog="app")
+        output = generate(p)
+        assert "// @generated by usage-spec-argparse from argparse metadata" in output
+
+    def test_uses_custom_bin_name(self):
+        p = argparse.ArgumentParser(prog="app")
+        output = generate(p, "my-app")
+        assert "bin my-app" in output
+
+
+class TestVersion:
+    def test_extracts_version_string(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--version", action="version", version="2.0.0")
+        spec = convert_root(p)
+        assert spec.version == "2.0.0"
+
+    def test_skips_version_field_when_not_set(self):
+        p = argparse.ArgumentParser(prog="app")
+        output = generate(p)
+        assert "version " not in output
+
+
+class TestAboutDescription:
+    def test_extracts_description_as_about(self):
+        p = argparse.ArgumentParser(prog="app", description="A simple CLI tool")
+        spec = convert_root(p)
+        assert spec.about == "A simple CLI tool"
+
+
+class TestNestedSubcommands:
+    def test_renders_subcommands_recursively(self):
+        p = argparse.ArgumentParser(prog="app", description="An app")
+        subparsers = p.add_subparsers()
+        sub_a = subparsers.add_parser("sub", help="A subcommand")
+        sub_a_sub = sub_a.add_subparsers()
+        sub_a_sub.add_parser("nested", help="A nested command")
+
+        output = generate(p)
+
+        assert "cmd sub" in output
+        assert 'help="A subcommand"' in output
+        assert "cmd nested" in output
+        assert 'help="A nested command"' in output
+
+    def test_renders_deeply_nested_command_structure(self):
+        p = argparse.ArgumentParser(prog="myapp", description="My application")
+        sub1 = p.add_subparsers()
+        db = sub1.add_parser("db", help="Database operations")
+        sub2 = db.add_subparsers()
+        migrate = sub2.add_parser("migrate", help="Run migrations")
+        sub3 = migrate.add_subparsers()
+        sub3.add_parser("up", help="Apply migrations")
+        sub3.add_parser("down", help="Rollback migrations")
+
+        output = generate(p)
+
+        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):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("-v", "--verbose", action="store_true", help="Be verbose")
+        p.add_argument("-o", "--output", help="Output dir")
+
+        output = generate(p)
+
+        assert 'flag "-v --verbose"' in output
+        assert 'flag "-o --output"' in output
+
+    def test_marks_required_options(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--env", required=True, help="Target environment")
+
+        output = generate(p)
+
+        assert "required=#true" in output
+
+    def test_renders_default_values_for_string_options(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--format", default="json", help="Output format")
+        p.add_argument("--retries", default="3", help="Number of retries")
+
+        spec = convert_root(p)
+        format_flag = next(f for f in spec.flags if f.long == "format")
+        assert format_flag.default == ["json"]
+
+        retries_flag = next(f for f in spec.flags if f.long == "retries")
+        assert retries_flag.default == ["3"]
+
+    def test_renders_choices(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--format", choices=["json", "yaml", "toml"], help="Output format")
+
+        spec = convert_root(p)
+        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_renders_long_only_flags(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--verbose", action="store_true", help="Be verbose")
+
+        output = generate(p)
+
+        assert "flag --verbose" in output
+
+    def test_renders_short_only_flags(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("-v", action="store_true", help="Be verbose")
+
+        output = generate(p)
+
+        assert "flag -v" in output
+
+
+class TestBooleanFlags:
+    def test_does_not_render_arg_for_boolean_flags(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--force", action="store_true", help="Force the operation")
+
+        spec = convert_root(p)
+        force_flag = next(f for f in spec.flags if f.long == "force")
+        assert force_flag.arg is None
+
+    def test_renders_default_true_for_boolean_flags(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--color", action="store_true", default=True, help="Enable color")
+
+        spec = convert_root(p)
+        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):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--force", action="store_true", default=False, help="Force")
+
+        spec = convert_root(p)
+        force_flag = next(f for f in spec.flags if f.long == "force")
+        assert force_flag.default == []
+        assert force_flag.default_bool is None
+
+
+class TestNegatedOptions:
+    def test_renders_negate_for_store_false(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--no-color", action="store_false", help="Disable color output")
+
+        output = generate(p)
+
+        assert "negate=--no-color" in output
+
+    def test_negated_boolean_options_do_not_have_arg(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--no-color", action="store_false", help="Disable color output")
+
+        spec = convert_root(p)
+        color_flag = next(f for f in spec.flags if f.long == "no-color")
+        assert color_flag.negate == "--no-color"
+        assert color_flag.arg is None
+
+
+class TestEnvironmentVariables:
+    def test_no_native_env_support_in_argparse(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--color", help="Color output")
+
+        spec = convert_root(p)
+        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_and_version_flags(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--version", action="version", version="1.0.0")
+        p.add_argument("--custom", help="A custom flag")
+
+        output = generate(p)
+
+        assert "flag --help" not in output
+        assert "flag --version" not in output
+        assert "flag --custom" in output
+
+
+class TestPositionalArguments:
+    def test_converts_required_arguments(self):
+        p = argparse.ArgumentParser(prog="cmd")
+        p.add_argument("file", help="Input file")
+
+        output = generate(p)
+
+        assert "arg <file>" in output
+        assert 'help="Input file"' in output
+
+    def test_converts_optional_arguments(self):
+        p = argparse.ArgumentParser(prog="cmd")
+        p.add_argument("name", nargs="?", help="Optional name")
+
+        output = generate(p)
+
+        assert "arg [name]" in output
+        assert "required=#false" in output
+
+    def test_converts_variadic_arguments(self):
+        p = argparse.ArgumentParser(prog="cmd")
+        p.add_argument("files", nargs="+", help="Multiple files")
+
+        output = generate(p)
+
+        assert "arg <files>" in output
+        assert "var=#true" in output
+
+    def test_converts_mixed_required_and_optional_args(self):
+        p = argparse.ArgumentParser(prog="cmd")
+        p.add_argument("source", help="Source path")
+        p.add_argument("dest", nargs="?", help="Destination path")
+
+        output = generate(p)
+
+        assert "arg <source>" in output
+        assert "arg [dest]" in output
+
+
+class TestChoices:
+    def test_renders_choices_for_option_arguments(self):
+        p = argparse.ArgumentParser(prog="deploy")
+        p.add_argument("--format", choices=["json", "yaml", "toml"], help="Output format")
+
+        output = generate(p)
+
+        assert "choices" in output
+        assert "json" in output
+        assert "yaml" in output
+        assert "toml" in output
+
+    def test_renders_choices_for_positional_arguments(self):
+        p = argparse.ArgumentParser(prog="deploy")
+        p.add_argument("env", choices=["dev", "staging", "prod"], help="Environment")
+
+        output = generate(p)
+
+        assert "arg <env>" in output
+        assert "choices" in output
+        assert "dev" in output
+
+
+class TestHiddenOptions:
+    def test_hides_options_with_suppress_help(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--secret", help=argparse.SUPPRESS)
+
+        spec = convert_root(p)
+        secret_flag = next(f for f in spec.flags if f.long == "secret")
+        assert secret_flag.hide is True
+        assert secret_flag.help == ""
+
+
+class TestLongHelp:
+    def test_uses_description_as_about_when_only_description(self):
+        p = argparse.ArgumentParser(prog="app", description="Just a description")
+        spec = convert_root(p)
+        assert spec.about == "Just a description"
+        assert spec.long == ""
+
+    def test_uses_epilog_as_long_when_both_description_and_epilog(self):
+        p = argparse.ArgumentParser(
+            prog="app",
+            description="Short description",
+            epilog="This is a much longer explanation of the app.",
+        )
+        spec = convert_root(p)
+        assert spec.about == "Short description"
+        assert spec.long == "This is a much longer explanation of the app."
+
+
+class TestOptionalOptionArgument:
+    def test_renders_flag_with_optional_argument(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--cheese", nargs="?", help="Add cheese")
+
+        spec = convert_root(p)
+        cheese_flag = next(f for f in spec.flags if f.long == "cheese")
+        assert cheese_flag.arg is not None
+        assert cheese_flag.arg.required is False
+
+
+class TestSkipsBuiltinCommands:
+    def test_does_not_render_help_subcommand(self):
+        p = argparse.ArgumentParser(prog="app")
+        sub = p.add_subparsers()
+        sub.add_parser("run", help="Run something")
+
+        output = generate(p)
+        assert "cmd run" in output
+        # argparse doesn't add a "help" subcommand by default,
+        # but ensure no help-related cmd leaks
+        assert "cmd help" not in output
+
+
+class TestSubcommandRequired:
+    def test_sets_subcommand_required_for_commands_with_subcommands(self):
+        p = argparse.ArgumentParser(prog="app")
+        sub = p.add_subparsers()
+        config = sub.add_parser("config", help="Manage config")
+        config_sub = config.add_subparsers()
+        config_sub.add_parser("get", help="Get a value")
+        config_sub.add_parser("set", help="Set a value")
+
+        output = generate(p)
+
+        assert "subcommand_required=#true" in output
+
+    def test_does_not_set_subcommand_required_when_command_has_positional_args(self):
+        p = argparse.ArgumentParser(prog="app")
+        sub = p.add_subparsers()
+        greet = sub.add_parser("greet", help="Greet someone")
+        greet.add_argument("name", help="Name to greet")
+        greet_sub = greet.add_subparsers()
+        greet_sub.add_parser("formally", help="Formal greeting")
+
+        spec = convert_root(p)
+        greet_cmd = next(c for c in spec.cmds if c.name == "greet")
+        assert not greet_cmd.subcommand_required
+
+    def test_does_not_set_subcommand_required_for_runnable_commands(self):
+        p = argparse.ArgumentParser(prog="app")
+        sub = p.add_subparsers()
+        task = sub.add_parser("task", help="Run a task")
+        task.set_defaults(func=lambda: None)  # runnable via func
+        task_sub = task.add_subparsers()
+        task_sub.add_parser("list", help="List tasks")
+
+        # argparse doesn't have a concept of "runnable" like commander,
+        # but when a command has positional args, it's not subcommand_required
+        # Here the task has subcommands and no positional args, so it IS subcommand_required
+        # This is the argparse equivalent behavior
+        spec = convert_root(p)
+        task_cmd = next(c for c in spec.cmds if c.name == "task")
+        assert task_cmd.subcommand_required is True
+
+
+class TestDefaultValues:
+    def test_renders_default_value_for_argument(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("file", nargs="?", default="input.txt", help="Input file")
+
+        output = generate(p)
+
+        assert "default=input.txt" in output
+
+    def test_preserves_string_zero_as_default(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--port", default="0", help="Port number")
+
+        output = generate(p)
+
+        assert "default=0" in output
+
+
+class TestCountFlags:
+    def test_renders_count_flags(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("-v", "--verbose", action="count", default=0, help="Verbosity level")
+
+        spec = convert_root(p)
+        verbose_flag = next(f for f in spec.flags if f.long == "verbose")
+        assert verbose_flag.count is True
+
+
+class TestSpecialCharacterEscaping:
+    def test_handles_special_chars_in_flag_help(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--format", help="Output format:\n  json\n  yaml")
+
+        output = generate(p)
+        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_description(self):
+        p = argparse.ArgumentParser(
+            prog="app",
+            description="First line.\nSecond line.\n\nThird paragraph.",
+        )
+
+        output = generate(p)
+        assert "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):
+        p = argparse.ArgumentParser(prog="app", description="A CLI")
+        p.add_argument("-v", "--verbose", action="store_true", help="Be verbose")
+        p.add_argument("-f", "--file", help="Input file")
+
+        output = generate(p)
+        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):
+        p = argparse.ArgumentParser(prog="app")
+        sub = p.add_subparsers()
+        config = sub.add_parser("config", help="Config")
+        config_sub = config.add_subparsers()
+        config_sub.add_parser("get", help="Get value")
+
+        output = generate(p)
+        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):
+        p = argparse.ArgumentParser(prog="app", description="A CLI")
+        assert generate_kdl(p) == generate(p)
+
+
+class TestConvertRoot:
+    def test_returns_spec_with_correct_structure(self):
+        p = argparse.ArgumentParser(prog="mycli", description="A CLI tool")
+        p.add_argument("--verbose", action="store_true", help="Be verbose")
+
+        spec = convert_root(p)
+
+        assert spec.name == "mycli"
+        assert spec.bin == "mycli"
+        assert spec.about == "A CLI tool"
+        assert len(spec.flags) == 1
+        assert spec.flags[0].long == "verbose"
+
+    def test_includes_arguments_in_spec(self):
+        p = argparse.ArgumentParser(prog="cmd")
+        p.add_argument("file", help="Input file")
+        p.add_argument("output", nargs="?", help="Output file")
+
+        spec = convert_root(p)
+
+        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):
+        p = argparse.ArgumentParser(prog="mycli", description="A CLI tool")
+        p.add_argument("--verbose", action="store_true", help="Be verbose")
+        sub = p.add_subparsers()
+        sub.add_parser("run", help="Run something")
+
+        j = generate_json(p)
+        parsed = json.loads(j)
+
+        assert parsed["name"] == "mycli"
+        assert parsed["bin"] == "mycli"
+        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):
+        p = argparse.ArgumentParser(prog="deploy")
+        p.add_argument("env", choices=["dev", "prod"], help="Environment")
+
+        j = generate_json(p)
+        parsed = json.loads(j)
+
+        assert parsed["args"][0]["choices"] == ["dev", "prod"]
+
+    def test_includes_flag_details_in_json(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--env", required=True, help="Target environment")
+        p.add_argument("--no-color", action="store_false", help="Disable color")
+
+        j = generate_json(p)
+        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"] == "--no-color")
+        assert color_flag["negate"] == "--no-color"
+
+    def test_handles_custom_bin_name_in_json(self):
+        p = argparse.ArgumentParser(prog="app", description="A tool")
+        j = generate_json(p, "my-tool")
+        parsed = json.loads(j)
+
+        assert parsed["bin"] == "my-tool"
+
+
+class TestEdgeCases:
+    def test_handles_empty_command_with_no_options_or_args(self):
+        p = argparse.ArgumentParser(prog="empty")
+        output = generate(p)
+
+        assert "name empty" in output
+        assert "bin empty" in output
+        # Skip the comment line and check no flag/arg/cmd in actual content
+        content = output.split("\n", 1)[1] if output.startswith("//") else output
+        assert "flag" not in content
+        assert "arg " not in content
+        assert "cmd" not in content
+
+    def test_handles_command_with_only_subcommands(self):
+        p = argparse.ArgumentParser(prog="app")
+        sub = p.add_subparsers()
+        sub.add_parser("start", help="Start")
+        sub.add_parser("stop", help="Stop")
+
+        output = generate(p)
+
+        assert "cmd start" in output
+        assert "cmd stop" in output
+
+    def test_handles_variadic_option_argument(self):
+        p = argparse.ArgumentParser(prog="app")
+        p.add_argument("--include", nargs="+", help="Include patterns")
+
+        spec = convert_root(p)
+        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_handles_multiple_flags_on_subcommand(self):
+        p = argparse.ArgumentParser(prog="app")
+        sub = p.add_subparsers()
+        build = sub.add_parser("build", help="Build the project")
+        build.add_argument("-o", "--output", help="Output directory")
+        build.add_argument("--minify", action="store_true", help="Minify output")
+        build.add_argument("--watch", action="store_true", help="Watch for changes")
+
+        output = generate(p)
+
+        assert 'flag "-o --output"' in output
+        assert "flag --minify" in output
+        assert "flag --watch" in output
+
+
+class TestFullOutputFormat:
+    def test_matches_expected_kdl_output(self):
+        p = argparse.ArgumentParser(prog="example", description="An example CLI")
+        p.add_argument("-f", "--file", help="Some input file")
+        p.add_argument("--verbose", action="store_true", help="Enable verbose output")
+
+        output = generate(p, "example")
+
+        assert "name example" in output
+        assert "bin example" in output
+        assert 'about "An example CLI"' in output
+        assert 'flag "-f --file"' in output
+        assert "flag --verbose" in output