usage-spec 1.0.0__tar.gz

usage_spec-1.0.0/.gitignore

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

usage_spec-1.0.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: usage-spec
+Version: 1.0.0
+Summary: Core types and rendering for usage spec
+License-Expression: MIT
+Keywords: cli,kdl,spec,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
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# usage-spec
+
+Core types and rendering for [usage spec](https://usage.jdx.dev).
+
+## Install
+
+```sh
+pip install usage-spec
+```
+
+## API
+
+### Types
+
+```python
+@dataclass
+class Spec:
+    name: str
+    bin: str
+    version: str
+    about: str
+    long: str
+    usage: str
+    flags: list[SpecFlag]
+    args: list[SpecArg]
+    cmds: list[SpecCommand]
+```
+
+### Functions
+
+```python
+from usage_spec import generate, render_kdl, render_json, validate_kdl
+
+# Render Spec as KDL string
+render_kdl(spec: Spec) -> str
+
+# Render Spec as JSON string
+render_json(spec: Spec) -> str
+
+# Generate spec output with optional format and comment
+generate(spec: Spec, format: str = "kdl", comment: str | None = None) -> str
+
+# Validate KDL string by basic structural check
+validate_kdl(kdl: str) -> None
+```
+
+## License
+
+MIT

usage_spec-1.0.0/README.md

@@ -0,0 +1,49 @@
+# usage-spec
+
+Core types and rendering for [usage spec](https://usage.jdx.dev).
+
+## Install
+
+```sh
+pip install usage-spec
+```
+
+## API
+
+### Types
+
+```python
+@dataclass
+class Spec:
+    name: str
+    bin: str
+    version: str
+    about: str
+    long: str
+    usage: str
+    flags: list[SpecFlag]
+    args: list[SpecArg]
+    cmds: list[SpecCommand]
+```
+
+### Functions
+
+```python
+from usage_spec import generate, render_kdl, render_json, validate_kdl
+
+# Render Spec as KDL string
+render_kdl(spec: Spec) -> str
+
+# Render Spec as JSON string
+render_json(spec: Spec) -> str
+
+# Generate spec output with optional format and comment
+generate(spec: Spec, format: str = "kdl", comment: str | None = None) -> str
+
+# Validate KDL string by basic structural check
+validate_kdl(kdl: str) -> None
+```
+
+## License
+
+MIT

usage_spec-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "usage-spec"
+version = "1.0.0"
+description = "Core types and rendering for usage spec"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+keywords = ["usage", "cli", "kdl", "spec"]
+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",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/usage_spec"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

usage_spec-1.0.0/src/usage_spec/__init__.py

@@ -0,0 +1,32 @@
+"""Usage spec core - Python implementation aligned with @usage-spec/core."""
+
+from .spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices
+from .kdl import render_kdl, validate_kdl
+from .json import render_json
+
+__all__ = [
+    "Spec",
+    "SpecArg",
+    "SpecFlag",
+    "SpecCommand",
+    "SpecChoices",
+    "render_kdl",
+    "validate_kdl",
+    "render_json",
+    "generate",
+]
+
+
+def generate(
+    spec: Spec,
+    *,
+    format: str = "kdl",
+    comment: str | None = None,
+) -> str:
+    """Generate usage spec output in the specified format."""
+    output = render_json(spec) if format == "json" else render_kdl(spec)
+
+    if comment:
+        return f"// {comment}\n{output}"
+
+    return output

usage_spec-1.0.0/src/usage_spec/json.py

@@ -0,0 +1,123 @@
+"""JSON renderer for usage spec, aligned with @usage-spec/core json.ts output."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .spec import Spec, SpecArg, SpecFlag, SpecCommand
+
+
+def _arg_to_json(arg: SpecArg) -> dict[str, Any]:
+    result: dict[str, Any] = {"name": arg.name}
+
+    if arg.help:
+        result["help"] = arg.help
+    if not arg.required:
+        result["required"] = False
+    if arg.var:
+        result["var"] = True
+    if arg.hide:
+        result["hide"] = True
+    if len(arg.default) == 1:
+        result["default"] = arg.default[0]
+    if len(arg.default) > 1:
+        result["default"] = arg.default
+    if arg.choices:
+        result["choices"] = arg.choices.values
+
+    return result
+
+
+def _flag_to_json(flag: SpecFlag) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+
+    name_parts: list[str] = []
+    if flag.short:
+        name_parts.append(f"-{flag.short}")
+    if flag.long:
+        name_parts.append(f"--{flag.long}")
+    result["name"] = " ".join(name_parts)
+
+    if flag.help:
+        result["help"] = flag.help
+    if flag.help_long:
+        result["help_long"] = flag.help_long
+    if flag.required:
+        result["required"] = True
+    if flag.hide:
+        result["hide"] = True
+    if flag.global_:
+        result["global"] = True
+    if flag.count:
+        result["count"] = True
+    if flag.var:
+        result["var"] = True
+    if flag.negate:
+        result["negate"] = flag.negate
+    if flag.deprecated:
+        result["deprecated"] = flag.deprecated
+    if flag.env:
+        result["env"] = flag.env
+    if len(flag.default) == 1:
+        result["default"] = flag.default[0]
+    if len(flag.default) > 1:
+        result["default"] = flag.default
+
+    if flag.arg:
+        result["arg"] = _arg_to_json(flag.arg)
+
+    return result
+
+
+def _cmd_to_json(cmd: SpecCommand) -> dict[str, Any]:
+    result: dict[str, Any] = {"name": cmd.name}
+
+    if cmd.help:
+        result["help"] = cmd.help
+    if cmd.help_long:
+        result["help_long"] = cmd.help_long
+    if cmd.hide:
+        result["hide"] = True
+    if cmd.deprecated:
+        result["deprecated"] = cmd.deprecated
+    if cmd.aliases:
+        result["aliases"] = cmd.aliases
+    if cmd.subcommand_required:
+        result["subcommand_required"] = True
+
+    if cmd.flags:
+        result["flags"] = [_flag_to_json(f) for f in cmd.flags]
+    if cmd.args:
+        result["args"] = [_arg_to_json(a) for a in cmd.args]
+    if cmd.cmds:
+        result["cmds"] = [_cmd_to_json(c) for c in cmd.cmds]
+
+    return result
+
+
+def render_json(spec: Spec) -> str:
+    """Render a Spec to JSON format string."""
+    result: dict[str, Any] = {}
+
+    if spec.name:
+        result["name"] = spec.name
+    if spec.bin:
+        result["bin"] = spec.bin
+    if spec.version:
+        result["version"] = spec.version
+    if spec.about:
+        result["about"] = spec.about
+    if spec.long:
+        result["long_about"] = spec.long
+    if spec.usage:
+        result["usage"] = spec.usage
+
+    if spec.flags:
+        result["flags"] = [_flag_to_json(f) for f in spec.flags]
+    if spec.args:
+        result["args"] = [_arg_to_json(a) for a in spec.args]
+    if spec.cmds:
+        result["cmds"] = [_cmd_to_json(c) for c in spec.cmds]
+
+    return json.dumps(result, indent=2) + "\n"

usage_spec-1.0.0/src/usage_spec/kdl.py

@@ -0,0 +1,247 @@
+"""KDL renderer for usage spec, aligned with @usage-spec/core kdl.ts output."""
+
+from __future__ import annotations
+
+from .spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices
+
+
+def _escape_kdl_string(value: str) -> str:
+    """Escape a string for KDL format."""
+    if not value:
+        return '""'
+    # KDL strings: if the value contains special chars, wrap in quotes
+    needs_quoting = any(c in value for c in (' ', '"', '\n', '\r', '\t', '\\', '{', '}', '#', '\0'))
+    if not needs_quoting and value not in ('true', 'false', 'null'):
+        return value
+    escaped = value.replace('\\', '\\\\').replace('"', '\\"').replace('\n', '\\n').replace('\r', '\\r').replace('\t', '\\t')
+    return f'"{escaped}"'
+
+
+def _format_bool(value: bool) -> str:
+    return "#true" if value else "#false"
+
+
+def _indent(lines: list[str], level: int) -> list[str]:
+    prefix = "    " * level
+    return [prefix + line for line in lines]
+
+
+def _render_choices(choices: SpecChoices) -> list[str]:
+    parts = " ".join(_escape_kdl_string(c) for c in choices.values)
+    return [f"choices {parts}"]
+
+
+def _render_arg(arg: SpecArg, *, is_flag_arg: bool = False, indent_level: int = 0) -> list[str]:
+    lines: list[str] = []
+
+    if is_flag_arg:
+        usage = f"<{arg.name}>"
+        line_parts = [f"arg {_escape_kdl_string(usage)}"]
+    else:
+        # Build usage string: <required> or [optional], with … for variadic
+        if arg.required:
+            usage = f"<{arg.name}>"
+        else:
+            usage = f"[{arg.name}]"
+        if arg.var:
+            usage += "\u2026"
+
+        line_parts = [f"arg {_escape_kdl_string(usage)}"]
+
+        if arg.help:
+            line_parts.append(f"help={_escape_kdl_string(arg.help)}")
+        if not arg.required:
+            line_parts.append(f"required={_format_bool(False)}")
+        if arg.var:
+            line_parts.append(f"var={_format_bool(True)}")
+        if arg.hide:
+            line_parts.append(f"hide={_format_bool(True)}")
+        if len(arg.default) == 1:
+            line_parts.append(f"default={_escape_kdl_string(arg.default[0])}")
+
+    # Check for children (choices, multiple defaults)
+    children: list[str] = []
+
+    if not is_flag_arg and len(arg.default) > 1:
+        parts = " ".join(_escape_kdl_string(d) for d in arg.default)
+        children.append(f"default {parts}")
+
+    if arg.choices:
+        children.extend(_render_choices(arg.choices))
+
+    if is_flag_arg:
+        # Flag arg: only has help and choices as children/properties
+        line_parts_flag = [f"arg {_escape_kdl_string(f'<{arg.name}>')}"]
+        if arg.help:
+            line_parts_flag.append(f"help={_escape_kdl_string(arg.help)}")
+
+        if arg.choices:
+            children_flag = _indent(_render_choices(arg.choices), 1)
+            lines.append(" ".join(line_parts_flag) + " {")
+            lines.extend(children_flag)
+            lines.append("}")
+        else:
+            lines.append(" ".join(line_parts_flag))
+        return lines
+
+    if children:
+        lines.append(" ".join(line_parts) + " {")
+        lines.extend(_indent(children, 1))
+        lines.append("}")
+    else:
+        lines.append(" ".join(line_parts))
+
+    return lines
+
+
+def _render_flag(flag: SpecFlag) -> list[str]:
+    # Build the flag name: "-s --long"
+    name_parts: list[str] = []
+    if flag.short:
+        name_parts.append(f"-{flag.short}")
+    if flag.long:
+        name_parts.append(f"--{flag.long}")
+    flag_name = " ".join(name_parts)
+
+    line_parts = [f"flag {_escape_kdl_string(flag_name)}"]
+
+    if flag.help:
+        line_parts.append(f"help={_escape_kdl_string(flag.help)}")
+    if flag.required:
+        line_parts.append(f"required={_format_bool(True)}")
+    if flag.var:
+        line_parts.append(f"var={_format_bool(True)}")
+    if flag.hide:
+        line_parts.append(f"hide={_format_bool(True)}")
+    if flag.global_:
+        line_parts.append(f"global={_format_bool(True)}")
+    if flag.count:
+        line_parts.append(f"count={_format_bool(True)}")
+    if flag.negate:
+        line_parts.append(f"negate={flag.negate}")
+    if flag.deprecated:
+        line_parts.append(f"deprecated={_escape_kdl_string(flag.deprecated)}")
+    if len(flag.default) == 1:
+        line_parts.append(f"default={_escape_kdl_string(flag.default[0])}")
+    elif flag.default_bool is not None:
+        line_parts.append(f"default={_format_bool(flag.default_bool)}")
+    if flag.env:
+        line_parts.append(f"env={_escape_kdl_string(flag.env)}")
+
+    # Check for children
+    children: list[str] = []
+
+    if flag.help_long:
+        children.append(f"long_help {_escape_kdl_string(flag.help_long)}")
+
+    if len(flag.default) > 1:
+        parts = " ".join(_escape_kdl_string(d) for d in flag.default)
+        children.append(f"default {parts}")
+
+    if flag.arg:
+        children.extend(_render_flag_arg(flag.arg))
+
+    if children:
+        return [" ".join(line_parts) + " {", *_indent(children, 1), "}"]
+    else:
+        return [" ".join(line_parts)]
+
+
+def _render_flag_arg(arg: SpecArg) -> list[str]:
+    """Render a flag's inner arg node."""
+    line_parts = [f"arg {_escape_kdl_string(f'<{arg.name}>')}"]
+
+    if arg.help:
+        line_parts.append(f"help={_escape_kdl_string(arg.help)}")
+
+    if arg.choices:
+        children = _indent(_render_choices(arg.choices), 1)
+        return [" ".join(line_parts) + " {", *children, "}"]
+    else:
+        return [" ".join(line_parts)]
+
+
+def _render_command(cmd: SpecCommand) -> list[str]:
+    line_parts = [f"cmd {_escape_kdl_string(cmd.name)}"]
+
+    if cmd.hide:
+        line_parts.append(f"hide={_format_bool(True)}")
+    if cmd.subcommand_required:
+        line_parts.append("subcommand_required=#true")
+    if cmd.help:
+        line_parts.append(f"help={_escape_kdl_string(cmd.help)}")
+    if cmd.deprecated:
+        line_parts.append(f"deprecated={_escape_kdl_string(cmd.deprecated)}")
+
+    # Check for children
+    children: list[str] = []
+
+    if cmd.aliases:
+        parts = " ".join(_escape_kdl_string(a) for a in cmd.aliases)
+        children.append(f"alias {parts}")
+
+    if cmd.help_long:
+        children.append(f"long_help {_escape_kdl_string(cmd.help_long)}")
+
+    for flag in cmd.flags:
+        children.extend(_render_flag(flag))
+
+    for arg in cmd.args:
+        children.extend(_render_arg(arg))
+
+    for sub in cmd.cmds:
+        children.extend(_render_command(sub))
+
+    if children:
+        indented = _indent(children, 1)
+        return [" ".join(line_parts) + " {", *indented, "}"]
+    else:
+        return [" ".join(line_parts)]
+
+
+def render_kdl(spec: Spec) -> str:
+    """Render a Spec to KDL format string."""
+    lines: list[str] = []
+
+    if spec.name:
+        lines.append(f"name {_escape_kdl_string(spec.name)}")
+    if spec.bin:
+        lines.append(f"bin {_escape_kdl_string(spec.bin)}")
+    if spec.version:
+        lines.append(f"version {_escape_kdl_string(spec.version)}")
+    if spec.about:
+        lines.append(f"about {_escape_kdl_string(spec.about)}")
+    if spec.long:
+        lines.append(f"long_about {_escape_kdl_string(spec.long)}")
+    if spec.usage:
+        lines.append(f"usage {_escape_kdl_string(spec.usage)}")
+
+    for flag in spec.flags:
+        lines.extend(_render_flag(flag))
+
+    for arg in spec.args:
+        lines.extend(_render_arg(arg))
+
+    for cmd in spec.cmds:
+        lines.extend(_render_command(cmd))
+
+    return "\n".join(lines) + "\n"
+
+
+def validate_kdl(kdl: str) -> None:
+    """Validate KDL output by attempting a basic structural parse.
+
+    This is a simplified validator - for full validation, use the
+    @bgotink/kdl parser via the TypeScript @usage-spec/core package.
+    """
+    if not kdl.strip():
+        return
+    # Basic bracket matching for child blocks
+    depth = 0
+    for line in kdl.split("\n"):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("//"):
+            continue
+        depth += stripped.count("{") - stripped.count("}")
+    if depth != 0:
+        raise ValueError(f"Unbalanced braces in KDL output (depth={depth})")

usage_spec-1.0.0/src/usage_spec/spec.py

@@ -0,0 +1,67 @@
+"""Usage spec type definitions, aligned with @usage-spec/core TypeScript types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SpecChoices:
+    values: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SpecArg:
+    name: str = ""
+    help: str = ""
+    required: bool = True
+    var: bool = False
+    hide: bool = False
+    default: list[str] = field(default_factory=list)
+    choices: SpecChoices | None = None
+
+
+@dataclass
+class SpecFlag:
+    short: str = ""
+    long: str = ""
+    help: str = ""
+    help_long: str = ""
+    required: bool = False
+    hide: bool = False
+    global_: bool = False
+    count: bool = False
+    var: bool = False
+    negate: str = ""
+    deprecated: str = ""
+    default: list[str] = field(default_factory=list)
+    default_bool: bool | None = None
+    env: str = ""
+    arg: SpecArg | None = None
+
+
+@dataclass
+class SpecCommand:
+    name: str = ""
+    help: str = ""
+    help_long: str = ""
+    hide: bool = False
+    deprecated: str = ""
+    aliases: list[str] = field(default_factory=list)
+    subcommand_required: bool = False
+    flags: list[SpecFlag] = field(default_factory=list)
+    args: list[SpecArg] = field(default_factory=list)
+    cmds: list[SpecCommand] = field(default_factory=list)
+
+
+@dataclass
+class Spec:
+    name: str = ""
+    bin: str = ""
+    version: str = ""
+    about: str = ""
+    long: str = ""
+    usage: str = ""
+    flags: list[SpecFlag] = field(default_factory=list)
+    args: list[SpecArg] = field(default_factory=list)
+    cmds: list[SpecCommand] = field(default_factory=list)

usage_spec-1.0.0/tests/test_json.py

@@ -0,0 +1,83 @@
+"""Tests for JSON renderer."""
+
+import json
+
+from usage_spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices, render_json
+
+
+def test_simple_spec():
+    spec = Spec(
+        name="mycli",
+        bin="mycli",
+        version="2.0.0",
+        about="A CLI tool",
+        flags=[
+            SpecFlag(short="v", long="verbose", help="Be verbose"),
+        ],
+        cmds=[
+            SpecCommand(name="run", help="Run something"),
+        ],
+    )
+    result = json.loads(render_json(spec))
+    assert result["name"] == "mycli"
+    assert result["bin"] == "mycli"
+    assert result["version"] == "2.0.0"
+    assert result["about"] == "A CLI tool"
+    assert len(result["flags"]) == 1
+    assert len(result["cmds"]) == 1
+    assert result["cmds"][0]["name"] == "run"
+
+
+def test_choices_in_json():
+    spec = Spec(
+        name="deploy",
+        flags=[
+            SpecFlag(
+                long="env",
+                help="Environment",
+                arg=SpecArg(name="ENV", choices=SpecChoices(values=["dev", "prod"])),
+            ),
+        ],
+    )
+    result = json.loads(render_json(spec))
+    assert result["flags"][0]["arg"]["choices"] == ["dev", "prod"]
+
+
+def test_flag_details():
+    spec = Spec(
+        name="app",
+        flags=[
+            SpecFlag(long="env", help="Target environment", required=True, arg=SpecArg(name="ENV")),
+            SpecFlag(long="no-color", help="Disable color", negate="--color"),
+        ],
+    )
+    result = json.loads(render_json(spec))
+    assert len(result["flags"]) == 2
+    env_flag = next(f for f in result["flags"] if f["name"] == "--env")
+    assert env_flag["required"] is True
+    assert env_flag["arg"]["name"] == "ENV"
+
+    color_flag = next(f for f in result["flags"] if f["name"] == "--no-color")
+    assert color_flag["negate"] == "--color"
+
+
+def test_args_in_json():
+    spec = Spec(
+        name="app",
+        args=[
+            SpecArg(name="file", help="Input file", required=True),
+            SpecArg(name="output", help="Output file", required=False),
+        ],
+    )
+    result = json.loads(render_json(spec))
+    assert len(result["args"]) == 2
+    assert result["args"][0]["name"] == "file"
+    # required=true is default, omitted in JSON
+    assert "required" not in result["args"][0]
+    assert result["args"][1]["required"] is False
+
+
+def test_omits_empty_fields():
+    spec = Spec(name="empty")
+    result = json.loads(render_json(spec))
+    assert result == {"name": "empty"}

usage_spec-1.0.0/tests/test_kdl.py

@@ -0,0 +1,261 @@
+"""Tests for KDL renderer."""
+
+from usage_spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices, render_kdl, validate_kdl
+
+
+def test_simple_spec():
+    spec = Spec(
+        name="mycli",
+        bin="mycli",
+        version="1.0.0",
+        about="A simple CLI",
+        flags=[
+            SpecFlag(short="v", long="verbose", help="Enable verbose output"),
+            SpecFlag(short="c", long="config", help="Config file path", arg=SpecArg(name="PATH")),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "name mycli" in output
+    assert "bin mycli" in output
+    assert "version 1.0.0" 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_required_option():
+    spec = Spec(
+        name="app",
+        flags=[
+            SpecFlag(long="env", help="Target environment", required=True, arg=SpecArg(name="ENV")),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "required=#true" in output
+
+
+def test_boolean_flag():
+    spec = Spec(
+        name="app",
+        flags=[
+            SpecFlag(long="force", help="Force the operation"),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "flag --force" in output
+    # Boolean flags should not have arg
+    force_line = next(l for l in output.split("\n") if "flag --force" in l)
+    assert "arg" not in force_line
+
+
+def test_default_values():
+    spec = Spec(
+        name="app",
+        flags=[
+            SpecFlag(long="output", help="Output format", default=["json"], arg=SpecArg(name="FORMAT")),
+            SpecFlag(long="retries", help="Number of retries", default=["3"], arg=SpecArg(name="N")),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "default=json" in output
+    assert "default=3" in output
+
+
+def test_boolean_default_true():
+    spec = Spec(
+        name="app",
+        flags=[
+            SpecFlag(long="color", help="Enable color", default_bool=True),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "default=#true" in output
+
+
+def test_boolean_default_false_omitted():
+    spec = Spec(
+        name="app",
+        flags=[
+            SpecFlag(long="force", help="Force operation", default_bool=None),
+        ],
+    )
+    output = render_kdl(spec)
+    force_line = next(l for l in output.split("\n") if "flag --force" in l)
+    assert "default" not in force_line
+
+
+def test_negated_option():
+    spec = Spec(
+        name="app",
+        flags=[
+            SpecFlag(long="no-color", help="Disable color output", negate="--color"),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "negate=--color" in output
+
+
+def test_choices():
+    spec = Spec(
+        name="deploy",
+        flags=[
+            SpecFlag(
+                long="format",
+                help="Output format",
+                arg=SpecArg(name="TYPE", choices=SpecChoices(values=["json", "yaml", "toml"])),
+            ),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "choices" in output
+    assert "json" in output
+    assert "yaml" in output
+    assert "toml" in output
+
+
+def test_positional_args():
+    spec = Spec(
+        name="cmd",
+        args=[
+            SpecArg(name="file", help="Input file", required=True),
+            SpecArg(name="output", help="Output file", required=False),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "arg <file>" in output
+    assert "arg [output]" in output
+    assert "required=#false" in output
+
+
+def test_variadic_arg():
+    spec = Spec(
+        name="cmd",
+        args=[
+            SpecArg(name="files", help="Multiple files", required=True, var=True),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "arg <files>\u2026" in output
+    assert "var=#true" in output
+
+
+def test_subcommands():
+    spec = Spec(
+        name="app",
+        cmds=[
+            SpecCommand(name="start", help="Start the app"),
+            SpecCommand(name="stop", help="Stop the app"),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "cmd start" in output
+    assert "cmd stop" in output
+
+
+def test_nested_subcommands():
+    spec = Spec(
+        name="app",
+        cmds=[
+            SpecCommand(
+                name="sub",
+                help="A subcommand",
+                cmds=[
+                    SpecCommand(name="nested", help="A nested command"),
+                ],
+            ),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "cmd sub" in output
+    assert "cmd nested" in output
+
+
+def test_subcommand_required():
+    spec = Spec(
+        name="app",
+        cmds=[
+            SpecCommand(
+                name="config",
+                help="Manage config",
+                subcommand_required=True,
+                cmds=[
+                    SpecCommand(name="get", help="Get a value"),
+                    SpecCommand(name="set", help="Set a value"),
+                ],
+            ),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "subcommand_required=#true" in output
+
+
+def test_aliases():
+    spec = Spec(
+        name="app",
+        cmds=[
+            SpecCommand(name="install", help="Install packages", aliases=["i", "add"]),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "alias" in output
+    assert "i" in output
+    assert "add" in output
+
+
+def test_long_help():
+    spec = Spec(
+        name="app",
+        about="Short help",
+        long="This is a much longer description of the app.",
+    )
+    output = render_kdl(spec)
+    assert 'about "Short help"' in output
+    assert 'long_about "This is a much longer description of the app."' in output
+
+
+def test_env_variable():
+    spec = Spec(
+        name="app",
+        flags=[
+            SpecFlag(long="color", help="Color output", env="MYCLI_COLOR", arg=SpecArg(name="BOOL")),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "env=MYCLI_COLOR" in output
+
+
+def test_validate_kdl_valid():
+    spec = Spec(
+        name="app",
+        version="1.0.0",
+        about="A CLI",
+        flags=[
+            SpecFlag(short="v", long="verbose", help="Be verbose"),
+            SpecFlag(short="f", long="file", help="Input file", arg=SpecArg(name="FILE")),
+        ],
+    )
+    output = render_kdl(spec)
+    validate_kdl(output)  # Should not raise
+
+
+def test_special_char_escaping():
+    spec = Spec(
+        name="app",
+        about="Short help",
+        long="First line.\nSecond line.\n\nThird paragraph.",
+    )
+    output = render_kdl(spec)
+    assert "long_about" in output
+    validate_kdl(output)
+
+def test_string_zero_default():
+    spec = Spec(
+        name="app",
+        flags=[
+            SpecFlag(long="port", help="Port number", default=["0"], arg=SpecArg(name="PORT")),
+        ],
+    )
+    output = render_kdl(spec)
+    assert "default=0" in output