apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/frameworks/python/click_plugin.py

@@ -0,0 +1,427 @@
+"""
+Click and Typer CLI framework plugin.
+
+Detects CLI command entry points from Click and Typer decorator patterns.
+
+Supported constructs:
+- @click.command() / @click.group() — standalone commands and groups
+- @app.command() / @grp.command() — commands registered on groups
+- @click.option() / @click.argument() — parameter decorators
+- @click.password_option() — sensitive input patterns
+- @click.pass_context / @click.pass_obj — context injection (skipped in params)
+- Typer @app.command() / @app.callback() — Typer command patterns
+- Typer function parameter defaults (typer.Option, typer.Argument)
+
+Not supported (yet):
+- Dynamic command registration via group.add_command()
+- click.MultiCommand subclasses
+- Lazy-loaded command groups
+- Complex group nesting hierarchy reconstruction
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ...core.types import (
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    ParameterLocation,
+)
+from ...parsing.base import ParsedDecorator, ParsedFile, ParsedFunction, ParsedParameter
+from ..base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedDependency,
+    ExtractedMiddleware,
+    ExtractedParameter,
+    ExtractedResponse,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+)
+
+CLICK_IMPORTS = frozenset({"click", "typer"})
+
+# Decorators that mark a function as a CLI command entry point.
+COMMAND_DECORATORS: set[str] = {
+    "command",
+    "group",
+    "callback",
+    "click.command",
+    "click.group",
+    "typer.command",
+}
+
+# Decorators that define CLI parameters (options/arguments).
+OPTION_DECORATORS: set[str] = {
+    "option",
+    "click.option",
+    "password_option",
+    "click.password_option",
+}
+
+ARGUMENT_DECORATORS: set[str] = {
+    "argument",
+    "click.argument",
+}
+
+# Decorators that inject Click context objects — the first function parameter
+# they introduce should be skipped during parameter extraction.
+CONTEXT_DECORATORS: set[str] = {
+    "pass_context",
+    "click.pass_context",
+    "pass_obj",
+    "click.pass_obj",
+}
+
+# Suffixes stripped from function names when deriving the CLI command path.
+_COMMAND_SUFFIXES = ("_command", "_cmd", "_group", "_grp")
+
+_CLI_ARGUMENT_LOCATION = ParameterLocation.CLI_ARGUMENT
+_CLI_OPTION_LOCATION = ParameterLocation.CLI_OPTION
+
+_STRIP_DASHES_RE = re.compile(r"^-+")
+
+
+def _derive_command_name(func_name: str) -> str:
+    """Derive a CLI command name from a Python function name.
+
+    Applies Click's default naming convention: lowercase, underscores become
+    dashes, and common command/group suffixes are stripped.
+    """
+    name = func_name.lower()
+    for suffix in _COMMAND_SUFFIXES:
+        if name.endswith(suffix):
+            name = name[: -len(suffix)]
+            break
+    return name.replace("_", "-")
+
+
+def _option_name_from_decls(decls: list[Any]) -> str:
+    """Extract the canonical option name from param_decls.
+
+    Click param_decls are like ("--verbose", "-v").  We pick the longest
+    long-option string, strip leading dashes, and normalise.
+    """
+    long_opts = [_STRIP_DASHES_RE.sub("", str(d)) for d in decls if str(d).startswith("--")]
+    if long_opts:
+        return max(long_opts, key=len).replace("-", "_")
+    # Fall back to the first positional decl.
+    if decls:
+        return _STRIP_DASHES_RE.sub("", str(decls[0])).replace("-", "_")
+    return "unknown"
+
+
+def _argument_name_from_decls(decls: list[Any]) -> str:
+    """Extract argument name from param_decls (usually a single positional)."""
+    if decls:
+        return str(decls[0]).strip().replace("-", "_")
+    return "unknown"
+
+
+class ClickPlugin(BaseFrameworkPlugin):
+    """Plugin for Click and Typer CLI framework extraction."""
+
+    FRAMEWORK = Framework.CLICK
+    LANGUAGE = Language.PYTHON
+    DETECTION_IMPORTS = CLICK_IMPORTS
+
+    # ------------------------------------------------------------------
+    # Detection
+    # ------------------------------------------------------------------
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        for imp in parsed_file.imports:
+            mod = (imp.module or "").split(".")[0]
+            if mod in ("click", "typer"):
+                return True
+            for name in imp.names:
+                if name in ("click", "typer", "Typer"):
+                    return True
+        return False
+
+    # ------------------------------------------------------------------
+    # Route / command extraction
+    # ------------------------------------------------------------------
+
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: Any = None,
+    ) -> list[ExtractedRoute]:
+        routes: list[ExtractedRoute] = []
+
+        for func in parsed_file.functions:
+            route = self._try_extract_command(func)
+            if route:
+                routes.append(route)
+
+        for cls in parsed_file.classes:
+            for method in cls.methods:
+                route = self._try_extract_command(method)
+                if route:
+                    routes.append(route)
+
+        return routes
+
+    # ------------------------------------------------------------------
+    # Stubs — CLI frameworks have no HTTP-level dependency/auth/middleware
+    # ------------------------------------------------------------------
+
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[ExtractedDependency]:
+        return []
+
+    def extract_auth_schemes(self, parsed_file: ParsedFile) -> list[ExtractedAuthScheme]:
+        return []
+
+    def extract_auth_dependencies(
+        self,
+        parsed_file: ParsedFile,
+        known_scheme_names: set[str] | None = None,
+        **kwargs: Any,
+    ) -> list[ExtractedAuthDependency]:
+        return []
+
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[ExtractedMiddleware]:
+        return []
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _try_extract_command(self, func: ParsedFunction) -> ExtractedRoute | None:
+        """If *func* is decorated as a Click/Typer command, return an ExtractedRoute."""
+        cmd_dec = self._find_command_decorator(func)
+        if cmd_dec is None:
+            return None
+
+        command_name = self._resolve_command_name(cmd_dec, func.name)
+        has_ctx = self._has_context_decorator(func)
+        params = self._extract_parameters(func, has_ctx)
+
+        return ExtractedRoute(
+            kind="cli",
+            method=HttpMethod.GET,
+            path=command_name,
+            handler_function=func.qualified_name,
+            handler_location=func.location,
+            query_params=[p for p in params if p.location == _CLI_OPTION_LOCATION],
+            path_params=[p for p in params if p.location == _CLI_ARGUMENT_LOCATION],
+            header_params=[],
+            cookie_params=[],
+            body=None,
+            response=ExtractedResponse(),
+            confidence=Confidence.HIGH,
+        )
+
+    def _find_command_decorator(self, func: ParsedFunction) -> ParsedDecorator | None:
+        """Return the first command/group/callback decorator on *func*."""
+        for dec in func.decorators:
+            base = self._decorator_base_name(dec)
+            if base in COMMAND_DECORATORS:
+                return dec
+        return None
+
+    def _has_context_decorator(self, func: ParsedFunction) -> bool:
+        for dec in func.decorators:
+            base = self._decorator_base_name(dec)
+            if base in CONTEXT_DECORATORS:
+                return True
+        return False
+
+    def _resolve_command_name(self, dec: ParsedDecorator, func_name: str) -> str:
+        """Get the CLI command path from the decorator or function name."""
+        explicit = self._extract_decorator_arg(dec, "name")
+        if explicit and isinstance(explicit, str):
+            return explicit
+        if dec.positional_args:
+            first = dec.positional_args[0]
+            if isinstance(first, str) and not first.startswith("-"):
+                return first
+        return _derive_command_name(func_name)
+
+    # ---- parameter extraction ----
+
+    def _extract_parameters(
+        self,
+        func: ParsedFunction,
+        has_ctx: bool,
+    ) -> list[ExtractedParameter]:
+        """Extract CLI parameters from decorators and function signature."""
+        params: list[ExtractedParameter] = []
+        decorator_param_names: set[str] = set()
+
+        for dec in func.decorators:
+            base = self._decorator_base_name(dec)
+
+            if base in OPTION_DECORATORS:
+                ep = self._param_from_option_decorator(dec, base)
+                params.append(ep)
+                decorator_param_names.add(ep.name)
+
+            elif base in ARGUMENT_DECORATORS:
+                ep = self._param_from_argument_decorator(dec)
+                params.append(ep)
+                decorator_param_names.add(ep.name)
+
+        # Infer remaining function parameters not covered by decorators.
+        params.extend(
+            self._infer_params_from_signature(
+                func.parameters,
+                decorator_param_names,
+                has_ctx,
+            )
+        )
+
+        return params
+
+    def _param_from_option_decorator(
+        self,
+        dec: ParsedDecorator,
+        base_name: str,
+    ) -> ExtractedParameter:
+        if base_name in ("password_option", "click.password_option"):
+            name = (
+                _option_name_from_decls(dec.positional_args) if dec.positional_args else "password"
+            )
+        else:
+            name = (
+                _option_name_from_decls(dec.positional_args) if dec.positional_args else "unknown"
+            )
+
+        required = dec.arguments.get("required", False)
+        default = dec.arguments.get("default")
+        type_hint = dec.arguments.get("type")
+
+        return ExtractedParameter(
+            name=name,
+            location=_CLI_OPTION_LOCATION,
+            type_annotation=str(type_hint) if type_hint is not None else None,
+            required=bool(required),
+            default_value=str(default) if default is not None else None,
+        )
+
+    def _param_from_argument_decorator(self, dec: ParsedDecorator) -> ExtractedParameter:
+        name = _argument_name_from_decls(dec.positional_args) if dec.positional_args else "unknown"
+        required = dec.arguments.get("required", True)
+        default = dec.arguments.get("default")
+        type_hint = dec.arguments.get("type")
+
+        return ExtractedParameter(
+            name=name,
+            location=_CLI_ARGUMENT_LOCATION,
+            type_annotation=str(type_hint) if type_hint is not None else None,
+            required=bool(required),
+            default_value=str(default) if default is not None else None,
+        )
+
+    def _infer_params_from_signature(
+        self,
+        parameters: list[ParsedParameter],
+        already_extracted: set[str],
+        has_ctx: bool,
+    ) -> list[ExtractedParameter]:
+        """Infer CLI params from the function signature.
+
+        Handles Typer-style defaults (``typer.Option(...)``, ``typer.Argument(...)``).
+        """
+        results: list[ExtractedParameter] = []
+        skip_first = has_ctx
+
+        for param in parameters:
+            if param.is_variadic or param.is_keyword_variadic:
+                continue
+            if skip_first:
+                skip_first = False
+                continue
+            if param.name in already_extracted:
+                continue
+            if param.name in ("self", "cls"):
+                continue
+
+            default = param.default_value
+            if default and "typer.Option" in default:
+                results.append(
+                    ExtractedParameter(
+                        name=param.name,
+                        location=_CLI_OPTION_LOCATION,
+                        type_annotation=param.type_annotation,
+                        required=False,
+                        default_value=None,
+                    )
+                )
+            elif default and "typer.Argument" in default or default is None:
+                results.append(
+                    ExtractedParameter(
+                        name=param.name,
+                        location=_CLI_ARGUMENT_LOCATION,
+                        type_annotation=param.type_annotation,
+                        required=True,
+                        default_value=None,
+                    )
+                )
+            else:
+                results.append(
+                    ExtractedParameter(
+                        name=param.name,
+                        location=_CLI_OPTION_LOCATION,
+                        type_annotation=param.type_annotation,
+                        required=False,
+                        default_value=default,
+                    )
+                )
+
+        return results
+
+    # ---- decorator name helpers ----
+
+    @staticmethod
+    def _decorator_base_name(dec: ParsedDecorator) -> str:
+        """Normalise a decorator to a lookup key.
+
+        Handles both ``click.command`` (qualified) and ``command`` (bare import)
+        as well as ``app.command`` / ``grp.group`` attribute forms.
+        """
+        if dec.qualified_name:
+            qn = dec.qualified_name.full
+            parts = qn.rsplit(".", 1)
+            if len(parts) == 2:
+                mod, attr = parts
+                if mod in ("click", "typer"):
+                    return f"{mod}.{attr}"
+                if attr in (
+                    "command",
+                    "group",
+                    "callback",
+                    "option",
+                    "argument",
+                    "password_option",
+                    "pass_context",
+                    "pass_obj",
+                ):
+                    return attr
+            return qn
+
+        name = dec.name
+        if "." in name:
+            _obj, _, attr = name.rpartition(".")
+            if attr in (
+                "command",
+                "group",
+                "callback",
+                "option",
+                "argument",
+                "password_option",
+                "pass_context",
+                "pass_obj",
+            ):
+                return attr
+        return name
+
+
+_click_plugin = ClickPlugin()
+FrameworkPluginRegistry.register(_click_plugin)