kctl-react 0.6.2__py3-none-any.whl

kctl_react/core/compliance/checks/structure.py

@@ -0,0 +1,76 @@
+"""Checker: project file/directory structure."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+REQUIRED_DIRS = [
+    "api",
+    "pages",
+    "components",
+    "config",
+    "hooks",
+    "contexts",
+    "constants",
+    "types",
+    "i18n",
+    "utils",
+    "__tests__",
+]
+
+REQUIRED_FILES = [
+    "main.tsx",
+    "App.tsx",
+    "config/navConfig.tsx",
+    "components/AppLayout.tsx",
+    "api/client.ts",
+    "types/api.ts",
+]
+
+
+class StructureChecker:
+    name = "structure"
+    label = "File Structure"
+    max_points = 8
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+
+        for d in REQUIRED_DIRS:
+            if not (src / d).is_dir():
+                violations.append(
+                    Violation(
+                        file=f"src/{d}/",
+                        message=f"Missing required directory: src/{d}/",
+                        fix_hint=f"mkdir -p apps/{app_name}/src/{d}",
+                    )
+                )
+
+        for f in REQUIRED_FILES:
+            if not (src / f).is_file():
+                violations.append(
+                    Violation(
+                        file=f"src/{f}",
+                        message=f"Missing required file: src/{f}",
+                    )
+                )
+
+        # .env.example in app root
+        if not (app_path / ".env.example").is_file():
+            violations.append(
+                Violation(
+                    file=".env.example",
+                    message="Missing .env.example in app root",
+                    fix_hint="Create .env.example with sanitized env vars",
+                )
+            )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/testing.py

@@ -0,0 +1,83 @@
+"""Checker: testing setup."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+
+class TestingChecker:
+    name = "testing"
+    label = "Testing Setup"
+    max_points = 4
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+
+        # __tests__/ directory with test files
+        tests_dir = src / "__tests__"
+        if tests_dir.is_dir():
+            test_files = list(tests_dir.rglob("*.test.tsx")) + list(tests_dir.rglob("*.test.ts"))
+            if not test_files:
+                violations.append(
+                    Violation(
+                        file="src/__tests__/",
+                        message="No test files found in __tests__/",
+                        fix_hint="Add .test.tsx/.test.ts files",
+                    )
+                )
+        else:
+            violations.append(
+                Violation(
+                    file="src/__tests__/",
+                    message="Missing __tests__/ directory",
+                    fix_hint="Create src/__tests__/ with test files",
+                )
+            )
+
+        # package.json test 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 s in ("test", "test:ci"):
+                if s not in scripts:
+                    violations.append(
+                        Violation(
+                            file="package.json",
+                            message=f'Missing script: "{s}"',
+                            fix_hint=f"Add {s} script to package.json",
+                        )
+                    )
+
+        # vitest config
+        vitest_config = app_path / "vitest.config.ts"
+        vite_config = app_path / "vite.config.ts"
+        has_vitest_config = vitest_config.is_file()
+        if not has_vitest_config and vite_config.is_file():
+            content = vite_config.read_text()
+            has_vitest_config = (
+                ("test" in content and "vitest" in content.lower()) or "test:" in content or "test :" in content
+            )
+
+        if not has_vitest_config:
+            violations.append(
+                Violation(
+                    file="vitest.config.ts",
+                    message="No vitest configuration found",
+                    fix_hint="Add vitest.config.ts or test config in vite.config.ts",
+                )
+            )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/theme.py

@@ -0,0 +1,92 @@
+"""Checker: theme setup and color token isolation."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+COLOR_TOKEN_PATTERN = re.compile(r"--(?:primary|secondary|accent|destructive)\s*:")
+
+
+class ThemeChecker:
+    name = "theme"
+    label = "Theme Setup"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+
+        # index.css should import themes/{app}.css
+        index_css = src / "index.css"
+        if index_css.is_file():
+            content = index_css.read_text()
+            expected_import = f"themes/{app_name}.css"
+            if expected_import not in content:
+                violations.append(
+                    Violation(
+                        file="src/index.css",
+                        message=f"index.css does not import {expected_import}",
+                        fix_hint=f'Add @import "{expected_import}" to index.css',
+                    )
+                )
+
+            # No color tokens in index.css
+            for i, line in enumerate(content.splitlines(), 1):
+                if COLOR_TOKEN_PATTERN.search(line):
+                    violations.append(
+                        Violation(
+                            file="src/index.css",
+                            line=i,
+                            message="Color token in index.css — should be in theme file",
+                            fix_hint="Move color tokens to themes/{app}.css",
+                        )
+                    )
+        else:
+            violations.append(Violation(file="src/index.css", message="Missing index.css"))
+
+        # Check globals.css for color tokens too
+        globals_css = src / "globals.css"
+        if globals_css.is_file():
+            content = globals_css.read_text()
+            for i, line in enumerate(content.splitlines(), 1):
+                if COLOR_TOKEN_PATTERN.search(line):
+                    violations.append(
+                        Violation(
+                            file="src/globals.css",
+                            line=i,
+                            message="Color token in globals.css — should be in theme file",
+                            fix_hint="Move color tokens to themes/{app}.css",
+                        )
+                    )
+
+        # ThemeToggle in AppLayout.tsx
+        layout = src / "components" / "AppLayout.tsx"
+        if layout.is_file():
+            content = layout.read_text()
+            if "ThemeToggle" not in content:
+                violations.append(
+                    Violation(
+                        file="src/components/AppLayout.tsx",
+                        message="Missing ThemeToggle in AppLayout",
+                        fix_hint="Add ThemeToggle from @kodemeio/ui",
+                    )
+                )
+            # Check app-specific storageKey
+            if "storageKey" not in content and "ThemeToggle" in content:
+                violations.append(
+                    Violation(
+                        file="src/components/AppLayout.tsx",
+                        message="ThemeToggle missing app-specific storageKey",
+                        fix_hint=f'Add storageKey="{app_name}_theme"',
+                    )
+                )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/ui_standard.py

@@ -0,0 +1,185 @@
+"""Checker: UI standardization — shared component usage and import consistency."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+# Components that should NOT exist locally — they are provided by @kodemeio/ui
+SHARED_COMPONENTS = {
+    "Button.tsx",
+    "Input.tsx",
+    "Textarea.tsx",
+    "Label.tsx",
+    "Select.tsx",
+    "Badge.tsx",
+    "Card.tsx",
+    "Dialog.tsx",
+    "Sheet.tsx",
+    "Alert.tsx",
+    "Table.tsx",
+    "Tabs.tsx",
+    "Tooltip.tsx",
+    "Skeleton.tsx",
+    "Progress.tsx",
+    "Separator.tsx",
+    "ScrollArea.tsx",
+    "Checkbox.tsx",
+    "Switch.tsx",
+    "DropdownMenu.tsx",
+    "Popover.tsx",
+    "RadioGroup.tsx",
+}
+
+# Shared components every app should import from @kodemeio/ui
+REQUIRED_SHARED = ["PageHeader", "LoadingSpinner", "Skeleton", "EmptyState"]
+
+# Pattern for relative path imports to packages/ui
+RELATIVE_UI_IMPORT = re.compile(r"""from\s+["']\.{1,3}/.*packages/ui""")
+
+
+class UiStandardChecker:
+    name = "ui-standard"
+    label = "UI Standardization"
+    max_points = 6
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+        src = app_path / "src"
+
+        # 1. Duplicate components
+        components_dir = src / "components"
+        if components_dir.is_dir():
+            for f in components_dir.rglob("*.tsx"):
+                if f.name in SHARED_COMPONENTS:
+                    rel = str(f.relative_to(app_path))
+                    violations.append(
+                        Violation(
+                            file=rel,
+                            message=f"Local duplicate of @kodemeio/ui component: {f.name}",
+                            auto_fixable=False,
+                        )
+                    )
+
+        # Collect all tsx files for subsequent checks
+        all_tsx: list[Path] = []
+        if src.is_dir():
+            all_tsx = list(src.rglob("*.tsx"))
+            all_tsx = [f for f in all_tsx if "__tests__" not in f.parts]
+
+        all_contents: dict[Path, str] = {}
+        for f in all_tsx:
+            try:
+                all_contents[f] = f.read_text()
+            except OSError:
+                continue
+
+        # 2. Required shared component imports
+        # Check LoadingSpinner OR Skeleton — either counts
+        found_page_header = False
+        found_loading = False
+        found_empty_state = False
+
+        for content in all_contents.values():
+            if "@kodemeio/ui" in content:
+                if "PageHeader" in content:
+                    found_page_header = True
+                if "LoadingSpinner" in content or "Skeleton" in content:
+                    found_loading = True
+                if "EmptyState" in content:
+                    found_empty_state = True
+
+        if not found_page_header:
+            violations.append(
+                Violation(
+                    file="src/",
+                    message="No usage of shared PageHeader from @kodemeio/ui",
+                    fix_hint="Import PageHeader from @kodemeio/ui for consistent UX",
+                )
+            )
+        if not found_loading:
+            violations.append(
+                Violation(
+                    file="src/",
+                    message="No usage of shared LoadingSpinner or Skeleton from @kodemeio/ui",
+                    fix_hint="Import LoadingSpinner or Skeleton from @kodemeio/ui for consistent UX",
+                )
+            )
+        if not found_empty_state:
+            violations.append(
+                Violation(
+                    file="src/",
+                    message="No usage of shared EmptyState from @kodemeio/ui",
+                    fix_hint="Import EmptyState from @kodemeio/ui for consistent UX",
+                )
+            )
+
+        # 3. Badge wrapper pattern
+        if components_dir.is_dir():
+            for f in components_dir.rglob("*.tsx"):
+                name = f.stem  # e.g. "StatusBadge"
+                if name.endswith("Badge") or name.endswith("StatusBadge"):
+                    if f.name in SHARED_COMPONENTS:
+                        continue  # already caught by check 1
+                    try:
+                        content = f.read_text()
+                    except OSError:
+                        continue
+                    if "Badge" not in content or "@kodemeio/ui" not in content:
+                        rel = str(f.relative_to(app_path))
+                        violations.append(
+                            Violation(
+                                file=rel,
+                                message=f"{f.name} should use Badge from @kodemeio/ui as base",
+                            )
+                        )
+
+        # 4. DataTable usage
+        table_page_count = 0
+        has_datatable = False
+        pages_dir = src / "pages"
+
+        for f, content in all_contents.items():
+            if "@kodemeio/ui" in content and "DataTable" in content:
+                has_datatable = True
+
+        if pages_dir.is_dir():
+            for f in pages_dir.rglob("*.tsx"):
+                if "__tests__" in f.parts:
+                    continue
+                content = all_contents.get(f, "")
+                if "<Table" in content or "<table" in content:
+                    table_page_count += 1
+
+        if table_page_count >= 3 and not has_datatable:
+            violations.append(
+                Violation(
+                    file="src/pages/",
+                    message=f"App has {table_page_count} table pages but doesn't use DataTable from @kodemeio/ui",
+                    fix_hint="Use DataTable from @kodemeio/ui for consistent table behavior",
+                )
+            )
+
+        # 5. Import source consistency — relative path imports to packages/ui
+        for f, content in all_contents.items():
+            lines = content.splitlines()
+            rel = str(f.relative_to(app_path))
+            for i, line in enumerate(lines, 1):
+                if RELATIVE_UI_IMPORT.search(line):
+                    violations.append(
+                        Violation(
+                            file=rel,
+                            line=i,
+                            message="Direct path import to packages/ui — use @kodemeio/ui",
+                            auto_fixable=True,
+                        )
+                    )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/checks/vite.py

@@ -0,0 +1,83 @@
+"""Checker: Vite configuration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kctl_react.core.compliance.models import CategoryResult, Violation
+
+# Expected ports per app
+APP_PORTS: dict[str, str] = {
+    "sfa": "4004",
+    "lfa": "4005",
+    "shop": "4006",
+    "wms": "4007",
+    "bia": "4008",
+    "eam": "4009",
+    "mrp": "4010",
+    "hrm": "4011",
+    "tpm": "4012",
+    "dms": "4013",
+    "saas": "4014",
+}
+
+
+class ViteChecker:
+    name = "vite"
+    label = "Vite Config"
+    max_points = 4
+
+    def check(self, app_path: Path, app_name: str) -> CategoryResult:
+        violations: list[Violation] = []
+
+        vite_config = app_path / "vite.config.ts"
+        if not vite_config.is_file():
+            violations.append(
+                Violation(
+                    file="vite.config.ts",
+                    message="Missing vite.config.ts",
+                )
+            )
+            return CategoryResult(
+                name=self.name,
+                label=self.label,
+                max_points=self.max_points,
+                violations=violations,
+            )
+
+        content = vite_config.read_text()
+
+        if "createViteConfig" not in content:
+            violations.append(
+                Violation(
+                    file="vite.config.ts",
+                    message="Does not use createViteConfig from @kodemeio/vite-config",
+                    fix_hint="Use createViteConfig() factory",
+                )
+            )
+
+        if "@kodemeio/vite-config" not in content:
+            violations.append(
+                Violation(
+                    file="vite.config.ts",
+                    message="Does not import from @kodemeio/vite-config",
+                    fix_hint="Import createViteConfig from @kodemeio/vite-config",
+                )
+            )
+
+        expected_port = APP_PORTS.get(app_name)
+        if expected_port and expected_port not in content:
+            violations.append(
+                Violation(
+                    file="vite.config.ts",
+                    message=f"Port {expected_port} not configured for {app_name}",
+                    fix_hint=f"Set port to {expected_port} in vite config",
+                )
+            )
+
+        return CategoryResult(
+            name=self.name,
+            label=self.label,
+            max_points=self.max_points,
+            violations=violations,
+        )

kctl_react/core/compliance/engine.py

@@ -0,0 +1,87 @@
+"""ComplianceEngine — runs checkers and generates reports."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kctl_react.core.compliance.checks import CHECKER_MAP
+from kctl_react.core.compliance.models import AppReport, CategoryResult
+
+
+class ComplianceEngine:
+    """Runs compliance checkers and generates fix prompts."""
+
+    def audit(
+        self,
+        app_path: Path,
+        app_name: str,
+        categories: list[str] | None = None,
+    ) -> AppReport:
+        """Run checkers (filtered by categories if given), return AppReport."""
+        report = AppReport(app=app_name)
+
+        if categories:
+            checkers = [(name, fn) for name, fn in CHECKER_MAP.items() if name in categories]
+        else:
+            checkers = list(CHECKER_MAP.items())
+
+        for _name, checker_fn in checkers:
+            result: CategoryResult = checker_fn(app_path, app_name)
+            report.categories.append(result)
+
+        return report
+
+    def generate_prompt(self, report: AppReport) -> str:
+        """Generate markdown prompt for AI/human fixing."""
+        pct = int(report.total_score / report.max_score * 100) if report.max_score > 0 else 100
+
+        lines: list[str] = [
+            f"# Fix Compliance Issues for `{report.app}`",
+            "",
+            f"- **App path**: `apps/{report.app}`",
+            f"- **Score**: {report.total_score}/{report.max_score} ({pct}%)",
+            f"- **Grade**: {report.grade}",
+            f"- **Total issues**: {report.total_violations}",
+            "",
+        ]
+
+        # Auto-fixable section
+        auto_violations = [(c, v) for c in report.categories for v in c.violations if v.auto_fixable]
+        lines.append("## Auto-fixable (run first)")
+        lines.append("")
+        if auto_violations:
+            lines.append(f"```bash\nkctl-react compliance fix {report.app}\n```")
+            lines.append("")
+            for cat, v in auto_violations:
+                hint = f" -- {v.fix_hint}" if v.fix_hint else ""
+                lines.append(f"- `{v.file}`:{v.line or '?'} {v.message}{hint}")
+        else:
+            lines.append("No auto-fixable issues found.")
+        lines.append("")
+
+        # Manual review section
+        manual_violations = [(c, v) for c in report.categories for v in c.violations if not v.auto_fixable]
+        lines.append("## Issues Requiring Review")
+        lines.append("")
+        if manual_violations:
+            current_cat = ""
+            for cat, v in manual_violations:
+                if cat.label != current_cat:
+                    current_cat = cat.label
+                    lines.append(f"### {current_cat}")
+                    lines.append("")
+                loc = f":{v.line}" if v.line else ""
+                hint = f"\n  - Hint: {v.fix_hint}" if v.fix_hint else ""
+                lines.append(f"- `{v.file}`{loc} {v.message}{hint}")
+            lines.append("")
+        else:
+            lines.append("No manual review issues found.")
+            lines.append("")
+
+        # Verification section
+        lines.append("## Verification")
+        lines.append("")
+        lines.append(f"```bash\nkctl-react compliance audit {report.app}\n```")
+        lines.append("")
+
+        return "\n".join(lines)

kctl_react/core/compliance/exceptions_map.py

@@ -0,0 +1,15 @@
+"""App-specific exceptions for compliance checks."""
+
+from __future__ import annotations
+
+APP_EXCEPTIONS: dict[str, dict[str, list[str]]] = {
+    "mrp": {"skip_providers": ["GPSProvider"]},
+    "tpm": {"skip_providers": ["GPSProvider"]},
+    "saas": {"skip_providers": ["GPSProvider"]},
+    "shop": {"skip_providers": ["GPSProvider"]},
+}
+
+
+def get_skip_providers(app_name: str) -> list[str]:
+    """Return list of providers to skip for the given app."""
+    return APP_EXCEPTIONS.get(app_name, {}).get("skip_providers", [])

kctl_react/core/compliance/fixes/__init__.py

@@ -0,0 +1,33 @@
+"""Auto-fixers registry."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kctl_react.core.compliance.fixes.codegen_fix import fix_codegen
+from kctl_react.core.compliance.fixes.i18n_fix import fix_i18n
+from kctl_react.core.compliance.fixes.imports_fix import fix_imports
+from kctl_react.core.compliance.fixes.structure_fix import fix_structure
+from kctl_react.core.compliance.fixes.theme_fix import fix_theme
+
+ALL_FIXERS: dict = {
+    "structure": fix_structure,
+    "imports": fix_imports,
+    "i18n": fix_i18n,
+    "codegen": fix_codegen,
+    "theme": fix_theme,
+}
+
+
+def apply_fixes(
+    app_path: Path,
+    app_name: str,
+    dry_run: bool = False,
+    categories: list[str] | None = None,
+) -> int:
+    """Apply auto-fixes and return count of fixes applied."""
+    fixers = {k: v for k, v in ALL_FIXERS.items() if not categories or k in categories}
+    total = 0
+    for fix_fn in fixers.values():
+        total += fix_fn(app_path, app_name, dry_run=dry_run)
+    return total

kctl_react/core/compliance/fixes/codegen_fix.py

@@ -0,0 +1,28 @@
+"""Fixer: create openapi-ts.config.ts if missing."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_TEMPLATE = """\
+import { defineConfig } from "@hey-api/openapi-ts";
+
+export default defineConfig({
+  client: "@hey-api/client-fetch",
+  input: "openapi.json",
+  output: "src/generated",
+  services: false,
+  schemas: false,
+});
+"""
+
+
+def fix_codegen(app_path: Path, app_name: str, dry_run: bool = False) -> int:
+    """Create openapi-ts.config.ts if missing. Return count of fixes applied."""
+    config_file = app_path / "openapi-ts.config.ts"
+    if config_file.is_file():
+        return 0
+
+    if not dry_run:
+        config_file.write_text(_TEMPLATE, encoding="utf-8")
+    return 1