kctl-react 0.6.2__py3-none-any.whl

kctl_react/core/compliance/checks/imports.py

@@ -0,0 +1,86 @@
+"""Checker: import conventions."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+_SKIP_PARTS = {"node_modules", "generated", "__tests__"}
+
+
+def _should_skip(file_path: Path) -> bool:
+    return bool(_SKIP_PARTS & set(file_path.parts))
+
+
+class ImportsChecker:
+    name = "imports"
+    label = "Import Conventions"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+        if not src.is_dir():
+            return CategoryResult(
+                name=self.name,
+                label=self.label,
+                max_points=self.max_points,
+                violations=violations,
+            )
+
+        for ext in ("*.ts", "*.tsx"):
+            for f in src.rglob(ext):
+                if _should_skip(f):
+                    continue
+                rel = str(f.relative_to(app_path))
+                try:
+                    lines = f.read_text().splitlines()
+                except OSError:
+                    continue
+
+                for i, line in enumerate(lines, 1):
+                    # "use client" directive
+                    if re.search(r'"use client"', line) or re.search(r"'use client'", line):
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                line=i,
+                                message='"use client" directive not needed in Vite apps',
+                                fix_hint="Remove the directive",
+                                auto_fixable=True,
+                            )
+                        )
+
+                    # Deep relative imports ../../
+                    if re.search(r'from\s+["\']\.\.\/\.\.', line):
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                line=i,
+                                message="Deep relative import (../../) — use @/ alias",
+                                fix_hint="Replace with @/ path alias",
+                                auto_fixable=True,
+                            )
+                        )
+
+                    # Direct @/generated/ imports outside types/api.ts
+                    if re.search(r'from\s+["\']@/generated/', line):
+                        if not rel.endswith("types/api.ts"):
+                            violations.append(
+                                Violation(
+                                    file=rel,
+                                    line=i,
+                                    message="Direct @/generated/ import — use @/types/api instead",
+                                    fix_hint="Import from @/types/api",
+                                    auto_fixable=True,
+                                )
+                            )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/navigation.py

@@ -0,0 +1,62 @@
+"""Checker: navigation config and lazy loading."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class NavigationChecker:
+    name = "navigation"
+    label = "Navigation"
+    max_points = 4
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+
+        # navConfig.tsx must exist with expected exports
+        nav = src / "config" / "navConfig.tsx"
+        if nav.is_file():
+            content = nav.read_text()
+            for fn_name in ("useDesktopNavGroups", "useMobileNavItems"):
+                if fn_name not in content:
+                    violations.append(
+                        Violation(
+                            file="src/config/navConfig.tsx",
+                            message=f"Missing {fn_name} in navConfig",
+                            fix_hint=f"Export {fn_name} from navConfig.tsx",
+                        )
+                    )
+        else:
+            violations.append(
+                Violation(
+                    file="src/config/navConfig.tsx",
+                    message="Missing navConfig.tsx",
+                )
+            )
+
+        # App.tsx should use React.lazy() for pages
+        app_tsx = src / "App.tsx"
+        if app_tsx.is_file():
+            content = app_tsx.read_text()
+            # Check for non-lazy page imports (direct named imports from pages/)
+            direct_imports = re.findall(r'import\s+\{[^}]+\}\s+from\s+["\']@/pages/', content)
+            lazy_count = len(re.findall(r"React\.lazy\(|lazy\(\s*\(\)\s*=>", content))
+            if direct_imports and lazy_count == 0:
+                violations.append(
+                    Violation(
+                        file="src/App.tsx",
+                        message="Pages imported directly without React.lazy()",
+                        fix_hint="Use React.lazy(() => import('@/pages/...')) for code splitting",
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/practices.py

@@ -0,0 +1,122 @@
+"""Checker: coding best practices."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+_SKIP_PARTS = {"node_modules", "__tests__", "generated"}
+
+
+def _should_skip(file_path: Path) -> bool:
+    return bool(_SKIP_PARTS & set(file_path.parts))
+
+
+class PracticesChecker:
+    name = "practices"
+    label = "Best Practices"
+    max_points = 4
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+        if not src.is_dir():
+            return CategoryResult(
+                name=self.name,
+                label=self.label,
+                max_points=self.max_points,
+                violations=violations,
+            )
+
+        for ext in ("*.ts", "*.tsx"):
+            for f in src.rglob(ext):
+                if _should_skip(f):
+                    continue
+                try:
+                    lines = f.read_text().splitlines()
+                except OSError:
+                    continue
+                rel = str(f.relative_to(app_path))
+
+                is_user_code = "pages" in f.parts or "components" in f.parts
+                for i, line in enumerate(lines, 1):
+                    stripped = line.lstrip()
+                    if stripped.startswith("//") or stripped.startswith("*"):
+                        continue
+
+                    # console.log in production code (pages/components only)
+                    if is_user_code and re.search(r"\bconsole\.log\s*\(", line):
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                line=i,
+                                message="console.log() in production code",
+                                fix_hint="Remove or replace with Sentry.captureMessage",
+                            )
+                        )
+
+                    # : any type annotation (pages/components only)
+                    if is_user_code and re.search(r":\s*any\b", line):
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                line=i,
+                                message=": any type annotation — use proper types",
+                                fix_hint="Replace with specific type",
+                            )
+                        )
+
+                    # process.env instead of import.meta.env (Vite apps)
+                    if re.search(r"\bprocess\.env\b", line):
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                line=i,
+                                message="process.env — use import.meta.env in Vite apps",
+                                fix_hint="Replace process.env.X with import.meta.env.VITE_X",
+                                auto_fixable=False,
+                            )
+                        )
+
+                    # Hardcoded localhost URLs in non-config files
+                    if is_user_code and re.search(r"https?://localhost[:\d/]", line):
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                line=i,
+                                message="Hardcoded localhost URL — use env variable",
+                                fix_hint="Use import.meta.env.VITE_API_BASE_URL",
+                            )
+                        )
+
+                    # Whole library imports (lodash, date-fns, etc.)
+                    if re.search(r'import\s+\w+\s+from\s+["\'](?:lodash|moment|date-fns)["\']', line):
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                line=i,
+                                message="Whole library import — use named imports for tree-shaking",
+                                fix_hint='Use import { fn } from "library" instead',
+                            )
+                        )
+
+                # export default check for page files
+                if "pages" in f.parts:
+                    text = "\n".join(lines)
+                    if re.search(r"\bexport\s+default\b", text):
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                message="export default in page — use named export",
+                                fix_hint="Use named export instead of export default",
+                            )
+                        )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/providers.py

@@ -0,0 +1,85 @@
+"""Checker: provider stack order and completeness in main.tsx."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from kctl_react.core.compliance.exceptions_map import get_skip_providers
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+EXPECTED_ORDER = [
+    "ErrorBoundary",
+    "PwaUpdatePrompt",
+    "QueryClientProvider",
+    "BrowserRouter",
+    "AuthProvider",
+    "GPSProvider",
+    "TooltipProvider",
+    "OfflineProvider",
+    "AiProvider",
+    "App",
+]
+
+
+class ProviderChecker:
+    name = "providers"
+    label = "Provider Stack"
+    max_points = 8
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        main_tsx = app_path / "src" / "main.tsx"
+
+        if not main_tsx.is_file():
+            violations.append(Violation(file="src/main.tsx", message="main.tsx not found"))
+            return CategoryResult(
+                name=self.name,
+                label=self.label,
+                max_points=self.max_points,
+                violations=violations,
+            )
+
+        content = main_tsx.read_text()
+        skip = get_skip_providers(app_name)
+        expected = [p for p in EXPECTED_ORDER if p not in skip]
+
+        # Find positions of each provider in the file
+        positions: dict[str, int] = {}
+        for provider in expected:
+            # Match <Provider or <Provider> or {Provider}
+            pattern = rf"<{provider}[\s>/]"
+            match = re.search(pattern, content)
+            if match:
+                positions[provider] = match.start()
+
+        # Check missing providers
+        for provider in expected:
+            if provider not in positions:
+                violations.append(
+                    Violation(
+                        file="src/main.tsx",
+                        message=f"Missing provider: {provider}",
+                        fix_hint=f"Add <{provider}> to the provider stack",
+                    )
+                )
+
+        # Check order of found providers
+        found_ordered = sorted(positions.keys(), key=lambda p: positions[p])
+        expected_found = [p for p in expected if p in positions]
+
+        if found_ordered != expected_found:
+            violations.append(
+                Violation(
+                    file="src/main.tsx",
+                    message=f"Provider order incorrect. Expected: {' > '.join(expected_found)}, got: {' > '.join(found_ordered)}",
+                    fix_hint="Reorder providers to match expected stack",
+                )
+            )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/pwa.py

@@ -0,0 +1,101 @@
+"""Checker: PWA configuration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+PWA_META_TAGS = [
+    "mobile-web-app-capable",
+    "apple-mobile-web-app-capable",
+    "viewport-fit=cover",
+]
+
+
+class PwaChecker:
+    name = "pwa"
+    label = "PWA Configuration"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+
+        # index.html checks
+        index_html = app_path / "index.html"
+        if index_html.is_file():
+            content = index_html.read_text()
+
+            for tag in PWA_META_TAGS:
+                if tag not in content:
+                    violations.append(
+                        Violation(
+                            file="index.html",
+                            message=f"Missing PWA meta tag: {tag}",
+                            fix_hint=f"Add {tag} meta tag to index.html",
+                        )
+                    )
+
+            if "manifest" not in content:
+                violations.append(
+                    Violation(
+                        file="index.html",
+                        message="Missing manifest reference in index.html",
+                        fix_hint="Add <link rel='manifest' href='manifest.webmanifest'>",
+                    )
+                )
+        else:
+            violations.append(Violation(file="index.html", message="Missing index.html"))
+
+        # Public icons
+        public_dir = app_path / "public"
+        if public_dir.is_dir():
+            icon_files = (
+                list(public_dir.glob("favicon*"))
+                + list(public_dir.glob("icon*"))
+                + list(public_dir.glob("*.png"))
+                + list(public_dir.glob("*.svg"))
+            )
+            if not icon_files:
+                violations.append(
+                    Violation(
+                        file="public/",
+                        message="No icon files found in public/",
+                        fix_hint="Add favicon and PWA icons to public/",
+                    )
+                )
+        else:
+            violations.append(
+                Violation(
+                    file="public/",
+                    message="Missing public/ directory",
+                )
+            )
+
+        # main.tsx PwaUpdatePrompt + useRegisterSW
+        main_tsx = app_path / "src" / "main.tsx"
+        if main_tsx.is_file():
+            content = main_tsx.read_text()
+            if "PwaUpdatePrompt" not in content:
+                violations.append(
+                    Violation(
+                        file="src/main.tsx",
+                        message="Missing PwaUpdatePrompt in main.tsx",
+                        fix_hint="Add PwaUpdatePrompt component",
+                    )
+                )
+            if "useRegisterSW" not in content:
+                violations.append(
+                    Violation(
+                        file="src/main.tsx",
+                        message="Missing useRegisterSW in main.tsx",
+                        fix_hint="Add useRegisterSW from virtual:pwa-register/react",
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/responsive.py

@@ -0,0 +1,47 @@
+"""Checker: responsive layout setup."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class ResponsiveChecker:
+    name = "responsive"
+    label = "Responsive Layout"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+
+        # AppLayout.tsx checks
+        layout = src / "components" / "AppLayout.tsx"
+        if layout.is_file():
+            content = layout.read_text()
+            for token in ("useIsMobile", "DesktopLayout", "MobileLayout"):
+                if token not in content:
+                    violations.append(
+                        Violation(
+                            file="src/components/AppLayout.tsx",
+                            message=f"Missing {token} in AppLayout",
+                            fix_hint=f"Add {token} for responsive switching",
+                        )
+                    )
+        else:
+            violations.append(
+                Violation(
+                    file="src/components/AppLayout.tsx",
+                    message="Missing AppLayout.tsx",
+                )
+            )
+
+        # navConfig.tsx checks are in navigation checker — skip here to avoid duplicates
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/scripts.py

@@ -0,0 +1,85 @@
+"""Checker: package.json scripts."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+REQUIRED_SCRIPTS = [
+    "dev",
+    "build",
+    "preview",
+    "lint",
+    "type-check",
+    "test",
+    "fetch:schema",
+    "generate:api",
+]
+
+HOOK_SCRIPTS = ["predev", "prebuild"]
+
+
+class ScriptsChecker:
+    name = "scripts"
+    label = "Package Scripts"
+    max_points = 4
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+
+        pkg = app_path / "package.json"
+        if not pkg.is_file():
+            violations.append(Violation(file="package.json", message="Missing package.json"))
+            return CategoryResult(
+                name=self.name,
+                label=self.label,
+                max_points=self.max_points,
+                violations=violations,
+            )
+
+        try:
+            data = json.loads(pkg.read_text())
+        except (json.JSONDecodeError, OSError):
+            violations.append(
+                Violation(
+                    file="package.json",
+                    message="Failed to parse package.json",
+                )
+            )
+            return CategoryResult(
+                name=self.name,
+                label=self.label,
+                max_points=self.max_points,
+                violations=violations,
+            )
+
+        scripts = data.get("scripts", {})
+
+        for script in REQUIRED_SCRIPTS:
+            if script not in scripts:
+                violations.append(
+                    Violation(
+                        file="package.json",
+                        message=f'Missing required script: "{script}"',
+                        fix_hint=f"Add {script} script to package.json",
+                    )
+                )
+
+        for hook in HOOK_SCRIPTS:
+            if hook not in scripts:
+                violations.append(
+                    Violation(
+                        file="package.json",
+                        message=f'Missing hook script: "{hook}"',
+                        fix_hint=f"Add {hook} hook to package.json",
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/shadcn.py

@@ -0,0 +1,51 @@
+"""Checker: shadcn/ui component usage (no raw HTML elements)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kctl_react.core.analyzers import find_raw_html_elements
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class ShadcnChecker:
+    name = "shadcn"
+    label = "shadcn/ui Usage"
+    max_points = 8
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+
+        for subdir in ("pages", "components"):
+            scan_dir = src / subdir
+            if not scan_dir.is_dir():
+                continue
+            for tsx_file in scan_dir.rglob("*.tsx"):
+                # Skip test files
+                if "__tests__" in tsx_file.parts:
+                    continue
+                results = find_raw_html_elements(tsx_file)
+                for r in results:
+                    # Skip title= prop on JSX components (title={...} is a
+                    # component prop, not an HTML tooltip attribute)
+                    if r["element"] == "title= attr":
+                        code = str(r.get("code", ""))
+                        if "title={" in code:
+                            continue
+                    rel = str(tsx_file.relative_to(app_path))
+                    violations.append(
+                        Violation(
+                            file=rel,
+                            line=int(r["line"]),
+                            message=f"Raw <{r['element']}> — use {r['replacement']}",
+                            fix_hint=f"Replace <{r['element']}> with {r['replacement']}",
+                        )
+                    )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )