kctl-react 0.6.2__py3-none-any.whl

kctl_react/core/compliance/api_health/client.py

@@ -0,0 +1,99 @@
+"""HTTP client for API health checks."""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HealthClient:
+    base_url: str
+    token: str | None = None
+    timeout: float = 3.0
+    rate_limit: float = 0.2  # seconds between requests
+    _last_request: float = field(default=0.0, repr=False)
+
+    def authenticate(self, app_path: Path, app_name: str) -> bool:
+        """Try dev-login. Read VITE_DEV_USER/VITE_DEV_PASSWORD from .env if available.
+
+        Fallback: try POST /auth/dev-login with admin/admin.
+        Store token if successful. Return True/False.
+        """
+        username = "admin"
+        password = "admin"
+
+        env_file = app_path / ".env"
+        if env_file.exists():
+            try:
+                content = env_file.read_text()
+                user_match = re.search(r"VITE_DEV_USER\s*=\s*(.+)", content)
+                if user_match:
+                    username = user_match.group(1).strip().strip("\"'")
+                pass_match = re.search(r"VITE_DEV_PASSWORD\s*=\s*(.+)", content)
+                if pass_match:
+                    password = pass_match.group(1).strip().strip("\"'")
+            except OSError as exc:
+                logger.warning("Failed to read .env: %s", exc)
+
+        try:
+            resp = httpx.post(
+                f"{self.base_url}/auth/dev-login",
+                json={"username": username, "password": password},
+                timeout=self.timeout,
+            )
+            if resp.status_code == 200:
+                data = resp.json()
+                if data.get("success") and data.get("data", {}).get("access_token"):
+                    self.token = data["data"]["access_token"]
+                    return True
+        except (httpx.HTTPError, ValueError) as exc:
+            logger.warning("Dev-login failed: %s", exc)
+
+        return False
+
+    def get(self, path: str) -> tuple[int, dict | None, float]:
+        """GET endpoint with auth header and rate limiting.
+
+        Returns (status_code, response_body_or_None, elapsed_seconds).
+        Handles httpx errors gracefully (return 0, None, 0.0 for connection errors).
+        """
+        self._rate_limit()
+        try:
+            start = time.monotonic()
+            resp = httpx.get(
+                f"{self.base_url}{path}",
+                headers=self._headers(),
+                timeout=self.timeout,
+            )
+            elapsed = time.monotonic() - start
+            self._last_request = time.monotonic()
+            try:
+                body = resp.json()
+            except ValueError:
+                body = None
+            return resp.status_code, body, elapsed
+        except httpx.HTTPError as exc:
+            logger.warning("GET %s failed: %s", path, exc)
+            return 0, None, 0.0
+
+    def _headers(self) -> dict[str, str]:
+        """Return headers with Authorization: Bearer {token} if token set."""
+        headers: dict[str, str] = {}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def _rate_limit(self) -> None:
+        """Sleep if needed to respect rate_limit interval."""
+        if self._last_request > 0:
+            elapsed = time.monotonic() - self._last_request
+            if elapsed < self.rate_limit:
+                time.sleep(self.rate_limit - elapsed)

kctl_react/core/compliance/api_health/sampler.py

@@ -0,0 +1,16 @@
+"""Select endpoints to test."""
+
+from __future__ import annotations
+
+from kctl_react.core.compliance.api_check.schema import Operation, ParsedSchema
+
+
+def sample_endpoints(schema: ParsedSchema, max_count: int = 20) -> list[Operation]:
+    """Select GET endpoints without path parameters (list endpoints).
+
+    These are safe to call without knowing valid IDs.
+    Cap at max_count. Sort by path for deterministic order.
+    """
+    candidates = [op for op in schema.operations if op.method == "get" and "{" not in op.path]
+    candidates.sort(key=lambda op: op.path)
+    return candidates[:max_count]

kctl_react/core/compliance/checks/__init__.py

@@ -0,0 +1,47 @@
+"""Compliance checkers registry."""
+
+from __future__ import annotations
+
+from .api import ApiChecker
+from .codegen import CodegenChecker
+from .darkmode import DarkmodeChecker
+from .errors import ErrorsChecker
+from .features import FeaturesChecker
+from .i18n_check import I18nChecker
+from .imports import ImportsChecker
+from .navigation import NavigationChecker
+from .practices import PracticesChecker
+from .providers import ProviderChecker
+from .pwa import PwaChecker
+from .responsive import ResponsiveChecker
+from .scripts import ScriptsChecker
+from .shadcn import ShadcnChecker
+from .structure import StructureChecker
+from .testing import TestingChecker
+from .theme import ThemeChecker
+from .ui_standard import UiStandardChecker
+from .vite import ViteChecker
+
+ALL_CHECKERS = [
+    StructureChecker(),
+    ProviderChecker(),
+    ShadcnChecker(),
+    ImportsChecker(),
+    CodegenChecker(),
+    I18nChecker(),
+    FeaturesChecker(),
+    ThemeChecker(),
+    ResponsiveChecker(),
+    DarkmodeChecker(),
+    NavigationChecker(),
+    ErrorsChecker(),
+    ApiChecker(),
+    PwaChecker(),
+    ViteChecker(),
+    ScriptsChecker(),
+    TestingChecker(),
+    PracticesChecker(),
+    UiStandardChecker(),
+]
+
+CHECKER_MAP = {c.name: c.check for c in ALL_CHECKERS}

kctl_react/core/compliance/checks/api.py

@@ -0,0 +1,101 @@
+"""Checker: API client patterns."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class ApiChecker:
+    name = "api"
+    label = "API Client"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+
+        # client.ts must import from @kodemeio/core
+        client_ts = src / "api" / "client.ts"
+        if client_ts.is_file():
+            content = client_ts.read_text()
+            if "@kodemeio/core" not in content:
+                violations.append(
+                    Violation(
+                        file="src/api/client.ts",
+                        message="client.ts does not import from @kodemeio/core",
+                        fix_hint="Use ApiClient from @kodemeio/core",
+                    )
+                )
+        else:
+            violations.append(
+                Violation(
+                    file="src/api/client.ts",
+                    message="Missing api/client.ts",
+                )
+            )
+
+        # No raw fetch() or axios in pages/components
+        for subdir in ("pages", "components"):
+            scan_dir = src / subdir
+            if not scan_dir.is_dir():
+                continue
+            for tsx_file in scan_dir.rglob("*.tsx"):
+                if "__tests__" in tsx_file.parts:
+                    continue
+                try:
+                    lines = tsx_file.read_text().splitlines()
+                except OSError:
+                    continue
+                rel = str(tsx_file.relative_to(app_path))
+                for i, line in enumerate(lines, 1):
+                    if re.search(r"\bfetch\s*\(", line) and "import" not in line:
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                line=i,
+                                message="Raw fetch() call — use ApiClient via hooks",
+                                fix_hint="Move API call to a hook using apiClient",
+                            )
+                        )
+                    if re.search(r"\baxios\b", line):
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                line=i,
+                                message="axios usage — use ApiClient from @kodemeio/core",
+                                fix_hint="Replace axios with apiClient",
+                            )
+                        )
+
+        # Hook files should use useQuery/useMutation
+        # Skip utility hooks that wrap non-fetch functionality
+        _SKIP_HOOKS = {"useExport", "useBarcode", "useSettings", "useWebSocket", "useEventSource"}
+        api_dir = src / "api"
+        if api_dir.is_dir():
+            for hook_file in api_dir.glob("use*.ts"):
+                hook_name = hook_file.stem
+                if hook_name in _SKIP_HOOKS:
+                    continue
+                try:
+                    content = hook_file.read_text()
+                except OSError:
+                    continue
+                rel = str(hook_file.relative_to(app_path))
+                if "useQuery" not in content and "useMutation" not in content and "useInfiniteQuery" not in content:
+                    violations.append(
+                        Violation(
+                            file=rel,
+                            message="Hook file does not use useQuery/useMutation",
+                            fix_hint="Use TanStack Query hooks",
+                        )
+                    )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/codegen.py

@@ -0,0 +1,94 @@
+"""Checker: OpenAPI codegen setup."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class CodegenChecker:
+    name = "codegen"
+    label = "OpenAPI Codegen"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+
+        # openapi-ts.config.ts must exist
+        if not (app_path / "openapi-ts.config.ts").is_file():
+            violations.append(
+                Violation(
+                    file="openapi-ts.config.ts",
+                    message="Missing openapi-ts.config.ts",
+                    fix_hint="Create OpenAPI codegen config",
+                    auto_fixable=True,
+                )
+            )
+
+        # types/api.ts must reference @/generated/types.gen
+        api_ts = app_path / "src" / "types" / "api.ts"
+        if api_ts.is_file():
+            content = api_ts.read_text()
+            if "@/generated/types.gen" not in content:
+                violations.append(
+                    Violation(
+                        file="src/types/api.ts",
+                        message="types/api.ts does not re-export from @/generated/types.gen",
+                        fix_hint="Add export from @/generated/types.gen",
+                    )
+                )
+        else:
+            violations.append(
+                Violation(
+                    file="src/types/api.ts",
+                    message="Missing src/types/api.ts",
+                )
+            )
+
+        # Check for manual API type files in types/
+        types_dir = app_path / "src" / "types"
+        if types_dir.is_dir():
+            manual_pattern = re.compile(r"export\s+(interface|type)\s+\w+(Response|Request|Item|Data)\b")
+            for ts_file in types_dir.glob("*.ts"):
+                if ts_file.name == "api.ts":
+                    continue
+                try:
+                    text = ts_file.read_text()
+                except OSError:
+                    continue
+                if manual_pattern.search(text):
+                    violations.append(
+                        Violation(
+                            file=f"src/types/{ts_file.name}",
+                            message=f"Manual API type definitions in {ts_file.name} — use OpenAPI codegen",
+                            fix_hint="Move types to OpenAPI schema and regenerate",
+                        )
+                    )
+
+        # package.json scripts
+        pkg = app_path / "package.json"
+        if pkg.is_file():
+            try:
+                data = json.loads(pkg.read_text())
+            except (json.JSONDecodeError, OSError):
+                data = {}
+            scripts = data.get("scripts", {})
+            for script_name in ("fetch:schema", "generate:api"):
+                if script_name not in scripts:
+                    violations.append(
+                        Violation(
+                            file="package.json",
+                            message=f'Missing script: "{script_name}"',
+                            fix_hint=f"Add {script_name} script to package.json",
+                        )
+                    )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/darkmode.py

@@ -0,0 +1,57 @@
+"""Checker: dark mode support."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+HARDCODED_COLORS = re.compile(r"\b(?:bg-white|text-black|border-gray-\w+|bg-gray-\w+|text-gray-\w+)\b")
+
+
+class DarkmodeChecker:
+    name = "darkmode"
+    label = "Dark Mode"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+
+        # ThemeToggle check is in theme checker — skip here to avoid duplicates
+
+        # Scan pages/ and components/ for hardcoded colors
+        for subdir in ("pages", "components"):
+            scan_dir = src / subdir
+            if not scan_dir.is_dir():
+                continue
+            for tsx_file in scan_dir.rglob("*.tsx"):
+                if "__tests__" in tsx_file.parts:
+                    continue
+                try:
+                    lines = tsx_file.read_text().splitlines()
+                except OSError:
+                    continue
+                rel = str(tsx_file.relative_to(app_path))
+                for i, line in enumerate(lines, 1):
+                    # Skip lines that have dark: variants — they handle dark mode
+                    if "dark:" in line:
+                        continue
+                    matches = HARDCODED_COLORS.findall(line)
+                    for m in matches:
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                line=i,
+                                message=f"Hardcoded color class: {m} — breaks dark mode",
+                                fix_hint=f"Replace {m} with semantic token (e.g. bg-background, text-foreground)",
+                            )
+                        )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/errors.py

@@ -0,0 +1,68 @@
+"""Checker: error handling patterns."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+MAIN_TSX_CHECKS = ["ErrorBoundary", "Sentry.init", "getErrorMessage"]
+
+BARE_CATCH_PATTERN = re.compile(r"catch\s*\([^)]*\)\s*\{[^}]*(?:console\.log|console\.error)\b")
+
+
+class ErrorsChecker:
+    name = "errors"
+    label = "Error Handling"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+
+        # main.tsx checks
+        main_tsx = src / "main.tsx"
+        if main_tsx.is_file():
+            content = main_tsx.read_text()
+            for check in MAIN_TSX_CHECKS:
+                if check not in content:
+                    violations.append(
+                        Violation(
+                            file="src/main.tsx",
+                            message=f"Missing {check} in main.tsx",
+                            fix_hint=f"Add {check} for proper error handling",
+                        )
+                    )
+        else:
+            violations.append(Violation(file="src/main.tsx", message="main.tsx not found"))
+
+        # Scan for bare catch + console.log/error patterns
+        for ext in ("*.ts", "*.tsx"):
+            for f in src.rglob(ext):
+                if "__tests__" in f.parts:
+                    continue
+                try:
+                    text = f.read_text()
+                except OSError:
+                    continue
+
+                rel = str(f.relative_to(app_path))
+                for match in BARE_CATCH_PATTERN.finditer(text):
+                    # Find the line number
+                    line_num = text[: match.start()].count("\n") + 1
+                    violations.append(
+                        Violation(
+                            file=rel,
+                            line=line_num,
+                            message="Bare catch with console.log/error — use getErrorMessage + toast",
+                            fix_hint="Use getErrorMessage(err) and toast.error() or Sentry.captureException()",
+                        )
+                    )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/features.py

@@ -0,0 +1,66 @@
+"""Checker: cross-app feature completeness."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+# Only features NOT already checked by other checkers:
+# - ErrorBoundary, Sentry, getErrorMessage → errors checker
+# - OfflineProvider, AiProvider, TooltipProvider → providers checker
+# - PwaUpdatePrompt → pwa checker
+MAIN_TSX_FEATURES = [
+    "Toaster",
+]
+
+APP_TSX_FEATURES = [
+    "DeepLinkHandler",
+    "OfflineIndicator",
+]
+
+
+class FeaturesChecker:
+    name = "features"
+    label = "Cross-App Features"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+
+        main_tsx = app_path / "src" / "main.tsx"
+        if main_tsx.is_file():
+            content = main_tsx.read_text()
+            for feat in MAIN_TSX_FEATURES:
+                if feat not in content:
+                    violations.append(
+                        Violation(
+                            file="src/main.tsx",
+                            message=f"Missing feature: {feat}",
+                            fix_hint=f"Add {feat} to main.tsx",
+                        )
+                    )
+        else:
+            violations.append(Violation(file="src/main.tsx", message="main.tsx not found"))
+
+        app_tsx = app_path / "src" / "App.tsx"
+        if app_tsx.is_file():
+            content = app_tsx.read_text()
+            for feat in APP_TSX_FEATURES:
+                if feat not in content:
+                    violations.append(
+                        Violation(
+                            file="src/App.tsx",
+                            message=f"Missing feature: {feat}",
+                            fix_hint=f"Add {feat} to App.tsx",
+                        )
+                    )
+        else:
+            violations.append(Violation(file="src/App.tsx", message="App.tsx not found"))
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/i18n_check.py

@@ -0,0 +1,105 @@
+"""Checker: i18n translation coverage and setup."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+def _flatten_keys(d: dict, prefix: str = "") -> set[str]:
+    """Flatten nested dict keys with dot notation."""
+    keys: set[str] = set()
+    for k, v in d.items():
+        full = f"{prefix}.{k}" if prefix else k
+        if isinstance(v, dict):
+            keys |= _flatten_keys(v, full)
+        else:
+            keys.add(full)
+    return keys
+
+
+class I18nChecker:
+    name = "i18n"
+    label = "Internationalization"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        i18n_dir = app_path / "src" / "i18n"
+
+        en_file = i18n_dir / "en.json"
+        id_file = i18n_dir / "id.json"
+
+        if not en_file.is_file():
+            violations.append(Violation(file="src/i18n/en.json", message="Missing en.json"))
+        if not id_file.is_file():
+            violations.append(Violation(file="src/i18n/id.json", message="Missing id.json"))
+
+        # Key comparison
+        if en_file.is_file() and id_file.is_file():
+            try:
+                en_data = json.loads(en_file.read_text())
+                id_data = json.loads(id_file.read_text())
+            except (json.JSONDecodeError, OSError):
+                violations.append(
+                    Violation(
+                        file="src/i18n/",
+                        message="Failed to parse i18n JSON files",
+                    )
+                )
+                en_data, id_data = {}, {}
+
+            en_keys = _flatten_keys(en_data)
+            id_keys = _flatten_keys(id_data)
+
+            missing_in_id = en_keys - id_keys
+            missing_in_en = id_keys - en_keys
+
+            for key in sorted(missing_in_id):
+                violations.append(
+                    Violation(
+                        file="src/i18n/id.json",
+                        message=f"Missing key in id.json: {key}",
+                        fix_hint=f'Add "{key}" to id.json',
+                        auto_fixable=True,
+                    )
+                )
+
+            for key in sorted(missing_in_en):
+                violations.append(
+                    Violation(
+                        file="src/i18n/en.json",
+                        message=f"Missing key in en.json: {key}",
+                        fix_hint=f'Add "{key}" to en.json',
+                        auto_fixable=True,
+                    )
+                )
+
+        # Check i18n/index.ts uses createI18n
+        index_ts = i18n_dir / "index.ts"
+        if index_ts.is_file():
+            content = index_ts.read_text()
+            if "createI18n" not in content:
+                violations.append(
+                    Violation(
+                        file="src/i18n/index.ts",
+                        message="i18n/index.ts does not use createI18n factory",
+                        fix_hint="Use createI18n from @kodemeio/core/i18n",
+                    )
+                )
+        else:
+            violations.append(
+                Violation(
+                    file="src/i18n/index.ts",
+                    message="Missing i18n/index.ts",
+                )
+            )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )