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

apisec_code_bolt/frameworks/dotnet/refit_plugin.py

@@ -0,0 +1,374 @@
+"""
+Refit framework plugin.
+
+Refit is a declarative REST client library for .NET — interfaces annotated with
+HTTP verb attributes are auto-implemented as typed HTTP clients at runtime.
+These represent *outbound* call surface (what the app calls), analogous to
+Spring's @FeignClient.
+
+Supports:
+- HTTP verbs: [Get], [Post], [Put], [Delete], [Patch], [Head], [Options]
+- Path parameters: method parameters whose names match {template} segments
+- Query parameters: [Query] / [AliasAs] or undecorated primitives outside path
+- Request body: [Body] or undecorated complex type (Refit default inference)
+- Header parameters: [Header("X-Custom")]
+- [Multipart] methods: body treated as multipart/form-data
+- Interface-level and method-level [Headers(...)] static header constants
+- RestService.For<T>() / RefitClient.For<T>() registration detection
+
+Routes are emitted with kind="refit_client" and tags=["refit"].
+"""
+
+from __future__ import annotations
+
+import re
+from typing import ClassVar
+
+from ...core.types import (
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    ParameterLocation,
+)
+from ...parsing.base import ParsedClass, ParsedFile, ParsedFunction
+from ...parsing.services import AnalysisContext
+from ..base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedBody,
+    ExtractedDependency,
+    ExtractedMiddleware,
+    ExtractedParameter,
+    ExtractedResponse,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+)
+from .aspnet_plugin import AspNetCorePlugin, _str_to_qname
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+_REFIT_IMPORTS: frozenset[str] = frozenset(
+    {
+        "Refit",
+        "Refit.Attributes",
+    }
+)
+
+# Refit HTTP verb attribute name → HttpMethod
+_REFIT_VERBS: dict[str, HttpMethod] = {
+    "Get": HttpMethod.GET,
+    "Post": HttpMethod.POST,
+    "Put": HttpMethod.PUT,
+    "Delete": HttpMethod.DELETE,
+    "Patch": HttpMethod.PATCH,
+    "Head": HttpMethod.HEAD,
+    "Options": HttpMethod.OPTIONS,
+}
+
+# Scalar C# type names — undecorated scalars outside the path template become
+# query params (Refit's default).  Complex types become the body.
+_SCALAR_TYPES: frozenset[str] = frozenset(
+    {
+        "bool",
+        "Boolean",
+        "byte",
+        "Byte",
+        "sbyte",
+        "SByte",
+        "char",
+        "Char",
+        "short",
+        "Int16",
+        "ushort",
+        "UInt16",
+        "int",
+        "Int32",
+        "uint",
+        "UInt32",
+        "long",
+        "Int64",
+        "ulong",
+        "UInt64",
+        "float",
+        "Single",
+        "double",
+        "Double",
+        "decimal",
+        "Decimal",
+        "string",
+        "String",
+        "Guid",
+        "DateTime",
+        "DateTimeOffset",
+        "DateOnly",
+        "TimeOnly",
+        "TimeSpan",
+        "Uri",
+        "int?",
+        "long?",
+        "bool?",
+        "double?",
+        "decimal?",
+        "Guid?",
+        "DateTime?",
+        "DateTimeOffset?",
+        "CancellationToken",  # always skipped
+    }
+)
+
+
+# =============================================================================
+# RefitPlugin
+# =============================================================================
+
+
+class RefitPlugin(BaseFrameworkPlugin):
+    """
+    Framework plugin for Refit declarative HTTP client interfaces.
+
+    Each interface method carrying a Refit HTTP verb attribute is emitted as
+    an ExtractedRoute with kind="refit_client".
+    """
+
+    FRAMEWORK: ClassVar[Framework] = Framework.REFIT
+    LANGUAGE: ClassVar[Language] = Language.CSHARP
+    DETECTION_IMPORTS: ClassVar[frozenset[str]] = _REFIT_IMPORTS
+
+    # Reuse path helpers from AspNetCorePlugin without inheriting its
+    # controller/MVC logic.
+    _helper = AspNetCorePlugin()
+
+    # -------------------------------------------------------------------------
+    # Detection
+    # -------------------------------------------------------------------------
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        for imp in parsed_file.imports:
+            if (imp.module or "").startswith("Refit"):
+                return True
+        # Attribute-only detection (no using statement but attributes present)
+        for cls in parsed_file.classes:
+            for method in cls.methods:
+                if any(dec.name in _REFIT_VERBS for dec in method.decorators):
+                    return True
+        return False
+
+    # -------------------------------------------------------------------------
+    # Route extraction
+    # -------------------------------------------------------------------------
+
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedRoute]:
+        routes: list[ExtractedRoute] = []
+
+        for cls in parsed_file.classes:
+            if not self._has_refit_methods(cls):
+                continue
+
+            for method in cls.methods:
+                route = self._extract_refit_route(method, cls)
+                if route:
+                    routes.append(route)
+
+        return routes
+
+    # Refit interfaces define outbound HTTP clients only — no server-side auth,
+    # middleware, or DI definitions to extract.
+
+    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
+    ) -> list[ExtractedAuthDependency]:
+        return []
+
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[ExtractedDependency]:
+        return []
+
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[ExtractedMiddleware]:
+        return []
+
+    # -------------------------------------------------------------------------
+    # Internal helpers
+    # -------------------------------------------------------------------------
+
+    def _has_refit_methods(self, cls: ParsedClass) -> bool:
+        return any(dec.name in _REFIT_VERBS for method in cls.methods for dec in method.decorators)
+
+    def _extract_refit_route(
+        self, method: ParsedFunction, cls: ParsedClass
+    ) -> ExtractedRoute | None:
+        http_method: HttpMethod | None = None
+        path_template: str = ""
+
+        for dec in method.decorators:
+            hm = _REFIT_VERBS.get(dec.name)
+            if hm is not None:
+                http_method = hm
+                raw = self._helper._dec_path(dec) or ""
+                path_template = raw
+                break
+
+        if http_method is None:
+            return None
+
+        # Normalise path
+        if path_template and not path_template.startswith("/"):
+            path_template = "/" + path_template
+        path_template = self._helper._normalize_path(path_template) if path_template else "/"
+
+        # Strip route constraints: {id:int} → {id}
+        path_template = re.sub(r"\{([^:}]+):[^}]+\}", r"{\1}", path_template)
+
+        path_tpl_names = {m.group(1) for m in re.finditer(r"\{([^}]+)\}", path_template)}
+
+        is_multipart = any(dec.name == "Multipart" for dec in method.decorators)
+
+        path_params: list[ExtractedParameter] = []
+        query_params: list[ExtractedParameter] = []
+        header_params: list[ExtractedParameter] = []
+        body: ExtractedBody | None = None
+
+        for param in method.parameters:
+            # CancellationToken is always a framework param — skip
+            base_type = (param.type_annotation or "").split("<")[0].strip().rstrip("?")
+            if base_type == "CancellationToken":
+                continue
+
+            # Parameter attributes are in param.metadata (keyed by attribute name).
+            # Values: positional string arg, or True for no-arg attributes.
+            meta = param.metadata or {}
+
+            # [AliasAs("name")] renames the parameter in the request
+            alias_val = meta.get("AliasAs")
+            alias = alias_val if isinstance(alias_val, str) else param.name
+
+            # [Header("X-Custom")] → explicit header parameter
+            if "Header" in meta:
+                header_name = meta["Header"] if isinstance(meta["Header"], str) else param.name
+                header_params.append(
+                    ExtractedParameter(
+                        name=header_name,
+                        location=ParameterLocation.HEADER,
+                        type_annotation=param.type_annotation,
+                        required=True,
+                        code_location=param.location,
+                    )
+                )
+                continue
+
+            # [Body] → request body
+            if "Body" in meta:
+                if body is None:
+                    content_type = "multipart/form-data" if is_multipart else "application/json"
+                    body = ExtractedBody(
+                        content_type=content_type,
+                        model_name=param.type_annotation,
+                        required=True,
+                    )
+                continue
+
+            # Path parameter: param name (or alias) matches a {template} segment
+            if alias in path_tpl_names or param.name in path_tpl_names:
+                matched_name = param.name if param.name in path_tpl_names else alias
+                path_params.append(
+                    ExtractedParameter(
+                        name=matched_name,
+                        location=ParameterLocation.PATH,
+                        type_annotation=param.type_annotation,
+                        required=True,
+                        code_location=param.location,
+                    )
+                )
+                continue
+
+            # [Query] or [AliasAs] → explicit query param
+            if "Query" in meta or "AliasAs" in meta:
+                query_params.append(
+                    ExtractedParameter(
+                        name=alias,
+                        location=ParameterLocation.QUERY,
+                        type_annotation=param.type_annotation,
+                        required=param.default_value is None and param.default_value != "null",
+                        default_value=param.default_value,
+                        code_location=param.location,
+                    )
+                )
+                continue
+
+            # Undecorated: scalar → query, complex → body
+            if self._is_scalar(param.type_annotation):
+                query_params.append(
+                    ExtractedParameter(
+                        name=param.name,
+                        location=ParameterLocation.QUERY,
+                        type_annotation=param.type_annotation,
+                        required=param.default_value is None and param.default_value != "null",
+                        default_value=param.default_value,
+                        code_location=param.location,
+                    )
+                )
+            else:
+                if body is None:
+                    content_type = "multipart/form-data" if is_multipart else "application/json"
+                    body = ExtractedBody(
+                        content_type=content_type,
+                        model_name=param.type_annotation,
+                        required=True,
+                    )
+
+        return ExtractedRoute(
+            method=http_method,
+            path=path_template,
+            handler_function=_str_to_qname(f"{cls.name}.{method.name}"),
+            handler_location=method.location,
+            path_params=path_params,
+            query_params=query_params,
+            header_params=header_params,
+            cookie_params=[],
+            body=body,
+            response=ExtractedResponse(
+                status_code=200,
+                model_name=self._extract_return_type(method),
+            ),
+            tags=["refit"],
+            dependency_refs=[],
+            confidence=Confidence.HIGH,
+            kind="refit_client",
+        )
+
+    # -------------------------------------------------------------------------
+    # Helpers
+    # -------------------------------------------------------------------------
+
+    def _is_scalar(self, type_annotation: str | None) -> bool:
+        if not type_annotation:
+            return True
+        base = type_annotation.split("<")[0].strip().rstrip("?")
+        return base in _SCALAR_TYPES
+
+    def _extract_return_type(self, method: ParsedFunction) -> str | None:
+        """
+        Extract the inner model type from Task<T> or IObservable<T> return.
+        e.g. Task<List<User>> → List<User>, Task<User> → User, Task → None
+        """
+        ret = method.return_type or ""
+        # Unwrap Task<> / IObservable<> / ValueTask<>
+        for wrapper in ("Task<", "IObservable<", "ValueTask<", "ApiResponse<"):
+            if ret.startswith(wrapper) and ret.endswith(">"):
+                inner = ret[len(wrapper) : -1].strip()
+                return inner if inner else None
+        return None
+
+
+# Self-registration
+_refit_plugin = RefitPlugin()
+FrameworkPluginRegistry.register(_refit_plugin)