kctl-react 0.6.2__py3-none-any.whl

kctl_react/core/analyzers.py

@@ -0,0 +1,200 @@
+"""Shared static analysis utilities for TSX/TS files.
+
+Used by ui_audit, lint, state, and i18n commands to scan React source
+files for shadcn violations, import patterns, query keys, and i18n issues.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# SHADCN_ELEMENT_MAP: regex pattern -> (element_name, shadcn_replacement)
+# ---------------------------------------------------------------------------
+
+SHADCN_ELEMENT_MAP: dict[str, tuple[str, str]] = {
+    # Basic HTML elements
+    r"<button[\s>]": ("button", "Button"),
+    r"<input[\s/>]": ("input", "Input"),
+    r"<select[\s>]": ("select", "Select + SelectTrigger + SelectContent + SelectItem"),
+    r"<textarea[\s/>]": ("textarea", "Textarea"),
+    r"<label[\s>]": ("label", "Label"),
+    r"<table[\s>]": ("table", "Table + TableHeader + TableBody + TableRow"),
+    r"<hr\s*/?\s*>": ("hr", "Separator"),
+    # Anti-patterns: title= attribute
+    r'\btitle\s*=\s*["\'{]': ("title= attr", "Tooltip + TooltipTrigger + TooltipContent"),
+    # Anti-patterns: custom modal (fixed inset-0)
+    r'className="[^"]*fixed\s+inset-0': ("fixed inset-0 div", "Dialog or Sheet"),
+    r"className='[^']*fixed\s+inset-0": ("fixed inset-0 div", "Dialog or Sheet"),
+    # Anti-patterns: animate-pulse skeleton
+    r'className="[^"]*animate-pulse': ("animate-pulse div", "Skeleton"),
+    r"className='[^']*animate-pulse": ("animate-pulse div", "Skeleton"),
+    # Anti-patterns: absolute dropdown
+    r'className="[^"]*absolute[^"]*top-': ("absolute dropdown div", "DropdownMenu"),
+    r"className='[^']*absolute[^']*top-": ("absolute dropdown div", "DropdownMenu"),
+    # More HTML elements
+    r"<img[\s/>]": ("img", "Avatar + AvatarImage + AvatarFallback (for avatars)"),
+    r"<progress[\s/>]": ("progress", "Progress"),
+    r"<details[\s>]": ("details", "Collapsible + CollapsibleTrigger + CollapsibleContent"),
+    r"<summary[\s>]": ("summary", "CollapsibleTrigger"),
+    # Anti-patterns: overflow-auto scroll area
+    r'className="[^"]*overflow-auto': ("overflow-auto div", "ScrollArea"),
+    r"className='[^']*overflow-auto": ("overflow-auto div", "ScrollArea"),
+    # Anti-patterns: custom toggle
+    r'role="switch"': ("role=switch", "Toggle or Switch"),
+    r'role="tab"': ("role=tab", "Tabs + TabsList + TabsTrigger + TabsContent"),
+}
+
+
+def find_raw_html_elements(file_path: Path) -> list[dict[str, str | int]]:
+    """Scan a TSX file for raw HTML that should use shadcn/ui components.
+
+    Returns a list of dicts with keys: file, line, element, replacement, code.
+    """
+    results: list[dict[str, str | int]] = []
+    try:
+        lines = file_path.read_text().splitlines()
+    except OSError:
+        return results
+
+    for line_num, line in enumerate(lines, start=1):
+        for pattern, (element, replacement) in SHADCN_ELEMENT_MAP.items():
+            if re.search(pattern, line):
+                results.append(
+                    {
+                        "file": str(file_path),
+                        "line": line_num,
+                        "element": element,
+                        "replacement": replacement,
+                        "code": line.strip(),
+                    }
+                )
+    return results
+
+
+def scan_imports(file_path: Path, package_name: str) -> list[str]:
+    """Extract named imports from a specific package.
+
+    Handles both single-line and multi-line import statements.
+    Returns a sorted list of imported names.
+    """
+    try:
+        text = file_path.read_text()
+    except OSError:
+        return []
+
+    # Collapse multi-line imports into single lines for easier parsing
+    # Match: import { ... } from "package"
+    escaped = re.escape(package_name)
+    pattern = rf'import\s*\{{([^}}]*)\}}\s*from\s*["\']{escaped}["\']'
+    names: list[str] = []
+    for match in re.finditer(pattern, text, re.DOTALL):
+        raw = match.group(1)
+        for name in raw.split(","):
+            name = name.strip()
+            if name:
+                # Handle "Foo as Bar" — keep the local name
+                parts = name.split(" as ")
+                names.append(parts[-1].strip())
+    return sorted(names)
+
+
+def read_tsconfig_strict(app_dir: Path) -> bool:
+    """Check if tsconfig.json has ``strict: true``.
+
+    Handles JSON with ``//`` comments (common in tsconfig files).
+    """
+    tsconfig = app_dir / "tsconfig.json"
+    if not tsconfig.exists():
+        return False
+    try:
+        text = tsconfig.read_text()
+        # Strip single-line comments
+        text = re.sub(r"//.*", "", text)
+        data = json.loads(text)
+        return bool(data.get("compilerOptions", {}).get("strict", False))
+    except (json.JSONDecodeError, OSError):
+        return False
+
+
+def find_query_keys(file_path: Path) -> list[dict[str, str | int]]:
+    """Extract TanStack Query queryKey definitions from a file.
+
+    Returns a list of dicts with keys: file, line, key_prefix, full_key.
+    """
+    results: list[dict[str, str | int]] = []
+    try:
+        lines = file_path.read_text().splitlines()
+    except OSError:
+        return results
+
+    pattern = re.compile(r"queryKey\s*:\s*\[([^\]]+)\]")
+
+    for line_num, line in enumerate(lines, start=1):
+        match = pattern.search(line)
+        if match:
+            full_key = match.group(1).strip()
+            # Extract first element as prefix (strip quotes)
+            parts = [p.strip().strip("\"'") for p in full_key.split(",")]
+            key_prefix = parts[0] if parts else ""
+            results.append(
+                {
+                    "file": str(file_path),
+                    "line": line_num,
+                    "key_prefix": key_prefix,
+                    "full_key": full_key,
+                }
+            )
+    return results
+
+
+def find_hook_files(src_dir: Path) -> list[Path]:
+    """Find all TanStack Query hook files (use*.ts) in src/hooks/.
+
+    Returns sorted list of Paths matching use*.ts in the hooks directory.
+    """
+    hooks_dir = src_dir / "hooks"
+    if not hooks_dir.is_dir():
+        return []
+    return sorted(p for p in hooks_dir.iterdir() if p.is_file() and p.name.startswith("use") and p.suffix == ".ts")
+
+
+def check_interpolation_vars(en: dict, id_: dict, prefix: str = "") -> list[dict[str, str | set[str]]]:
+    """Compare ``{{var}}`` placeholders between en and id translation dicts.
+
+    Recursively walks nested dicts. Returns a list of dicts with keys:
+    key, en_vars, id_vars, missing_in_id, extra_in_id.
+    """
+    var_pattern = re.compile(r"\{\{(\w+)\}\}")
+    mismatches: list[dict[str, str | set[str]]] = []
+
+    for key in en:
+        full_key = f"{prefix}.{key}" if prefix else key
+        en_val = en[key]
+        id_val = id_.get(key)
+
+        if isinstance(en_val, dict):
+            id_sub = id_val if isinstance(id_val, dict) else {}
+            mismatches.extend(check_interpolation_vars(en_val, id_sub, prefix=full_key))
+            continue
+
+        if not isinstance(en_val, str):
+            continue
+
+        en_vars = set(var_pattern.findall(en_val))
+        id_vars = set(var_pattern.findall(id_val)) if isinstance(id_val, str) else set()
+
+        if en_vars != id_vars:
+            mismatches.append(
+                {
+                    "key": full_key,
+                    "en_vars": en_vars,
+                    "id_vars": id_vars,
+                    "missing_in_id": en_vars - id_vars,
+                    "extra_in_id": id_vars - en_vars,
+                }
+            )
+
+    return mismatches

kctl_react/core/callbacks.py

@@ -0,0 +1,70 @@
+"""Typer global callback and shared context."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from kctl_lib.callbacks import AppContextBase
+
+from kctl_react.core.config import resolve_project_root
+from kctl_react.core.discovery import discover_apps, discover_packages, get_app_dir as _get_app_dir
+
+
+@dataclass
+class AppContext(AppContextBase):
+    """kctl-react application context with monorepo discovery."""
+
+    root_override: str | None = None
+    _project_root: Path | None = field(default=None, repr=False)
+    _app_registry: dict[str, dict[str, Any]] | None = field(default=None, repr=False)
+    _package_list: list[str] | None = field(default=None, repr=False)
+
+    @property
+    def project_root(self) -> Path:
+        """Lazy-resolved monorepo root path."""
+        if self._project_root is None:
+            self._project_root = resolve_project_root(
+                profile_name=self.profile,
+                root_override=self.root_override,
+            )
+        return self._project_root
+
+    @property
+    def apps(self) -> dict[str, dict[str, Any]]:
+        """Auto-discovered app registry from apps/ directory."""
+        if self._app_registry is None:
+            self._app_registry = discover_apps(self.project_root)
+        return self._app_registry
+
+    @property
+    def app_names(self) -> list[str]:
+        """Sorted list of discovered app names."""
+        return list(self.apps.keys())
+
+    @property
+    def packages(self) -> list[str]:
+        """Auto-discovered package names from packages/ directory."""
+        if self._package_list is None:
+            self._package_list = discover_packages(self.project_root)
+        return self._package_list
+
+    def get_framework(self, app_name: str) -> str:
+        """Return framework for an app: 'vite' or 'nextjs'."""
+        return self.apps.get(app_name, {}).get("framework", "vite")
+
+    def is_nextjs(self, app_name: str) -> bool:
+        """Check if an app uses Next.js."""
+        return self.get_framework(app_name) == "nextjs"
+
+    def get_app_dir(self, app_name: str) -> Path:
+        """Get the filesystem path for an app."""
+        return _get_app_dir(self.project_root, app_name, self.apps)
+
+    def validate_app(self, app_name: str) -> None:
+        """Validate app name against discovered apps."""
+        if app_name not in self.apps:
+            from kctl_lib.exceptions import AppNotFoundError
+
+            raise AppNotFoundError(app_name, self.app_names)

kctl_react/core/compliance/__init__.py

@@ -0,0 +1,3 @@
+"""Compliance audit engine for kctl-react."""
+
+from __future__ import annotations

kctl_react/core/compliance/api_check/__init__.py

@@ -0,0 +1,3 @@
+"""API check: static schema vs hooks cross-validation."""
+
+from __future__ import annotations

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

@@ -0,0 +1,18 @@
+"""API check registry — all 6 checkers."""
+
+from .endpoints import EndpointChecker
+from .envelope import EnvelopeChecker
+from .naming import NamingChecker
+from .params import ParamChecker
+from .requests import RequestChecker
+from .types import TypeChecker
+
+ALL_API_CHECKERS = [
+    EndpointChecker(),
+    TypeChecker(),
+    RequestChecker(),
+    ParamChecker(),
+    EnvelopeChecker(),
+    NamingChecker(),
+]
+CHECKER_MAP = {c.name: c for c in ALL_API_CHECKERS}

kctl_react/core/compliance/api_check/checks/endpoints.py

@@ -0,0 +1,53 @@
+"""Endpoint coverage checker — orphan and dead endpoints."""
+
+from __future__ import annotations
+
+from kctl_react.core.compliance.api_check.hooks import HookCall
+from kctl_react.core.compliance.api_check.matcher import MatchResult
+from kctl_react.core.compliance.api_check.schema import ParsedSchema
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class EndpointChecker:
+    name = "endpoints"
+    label = "Endpoint Coverage"
+    max_points = 10
+
+    def check(
+        self,
+        schema: ParsedSchema,
+        hooks: list[HookCall],
+        match: MatchResult,
+    ) -> CategoryResult:
+        violations: list[Violation] = []
+
+        # Skip auth endpoints — handled by @kodemeio/core, not app hooks
+        _SKIP_PREFIXES = ("/auth/",)
+
+        for op in match.orphan_endpoints:
+            if any(op.path.startswith(p) for p in _SKIP_PREFIXES):
+                continue
+            violations.append(
+                Violation(
+                    file="openapi.json",
+                    message=f"Orphan endpoint: {op.method.upper()} {op.path} — no hook calls this",
+                    fix_hint=f"Create a hook that calls {op.method.upper()} {op.path}",
+                )
+            )
+
+        for hook in match.dead_endpoints:
+            violations.append(
+                Violation(
+                    file=hook.file,
+                    line=hook.line,
+                    message=f"Dead endpoint: {hook.method.upper()} {hook.normalized_url} in {hook.file} — not in OpenAPI schema",
+                    fix_hint="Remove this API call or add the endpoint to the OpenAPI schema",
+                )
+            )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/api_check/checks/envelope.py

@@ -0,0 +1,44 @@
+"""Response envelope conformance checker."""
+
+from __future__ import annotations
+
+from kctl_react.core.compliance.api_check.hooks import HookCall
+from kctl_react.core.compliance.api_check.matcher import MatchResult
+from kctl_react.core.compliance.api_check.schema import ParsedSchema
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class EnvelopeChecker:
+    name = "envelope"
+    label = "Response Envelope"
+    max_points = 5
+
+    def check(
+        self,
+        schema: ParsedSchema,
+        hooks: list[HookCall],
+        match: MatchResult,
+    ) -> CategoryResult:
+        violations: list[Violation] = []
+
+        for name, schema_def in schema.response_schemas.items():
+            # Only check schemas that are response envelopes (end with Response)
+            if not name.endswith("Response"):
+                continue
+            properties = schema_def.get("properties", {})
+            for required_key in ("success", "data"):
+                if required_key not in properties:
+                    violations.append(
+                        Violation(
+                            file="openapi.json",
+                            message=f"Schema {name} missing {required_key} in response envelope",
+                            fix_hint=f"Add '{required_key}' property to {name}",
+                        )
+                    )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/api_check/checks/naming.py

@@ -0,0 +1,60 @@
+"""Hook naming convention checker."""
+
+from __future__ import annotations
+
+import re
+
+from kctl_react.core.compliance.api_check.hooks import HookCall
+from kctl_react.core.compliance.api_check.matcher import MatchResult
+from kctl_react.core.compliance.api_check.schema import ParsedSchema
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+_USE_PREFIX_RE = re.compile(r"use([A-Z]\w*)\.ts$")
+
+
+class NamingChecker:
+    name = "naming"
+    label = "Hook Naming"
+    max_points = 5
+
+    def check(
+        self,
+        schema: ParsedSchema,
+        hooks: list[HookCall],
+        match: MatchResult,
+    ) -> CategoryResult:
+        violations: list[Violation] = []
+
+        # Collect all tags from the schema
+        tags = {op.tag.lower() for op in schema.operations}
+
+        # Group hooks by file to avoid duplicate violations
+        seen_files: set[str] = set()
+        for hook in hooks:
+            if hook.file in seen_files:
+                continue
+            seen_files.add(hook.file)
+
+            # Extract resource name from filename
+            filename = hook.file.rsplit("/", 1)[-1] if "/" in hook.file else hook.file
+            m = _USE_PREFIX_RE.match(filename)
+            if not m:
+                continue
+
+            resource = m.group(1).lower()
+
+            if not any(resource in tag for tag in tags):
+                violations.append(
+                    Violation(
+                        file=hook.file,
+                        message=f"Hook {hook.file} name doesn't match any OpenAPI tag",
+                        fix_hint="Rename the hook file to match a tag in the OpenAPI schema",
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/api_check/checks/params.py

@@ -0,0 +1,44 @@
+"""Query parameter validation checker."""
+
+from __future__ import annotations
+
+from kctl_react.core.compliance.api_check.hooks import HookCall
+from kctl_react.core.compliance.api_check.matcher import MatchResult
+from kctl_react.core.compliance.api_check.schema import ParsedSchema
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class ParamChecker:
+    name = "params"
+    label = "Query Parameters"
+    max_points = 5
+
+    def check(
+        self,
+        schema: ParsedSchema,
+        hooks: list[HookCall],
+        match: MatchResult,
+    ) -> CategoryResult:
+        violations: list[Violation] = []
+
+        for hook, operation in match.matched:
+            for param in hook.query_params:
+                if param not in operation.parameters:
+                    violations.append(
+                        Violation(
+                            file=hook.file,
+                            line=hook.line,
+                            message=(
+                                f"Unknown query param '{param}' on "
+                                f"{hook.method.upper()} {hook.normalized_url} in {hook.file}"
+                            ),
+                            fix_hint=f"Remove '{param}' or add it to the OpenAPI schema",
+                        )
+                    )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/api_check/checks/requests.py

@@ -0,0 +1,57 @@
+"""Request type matching checker."""
+
+from __future__ import annotations
+
+from kctl_react.core.compliance.api_check.hooks import HookCall
+from kctl_react.core.compliance.api_check.matcher import MatchResult
+from kctl_react.core.compliance.api_check.schema import ParsedSchema
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class RequestChecker:
+    name = "requests"
+    label = "Request Types"
+    max_points = 5
+
+    def check(
+        self,
+        schema: ParsedSchema,
+        hooks: list[HookCall],
+        match: MatchResult,
+    ) -> CategoryResult:
+        violations: list[Violation] = []
+
+        for hook, operation in match.matched:
+            if operation.method not in ("post", "put", "patch"):
+                continue
+
+            if operation.request_schema and hook.request_type is None:
+                violations.append(
+                    Violation(
+                        file=hook.file,
+                        line=hook.line,
+                        message=(
+                            f"Missing request body type on {hook.method.upper()} {hook.normalized_url} in {hook.file}"
+                        ),
+                        fix_hint=f"Add request type {operation.request_schema}",
+                    )
+                )
+            elif hook.request_type and operation.request_schema and hook.request_type != operation.request_schema:
+                violations.append(
+                    Violation(
+                        file=hook.file,
+                        line=hook.line,
+                        message=(
+                            f"Request type mismatch: hook uses {hook.request_type} "
+                            f"but schema expects {operation.request_schema}"
+                        ),
+                        fix_hint=f"Change request type to {operation.request_schema}",
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/api_check/checks/types.py

@@ -0,0 +1,55 @@
+"""Response type matching checker."""
+
+from __future__ import annotations
+
+from kctl_react.core.compliance.api_check.hooks import HookCall
+from kctl_react.core.compliance.api_check.matcher import MatchResult
+from kctl_react.core.compliance.api_check.schema import ParsedSchema
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class TypeChecker:
+    name = "types"
+    label = "Response Types"
+    max_points = 10
+
+    def check(
+        self,
+        schema: ParsedSchema,
+        hooks: list[HookCall],
+        match: MatchResult,
+    ) -> CategoryResult:
+        violations: list[Violation] = []
+
+        for hook, operation in match.matched:
+            if hook.response_type is None:
+                violations.append(
+                    Violation(
+                        file=hook.file,
+                        line=hook.line,
+                        message=(
+                            f"Missing response type generic on "
+                            f"{hook.method.upper()} {hook.normalized_url} in {hook.file}"
+                        ),
+                        fix_hint="Add a response type generic to the API call",
+                    )
+                )
+            elif operation.response_schema and hook.response_type != operation.response_schema:
+                violations.append(
+                    Violation(
+                        file=hook.file,
+                        line=hook.line,
+                        message=(
+                            f"Type mismatch: hook uses {hook.response_type} "
+                            f"but schema expects {operation.response_schema}"
+                        ),
+                        fix_hint=f"Change response type to {operation.response_schema}",
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )