clckernel 1.2.18 → 2.0.0

package/tools/celery_guard.py

@@ -9,33 +9,14 @@ from __future__ import annotations
 import ast
 import json
 import os
-import subprocess
 import sys
-from pathlib import Path
 
-
-def _get_changed_files(target_dir: str) -> list[str] | None:
-    """Return list of changed Python 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
+# Sibling helper shipped next to the guards; works both as a script and when
+# loaded by audit.py through importlib.
+_TOOLS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _TOOLS_DIR not in sys.path:
+    sys.path.insert(0, _TOOLS_DIR)
+import _changes  # noqa: E402
 
 
 class CeleryVisitor(ast.NodeVisitor):
@@ -155,8 +136,10 @@ def check(target_dir: str | None = None) -> dict:
     """
     dir_path = target_dir or os.getcwd()
 
-    files = _get_changed_files(dir_path)
-    if files is None:
+    # The snapshot being verified: the index, or HEAD when nothing is staged.
+    changes = _changes.changed_files(dir_path, extensions=[".py"])
+    mode, files = changes["mode"], changes["files"]
+    if mode is None:
         return {
             "exit_code": 0, "skipped": True, "name": "celery_guard",
             "data": {"findings": [], "message": "No git diff available"},
@@ -171,17 +154,12 @@ def check(target_dir: str | None = None) -> dict:
     all_violations: list[dict] = []
 
     for filepath in files:
-        full_path = Path(dir_path) / filepath
-        if not full_path.exists():
-            continue
-
-        try:
-            content = full_path.read_text(encoding="utf-8", errors="replace")
-        except (OSError, PermissionError):
+        content = _changes.read_file(dir_path, filepath, mode)
+        if content is None:
             continue
 
         try:
-            tree = ast.parse(content, filename=str(full_path))
+            tree = ast.parse(content, filename=filepath)
         except SyntaxError:
             continue
 

package/tools/check_a11y.js

@@ -8,28 +8,15 @@
  * @param {string} targetDir - Directory to scan (defaults to cwd)
  * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
  */
-const check = async function checkA11y(targetDir) {
-  const fs = require('fs');
-  const path = require('path');
-  const { execSync } = require('child_process');
+const { changedFiles, readFile } = require('./_changes');
 
+const check = async function checkA11y(targetDir) {
   const dir = targetDir || process.cwd();
 
-  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)$/.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)$/.test(f.trim()));
-    } catch {
-      return { exitCode: 0, skipped: true, name: 'check_a11y', data: { violations: {}, message: 'No git diff available' } };
-    }
+  // The snapshot being verified: the index, or HEAD when nothing is staged.
+  const { mode, files } = changedFiles(dir, { extensions: ['.tsx', '.jsx'] });
+  if (mode === null) {
+    return { exitCode: 0, skipped: true, name: 'check_a11y', data: { violations: {}, message: 'No git diff available' } };
   }
 
   if (!files || files.length === 0) {
@@ -39,15 +26,8 @@ const check = async function checkA11y(targetDir) {
   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 content = readFile(dir, file, mode);
+    if (content === null) continue;
 
     const lines = content.split('\n');
     const fileViolations = [];

package/tools/check_api_contracts.js

@@ -7,40 +7,16 @@
  * @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 { changedFiles, readFile, nearestPackageDeps } = require('./_changes');
 
+const check = async function checkApiContracts(targetDir) {
   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 */ }
-  }
+  // The snapshot being verified: the index, or HEAD when nothing is staged.
+  const { mode, files } = changedFiles(dir, { extensions: ['.ts', '.js', '.tsx', '.jsx'] });
 
-  // 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 (mode === null) {
+    return { exitCode: 0, skipped: true, name: 'check_api_contracts', data: { violations: {}, message: 'No git diff available' } };
   }
 
   if (!files || files.length === 0) {
@@ -57,17 +33,15 @@ const check = async function checkApiContracts(targetDir) {
   }
 
   const violations = {};
+  const pkgCache = new Map();
 
   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 content = readFile(dir, file, mode);
+    if (content === null) continue;
+
+    // Zod available to this file: its nearest package.json (a monorepo part's
+    // own, else the root's), as of the same snapshot.
+    const hasZod = Boolean((nearestPackageDeps(dir, file, mode, pkgCache) || {}).zod);
 
     const fileViolations = [];
 

package/tools/check_architecture.js

@@ -7,48 +7,46 @@
  * @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' } };
-  }
+const { changedFiles, readFile, nearestPackageDeps } = require('./_changes');
 
-  let isNext;
+/**
+ * Skip message when the root package.json (as of the snapshot) is missing or
+ * does not depend on next; null when the root is a Next.js project.
+ * @returns {string|null}
+ */
+function rootSkip(dir, mode) {
+  const pkgRaw = readFile(dir, 'package.json', mode);
+  if (pkgRaw === null) return 'No package.json found — skipping architecture check';
   try {
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const pkg = JSON.parse(pkgRaw);
     const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
-    isNext = Boolean(deps['next']);
+    if (deps['next']) return null;
   } catch {
-    isNext = false;
+    // Malformed package.json: not a Next.js project.
   }
+  return 'Not a Next.js project — skipping';
+}
+
+const check = async function checkArchitecture(targetDir) {
+  const dir = targetDir || process.cwd();
+
+  // The snapshot being verified: the index, or HEAD when nothing is staged.
+  const { mode, files } = changedFiles(dir, { extensions: ['.tsx', '.jsx', '.ts', '.js'] });
 
-  if (!isNext) {
-    return { exitCode: 0, skipped: true, name: 'check_architecture', data: { violations: {}, message: 'Not a Next.js project — skipping' } };
+  // Each changed file belongs to the project of its nearest package.json (a
+  // monorepo part's own, else the root's), as of the same snapshot: only
+  // files of a Next.js project are checked.
+  const pkgCache = new Map();
+  const nextFiles = files.filter(f => Boolean((nearestPackageDeps(dir, f, mode, pkgCache) || {}).next));
+
+  // No changed file in a Next.js project: the root package.json decides.
+  if (nextFiles.length === 0) {
+    const skip = rootSkip(dir, mode);
+    if (skip) return { exitCode: 0, skipped: true, name: 'check_architecture', data: { violations: {}, message: skip } };
   }
 
-  // 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 (mode === null) {
+    return { exitCode: 0, skipped: true, name: 'check_architecture', data: { violations: {}, message: 'No git diff available' } };
   }
 
   if (!files || files.length === 0) {
@@ -57,16 +55,9 @@ const check = async function checkArchitecture(targetDir) {
 
   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;
-    }
+  for (const file of nextFiles) {
+    const content = readFile(dir, file, mode);
+    if (content === null) continue;
 
     const fileViolations = [];
     const isLayout = /layout\.(tsx|jsx|ts|js)$/.test(file);

package/tools/check_architecture.py

@@ -6,6 +6,9 @@ Validates that Python code respects architectural layer boundaries:
   - 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.
+The framework is decided per changed file, from its nearest project root in the
+snapshot (manage.py / pyproject.toml / setup.cfg / requirements*.txt), so each
+part of a monorepo gets its own rules.
 Self-contained: uses only Python stdlib (ast, pathlib, subprocess, json).
 """
 from __future__ import annotations
@@ -13,56 +16,115 @@ from __future__ import annotations
 import ast
 import json
 import os
-import pathlib
 import re
-import subprocess
 import sys
 
+# Sibling helper shipped next to the guards; works both as a script and when
+# loaded by audit.py through importlib.
+_TOOLS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _TOOLS_DIR not in sys.path:
+    sys.path.insert(0, _TOOLS_DIR)
+import _changes  # noqa: E402
 
-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
+
+# Files that make their directory a Python project root (requirements*.txt too).
+_ROOT_MARKERS = ("manage.py", "pyproject.toml", "setup.cfg")
+
+
+def _is_requirements(name: str) -> bool:
+    return name.startswith("requirements") and name.endswith(".txt")
 
 
-def _detect_framework(target_dir: str) -> str:
-    """Detect whether this is a Django, FastAPI, or generic Python project."""
-    root = pathlib.Path(target_dir)
+def _markers_by_dir(target_dir: str, mode: str | None) -> dict[str, list[str]]:
+    """Project-marker file names of the snapshot, by directory ("" for the repository root)."""
+    by_dir: dict[str, list[str]] = {}
+    for rel in _changes.list_files(target_dir, mode):
+        head, _, name = rel.rpartition("/")
+        if name in _ROOT_MARKERS or _is_requirements(name):
+            by_dir.setdefault(head, []).append(name)
+    return by_dir
 
-    if (root / "manage.py").exists():
+
+def _framework_of(target_dir: str, mode: str | None, directory: str, names: list[str]) -> str:
+    """Framework of the project rooted at directory, from its marker files (snapshot content)."""
+    if "manage.py" in names:
         return "django"
+    found = "generic"
+    for name in sorted(names):
+        text = _changes.read_file(target_dir, f"{directory}/{name}" if directory else name, mode)
+        if text is None:
+            continue
+        text = text.lower()
+        if "django" in text:
+            return "django"
+        if "fastapi" in text:
+            found = "fastapi"
+    return found
+
+
+def _nearest_framework(
+    target_dir: str, mode: str | None, filepath: str,
+    markers: dict[str, list[str]], cache: dict[str, str],
+) -> str:
+    """
+    Framework of the nearest project root of a repository path: the file's
+    directory, then each parent up to the repository root; the first one
+    holding a project marker decides (a monorepo part's own manifest wins over
+    the root one). Memoized per directory in cache.
+    """
+    visited: list[str] = []
+    current = filepath.rpartition("/")[0]
+    framework = "generic"
+    while True:
+        if current in cache:
+            framework = cache[current]
+            break
+        visited.append(current)
+        if current in markers:
+            framework = _framework_of(target_dir, mode, current, markers[current])
+            break
+        if not current:
+            break
+        current = current.rpartition("/")[0]
+    for directory in visited:
+        cache[directory] = framework
+    return framework
+
+
+def _package_parts(filepath: str) -> list[str]:
+    """Directory segments of a file: the package a relative import resolves against."""
+    return [part for part in filepath.replace("\\", "/").split("/")[:-1] if part]
+
+
+def _imported_modules(node: ast.AST, filepath: str, with_names: bool = True) -> list[str]:
+    """
+    Every module an import statement reaches, as dotted absolute names.
 
-    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"
+    `import a, b` yields a and b; `from m import x` yields m and m.x (x may be a
+    submodule; only with with_names); relative imports are resolved against
+    the file's package path.
+    """
+    if isinstance(node, ast.Import):
+        return [alias.name for alias in node.names]
+    if not isinstance(node, ast.ImportFrom):
+        return []
+
+    if node.level:
+        package = _package_parts(filepath)
+        keep = max(0, len(package) - (node.level - 1))
+        base = package[:keep]
+    else:
+        base = []
+    if node.module:
+        base = base + node.module.split(".")
 
-    return "generic"
+    modules = [".".join(base)] if base else []
+    if not with_names:
+        return modules
+    for alias in node.names:
+        if alias.name != "*":
+            modules.append(".".join(base + [alias.name]))
+    return modules
 
 
 def _check_django_layers(
@@ -91,14 +153,7 @@ def _check_django_layers(
         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
-
+        for imported in _imported_modules(node, filepath, with_names=False):
             # Django models should not import from views, urls, admin
             if file_layer == "models":
                 bad_targets = ("views", "urls", "admin", "serializers", "forms")
@@ -134,60 +189,73 @@ def _check_django_layers(
     return violations
 
 
+# Clean Architecture layers: the directory names that mark each one.
+_LAYER_DIRS = {
+    "domain": ("domain",),
+    "application": ("application", "use_cases"),
+    "infrastructure": ("infrastructure", "adapters"),
+    "routes": ("routes", "api"),
+}
+
+# For each layer, the directory names its code must not import from.
+_FORBIDDEN = {
+    "domain": ("application", "use_cases", "infrastructure", "adapters", "routes", "api"),
+    "application": ("infrastructure", "adapters", "routes", "api"),
+}
+
+_REASONS = {
+    "domain": "Domain layer imports from '{0}' — domain must be framework-independent",
+    "application": "Application layer imports from '{0}' — use dependency inversion",
+}
+
+
+def _file_layer(filepath: str) -> str | None:
+    """The layer of a file: the first layer (by priority) whose name is a path segment."""
+    segments = set(_package_parts(filepath))
+    for layer, names in _LAYER_DIRS.items():
+        if segments.intersection(names):
+            return layer
+    return None
+
+
+def _own_prefix_len(module_parts: list[str], package: list[str]) -> int:
+    """Leading segments an imported module shares with the importing file's package."""
+    n = 0
+    for a, b in zip(module_parts, package):
+        if a != b:
+            break
+        n += 1
+    return n
+
+
 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
+    file_layer = _file_layer(filepath)
+    if file_layer not in _FORBIDDEN:
+        return violations  # Unknown layer, or one with no outgoing restriction
 
-    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"
-                            ),
-                        })
+    package = _package_parts(filepath)
+    forbidden = _FORBIDDEN[file_layer]
 
-            # 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"
-                            ),
-                        })
+    for node in ast.walk(tree):
+        reported: set[str] = set()
+        for imported in _imported_modules(node, filepath):
+            parts = imported.split(".")
+            # Segments shared with the file's own package (e.g. a root package
+            # named `api`) are the file's location, not the imported layer.
+            tail = parts[_own_prefix_len(parts, package):]
+            for b in forbidden:
+                if b in tail and b not in reported:
+                    reported.add(b)
+                    violations.append({
+                        "lineNo": getattr(node, "lineno", 0),
+                        "module": imported,
+                        "reason": _REASONS[file_layer].format(b),
+                    })
 
     return violations
 
@@ -202,8 +270,10 @@ def check(target_dir: str | None = None) -> dict:
     """
     dir_path = target_dir or os.getcwd()
 
-    files = _get_changed_py_files(dir_path)
-    if files is None:
+    # The snapshot being verified: the index, or HEAD when nothing is staged.
+    changes = _changes.changed_files(dir_path, extensions=[".py"])
+    mode, files = changes["mode"], changes["files"]
+    if mode is None:
         return {
             "exit_code": 0, "skipped": True, "name": "check_architecture",
             "data": {"violations": {}, "message": "No git diff available"},
@@ -215,17 +285,14 @@ def check(target_dir: str | None = None) -> dict:
             "data": {"violations": {}, "message": "No Python files changed"},
         }
 
-    framework = _detect_framework(dir_path)
+    # Each file is judged by its own project part (Django in backend/, FastAPI in api/, ...).
+    markers = _markers_by_dir(dir_path, mode)
+    frameworks: dict[str, str] = {}
     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):
+        content = _changes.read_file(dir_path, filepath, mode)
+        if content is None:
             continue
 
         try:
@@ -233,7 +300,7 @@ def check(target_dir: str | None = None) -> dict:
         except SyntaxError:
             continue
 
-        if framework == "django":
+        if _nearest_framework(dir_path, mode, filepath, markers, frameworks) == "django":
             file_violations = _check_django_layers(filepath, content, tree)
         else:
             file_violations = _check_clean_architecture(filepath, content, tree)