kctl-react 0.6.2__py3-none-any.whl

kctl_react/core/compliance/api_check/hooks.py

@@ -0,0 +1,133 @@
+"""Parse React hook files for API call patterns."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Matches: apiClient.get<Type>("url") or apiClient.post<Resp, Req>(`url`)
+# Single-line variant
+_API_CALL_RE = re.compile(r"apiClient\.(get|post|put|delete|patch)<([^>]*)>\s*\(\s*[`\"']([^`\"']*)[`\"']")
+# Multi-line variant: captures method and generics on one line, URL on next line
+_API_CALL_MULTILINE_RE = re.compile(r"apiClient\.(get|post|put|delete|patch)<([^>]*)>\s*\(\s*$")
+_URL_LINE_RE = re.compile(r"^\s*[`\"']([^`\"']*)[`\"']")
+
+# Matches template literal interpolations: ${someVar}
+_TEMPLATE_VAR_RE = re.compile(r"\$\{[^}]+\}")
+
+# Matches URLSearchParams .set("key", ...) or searchParams.set("key", ...)
+_SEARCH_PARAM_RE = re.compile(r"\.set\(\s*[\"'](\w+)[\"']")
+
+
+@dataclass
+class HookCall:
+    file: str  # relative path from app root
+    line: int
+    method: str  # get, post, put, delete
+    url: str  # /productions/${id} (raw)
+    normalized_url: str  # /productions/{id}
+    response_type: str | None = None
+    request_type: str | None = None
+    query_params: list[str] = field(default_factory=list)
+
+
+def _normalize_url(url: str) -> str:
+    """Replace template literal variables with OpenAPI-style path params and clean up."""
+    # Strip everything after ? (query string)
+    clean = url.split("?")[0]
+    # Strip template literal ternary/query patterns: ${qs ...}, ${qs}, etc.
+    # This handles: /path${qs ? `?${qs}` : ""}  →  /path
+    clean = re.sub(r"\$\{qs\b.*", "", clean)
+    # Strip any trailing template expressions that look like query strings
+    clean = re.sub(r"\$\{[^}]*qs[^}]*\}.*$", "", clean)
+    # Replace path-segment template vars (e.g., ${id}, ${bomId}) with {id}
+    clean = _TEMPLATE_VAR_RE.sub("{id}", clean)
+    # Normalize trailing slash
+    clean = clean.rstrip("/")
+    return clean
+
+
+def _parse_generics(generics: str) -> tuple[str | None, str | None]:
+    """Parse generic type args like 'ResponseType, RequestType'."""
+    parts = [p.strip() for p in generics.split(",") if p.strip()]
+    response_type = parts[0] if len(parts) >= 1 else None
+    request_type = parts[1] if len(parts) >= 2 else None
+    return response_type, request_type
+
+
+def parse_hooks(app_path: Path) -> list[HookCall]:
+    """Scan hook files for API client calls and return structured results."""
+    api_dir = app_path / "src" / "api"
+    if not api_dir.is_dir():
+        return []
+
+    results: list[HookCall] = []
+
+    for hook_file in sorted(api_dir.glob("use*.ts")):
+        if hook_file.name == "client.ts":
+            continue
+
+        try:
+            content = hook_file.read_text()
+        except OSError:
+            continue
+
+        # Extract query params used across the file
+        file_query_params = _SEARCH_PARAM_RE.findall(content)
+
+        rel_path = str(hook_file.relative_to(app_path))
+        lines = content.splitlines()
+
+        pending_multiline: tuple[int, str, str] | None = None  # (line_num, method, generics)
+
+        for line_num, line in enumerate(lines, start=1):
+            # Check for multi-line continuation from previous line
+            if pending_multiline is not None:
+                url_match = _URL_LINE_RE.search(line)
+                if url_match:
+                    ml_line, method, generics = pending_multiline
+                    url = url_match.group(1)
+                    response_type, request_type = _parse_generics(generics)
+                    normalized = _normalize_url(url)
+                    results.append(
+                        HookCall(
+                            file=rel_path,
+                            line=ml_line,
+                            method=method,
+                            url=url,
+                            normalized_url=normalized,
+                            response_type=response_type,
+                            request_type=request_type,
+                            query_params=file_query_params,
+                        )
+                    )
+                pending_multiline = None
+                continue
+
+            # Single-line matches
+            for match in _API_CALL_RE.finditer(line):
+                method = match.group(1)
+                generics = match.group(2)
+                url = match.group(3)
+                response_type, request_type = _parse_generics(generics)
+                normalized = _normalize_url(url)
+                results.append(
+                    HookCall(
+                        file=rel_path,
+                        line=line_num,
+                        method=method,
+                        url=url,
+                        normalized_url=normalized,
+                        response_type=response_type,
+                        request_type=request_type,
+                        query_params=file_query_params,
+                    )
+                )
+
+            # Check if this line starts a multi-line call
+            ml_match = _API_CALL_MULTILINE_RE.search(line)
+            if ml_match and not _API_CALL_RE.search(line):
+                pending_multiline = (line_num, ml_match.group(1), ml_match.group(2))
+
+    return results

kctl_react/core/compliance/api_check/matcher.py

@@ -0,0 +1,55 @@
+"""Match hook API calls against OpenAPI schema operations."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from .hooks import HookCall
+from .schema import Operation, ParsedSchema
+
+
+@dataclass
+class MatchResult:
+    matched: list[tuple[HookCall, Operation]] = field(default_factory=list)
+    orphan_endpoints: list[Operation] = field(default_factory=list)
+    dead_endpoints: list[HookCall] = field(default_factory=list)
+
+
+_PATH_PARAM_RE = re.compile(r"\{[^}]+\}")
+
+
+def _norm(path: str) -> str:
+    """Normalize path for comparison: strip trailing slash, normalize path params to {id}."""
+    path = path.rstrip("/")
+    path = _PATH_PARAM_RE.sub("{id}", path)
+    return path
+
+
+def match_hooks_to_schema(hooks: list[HookCall], schema: ParsedSchema) -> MatchResult:
+    """Cross-reference hook API calls against OpenAPI schema operations."""
+    # Normalize schema paths for comparison
+    schema_by_key: dict[tuple[str, str], Operation] = {(op.method, _norm(op.path)): op for op in schema.operations}
+    hook_by_key: dict[tuple[str, str], HookCall] = {(h.method, _norm(h.normalized_url)): h for h in hooks}
+
+    schema_keys = set(schema_by_key.keys())
+    hook_keys = set(hook_by_key.keys())
+
+    # Matched: hooks whose (method, normalized_url) matches a schema (method, path)
+    matched: list[tuple[HookCall, Operation]] = []
+    for key in hook_keys & schema_keys:
+        matched.append((hook_by_key[key], schema_by_key[key]))
+
+    # Orphan: schema operations not matched by any hook (GET only)
+    orphan_endpoints = [
+        op for op in schema.operations if op.method == "get" and (op.method, _norm(op.path)) not in hook_keys
+    ]
+
+    # Dead: hook calls not matched by any schema operation
+    dead_endpoints = [h for h in hooks if (h.method, _norm(h.normalized_url)) not in schema_keys]
+
+    return MatchResult(
+        matched=matched,
+        orphan_endpoints=orphan_endpoints,
+        dead_endpoints=dead_endpoints,
+    )

kctl_react/core/compliance/api_check/schema.py

@@ -0,0 +1,151 @@
+"""OpenAPI schema loader and parser."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+APP_BACKEND_MAP = {
+    "sfa": "sfa_management",
+    "lfa": "lfa_management",
+    "shop": "shop_management",
+    "wms": "wms_management",
+    "bia": "bia_management",
+    "eam": "asset_management",
+    "mrp": "mrp_management",
+    "hrm": "hrm_management",
+    "tpm": "tpm_management",
+    "dms": "dms_management",
+    "saas": "saas_management",
+}
+
+
+@dataclass
+class Operation:
+    method: str  # get, post, put, delete
+    path: str  # /productions/{id}
+    tag: str  # mrp-productions
+    response_schema: str | None = None  # ProductionDetailResponse
+    request_schema: str | None = None  # ProduceQuantityRequest
+    parameters: list[str] = field(default_factory=list)  # ["state", "search"]
+
+
+@dataclass
+class ParsedSchema:
+    operations: list[Operation] = field(default_factory=list)
+    response_schemas: dict[str, dict] = field(default_factory=dict)
+
+
+def load_schema(app_path: Path, app_name: str, *, offline: bool = False) -> dict | None:
+    """Load OpenAPI schema from cache or fetch from backend."""
+    cached = app_path / "openapi.json"
+    if cached.exists():
+        try:
+            return json.loads(cached.read_text())
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.warning("Failed to read cached schema: %s", exc)
+
+    if offline:
+        return None
+
+    return fetch_schema(app_path, app_name)
+
+
+def fetch_schema(app_path: Path, app_name: str) -> dict | None:
+    """Fetch OpenAPI schema from the Odoo backend and cache it."""
+    odoo_url = "http://localhost:8069"
+    odoo_db = "odoo_18"
+
+    env_file = app_path / ".env"
+    if env_file.exists():
+        try:
+            content = env_file.read_text()
+            url_match = re.search(r"VITE_ODOO_URL\s*=\s*(.+)", content)
+            if url_match:
+                odoo_url = url_match.group(1).strip().strip("\"'")
+            db_match = re.search(r"VITE_ODOO_DB\s*=\s*(.+)", content)
+            if db_match:
+                odoo_db = db_match.group(1).strip().strip("\"'")
+        except OSError as exc:
+            logger.warning("Failed to read .env: %s", exc)
+
+    backend_name = APP_BACKEND_MAP.get(app_name)
+    if not backend_name:
+        logger.warning("Unknown app %r — no backend mapping", app_name)
+        return None
+
+    url = f"{odoo_url}/{backend_name}/api/openapi.json?db={odoo_db}"
+
+    try:
+        resp = httpx.get(url, timeout=10)
+        resp.raise_for_status()
+        data = resp.json()
+    except (httpx.HTTPError, json.JSONDecodeError) as exc:
+        logger.warning("Failed to fetch schema from %s: %s", url, exc)
+        return None
+
+    try:
+        (app_path / "openapi.json").write_text(json.dumps(data, indent=2))
+    except OSError as exc:
+        logger.warning("Failed to cache schema: %s", exc)
+
+    return data
+
+
+def _extract_ref_name(ref: str) -> str:
+    """Extract schema name from a $ref string like '#/components/schemas/Foo'."""
+    return ref.rsplit("/", 1)[-1]
+
+
+def parse_schema(raw: dict) -> ParsedSchema:
+    """Parse a raw OpenAPI JSON dict into structured operations."""
+    operations: list[Operation] = []
+
+    for path, methods in raw.get("paths", {}).items():
+        for method in ("get", "post", "put", "delete", "patch"):
+            operation = methods.get(method)
+            if operation is None:
+                continue
+
+            tag = operation.get("tags", ["unknown"])[0]
+
+            # Response schema
+            response_schema: str | None = None
+            resp_200 = operation.get("responses", {}).get("200", {})
+            resp_content = resp_200.get("content", {}).get("application/json", {})
+            resp_schema_obj = resp_content.get("schema", {})
+            if "$ref" in resp_schema_obj:
+                response_schema = _extract_ref_name(resp_schema_obj["$ref"])
+
+            # Request schema
+            request_schema: str | None = None
+            req_body = operation.get("requestBody", {})
+            req_content = req_body.get("content", {}).get("application/json", {})
+            req_schema_obj = req_content.get("schema", {})
+            if "$ref" in req_schema_obj:
+                request_schema = _extract_ref_name(req_schema_obj["$ref"])
+
+            # Parameters
+            parameters = [p["name"] for p in operation.get("parameters", []) if "name" in p]
+
+            operations.append(
+                Operation(
+                    method=method,
+                    path=path,
+                    tag=tag,
+                    response_schema=response_schema,
+                    request_schema=request_schema,
+                    parameters=parameters,
+                )
+            )
+
+    response_schemas = raw.get("components", {}).get("schemas", {})
+
+    return ParsedSchema(operations=operations, response_schemas=response_schemas)

kctl_react/core/compliance/api_health/__init__.py

@@ -0,0 +1,35 @@
+"""API health: runtime endpoint validation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from kctl_react.core.compliance.api_check.schema import Operation
+
+from .client import HealthClient
+
+
+@dataclass
+class EndpointResult:
+    """Result of hitting a single endpoint."""
+
+    operation: Operation
+    status_code: int
+    body: dict | None
+    elapsed: float
+
+
+def run_health_checks(client: HealthClient, endpoints: list[Operation]) -> list[EndpointResult]:
+    """Hit each endpoint once, return results for all checkers to use."""
+    results: list[EndpointResult] = []
+    for op in endpoints:
+        status, body, elapsed = client.get(op.path)
+        results.append(
+            EndpointResult(
+                operation=op,
+                status_code=status,
+                body=body,
+                elapsed=elapsed,
+            )
+        )
+    return results

kctl_react/core/compliance/api_health/checks/__init__.py

@@ -0,0 +1,9 @@
+"""API health check registry — all 4 checkers."""
+
+from .auth import AuthChecker
+from .reachable import ReachableChecker
+from .response import ResponseChecker
+from .timing import TimingChecker
+
+ALL_HEALTH_CHECKERS = [AuthChecker(), ReachableChecker(), ResponseChecker(), TimingChecker()]
+CHECKER_MAP = {c.name: c for c in ALL_HEALTH_CHECKERS}

kctl_react/core/compliance/api_health/checks/auth.py

@@ -0,0 +1,72 @@
+"""Auth validation checker."""
+
+from __future__ import annotations
+
+from kctl_react.core.compliance.api_check.schema import ParsedSchema
+from kctl_react.core.compliance.api_health.client import HealthClient
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class AuthChecker:
+    name = "auth"
+    label = "Auth"
+    max_points = 10
+
+    def check(self, client: HealthClient, schema: ParsedSchema) -> CategoryResult:
+        """Check /auth/me returns valid response.
+
+        If no token and authenticate() fails -> violation.
+        If /auth/me returns non-200 -> violation.
+        If /auth/me response missing success/data -> violation.
+        """
+        violations: list[Violation] = []
+
+        if not client.token:
+            violations.append(
+                Violation(
+                    file="runtime",
+                    message="No auth token available — dev-login failed or was not attempted",
+                    fix_hint="Ensure VITE_DEV_USER/VITE_DEV_PASSWORD are set in .env or backend accepts admin/admin",
+                )
+            )
+            return CategoryResult(
+                name=self.name,
+                label=self.label,
+                max_points=self.max_points,
+                violations=violations,
+            )
+
+        status, body, _elapsed = client.get("/auth/me")
+
+        if status != 200:
+            violations.append(
+                Violation(
+                    file="runtime",
+                    message=f"GET /auth/me returned {status}",
+                    fix_hint="Check auth token validity and /auth/me endpoint",
+                )
+            )
+        elif body is not None:
+            if not body.get("success"):
+                violations.append(
+                    Violation(
+                        file="runtime",
+                        message="GET /auth/me response missing 'success: true'",
+                        fix_hint="Ensure /auth/me returns {success: true, data: ...}",
+                    )
+                )
+            if "data" not in body:
+                violations.append(
+                    Violation(
+                        file="runtime",
+                        message="GET /auth/me response missing 'data' key",
+                        fix_hint="Ensure /auth/me returns {success: true, data: ...}",
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/api_health/checks/reachable.py

@@ -0,0 +1,44 @@
+"""Endpoint reachability checker."""
+
+from __future__ import annotations
+
+from kctl_react.core.compliance.api_health import EndpointResult
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class ReachableChecker:
+    name = "reachable"
+    label = "Endpoints Reachable"
+    max_points = 10
+
+    def check(self, results: list[EndpointResult]) -> CategoryResult:
+        """Hit each sampled endpoint. Violations for non-200 responses.
+
+        Message: "GET {path} returned {status}" or "GET {path} connection error".
+        """
+        violations: list[Violation] = []
+
+        for r in results:
+            if r.status_code == 0:
+                violations.append(
+                    Violation(
+                        file="runtime",
+                        message=f"GET {r.operation.path} connection error",
+                        fix_hint="Check that the backend is running and reachable",
+                    )
+                )
+            elif r.status_code != 200:
+                violations.append(
+                    Violation(
+                        file="runtime",
+                        message=f"GET {r.operation.path} returned {r.status_code}",
+                        fix_hint="Check endpoint implementation and auth",
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/api_health/checks/response.py

@@ -0,0 +1,55 @@
+"""Response envelope validation checker."""
+
+from __future__ import annotations
+
+from kctl_react.core.compliance.api_health import EndpointResult
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class ResponseChecker:
+    name = "response"
+    label = "Response Valid"
+    max_points = 5
+
+    def check(self, results: list[EndpointResult]) -> CategoryResult:
+        """For each sampled endpoint that returned 200, check response body has {success, data}.
+
+        Violation if success is not True or data key is missing.
+        """
+        violations: list[Violation] = []
+
+        for r in results:
+            if r.status_code != 200:
+                continue
+            if r.body is None:
+                violations.append(
+                    Violation(
+                        file="runtime",
+                        message=f"GET {r.operation.path} returned non-JSON body",
+                        fix_hint="Ensure endpoint returns JSON with {success, data}",
+                    )
+                )
+                continue
+            if not r.body.get("success"):
+                violations.append(
+                    Violation(
+                        file="runtime",
+                        message=f"GET {r.operation.path} response missing 'success: true'",
+                        fix_hint="Ensure response envelope has success: true",
+                    )
+                )
+            if "data" not in r.body:
+                violations.append(
+                    Violation(
+                        file="runtime",
+                        message=f"GET {r.operation.path} response missing 'data' key",
+                        fix_hint="Ensure response envelope has data key",
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/api_health/checks/timing.py

@@ -0,0 +1,38 @@
+"""Response time checker."""
+
+from __future__ import annotations
+
+from kctl_react.core.compliance.api_health import EndpointResult
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class TimingChecker:
+    name = "timing"
+    label = "Response Time"
+    max_points = 5
+
+    def check(self, results: list[EndpointResult], threshold: float = 3.0) -> CategoryResult:
+        """Flag endpoints slower than threshold.
+
+        Message: "GET {path} took {elapsed:.1f}s (threshold: {threshold}s)".
+        """
+        violations: list[Violation] = []
+
+        for r in results:
+            if r.status_code == 0:
+                continue  # connection error — already flagged by reachable
+            if r.elapsed > threshold:
+                violations.append(
+                    Violation(
+                        file="runtime",
+                        message=f"GET {r.operation.path} took {r.elapsed:.1f}s (threshold: {threshold}s)",
+                        fix_hint="Optimize endpoint performance or increase timeout",
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )