kd-cli 2.0.4__py3-none-any.whl

kd/cli/core/command_parser.py

@@ -0,0 +1,246 @@
+"""Two-phase command parser.
+
+Phase 1 (parse_command): Resolve namespace + command from positional
+args and tokenize options into a raw dict.  No validation.
+
+Phase 2 (resolve_options): Validate types, choices, and required
+options, producing the final ResolvedOptions.
+
+The convenience method ``parse()`` runs both phases in one call.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from kd.cli.core.command_base import Command
+from kd.cli.core.namespaces import Namespace, NamespaceRegistry
+from kd.cli.core.option_registry import (
+    OUTPUT_OPTIONS,
+    OptionError,
+    OptionRegistry,
+    ResolvedOptions,
+)
+
+
+class ParseError(Exception):
+    """Raised when command parsing fails."""
+
+
+@dataclass
+class UnresolvedCommand:
+    """Phase-1 result: command identified, options tokenized but not validated."""
+
+    namespace: Namespace
+    command_name: str
+    command: Command | None  # None if command not found
+    args: list[str] = field(default_factory=list)
+    raw_options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ParsedCommand:
+    """Result of parsing a command line."""
+
+    namespace: Namespace
+    command_name: str
+    command: Command | None  # None if command not found
+    args: list[str] = field(default_factory=list)
+    options: ResolvedOptions = field(default_factory=ResolvedOptions)
+    raw_options: dict[str, Any] = field(default_factory=dict)
+
+
+class CommandParser:
+    """Parses argv into a resolved command with options."""
+
+    def __init__(self, registry: NamespaceRegistry) -> None:
+        self._registry = registry
+
+    def parse_command(self, argv: list[str]) -> UnresolvedCommand:
+        """Phase 1: resolve command and tokenize options.  No validation.
+
+        1. Split argv into positionals and option tokens
+        2. Resolve namespace + command from positionals
+        3. Build option registry from command declarations + OUTPUT_OPTIONS
+        4. Parse option tokens into a raw dict (recovering misclassified positionals)
+        """
+        positionals, option_tokens = self._split_args(argv)
+        namespace, command_name, remaining = self._registry.resolve(positionals)
+
+        command = namespace.get_command(command_name) if command_name else None
+
+        option_reg = self._build_option_registry(command)
+        raw_options, recovered = self._parse_option_tokens(option_tokens, option_reg)
+
+        # Recovered positionals are tokens that _split_args heuristically
+        # consumed as option values but were actually after boolean flags.
+        # Prepend them to args so the command sees them.
+        if recovered:
+            remaining = recovered + remaining
+
+        return UnresolvedCommand(
+            namespace=namespace,
+            command_name=command_name,
+            command=command,
+            args=remaining,
+            raw_options=raw_options,
+        )
+
+    def resolve_options(self, unresolved: UnresolvedCommand) -> ParsedCommand:
+        """Phase 2: validate and resolve options.
+
+        Builds the option registry, validates types/choices/required,
+        and returns a fully resolved ``ParsedCommand``.
+        """
+        option_reg = self._build_option_registry(unresolved.command)
+        try:
+            resolved = option_reg.resolve(unresolved.raw_options)
+        except OptionError as e:
+            raise ParseError(str(e)) from e
+
+        return ParsedCommand(
+            namespace=unresolved.namespace,
+            command_name=unresolved.command_name,
+            command=unresolved.command,
+            args=unresolved.args,
+            options=resolved,
+            raw_options=unresolved.raw_options,
+        )
+
+    def parse(self, argv: list[str]) -> ParsedCommand:
+        """Full parse: resolve command + validate options in one call.
+
+        Convenience wrapper equivalent to ``parse_command()`` then
+        ``resolve_options()``.
+        """
+        return self.resolve_options(self.parse_command(argv))
+
+    def _split_args(self, argv: list[str]) -> tuple[list[str], list[str]]:
+        """Split argv into positional args and option tokens.
+
+        Supports GNU-style mixed placement: options can appear anywhere
+        in the command line (before, between, or after positionals).
+
+        Slash-path expansion: the first positional token starting with
+        ``/`` is expanded into namespace segments (``/a/b`` → ``a``, ``b``).
+        Once any positional has been emitted, later ``/``-prefixed tokens
+        are treated as literal arguments (file paths, etc.).
+        A bare ``/`` expands to nothing (root namespace).
+
+        The ``--`` separator ends option parsing: everything after it
+        is positional.
+
+        Heuristic: any ``--option`` followed by a non-dash token consumes
+        it as a value. If the option turns out to be a boolean flag,
+        ``_parse_option_tokens`` recovers the stray value (see there).
+        A lone ``-`` is consumed as a value (stdin convention).
+        """
+        positionals: list[str] = []
+        option_tokens: list[str] = []
+
+        i = 0
+        while i < len(argv):
+            token = argv[i]
+
+            # -- separator: everything after is positional
+            if token == "--":
+                positionals.extend(argv[i + 1 :])
+                break
+
+            if token.startswith("-") and len(token) > 1:
+                # Option token
+                option_tokens.append(token)
+
+                # If not --key=value form, consume next token as value
+                # (heuristic: assume non-dash options take a value)
+                if "=" not in token and i + 1 < len(argv):
+                    next_token = argv[i + 1]
+                    if next_token != "--" and not (
+                        next_token.startswith("-") and len(next_token) > 1
+                    ):
+                        option_tokens.append(next_token)
+                        i += 2
+                        continue
+                i += 1
+            else:
+                # Positional token — expand slash path only for the first one
+                if not positionals and token.startswith("/"):
+                    segments = [s for s in token.split("/") if s]
+                    positionals.extend(segments)
+                else:
+                    positionals.append(token)
+                i += 1
+
+        return positionals, option_tokens
+
+    def _build_option_registry(self, command: Command | None) -> OptionRegistry:
+        """Build option registry from command declarations + standard OUTPUT options."""
+        registry = OptionRegistry()
+        registry.register_all(OUTPUT_OPTIONS)
+        if command:
+            registry.register_all(command.get_options())
+        return registry
+
+    def _parse_option_tokens(
+        self, tokens: list[str], registry: OptionRegistry
+    ) -> tuple[dict[str, Any], list[str]]:
+        """Parse option tokens into a raw name->value dict.
+
+        Handles: --key value, --key=value, -k value, -k=value, boolean flags.
+
+        Returns (raw_options, recovered_positionals). Recovered positionals
+        are tokens that ``_split_args`` heuristically consumed as option values
+        but actually follow boolean flags — they belong in the positional stream.
+        """
+        raw: dict[str, Any] = {}
+        recovered: list[str] = []
+        i = 0
+
+        while i < len(tokens):
+            token = tokens[i]
+
+            if "=" in token:
+                # --key=value or -k=value
+                name_part, value = token.split("=", 1)
+                name = name_part.lstrip("-")
+                canonical = registry.resolve_name(name) or name
+                self._set_option(raw, canonical, value, registry)
+                i += 1
+                continue
+
+            if not token.startswith("-") or len(token) == 1:
+                # Stray positional (includes lone `-`) — recover for command args
+                recovered.append(token)
+                i += 1
+                continue
+
+            name = token.lstrip("-")
+            canonical = registry.resolve_name(name) or name
+
+            # Boolean flag: no value consumed
+            if registry.is_boolean_flag(name):
+                raw[canonical] = True
+                i += 1
+                continue
+
+            # Regular option: consume next token as value (lone `-` is valid)
+            if i + 1 < len(tokens) and not (
+                tokens[i + 1].startswith("-") and len(tokens[i + 1]) > 1
+            ):
+                self._set_option(raw, canonical, tokens[i + 1], registry)
+                i += 2
+            elif registry.get_declaration(name) is not None:
+                raise ParseError(f"Option --{canonical} requires a value")
+            else:
+                raise ParseError(f"Unknown option: --{name}")
+
+        return raw, recovered
+
+    @staticmethod
+    def _set_option(raw: dict[str, Any], name: str, value: str, registry: OptionRegistry) -> None:
+        """Set an option value, appending to a list for repeatable options."""
+        if registry.is_list_option(name):
+            raw.setdefault(name, []).append(value)
+        else:
+            raw[name] = value

kd/cli/core/namespaces.py

@@ -0,0 +1,175 @@
+"""Namespace tree and registry.
+
+A Namespace is a node in the command tree (e.g., /system, /system/config).
+Each namespace holds commands and optional sub-namespaces.
+The NamespaceRegistry is the root of the tree.
+
+Resolution is greedy left-to-right: ``kd system config set url value``
+resolves to namespace=/system/config, command=set, args=[url, value].
+
+Built-in command synonyms (e.g., ``get`` → ``show``) are loaded from
+``kd/resources/command-synonyms.yaml`` and applied globally after
+namespace registration. See :func:`load_synonyms` and :func:`apply_synonyms`.
+"""
+
+from __future__ import annotations
+
+from importlib import resources as importlib_resources
+from typing import TYPE_CHECKING
+
+import yaml
+
+if TYPE_CHECKING:
+    from kd.cli.core.command_base import Command
+
+
+class Namespace:
+    """A node in the command tree."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        path: str = "",
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.path = path
+        self.commands: dict[str, Command] = {}
+        self.sub_namespaces: dict[str, Namespace] = {}
+        self.synonyms: dict[str, str] = {}
+
+    def register_command(self, name: str, command: Command) -> None:
+        """Register a command in this namespace."""
+        self.commands[name] = command
+
+    def register_sub_namespace(self, namespace: Namespace) -> None:
+        """Register a child namespace."""
+        self.sub_namespaces[namespace.name] = namespace
+
+    def get_command(self, name: str) -> Command | None:
+        """Look up a command by name, falling through to synonyms."""
+        cmd = self.commands.get(name)
+        if cmd is not None:
+            return cmd
+        canonical = self.synonyms.get(name)
+        if canonical is not None:
+            return self.commands.get(canonical)
+        return None
+
+    def get_sub_namespace(self, name: str) -> Namespace | None:
+        """Look up a child namespace by name."""
+        return self.sub_namespaces.get(name)
+
+
+class NamespaceRegistry:
+    """Root of the namespace tree. Resolves token sequences to commands."""
+
+    def __init__(self) -> None:
+        self.root = Namespace("kd", "YouTrack CLI and SDK")
+
+    def register_namespace(self, namespace: Namespace) -> None:
+        """Place a namespace in the tree by its path.
+
+        Path segments are split on '/'. Intermediate namespaces are
+        created automatically if they don't exist.
+
+        Example: path="system/config" creates /system (if missing)
+        then places the namespace as /system/config.
+        """
+        if not namespace.path:
+            self.root.register_sub_namespace(namespace)
+            return
+
+        segments = namespace.path.split("/")
+        parent = self.root
+
+        # Navigate/create intermediate namespaces
+        for segment in segments[:-1]:
+            child = parent.get_sub_namespace(segment)
+            if child is None:
+                child = Namespace(segment, f"{segment} commands", path=segment)
+                parent.register_sub_namespace(child)
+            parent = child
+
+        # Register using the last path segment as key (not namespace.name)
+        parent.sub_namespaces[segments[-1]] = namespace
+
+    def resolve(self, tokens: list[str]) -> tuple[Namespace, str, list[str]]:
+        """Resolve tokens to (namespace, command_name, remaining_args).
+
+        Uses greedy left-to-right matching: consumes tokens as namespace
+        segments as long as matching sub-namespaces exist, then takes the
+        next token as the command name.
+
+        Returns empty command_name when no command token remains (bare
+        namespace invocation — triggers discovery).
+
+        Examples:
+            ["system", "config", "set", "url", "val"]
+            -> (system/config namespace, "set", ["url", "val"])
+
+            ["system", "config"]
+            -> (system/config namespace, "", [])
+
+            []
+            -> (root namespace, "", [])
+        """
+        if not tokens:
+            return self.root, "", []
+
+        current = self.root
+        consumed = 0
+
+        # Greedy namespace resolution
+        for token in tokens:
+            child = current.get_sub_namespace(token)
+            if child is None:
+                break
+            current = child
+            consumed += 1
+
+        remaining = tokens[consumed:]
+
+        if remaining:
+            command_name = remaining[0]
+            args = remaining[1:]
+        else:
+            command_name = ""
+            args = []
+
+        return current, command_name, args
+
+
+# ---------------------------------------------------------------------------
+# Built-in command synonyms
+# ---------------------------------------------------------------------------
+
+
+def load_synonyms() -> list[tuple[str, str]]:
+    """Load synonym definitions from the YAML resource file.
+
+    Returns a list of ``(synonym, canonical)`` pairs.
+    """
+    ref = importlib_resources.files("kd.resources").joinpath("command-synonyms.yaml")
+    raw = yaml.safe_load(ref.read_text(encoding="utf-8"))
+    return [(entry["synonym"], entry["canonical"]) for entry in raw]
+
+
+def _apply_to_namespace(ns: Namespace, synonyms: list[tuple[str, str]]) -> None:
+    """Apply synonyms to a single namespace (non-recursive)."""
+    for synonym, canonical in synonyms:
+        if canonical in ns.commands and synonym not in ns.commands:
+            ns.synonyms[synonym] = canonical
+
+
+def apply_synonyms(root: Namespace, synonyms: list[tuple[str, str]]) -> None:
+    """Recursively apply synonym mappings to a namespace tree.
+
+    For each namespace that has the canonical command and does *not*
+    already define a command with the synonym name, a synonym entry
+    is added.  Existing canonical commands are never overwritten.
+    """
+    _apply_to_namespace(root, synonyms)
+    for child in root.sub_namespaces.values():
+        apply_synonyms(child, synonyms)

kd/cli/core/option_registry.py

@@ -0,0 +1,265 @@
+"""Option declaration and resolution.
+
+Two option layers for kd:
+- COMMAND: command-specific options (--project, --query, --limit)
+- OUTPUT: output formatting options (--output, --fields)
+
+Options are declared per-command and resolved by the parser.
+Global options (--connection, --help, --version, --debug, --reference)
+are handled separately in main.py, outside the layer system.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class OptionLayer(Enum):
+    """Option layers — separates options by concern."""
+
+    GLOBAL = "global"
+    COMMAND = "command"
+    OUTPUT = "output"
+
+
+@dataclass
+class OptionDeclaration:
+    """Metadata for a single CLI option."""
+
+    name: str
+    layer: OptionLayer
+    type: type = str
+    short_name: str | None = None
+    default: Any = None
+    choices: list[str] | None = None
+    required: bool = False
+    help_text: str = ""
+    is_list: bool = False
+    aliases: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ResolvedOptions:
+    """Parsed and validated options, organized by layer."""
+
+    command: dict[str, Any] = field(default_factory=dict)
+    output: dict[str, Any] = field(default_factory=dict)
+
+    def get_layer(self, layer: OptionLayer) -> dict[str, Any]:
+        """Get options dict for a specific layer."""
+        if layer == OptionLayer.COMMAND:
+            return self.command
+        return self.output
+
+
+class OptionRegistry:
+    """Manages option declarations and resolves raw option dicts."""
+
+    def __init__(self) -> None:
+        self._declarations: dict[str, OptionDeclaration] = {}
+        self._short_names: dict[str, str] = {}  # short_name -> full name
+        self._aliases: dict[str, str] = {}  # alias -> canonical name
+
+    def register(self, declaration: OptionDeclaration) -> None:
+        """Register an option declaration."""
+        self._declarations[declaration.name] = declaration
+        if declaration.short_name:
+            self._short_names[declaration.short_name] = declaration.name
+        for alias in declaration.aliases:
+            self._aliases[alias] = declaration.name
+
+    def register_all(self, declarations: list[OptionDeclaration]) -> None:
+        """Register multiple declarations."""
+        for decl in declarations:
+            self.register(decl)
+
+    def get_declaration(self, name: str) -> OptionDeclaration | None:
+        """Look up declaration by name, short name, or alias."""
+        if name in self._declarations:
+            return self._declarations[name]
+        full_name = self._short_names.get(name) or self._aliases.get(name)
+        if full_name:
+            return self._declarations[full_name]
+        return None
+
+    def resolve_name(self, name: str) -> str | None:
+        """Resolve a short name or alias to its canonical name. Returns None if unknown."""
+        if name in self._declarations:
+            return name
+        return self._short_names.get(name) or self._aliases.get(name)
+
+    def is_boolean_flag(self, name: str) -> bool:
+        """Check if an option is a boolean flag (no value expected)."""
+        decl = self.get_declaration(name)
+        return decl is not None and decl.type is bool
+
+    def is_list_option(self, name: str) -> bool:
+        """Check if an option is a repeatable list option."""
+        decl = self.get_declaration(name)
+        return decl is not None and decl.is_list
+
+    def resolve(self, raw: dict[str, Any]) -> ResolvedOptions:
+        """Resolve raw options dict into layered ResolvedOptions.
+
+        Validates types, choices, and required options.
+        Applies defaults for missing options.
+        """
+        result = ResolvedOptions()
+
+        # Apply provided values
+        for raw_name, value in raw.items():
+            full_name = self.resolve_name(raw_name)
+            if full_name is None:
+                raise OptionError(f"Unknown option: --{raw_name}")
+            decl = self._declarations[full_name]
+            validated = self._validate_value(decl, value)
+            result.get_layer(decl.layer)[decl.name] = validated
+
+        # Apply defaults and check required
+        for decl in self._declarations.values():
+            layer_dict = result.get_layer(decl.layer)
+            if decl.name not in layer_dict:
+                if decl.required:
+                    raise OptionError(f"Required option missing: --{decl.name}")
+                if decl.is_list:
+                    layer_dict[decl.name] = []
+                elif decl.default is not None:
+                    layer_dict[decl.name] = decl.default
+
+        return result
+
+    def _validate_value(self, decl: OptionDeclaration, value: Any) -> Any:
+        """Validate and coerce an option value (single or list)."""
+        if decl.is_list:
+            items = value if isinstance(value, list) else [value]
+            return [self._validate_single(decl, v) for v in items]
+        return self._validate_single(decl, value)
+
+    def _validate_single(self, decl: OptionDeclaration, value: Any) -> Any:
+        """Validate and coerce a single option value."""
+        if decl.type is bool:
+            if isinstance(value, bool):
+                return value
+            if isinstance(value, str):
+                if value.lower() in ("true", "1", "yes"):
+                    return True
+                if value.lower() in ("false", "0", "no"):
+                    return False
+            raise OptionError(f"Invalid boolean value for --{decl.name}: {value}")
+
+        if decl.type is int:
+            try:
+                return int(value)
+            except (ValueError, TypeError):
+                raise OptionError(f"Expected integer for --{decl.name}: {value}") from None
+
+        if decl.type is float:
+            try:
+                return float(value)
+            except (ValueError, TypeError):
+                raise OptionError(f"Expected number for --{decl.name}: {value}") from None
+
+        # str type — check choices
+        str_value = str(value)
+        if decl.choices and str_value not in decl.choices:
+            choices_str = ", ".join(decl.choices)
+            raise OptionError(
+                f"Invalid value for --{decl.name}: '{str_value}'. Choose from: {choices_str}"
+            )
+        return str_value
+
+
+class OptionError(Exception):
+    """Raised when option parsing or validation fails."""
+
+
+# ---------------------------------------------------------------------------
+# Shared COMMAND option builders
+# ---------------------------------------------------------------------------
+# Factory functions for recurring options. Commands opt in by calling the
+# builder in _register_options(). Flags and short names are locked; callers
+# may override help_text, required, and default.
+
+
+def project_option(
+    *, help_text: str = "Filter by project key", required: bool = False
+) -> OptionDeclaration:
+    """``--project / -p`` — project key filter."""
+    return OptionDeclaration(
+        name="project",
+        short_name="p",
+        layer=OptionLayer.COMMAND,
+        help_text=help_text,
+        required=required,
+    )
+
+
+def limit_option(
+    *, default: int = 50, help_text: str = "Maximum number of results"
+) -> OptionDeclaration:
+    """``--limit / -l`` — result cap."""
+    return OptionDeclaration(
+        name="limit",
+        short_name="l",
+        layer=OptionLayer.COMMAND,
+        type=int,
+        default=default,
+        help_text=help_text,
+    )
+
+
+def type_option(*, help_text: str = "Issue type (Bug, Task, Feature, etc.)") -> OptionDeclaration:
+    """``--type / -T`` — issue type field."""
+    return OptionDeclaration(
+        name="type",
+        short_name="T",
+        layer=OptionLayer.COMMAND,
+        help_text=help_text,
+    )
+
+
+def priority_option(
+    *, help_text: str = "Priority (Critical, Major, Normal, Minor)"
+) -> OptionDeclaration:
+    """``--priority / -P`` — issue priority field."""
+    return OptionDeclaration(
+        name="priority",
+        short_name="P",
+        layer=OptionLayer.COMMAND,
+        help_text=help_text,
+    )
+
+
+def state_option(
+    *,
+    help_text: str = "State (Submitted, Open, etc.). See: /project/field list KEY --field State",
+) -> OptionDeclaration:
+    """``--state / -S`` — issue state field."""
+    return OptionDeclaration(
+        name="state",
+        short_name="S",
+        layer=OptionLayer.COMMAND,
+        help_text=help_text,
+    )
+
+
+# Standard OUTPUT options available to all commands
+OUTPUT_OPTIONS: list[OptionDeclaration] = [
+    OptionDeclaration(
+        name="output",
+        short_name="o",
+        layer=OptionLayer.OUTPUT,
+        type=str,
+        choices=["table", "json", "yaml", "md"],
+        help_text="Output format (table, json, yaml, md)",
+    ),
+    OptionDeclaration(
+        name="fields",
+        short_name="f",
+        layer=OptionLayer.OUTPUT,
+        type=str,
+        help_text="Comma-separated field list",
+    ),
+]