clckernel 1.2.6

package/tools/audit.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""
+Modular Audit Orchestrator — Python
+Discovers check_*.py and scan_*.py guard scripts at runtime, runs each with
+graceful degradation, and generates an English audit report (05-audit-report.md).
+Self-contained: uses only Python stdlib.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import pathlib
+import subprocess
+import sys
+import traceback
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+def find_active_sdd(change_name: str | None = None) -> pathlib.Path | None:
+    """Find the active SDD directory by name or pick the sole candidate."""
+    sdds_dir = REPO_ROOT / "sdds"
+    if not sdds_dir.exists():
+        return None
+    if change_name:
+        target = sdds_dir / change_name
+        return target if target.is_dir() else None
+    candidates = [p for p in sdds_dir.iterdir() if p.is_dir()]
+    if len(candidates) == 1:
+        return candidates[0]
+    return None
+
+
+def discover_guards(tools_dir: pathlib.Path) -> list[pathlib.Path]:
+    """
+    Discover all check_*.py and scan_*.py guard scripts in tools/.
+    Excludes audit.py itself. Returns sorted list for deterministic ordering.
+    """
+    guards: list[pathlib.Path] = []
+    for f in sorted(tools_dir.iterdir()):
+        if not f.is_file():
+            continue
+        name = f.name
+        if (name.startswith("check_") or name.startswith("scan_") or name.startswith("verify_")) and name.endswith(".py"):
+            guards.append(f)
+    return guards
+
+
+def run_guard(guard_path: pathlib.Path, target_dir: str) -> dict:
+    """
+    Run a single guard module by dynamic import and call its check() function.
+    Returns a normalized result dict on success, or a skip result on failure.
+    """
+    guard_name = guard_path.stem  # e.g. "check_scope"
+
+    try:
+        spec = importlib.util.spec_from_file_location(guard_name, str(guard_path))
+        if spec is None or spec.loader is None:
+            return {
+                "exit_code": 0, "skipped": True, "name": guard_name,
+                "data": {"message": f"Cannot load module spec for {guard_name}"},
+            }
+
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+
+        fn = getattr(mod, "check", None)
+        if fn is None or not callable(fn):
+            return {
+                "exit_code": 0, "skipped": True, "name": guard_name,
+                "data": {"message": f"Guard {guard_name} does not export a check() function"},
+            }
+
+        result = fn(target_dir)
+
+        # Normalize result shape
+        if not isinstance(result, dict):
+            return {
+                "exit_code": 0, "skipped": True, "name": guard_name,
+                "data": {"message": f"Guard {guard_name} returned non-dict: {type(result).__name__}"},
+            }
+
+        return {
+            "exit_code": result.get("exit_code", 0),
+            "skipped": bool(result.get("skipped", False)),
+            "name": result.get("name", guard_name),
+            "data": result.get("data", result),
+        }
+
+    except Exception as exc:
+        return {
+            "exit_code": 0, "skipped": True, "name": guard_name,
+            "data": {"message": f"Guard unavailable: {exc}"},
+        }
+
+
+# ── Report Generation ────────────────────────────────────────────────────────
+
+def _format_guard_section(name: str, result: dict) -> str:
+    """Format a single guard result into a markdown section."""
+    lines: list[str] = []
+    skipped = result.get("skipped", False)
+    exit_code = result.get("exit_code", 0)
+    data = result.get("data", {})
+
+    if skipped:
+        icon, status = "\u23ed\ufe0f", "SKIPPED"
+    elif exit_code == 0:
+        icon, status = "\u2705", "PASSED"
+    else:
+        icon, status = "\u274c", "FAILED"
+
+    title = name.replace("_", " ").title()
+    lines.append(f"### {icon} {title} \u2014 {status}")
+    lines.append("")
+
+    if skipped:
+        lines.append(f"> Skipped: {data.get('message', 'Dependencies not available')}")
+    elif exit_code == 0:
+        lines.append(f"> {data.get('message', 'All checks passed')}")
+    else:
+        lines.append(f"> {data.get('message', 'Issues found')}")
+        lines.append("")
+
+        # Format violations or findings
+        violations = data.get("violations") or data.get("findings") or {}
+        if isinstance(violations, dict):
+            for filepath, items in violations.items():
+                if not isinstance(items, list):
+                    continue
+                for item in items:
+                    loc = f" (line {item.get('lineNo', '')})" if item.get("lineNo") else ""
+                    label = item.get("label") or item.get("rule") or item.get("module") or ""
+                    msg = item.get("reason") or item.get("message") or ""
+                    lines.append(f"- `{filepath}`{loc}: {f'[{label}] ' if label else ''}{msg}")
+
+        # Handle list-style data (e.g. scope unauthorized files)
+        for key in ("unrelated", "warnings", "authorized"):
+            items = data.get(key, [])
+            if isinstance(items, list) and items:
+                icon_map = {"unrelated": "\u274c", "warnings": "\u26a0\ufe0f", "authorized": "\u2705"}
+                label_map = {"unrelated": "Not in SDD scope", "warnings": "Related warnings", "authorized": "Authorized"}
+                lines.append(f"\n{icon_map.get(key, '')} **{label_map.get(key, key)}:**")
+                for f in items:
+                    lines.append(f"  - `{f}`")
+
+    return "\n".join(lines)
+
+
+def generate_report(results: list[dict], sdd_dir: pathlib.Path) -> str:
+    """Generate the 05-audit-report.md from aggregated guard results."""
+    task_name = sdd_dir.name
+    passed = sum(1 for r in results if not r.get("skipped") and r.get("exit_code") == 0)
+    failed = sum(1 for r in results if not r.get("skipped") and r.get("exit_code") != 0)
+    skipped = sum(1 for r in results if r.get("skipped"))
+    total = len(results)
+
+    sections: list[str] = []
+    sections.append(f"# Code Audit Report: {task_name}")
+    sections.append("")
+    sections.append("> **Note for reviewer:** This report summarizes security, architecture,")
+    sections.append("> scope, migration safety, and TDD coverage to facilitate code review.")
+    sections.append("")
+    sections.append("---")
+    sections.append("")
+    sections.append("## Summary")
+    sections.append("")
+    sections.append("| Metric | Count |")
+    sections.append("|--------|-------|")
+    sections.append(f"| Total guards | {total} |")
+    sections.append(f"| Passed | {passed} |")
+    sections.append(f"| Failed | {failed} |")
+    sections.append(f"| Skipped | {skipped} |")
+    sections.append("")
+    sections.append("---")
+    sections.append("")
+
+    for result in results:
+        sections.append(_format_guard_section(result.get("name", "unknown"), result))
+        sections.append("")
+        sections.append("---")
+        sections.append("")
+
+    return "\n".join(sections)
+
+
+# ── Console Summary ──────────────────────────────────────────────────────────
+
+def print_summary(results: list[dict], report_path: pathlib.Path) -> None:
+    """Print an educational summary to the terminal."""
+    print("\n" + "=" * 65)
+    print("  CLC FORGE \u2014 EDUCATIONAL AUDIT SUMMARY")
+    print("=" * 65 + "\n")
+
+    for result in results:
+        skipped = result.get("skipped", False)
+        exit_code = result.get("exit_code", 0)
+        name = result.get("name", "unknown").replace("_", " ")
+        msg = result.get("data", {}).get("message", "")
+
+        if skipped:
+            icon = "\u23ed\ufe0f"
+        elif exit_code == 0:
+            icon = "\u2705"
+        else:
+            icon = "\u274c"
+
+        print(f"  {icon} {name}: {msg}")
+
+    print(f"\n  Report: {report_path}")
+    print("=" * 65 + "\n")
+
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+def main(target_dir: str | None = None) -> int:
+    """Run all discovered guards and produce the audit report."""
+    tools_dir = pathlib.Path(__file__).resolve().parent
+    dir_path = target_dir or os.getcwd()
+
+    sdd_dir = find_active_sdd()
+    if sdd_dir is None:
+        # Create a default SDD dir for the report
+        sdds_dir = REPO_ROOT / "sdds"
+        sdds_dir.mkdir(parents=True, exist_ok=True)
+        sdd_dir = sdds_dir / "audit-run"
+        sdd_dir.mkdir(parents=True, exist_ok=True)
+
+    print(f"\nRunning CLC Forge audit for: {sdd_dir.name}\n")
+
+    guard_paths = discover_guards(tools_dir)
+
+    if not guard_paths:
+        print("No guard tools found in tools/. Nothing to audit.")
+        return 0
+
+    print(
+        f"Discovered {len(guard_paths)} guard(s): "
+        + ", ".join(p.stem for p in guard_paths)
+        + "\n"
+    )
+
+    results: list[dict] = []
+    for guard_path in guard_paths:
+        result = run_guard(guard_path, dir_path)
+        results.append(result)
+
+    # Generate and write report
+    report_content = generate_report(results, sdd_dir)
+    report_path = sdd_dir / "05-audit-report.md"
+    report_path.write_text(report_content, encoding="utf-8")
+
+    # Print summary
+    print_summary(results, report_path)
+
+    # Exit with failure if any guard failed (not skipped)
+    has_failure = any(
+        not r.get("skipped") and r.get("exit_code", 0) != 0
+        for r in results
+    )
+    return 1 if has_failure else 0
+
+
+if __name__ == "__main__":
+    try:
+        target = sys.argv[1] if len(sys.argv) > 1 else None
+        sys.exit(main(target))
+    except Exception:
+        traceback.print_exc()
+        sys.exit(0)  # Graceful degradation

package/tools/celery_guard.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""
+Celery Guard
+Checks for Celery task security issues in changed Python files.
+Self-contained: uses only Python stdlib (ast, pathlib, subprocess, json, sys).
+"""
+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
+
+
+class CeleryVisitor(ast.NodeVisitor):
+    """AST visitor that detects Celery task security issues."""
+
+    def __init__(self, filepath: str):
+        self.filepath = filepath
+        self.violations: list[dict] = []
+
+    def _add_violation(self, lineno: int, issue: str, snippet: str):
+        self.violations.append({
+            "file": self.filepath,
+            "lineNo": lineno,
+            "issue": issue,
+            "snippet": snippet[:120],
+        })
+
+    def _is_redis_url(self, node: ast.expr) -> bool:
+        """Check if expression looks like a redis:// URL."""
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            val = node.value.lower()
+            return 'redis://' in val or 'rediss://' in val
+        return False
+
+    def _is_broker_url(self, node: ast.expr) -> bool:
+        """Check if expression looks like a broker URL."""
+        return self._is_redis_url(node)
+
+    def visit_Call(self, node: ast.Call):
+        # Check for Celery() instantiation with broker_url or result_backend
+        if isinstance(node.func, ast.Name) and node.func.id == 'Celery':
+            for keyword in node.keywords:
+                if keyword.arg == 'broker_url':
+                    if self._is_broker_url(keyword.value):
+                        self._add_violation(
+                            node.lineno or 0,
+                            "hardcoded_broker_url",
+                            f"Celery broker_url directly in code"
+                        )
+                if keyword.arg == 'result_backend':
+                    if not isinstance(keyword.value, ast.Constant) or keyword.value.value is None:
+                        pass  # Skip None defaults
+                    elif isinstance(keyword.value, ast.Constant) and isinstance(keyword.value.value, str):
+                        val = keyword.value.value.lower()
+                        if val and val not in ('None', 'null', ''):
+                            self._add_violation(
+                                node.lineno or 0,
+                                "hardcoded_result_backend",
+                                f"Celery result_backend directly in code"
+                            )
+
+        # Check for @shared_task or @celery.task decorators
+        # Handle @shared_task(...) or @shared_task
+        try:
+            for decorator in node.decorator_list:
+                dec_name = ''
+                dec_args: list[ast.expr] = []
+                if isinstance(decorator, ast.Call):
+                    if isinstance(decorator.func, ast.Name):
+                        dec_name = decorator.func.id
+                    elif isinstance(decorator.func, ast.Attribute):
+                        dec_name = decorator.func.attr
+                    dec_args = decorator.args
+                elif isinstance(decorator, ast.Name):
+                    dec_name = decorator.id
+                elif isinstance(decorator, ast.Attribute):
+                    dec_name = decorator.attr
+
+                if dec_name in ('shared_task', 'task'):
+                    # Check if ignore_result=True is missing
+                    ignore_found = False
+                    for arg in dec_args:
+                        if isinstance(arg, ast.keyword) and arg.arg == 'ignore_result':
+                            if isinstance(arg.value, ast.Constant) and arg.value.value is True:
+                                ignore_found = True
+                    if not ignore_found:
+                        # Check decorators with keyword args
+                        for decorator_node in node.decorator_list:
+                            if isinstance(decorator_node, ast.Call):
+                                for kw in decorator_node.keywords:
+                                    if kw.arg == 'ignore_result':
+                                        if isinstance(kw.value, ast.Constant) and kw.value.value is True:
+                                            ignore_found = True
+                        if not ignore_found:
+                            snippet = f"@{dec_name} without ignore_result=True"
+                            self._add_violation(node.lineno or 0, "missing_ignore_result", snippet)
+        except Exception:
+            pass
+
+        self.generic_visit(node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef):
+        # Check function body for broker URL strings
+        for stmt in ast.walk(node):
+            if isinstance(stmt, ast.Assign):
+                for target in stmt.targets:
+                    if isinstance(target, ast.Name):
+                        var_name = target.id.lower()
+                        if 'broker' in var_name or 'url' in var_name:
+                            if isinstance(stmt.value, ast.Constant) and isinstance(stmt.value.value, str):
+                                val = stmt.value.value.lower()
+                                if 'redis://' in val or 'rediss://' in val:
+                                    self._add_violation(
+                                        stmt.lineno or 0,
+                                        "broker_url_in_variable",
+                                        f"Broker URL assigned to variable {target.id}"
+                                    )
+        self.generic_visit(node)
+
+
+def check(target_dir: str | None = None) -> dict:
+    """
+    Scan changed Python files for Celery security issues.
+
+    Returns:
+        dict with keys: exit_code, skipped, name, data
+    """
+    dir_path = target_dir or os.getcwd()
+
+    files = _get_changed_files(dir_path)
+    if files is None:
+        return {
+            "exit_code": 0, "skipped": True, "name": "celery_guard",
+            "data": {"findings": [], "message": "No git diff available"},
+        }
+
+    if not files:
+        return {
+            "exit_code": 0, "skipped": False, "name": "celery_guard",
+            "data": {"findings": [], "message": "No changed Python files to scan"},
+        }
+
+    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):
+            continue
+
+        try:
+            tree = ast.parse(content, filename=str(full_path))
+        except SyntaxError:
+            continue
+
+        visitor = CeleryVisitor(filepath)
+        visitor.visit(tree)
+        all_violations.extend(visitor.violations)
+
+    total = len(all_violations)
+    if total:
+        msg = f"{total} Celery violation(s) found"
+    else:
+        msg = "No Celery violations found"
+
+    return {
+        "exit_code": 1 if total else 0,
+        "skipped": False,
+        "name": "celery_guard",
+        "data": {"findings": all_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"])

package/tools/check_a11y.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * Accessibility & ARIA Guard
+ * Scans changed .tsx/.jsx files for missing alt tags, aria-labels,
+ * and semantic HTML violations.
+ * 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 checkA11y(targetDir) {
+  const fs = require('fs');
+  const path = require('path');
+  const { execSync } = require('child_process');
+
+  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' } };
+    }
+  }
+
+  if (!files || files.length === 0) {
+    return { exitCode: 0, skipped: false, name: 'check_a11y', data: { violations: {}, message: 'No frontend 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 lines = content.split('\n');
+    const fileViolations = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Check for <img without alt
+      if (/<img\b[^>]*(?!.*\balt\s*=)[^>]*>/i.test(line) && !/\balt\s*=/.test(line)) {
+        fileViolations.push({ lineNo: i + 1, rule: 'img-alt', message: 'Image missing alt attribute' });
+      }
+
+      // Check for <input without aria-label or aria-labelledby
+      if (/<input\b/i.test(line) && !/aria-label|aria-labelledby|aria-describedby/.test(line)) {
+        fileViolations.push({ lineNo: i + 1, rule: 'input-label', message: 'Input missing aria-label or aria-labelledby' });
+      }
+
+      // Check for button/link with only icon and no aria-label
+      if (/<button[^>]*>\s*(?:<[A-Z]|<span[^>]*className=['"][^'"]*(?:icon|Icon))/i.test(line) && !/aria-label/.test(line)) {
+        fileViolations.push({ lineNo: i + 1, rule: 'icon-button', message: 'Icon-only button missing aria-label' });
+      }
+
+      // Check for role="button" without keyboard handler
+      if (/role\s*=\s*['"]button['"]/i.test(line) && !/onKeyDown|onKeyUp|onKeyPress/i.test(line)) {
+        fileViolations.push({ lineNo: i + 1, rule: 'role-button-keyboard', message: 'role="button" without keyboard handler' });
+      }
+
+      // Check for <a> with href but missing accessible text for icon-only links
+      if (/<a\b[^>]*>\s*<[A-Z]/i.test(line) && !/aria-label/.test(line)) {
+        fileViolations.push({ lineNo: i + 1, rule: 'link-accessible', message: 'Link with component child may need aria-label' });
+      }
+    }
+
+    if (fileViolations.length > 0) {
+      violations[file] = fileViolations;
+    }
+  }
+
+  const totalCount = Object.values(violations).flat().length;
+  return {
+    exitCode: totalCount > 0 ? 1 : 0,
+    skipped: false,
+    name: 'check_a11y',
+    data: {
+      violations,
+      message: totalCount > 0
+        ? `${totalCount} a11y issue(s) found in ${Object.keys(violations).length} file(s)`
+        : 'All a11y 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);
+  });
+}