clckernel 1.2.6

package/tools/check_api_contracts.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * Zod API Contract Guard
+ * Validates that API routes use Zod for request/response schema validation.
+ * Self-contained: uses only Node.js built-ins.
+ *
+ * @param {string} targetDir - Directory to scan (defaults to cwd)
+ * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
+ */
+const check = async function checkApiContracts(targetDir) {
+  const fs = require('fs');
+  const path = require('path');
+  const { execSync } = require('child_process');
+
+  const dir = targetDir || process.cwd();
+
+  // Check if Zod is available
+  let hasZod = false;
+  const pkgPath = path.join(dir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      hasZod = Boolean(deps['zod']);
+    } catch { /* skip */ }
+  }
+
+  // Collect API route files
+  let files;
+  try {
+    const out = execSync('git diff --name-only HEAD~1', {
+      cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
+    });
+    files = out.split('\n').filter(f => /\.(ts|js|tsx|jsx)$/.test(f.trim()));
+  } catch {
+    try {
+      const out = execSync('git diff --name-only --cached', {
+        cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
+      });
+      files = out.split('\n').filter(f => /\.(ts|js|tsx|jsx)$/.test(f.trim()));
+    } catch {
+      return { exitCode: 0, skipped: true, name: 'check_api_contracts', data: { violations: {}, message: 'No git diff available' } };
+    }
+  }
+
+  if (!files || files.length === 0) {
+    return { exitCode: 0, skipped: false, name: 'check_api_contracts', data: { violations: {}, message: 'No files changed' } };
+  }
+
+  // Identify API route files (Next.js App Router or Pages Router)
+  const apiFiles = files.filter(f =>
+    f.includes('/api/') || f.includes('route.') || f.includes('/routes/')
+  );
+
+  if (apiFiles.length === 0) {
+    return { exitCode: 0, skipped: false, name: 'check_api_contracts', data: { violations: {}, message: 'No API route files changed' } };
+  }
+
+  const violations = {};
+
+  for (const file of apiFiles) {
+    const filePath = path.join(dir, file);
+    if (!fs.existsSync(filePath)) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const fileViolations = [];
+
+    // Check: API route handler without Zod validation
+    const hasHandler = /export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH)/.test(content);
+    if (hasHandler) {
+      // Look for request body parsing without Zod
+      if (/await\s+req\.json\s*\(\s*\)/.test(content) && !/\.parse\s*\(|\.safeParse\s*\(/.test(content)) {
+        fileViolations.push({
+          lineNo: 0,
+          rule: 'no-body-validation',
+          message: 'API route parses request body without Zod validation — use z.object().parse() or .safeParse()',
+        });
+      }
+
+      // Look for NextRequest without Zod
+      if (/NextRequest/.test(content) && !/z\.|zod/.test(content)) {
+        fileViolations.push({
+          lineNo: 0,
+          rule: 'no-request-validation',
+          message: 'API route uses NextRequest without Zod schema validation',
+        });
+      }
+
+      // Check: response without schema validation
+      if (/Response\.json\s*\(/.test(content) && !/z\.|zod/.test(content) && hasZod) {
+        fileViolations.push({
+          lineNo: 0,
+          rule: 'no-response-validation',
+          message: 'API route returns JSON without Zod response schema — consider validating output',
+        });
+      }
+    }
+
+    // Check: fetch calls without response validation
+    if (/fetch\s*\(/.test(content) && !/z\.|zod/.test(content) && hasZod) {
+      fileViolations.push({
+        lineNo: 0,
+        rule: 'no-fetch-validation',
+        message: 'fetch() call without Zod response parsing — validate external API responses',
+      });
+    }
+
+    if (fileViolations.length > 0) {
+      violations[file] = fileViolations;
+    }
+  }
+
+  const totalCount = Object.values(violations).flat().length;
+  return {
+    exitCode: totalCount > 0 ? 1 : 0,
+    skipped: false,
+    name: 'check_api_contracts',
+    data: {
+      violations,
+      message: totalCount > 0
+        ? `${totalCount} API contract issue(s) found in ${Object.keys(violations).length} file(s)`
+        : 'All API contract checks passed',
+    },
+  };
+};
+module.exports = check;
+
+if (require.main === module) {
+  check(process.argv[2]).then(result => {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.exitCode);
+  });
+}

package/tools/check_architecture.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * Next.js Architecture & Server Components Guard
+ * Validates Server Component boundaries, layout protection, and layer separation.
+ * Self-contained: uses only Node.js built-ins.
+ *
+ * @param {string} targetDir - Directory to scan (defaults to cwd)
+ * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
+ */
+const check = async function checkArchitecture(targetDir) {
+  const fs = require('fs');
+  const path = require('path');
+  const { execSync } = require('child_process');
+
+  const dir = targetDir || process.cwd();
+
+  // Verify this is a Next.js project
+  const pkgPath = path.join(dir, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    return { exitCode: 0, skipped: true, name: 'check_architecture', data: { violations: {}, message: 'No package.json found — skipping architecture check' } };
+  }
+
+  let isNext;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    isNext = Boolean(deps['next']);
+  } catch {
+    isNext = false;
+  }
+
+  if (!isNext) {
+    return { exitCode: 0, skipped: true, name: 'check_architecture', data: { violations: {}, message: 'Not a Next.js project — skipping' } };
+  }
+
+  // Collect changed files
+  let files;
+  try {
+    const out = execSync('git diff --name-only HEAD~1', {
+      cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
+    });
+    files = out.split('\n').filter(f => /\.(tsx|jsx|ts|js)$/.test(f.trim()));
+  } catch {
+    try {
+      const out = execSync('git diff --name-only --cached', {
+        cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
+      });
+      files = out.split('\n').filter(f => /\.(tsx|jsx|ts|js)$/.test(f.trim()));
+    } catch {
+      return { exitCode: 0, skipped: true, name: 'check_architecture', data: { violations: {}, message: 'No git diff available' } };
+    }
+  }
+
+  if (!files || files.length === 0) {
+    return { exitCode: 0, skipped: false, name: 'check_architecture', data: { violations: {}, message: 'No files changed' } };
+  }
+
+  const violations = {};
+
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+    if (!fs.existsSync(filePath)) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const fileViolations = [];
+    const isLayout = /layout\.(tsx|jsx|ts|js)$/.test(file);
+    const isPage = /page\.(tsx|jsx|ts|js)$/.test(file);
+    const hasUseClient = /['"]use client['"]/.test(content);
+
+    // Check: layout.tsx should NOT have "use client"
+    if (isLayout && hasUseClient) {
+      fileViolations.push({ lineNo: 1, module: 'layout-boundary', reason: 'Layout must be a Server Component — remove "use client"' });
+    }
+
+    // Check: page.tsx should NOT have "use client" (prefer Server Components)
+    if (isPage && hasUseClient) {
+      fileViolations.push({ lineNo: 1, module: 'page-boundary', reason: 'Page uses "use client" — prefer Server Component unless client interactivity is required' });
+    }
+
+    // Check: files with "use client" importing server-only modules
+    if (hasUseClient) {
+      if (/require\s*\(\s*['"]fs['"]\s*\)/.test(content) || /from\s+['"]fs['"]/.test(content)) {
+        fileViolations.push({ lineNo: 0, module: 'server-in-client', reason: 'Client Component imports "fs" — use a Server Component or API route instead' });
+      }
+      if (/require\s*\(\s*['"]path['"]\s*\)/.test(content) || /from\s+['"]path['"]/.test(content)) {
+        fileViolations.push({ lineNo: 0, module: 'server-in-client', reason: 'Client Component imports "path" — move logic to Server Component' });
+      }
+      if (/require\s*\(\s*['"]child_process['"]\s*\)/.test(content) || /from\s+['"]child_process['"]/.test(content)) {
+        fileViolations.push({ lineNo: 0, module: 'server-in-client', reason: 'Client Component imports "child_process" — this is a server-only module' });
+      }
+    }
+
+    // Check: files without "use client" using useState/useEffect
+    if (!hasUseClient && (/\buseState\b/.test(content) || /\buseEffect\b/.test(content))) {
+      fileViolations.push({ lineNo: 0, module: 'missing-use-client', reason: 'Uses React hooks without "use client" directive — add directive or move to Client Component' });
+    }
+
+    // Check: files without "use client" using onClick/onSubmit handlers
+    if (!hasUseClient && /on(Click|Submit|Change|Focus|Blur)\s*=\s*\{/.test(content)) {
+      fileViolations.push({ lineNo: 0, module: 'event-handler', reason: 'Event handler in Server Component — move to Client Component with "use client"' });
+    }
+
+    // Check: "use server" should only be in API or action files
+    if (/['"]use server['"]/.test(content) && !/action|api|route/i.test(file)) {
+      fileViolations.push({ lineNo: 1, module: 'server-action-location', reason: '"use server" in non-action file — Server Actions belong in dedicated action files' });
+    }
+
+    if (fileViolations.length > 0) {
+      violations[file] = fileViolations;
+    }
+  }
+
+  const totalCount = Object.values(violations).flat().length;
+  return {
+    exitCode: totalCount > 0 ? 1 : 0,
+    skipped: false,
+    name: 'check_architecture',
+    data: {
+      violations,
+      message: totalCount > 0
+        ? `${totalCount} architecture issue(s) found in ${Object.keys(violations).length} file(s)`
+        : 'All architecture checks passed',
+    },
+  };
+};
+module.exports = check;
+
+if (require.main === module) {
+  check(process.argv[2]).then(result => {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.exitCode);
+  });
+}

package/tools/check_architecture.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""
+Clean Architecture / Django Layer Boundary Guard
+Validates that Python code respects architectural layer boundaries:
+  - Domain layer should not import from Application or Infrastructure
+  - Application layer should not import from Infrastructure or Routes
+  - Routes/API should not import from Domain directly (go through Application)
+For Django: checks that models don't import from views, views don't import from urls, etc.
+Self-contained: uses only Python stdlib (ast, pathlib, subprocess, json).
+"""
+from __future__ import annotations
+
+import ast
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+
+
+def _get_changed_py_files(target_dir: str) -> list[str] | None:
+    """Return changed .py files from git diff, or None on failure."""
+    for ref in ("HEAD~1", "--cached"):
+        try:
+            args = ["git", "diff", "--name-only"]
+            if ref == "--cached":
+                args.append("--cached")
+            else:
+                args.append(ref)
+            out = subprocess.check_output(
+                args, cwd=target_dir,
+                stderr=subprocess.DEVNULL, text=True,
+            )
+            files = [
+                f.strip() for f in out.splitlines()
+                if f.strip().endswith(".py")
+            ]
+            if files:
+                return files
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            continue
+    return None
+
+
+def _detect_framework(target_dir: str) -> str:
+    """Detect whether this is a Django, FastAPI, or generic Python project."""
+    root = pathlib.Path(target_dir)
+
+    if (root / "manage.py").exists():
+        return "django"
+
+    for name in ("pyproject.toml", "requirements.txt"):
+        fpath = root / name
+        if fpath.exists():
+            try:
+                text = fpath.read_text(encoding="utf-8", errors="replace").lower()
+            except OSError:
+                continue
+            if "django" in text:
+                return "django"
+            if "fastapi" in text:
+                return "fastapi"
+
+    return "generic"
+
+
+def _check_django_layers(
+    filepath: str, content: str, tree: ast.Module,
+) -> list[dict]:
+    """Check Django layer boundary violations."""
+    violations: list[dict] = []
+    rel_path = filepath
+
+    # Determine file layer from path
+    if "/models" in rel_path or rel_path.endswith("/models.py"):
+        file_layer = "models"
+    elif "/views" in rel_path or rel_path.endswith("/views.py"):
+        file_layer = "views"
+    elif "/urls" in rel_path or rel_path.endswith("/urls.py"):
+        file_layer = "urls"
+    elif "/serializers" in rel_path or rel_path.endswith("/serializers.py"):
+        file_layer = "serializers"
+    elif "/forms" in rel_path or rel_path.endswith("/forms.py"):
+        file_layer = "forms"
+    elif "/admin" in rel_path or rel_path.endswith("/admin.py"):
+        file_layer = "admin"
+    elif "/tasks" in rel_path or rel_path.endswith("/tasks.py"):
+        file_layer = "tasks"
+    else:
+        return violations  # Can't determine layer, skip
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            if isinstance(node, ast.ImportFrom) and node.module:
+                imported = node.module
+            elif isinstance(node, ast.Import):
+                imported = node.names[0].name if node.names else ""
+            else:
+                continue
+
+            # Django models should not import from views, urls, admin
+            if file_layer == "models":
+                bad_targets = ("views", "urls", "admin", "serializers", "forms")
+                for bad in bad_targets:
+                    if f".{bad}" in imported or imported == bad:
+                        violations.append({
+                            "lineNo": getattr(node, "lineno", 0),
+                            "module": imported,
+                            "reason": (
+                                f"Model imports from {bad} layer — "
+                                f"models must not depend on presentation or routing"
+                            ),
+                        })
+
+            # Views should not import from other views or urls
+            if file_layer == "views":
+                if ".urls" in imported or imported.endswith("urls"):
+                    violations.append({
+                        "lineNo": getattr(node, "lineno", 0),
+                        "module": imported,
+                        "reason": "View imports from urls — views should not depend on URL configuration",
+                    })
+
+            # URLs should not import from models directly
+            if file_layer == "urls":
+                if ".models" in imported or imported.endswith("models"):
+                    violations.append({
+                        "lineNo": getattr(node, "lineno", 0),
+                        "module": imported,
+                        "reason": "URL module imports models directly — route through views",
+                    })
+
+    return violations
+
+
+def _check_clean_architecture(
+    filepath: str, content: str, tree: ast.Module,
+) -> list[dict]:
+    """Check Clean Architecture boundary violations for generic Python projects."""
+    violations: list[dict] = []
+
+    # Detect layer from path
+    if "/domain" in filepath:
+        file_layer = "domain"
+    elif "/application" in filepath or "/use_cases" in filepath:
+        file_layer = "application"
+    elif "/infrastructure" in filepath or "/adapters" in filepath:
+        file_layer = "infrastructure"
+    elif "/routes" in filepath or "/api" in filepath:
+        file_layer = "routes"
+    else:
+        return violations  # Can't determine layer
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            if isinstance(node, ast.ImportFrom) and node.module:
+                imported = node.module
+            elif isinstance(node, ast.Import):
+                imported = node.names[0].name if node.names else ""
+            else:
+                continue
+
+            # Domain must not import from application, infrastructure, or routes
+            if file_layer == "domain":
+                bad = ("application", "use_cases", "infrastructure", "adapters", "routes", "api")
+                for b in bad:
+                    if f".{b}" in imported or imported.startswith(b):
+                        violations.append({
+                            "lineNo": getattr(node, "lineno", 0),
+                            "module": imported,
+                            "reason": (
+                                f"Domain layer imports from '{b}' — "
+                                f"domain must be framework-independent"
+                            ),
+                        })
+
+            # Application must not import from infrastructure or routes
+            if file_layer == "application":
+                bad = ("infrastructure", "adapters", "routes", "api")
+                for b in bad:
+                    if f".{b}" in imported or imported.startswith(b):
+                        violations.append({
+                            "lineNo": getattr(node, "lineno", 0),
+                            "module": imported,
+                            "reason": (
+                                f"Application layer imports from '{b}' — "
+                                f"use dependency inversion"
+                            ),
+                        })
+
+    return violations
+
+
+def check(target_dir: str | None = None) -> dict:
+    """
+    Validate architecture layer boundaries in changed Python files.
+
+    Returns:
+        dict with keys: exit_code, skipped, name, data
+        data.violations maps filepath -> list of {lineNo, module, reason}
+    """
+    dir_path = target_dir or os.getcwd()
+
+    files = _get_changed_py_files(dir_path)
+    if files is None:
+        return {
+            "exit_code": 0, "skipped": True, "name": "check_architecture",
+            "data": {"violations": {}, "message": "No git diff available"},
+        }
+
+    if not files:
+        return {
+            "exit_code": 0, "skipped": False, "name": "check_architecture",
+            "data": {"violations": {}, "message": "No Python files changed"},
+        }
+
+    framework = _detect_framework(dir_path)
+    violations: dict[str, list[dict]] = {}
+
+    for filepath in files:
+        full_path = pathlib.Path(dir_path) / filepath
+        if not full_path.exists():
+            continue
+
+        try:
+            content = full_path.read_text(encoding="utf-8", errors="replace")
+        except (OSError, PermissionError):
+            continue
+
+        try:
+            tree = ast.parse(content, filename=filepath)
+        except SyntaxError:
+            continue
+
+        if framework == "django":
+            file_violations = _check_django_layers(filepath, content, tree)
+        else:
+            file_violations = _check_clean_architecture(filepath, content, tree)
+
+        if file_violations:
+            violations[filepath] = file_violations
+
+    total = sum(len(v) for v in violations.values())
+    if total:
+        msg = (
+            f"{total} architecture violation(s) found in "
+            f"{len(violations)} file(s)"
+        )
+    else:
+        msg = "All architecture checks passed"
+
+    return {
+        "exit_code": 1 if total else 0,
+        "skipped": False,
+        "name": "check_architecture",
+        "data": {"violations": violations, "message": msg},
+    }
+
+
+if __name__ == "__main__":
+    result = check(sys.argv[1] if len(sys.argv) > 1 else None)
+    print(json.dumps(result, indent=2))
+    sys.exit(result["exit_code"])