clckernel 1.2.18 → 2.0.0

package/tools/check_migrations.py

@@ -1,12 +1,13 @@
 #!/usr/bin/env python3
 """
-Alembic / Django Migration Idempotency & Safety Guard
-Checks that database migration scripts follow safe practices:
-  - Migrations have both upgrade() and downgrade()
-  - No destructive operations without downgrade safeguards
-  - Migration files are not empty
-  - Django migrations reference existing model classes
-Self-contained: uses only Python stdlib (ast, pathlib, subprocess, json).
+Alembic / Django Migration Reversibility & Safety Guard
+Checks that database migration scripts are reversible:
+  - Alembic migrations have both upgrade() and downgrade()
+  - A destructive op in upgrade() (drop_table/drop_column/drop_index/
+    drop_constraint) has a matching create/add op in downgrade()
+  - Django RunPython/RunSQL operations pass a reverse (positionally or by keyword)
+  - Django migration files are not empty
+Self-contained: uses only Python stdlib (ast-based checks; pathlib, subprocess, json).
 """
 from __future__ import annotations
 
@@ -14,30 +15,31 @@ 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_files(target_dir: str) -> list[str] | None:
-    """Return changed 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()]
-            if files:
-                return files
-        except (subprocess.CalledProcessError, FileNotFoundError):
-            continue
-    return None
+
+def _is_migration_path(rel: str) -> bool:
+    """
+    True for the paths _find_migration_files would report: alembic/versions/*.py
+    and *.py (except __init__.py) directly inside a migrations/ directory that
+    is not hidden and not under __pycache__.
+    """
+    parts = pathlib.PurePosixPath(rel).parts
+    if not rel.endswith(".py") or len(parts) < 2:
+        return False
+    if parts[:2] == ("alembic", "versions") and len(parts) == 3:
+        return True
+    if parts[-2] != "migrations" or parts[-1] == "__init__.py":
+        return False
+    migrations_dir = "/".join(parts[:-1])
+    return not migrations_dir.startswith(".") and "__pycache__" not in migrations_dir
 
 
 def _find_migration_files(target_dir: str) -> list[str]:
@@ -65,51 +67,104 @@ def _find_migration_files(target_dir: str) -> list[str]:
     return migrations
 
 
+# Destructive Alembic ops and the ops in downgrade() that undo each of them.
+_DESTRUCTIVE_OPS = {
+    "drop_table": ("create_table",),
+    "drop_column": ("add_column",),
+    "drop_index": ("create_index",),
+    "drop_constraint": (
+        "create_foreign_key", "create_unique_constraint", "create_check_constraint",
+        "create_primary_key", "create_exclude_constraint",
+    ),
+}
+
+
+def _method_calls(node: ast.AST | None) -> list[ast.Call]:
+    """Every `<receiver>.<method>(...)` call under node (op.x, batch_op.x, ...)."""
+    if node is None:
+        return []
+    return [
+        n for n in ast.walk(node)
+        if isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute)
+    ]
+
+
+def _module_function(tree: ast.Module, name: str) -> ast.FunctionDef | None:
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == name:
+            return node
+    return None
+
+
 def _check_alembic_migration(filepath: str, content: str) -> list[dict]:
-    """Check an Alembic migration file for issues."""
+    """Check an Alembic migration file for reversibility."""
     violations: list[dict] = []
 
-    # Check for upgrade function
-    if "def upgrade(" not in content:
+    try:
+        tree = ast.parse(content, filename=filepath)
+    except SyntaxError as exc:
+        return [{
+            "lineNo": exc.lineno or 0,
+            "rule": "unparseable-migration",
+            "reason": "Migration is not valid Python — reversibility cannot be checked",
+        }]
+
+    upgrade = _module_function(tree, "upgrade")
+    downgrade = _module_function(tree, "downgrade")
+
+    if upgrade is None:
         violations.append({
             "lineNo": 0,
             "rule": "missing-upgrade",
             "reason": "Migration has no upgrade() function",
         })
 
-    # Check for downgrade function
-    if "def downgrade(" not in content:
+    if downgrade is None:
         violations.append({
             "lineNo": 0,
             "rule": "missing-downgrade",
             "reason": "Migration has no downgrade() function — rollback impossible",
         })
 
-    # Check for destructive operations
-    destructive_patterns = [
-        (r"\.drop_table\(", "DROP TABLE", "Destructive: table drop without safeguard"),
-        (r"\.drop_column\(", "DROP COLUMN", "Destructive: column drop without safeguard"),
-        (r"\.drop_index\(", "DROP INDEX", "Destructive: index drop"),
-        (r"batch_alter_table.*\.drop_column", "BATCH DROP COLUMN", "Batch column drop"),
-    ]
-    for pattern, label, reason in destructive_patterns:
-        if re.search(pattern, content):
-            # Check if there's a corresponding downgrade
-            if "def downgrade(" in content:
-                downgrade_section = content.split("def downgrade(")[1] if "def downgrade(" in content else ""
-                if label.lower().replace(" ", "_") not in downgrade_section.lower().replace(" ", "_"):
-                    # More lenient: just flag it
-                    violations.append({
-                        "lineNo": 0,
-                        "rule": f"destructive-{label.lower().replace(' ', '_')}",
-                        "reason": f"{reason} — verify downgrade covers this",
-                    })
+    # A destructive op in upgrade() is reversible only when downgrade()
+    # recreates what it removed. An empty / `pass` downgrade recreates nothing.
+    undo_ops = {call.func.attr for call in _method_calls(downgrade)}
+    for call in _method_calls(upgrade):
+        op = call.func.attr
+        if op in _DESTRUCTIVE_OPS and not undo_ops.intersection(_DESTRUCTIVE_OPS[op]):
+            violations.append({
+                "lineNo": call.lineno,
+                "rule": f"destructive-{op}",
+                "reason": (
+                    f"upgrade() calls {op}() but downgrade() has no "
+                    f"{' / '.join(_DESTRUCTIVE_OPS[op])}() — the migration is not reversible"
+                ),
+            })
 
     return violations
 
 
+# Django operations that need a reverse, with the keyword that supplies it.
+# The reverse is also accepted as the second positional argument.
+_DJANGO_REVERSIBLE = {
+    "RunPython": ("reverse_code", "run-python-no-reverse",
+                  "RunPython without reverse_code — rollback may fail"),
+    "RunSQL": ("reverse_sql", "run-sql-no-reverse",
+               "RunSQL without reverse_sql — rollback may fail"),
+}
+
+
+def _call_name(call: ast.Call) -> str:
+    func = call.func
+    if isinstance(func, ast.Attribute):
+        return func.attr
+    if isinstance(func, ast.Name):
+        return func.id
+    return ""
+
+
 def _check_django_migration(filepath: str, content: str) -> list[dict]:
-    """Check a Django migration file for issues."""
+    """Check a Django migration file for reversibility."""
     violations: list[dict] = []
 
     # Check for empty migration
@@ -120,37 +175,33 @@ def _check_django_migration(filepath: str, content: str) -> list[dict]:
             "reason": "Migration file appears empty or near-empty",
         })
 
-    # Check for RunPython without reverse_code
-    if "RunPython(" in content:
-        # Find RunPython calls and check for reverse_code
-        run_python_pattern = re.compile(r"RunPython\(([^)]*)\)")
-        for match in run_python_pattern.finditer(content):
-            args = match.group(1)
-            if "reverse_code" not in args and "run_python" not in args.lower():
-                violations.append({
-                    "lineNo": content[:match.start()].count("\n") + 1,
-                    "rule": "run-python-no-reverse",
-                    "reason": "RunPython without reverse_code — rollback may fail",
-                })
-
-    # Check for RunSQL without reverse_sql
-    if "RunSQL(" in content:
-        run_sql_pattern = re.compile(r"RunSQL\(([^)]*)\)")
-        for match in run_sql_pattern.finditer(content):
-            args = match.group(1)
-            if "reverse_sql" not in args:
-                violations.append({
-                    "lineNo": content[:match.start()].count("\n") + 1,
-                    "rule": "run-sql-no-reverse",
-                    "reason": "RunSQL without reverse_sql — rollback may fail",
-                })
+    try:
+        tree = ast.parse(content, filename=filepath)
+    except SyntaxError as exc:
+        violations.append({
+            "lineNo": exc.lineno or 0,
+            "rule": "unparseable-migration",
+            "reason": "Migration is not valid Python — reversibility cannot be checked",
+        })
+        return violations
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        spec = _DJANGO_REVERSIBLE.get(_call_name(node))
+        if spec is None:
+            continue
+        keyword, rule, reason = spec
+        has_reverse = len(node.args) >= 2 or any(kw.arg == keyword for kw in node.keywords)
+        if not has_reverse:
+            violations.append({"lineNo": node.lineno, "rule": rule, "reason": reason})
 
     return violations
 
 
 def check(target_dir: str | None = None) -> dict:
     """
-    Check migration files for idempotency and safety issues.
+    Check migration files for reversibility and safety issues.
 
     Returns:
         dict with keys: exit_code, skipped, name, data
@@ -158,35 +209,33 @@ def check(target_dir: str | None = None) -> dict:
     """
     dir_path = target_dir or os.getcwd()
 
-    changed_files = _get_changed_files(dir_path)
-    if changed_files is None:
+    # The snapshot being verified: the index, or HEAD when nothing is staged.
+    changes = _changes.changed_files(dir_path)
+    mode = changes["mode"]
+    if mode is None:
         return {
             "exit_code": 0, "skipped": True, "name": "check_migrations",
             "data": {"violations": {}, "message": "No git diff available"},
         }
 
-    migration_files = _find_migration_files(dir_path)
-    if not migration_files:
-        return {
-            "exit_code": 0, "skipped": False, "name": "check_migrations",
-            "data": {"violations": {}, "message": "No migration files found"},
-        }
-
-    # Only check migrations that were changed
-    changed_migrations = [f for f in migration_files if f in changed_files]
+    # Changed migrations come from the snapshot's path list: a migration
+    # deleted or edited in the working copy must not hide the staged one.
+    changed_migrations = [f for f in changes["files"] if _is_migration_path(f)]
     if not changed_migrations:
+        message = (
+            "No migration files were changed" if _find_migration_files(dir_path)
+            else "No migration files found"
+        )
         return {
             "exit_code": 0, "skipped": False, "name": "check_migrations",
-            "data": {"violations": {}, "message": "No migration files were changed"},
+            "data": {"violations": {}, "message": message},
         }
 
     violations: dict[str, list[dict]] = {}
 
     for filepath in changed_migrations:
-        full_path = pathlib.Path(dir_path) / filepath
-        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
 
         # Determine migration framework

package/tools/check_performance.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 checkPerformance(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_performance', data: { violations: {}, message: 'No package.json found — skipping performance 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 performance 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';
+}
 
-  if (!isNext) {
-    return { exitCode: 0, skipped: true, name: 'check_performance', data: { violations: {}, message: 'Not a Next.js project — skipping' } };
+const check = async function checkPerformance(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'] });
+
+  // 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_performance', 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_performance', data: { violations: {}, message: 'No git diff available' } };
-    }
+  if (mode === null) {
+    return { exitCode: 0, skipped: true, name: 'check_performance', data: { violations: {}, message: 'No git diff available' } };
   }
 
   if (!files || files.length === 0) {
@@ -57,16 +55,9 @@ const check = async function checkPerformance(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 = [];
 

package/tools/check_placeholders.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Forgotten Placeholder Guard
+ * In every .md/.yml/.yaml/.json file changed in the snapshot, flags the
+ * markers a draft leaves behind: the uppercase draft words listed in
+ * DRAFT_WORDS (whole words), "lorem ipsum" (any case) and unresolved
+ * `{{...}}` slots.
+ * Inside templates/ the `{{...}}` slots are legitimate and not flagged.
+ * GitHub Actions expressions (`${{ ... }}`) are never flagged; in Markdown,
+ * code spans and fenced code blocks are ignored.
+ * Skills the harness installs (clckernel_cli) and registry files are ignored.
+ * Self-contained: uses only Node.js built-ins.
+ *
+ * @param {string} targetDir - Repository root (defaults to cwd)
+ * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
+ */
+const { changedFiles, readFile } = require('./_changes');
+
+const NAME = 'check_placeholders';
+const EXTENSIONS = ['.md', '.yml', '.yaml', '.json'];
+const HARNESS_SKILLS = new Set(['clckernel_cli', 'clc_forge_cli']);
+const FENCE_RE = /^\s{0,3}(`{3,}|~{3,})/;
+// Spelled in parts so this source never carries the markers it looks for.
+const DRAFT_WORDS = [['TO', 'DO'], ['T', 'BD'], ['FIX', 'ME']].map(parts => parts.join(''));
+const MARKERS = [
+  ...DRAFT_WORDS.map(word => ({ label: word, re: new RegExp(`\\b${word}\\b`) })),
+  { label: 'lorem ipsum', re: /\blorem\s+ipsum\b/i },
+];
+const SLOT = { label: 'unresolved {{...}}', re: /(?<!\$)\{\{[^{}\n]*\}\}/ };
+
+function isHarnessFile(file) {
+  return file.split('/').some(segment => HARNESS_SKILLS.has(segment));
+}
+
+/** True for a file under a templates/ folder (at any depth). */
+function inTemplates(file) {
+  return file.split('/').slice(0, -1).includes('templates');
+}
+
+/** Markdown lines with fenced code blocks blanked and code spans removed. */
+function proseLines(text) {
+  let fence = null;
+  return text.split(/\r?\n/).map(line => {
+    const open = FENCE_RE.exec(line);
+    if (fence) {
+      if (open && open[1][0] === fence[0] && open[1].length >= fence.length) fence = null;
+      return '';
+    }
+    if (open) {
+      fence = open[1];
+      return '';
+    }
+    return line.replace(/(`+)[^`]*?\1/g, '');
+  });
+}
+
+const check = async function checkPlaceholders(targetDir) {
+  const dir = targetDir || process.cwd();
+  const { mode, files } = changedFiles(dir, { extensions: EXTENSIONS });
+  const candidates = files.filter(f => !isHarnessFile(f));
+
+  if (candidates.length === 0) {
+    return {
+      exitCode: 0, skipped: true, name: NAME,
+      data: { violations: [], message: 'No changed .md/.yml/.yaml/.json files' },
+    };
+  }
+
+  const violations = [];
+  for (const file of candidates) {
+    const text = readFile(dir, file, mode);
+    if (text === null) continue;
+    const markers = inTemplates(file) ? MARKERS : [...MARKERS, SLOT];
+    const lines = file.endsWith('.md') ? proseLines(text) : text.split(/\r?\n/);
+    lines.forEach((line, index) => {
+      for (const { label, re } of markers) {
+        if (re.test(line)) {
+          violations.push({ file, line: index + 1, message: `Forgotten placeholder (${label}): ${line.trim().slice(0, 120)}` });
+        }
+      }
+    });
+  }
+
+  return {
+    exitCode: violations.length > 0 ? 1 : 0,
+    skipped: false,
+    name: NAME,
+    data: {
+      violations,
+      message: violations.length > 0
+        ? `${violations.length} forgotten placeholder(s) found`
+        : `No forgotten placeholders in ${candidates.length} changed file(s)`,
+    },
+  };
+};
+
+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_responsive.js

@@ -12,28 +12,15 @@
  * @param {string} targetDir - Directory to scan (defaults to cwd)
  * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
  */
-const check = async function checkResponsive(targetDir) {
-  const fs = require('fs');
-  const path = require('path');
-  const { execSync } = require('child_process');
+const { changedFiles, readFile } = require('./_changes');
 
+const check = async function checkResponsive(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|vue|astro|html|css)$/.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|vue|astro|html|css)$/.test(f.trim()));
-    } catch {
-      return { exitCode: 0, skipped: true, name: 'check_responsive', 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', '.vue', '.astro', '.html', '.css'] });
+  if (mode === null) {
+    return { exitCode: 0, skipped: true, name: 'check_responsive', data: { violations: {}, message: 'No git diff available' } };
   }
 
   if (!files || files.length === 0) {
@@ -43,15 +30,8 @@ const check = async function checkResponsive(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 = [];