clckernel 1.2.6

package/tools/check_scope.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""
+Scope Guard — SDD Scope Validation
+Validates that changed files match the declared SDD scope by comparing
+git diff output against the SDD affected files list.
+Self-contained: uses only Python stdlib (pathlib, subprocess, json).
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+
+
+def _get_changed_files(target_dir: str) -> list[str] | None:
+    """Return list of 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 _find_sdd_declared_files(target_dir: str) -> list[str] | None:
+    """
+    Find declared affected files from the active SDD directory.
+    Looks for 00-state.md, 01-proposal.md, or any .md with 'affected' or 'files'.
+    Returns None if no SDD context found.
+    """
+    root = pathlib.Path(target_dir)
+    sdds_dir = root / "sdds"
+    if not sdds_dir.is_dir():
+        return None
+
+    # Find active SDD dir (most recently modified)
+    candidates = sorted(
+        [d for d in sdds_dir.iterdir() if d.is_dir()],
+        key=lambda d: d.stat().st_mtime,
+        reverse=True,
+    )
+    if not candidates:
+        return None
+
+    sdd_dir = candidates[0]
+
+    # Try to extract file list from SDD markdown files
+    declared: list[str] = []
+    for md_file in sdd_dir.glob("*.md"):
+        try:
+            content = md_file.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+
+        # Look for file references in common SDD patterns
+        # Pattern: `- path/to/file` or `| path/to/file |`
+        for line in content.splitlines():
+            # Match bullet-point file paths
+            m = re.match(r"\s*[-*]\s+`?([a-zA-Z_][\w./-]+\.\w+)`?", line)
+            if m:
+                declared.append(m.group(1))
+            # Match table cell file paths
+            m = re.match(r"\s*\|[^|]*`?([a-zA-Z_][\w./-]+\.\w+)`?[^|]*\|", line)
+            if m:
+                declared.append(m.group(1))
+
+    # Deduplicate while preserving order
+    seen: set[str] = set()
+    unique: list[str] = []
+    for f in declared:
+        if f not in seen:
+            seen.add(f)
+            unique.append(f)
+
+    return unique if unique else None
+
+
+def check(target_dir: str | None = None) -> dict:
+    """
+    Validate that changed files match declared SDD scope.
+
+    Returns:
+        dict with keys: exit_code, skipped, name, data
+        data.authorized, data.warnings, data.unrelated — lists of file paths
+    """
+    dir_path = target_dir or os.getcwd()
+
+    changed = _get_changed_files(dir_path)
+    if changed is None:
+        return {
+            "exit_code": 0, "skipped": True, "name": "check_scope",
+            "data": {
+                "authorized": [], "warnings": [], "unrelated": [],
+                "message": "No git diff available",
+            },
+        }
+
+    if not changed:
+        return {
+            "exit_code": 0, "skipped": False, "name": "check_scope",
+            "data": {
+                "authorized": [], "warnings": [], "unrelated": [],
+                "message": "No changed files",
+            },
+        }
+
+    declared = _find_sdd_declared_files(dir_path)
+    if declared is None:
+        # No SDD context — all files are "unrelated" but it's not an error
+        return {
+            "exit_code": 0, "skipped": False, "name": "check_scope",
+            "data": {
+                "authorized": [], "warnings": [], "unrelated": changed,
+                "message": "No SDD context found — all changed files are undeclared",
+            },
+        }
+
+    authorized: list[str] = []
+    warnings: list[str] = []
+    unrelated: list[str] = []
+
+    for f in changed:
+        if f in declared:
+            authorized.append(f)
+        else:
+            # Check if it's in the same directory as a declared file (warn)
+            declared_dirs = {str(pathlib.Path(d).parent) for d in declared}
+            if str(pathlib.Path(f).parent) in declared_dirs:
+                warnings.append(f)
+            else:
+                unrelated.append(f)
+
+    total = len(changed)
+    if unrelated:
+        msg = (
+            f"{len(unrelated)} file(s) not in declared SDD scope "
+            f"({len(authorized)} authorized, {len(warnings)} related warnings)"
+        )
+        exit_code = 1
+    elif warnings:
+        msg = (
+            f"All files related to declared scope "
+            f"({len(authorized)} authorized, {len(warnings)} related warnings)"
+        )
+        exit_code = 0
+    else:
+        msg = f"All {total} changed file(s) are within declared SDD scope"
+        exit_code = 0
+
+    return {
+        "exit_code": exit_code,
+        "skipped": False,
+        "name": "check_scope",
+        "data": {
+            "authorized": authorized,
+            "warnings": warnings,
+            "unrelated": unrelated,
+            "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_seo.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * SEO, GEO & Web Performance Guard
+ * Scans changed frontend files (.tsx, .jsx, .vue, .astro, .html) for:
+ * 1. Missing page metadata (title, description, canonical)
+ * 2. OpenGraph & Social Sharing tags (og:title, og:image, og:description)
+ * 3. Semantic HTML & Heading hierarchy (single <h1> per page, <main> landmark usage)
+ * 4. GEO & Localized Structured Data tags (geo.region, geo.position, ICBM, JSON-LD)
+ * 5. LCP & Performance: Hero image priority optimization
+ *
+ * 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 checkSeo(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|vue|astro|html)$/.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)$/.test(f.trim()));
+    } catch {
+      return { exitCode: 0, skipped: true, name: 'check_seo', data: { violations: {}, message: 'No git diff available' } };
+    }
+  }
+
+  if (!files || files.length === 0) {
+    return { exitCode: 0, skipped: false, name: 'check_seo', 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 = [];
+    const isPageOrLayout = /(?:page|layout|index|App|document)\.(?:tsx|jsx|astro|vue|html)$/i.test(file);
+
+    // 1. Heading hierarchy: Check for multiple <h1> in a single page file
+    const h1Matches = content.match(/<h1\b/gi) || [];
+    if (isPageOrLayout && h1Matches.length > 1) {
+      fileViolations.push({
+        lineNo: 1,
+        rule: 'seo-multiple-h1',
+        message: `Found ${h1Matches.length} <h1> tags in single page component. Only one <h1> is recommended for SEO hierarchy.`
+      });
+    }
+
+    // 2. Line-by-line checks
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Check for malformed GEO tags if GEO meta is present
+      if (/name\s*=\s*['"]geo\.position['"]/i.test(line) && !/content\s*=\s*['"]-?\d+\.\d+;-?\d+\.\d+['"]/i.test(line)) {
+        fileViolations.push({
+          lineNo: i + 1,
+          rule: 'geo-position-format',
+          message: 'Malformed geo.position meta tag. Expected format: content="latitude;longitude"'
+        });
+      }
+
+      if (/name\s*=\s*['"]ICBM['"]/i.test(line) && !/content\s*=\s*['"]-?\d+\.\d+,\s*-?\d+\.\d+['"]/i.test(line)) {
+        fileViolations.push({
+          lineNo: i + 1,
+          rule: 'geo-icbm-format',
+          message: 'Malformed ICBM meta tag. Expected format: content="latitude, longitude"'
+        });
+      }
+
+      // Check for Hero / Banner images without priority (Core Web Vitals / LCP)
+      if (/(?:hero|banner|cover|hero-image|heroImage|HeroBanner)/i.test(line) && /<(?:img|Image)\b/i.test(line)) {
+        if (!/priority|fetchpriority|loading\s*=\s*['"]eager['"]/i.test(line)) {
+          fileViolations.push({
+            lineNo: i + 1,
+            rule: 'cwv-lcp-priority',
+            message: 'Hero/Banner image missing priority / fetchpriority="high" attribute (Core Web Vitals LCP optimization).'
+          });
+        }
+      }
+
+      // Check for raw <a> with target="_blank" missing rel="noopener noreferrer"
+      if (/<a\b[^>]*target\s*=\s*['"]_blank['"][^>]*>/i.test(line) && !/rel\s*=\s*['"][^'"]*noopener/i.test(line)) {
+        fileViolations.push({
+          lineNo: i + 1,
+          rule: 'seo-security-target-blank',
+          message: 'External link with target="_blank" is missing rel="noopener noreferrer" (SEO authority leak & security vulnerability).'
+        });
+      }
+    }
+
+    if (fileViolations.length > 0) {
+      violations[file] = fileViolations;
+    }
+  }
+
+  const totalCount = Object.values(violations).flat().length;
+  return {
+    exitCode: totalCount > 0 ? 1 : 0,
+    skipped: false,
+    name: 'check_seo',
+    data: {
+      violations,
+      message: totalCount > 0
+        ? `${totalCount} SEO / GEO / Web Performance issue(s) found in ${Object.keys(violations).length} file(s)`
+        : 'All SEO, GEO & Web Performance 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_storybook.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Storybook Story Coverage Guard
+ * Checks that UI components have corresponding .stories.tsx files.
+ * 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 checkStorybook(targetDir) {
+  const fs = require('fs');
+  const path = require('path');
+  const { execSync } = require('child_process');
+
+  const dir = targetDir || process.cwd();
+
+  // Check if Storybook is configured
+  const hasStorybook = fs.existsSync(path.join(dir, '.storybook')) ||
+    fs.existsSync(path.join(dir, 'storybook.config.js')) ||
+    fs.existsSync(path.join(dir, 'storybook.config.ts'));
+
+  if (!hasStorybook) {
+    return { exitCode: 0, skipped: true, name: 'check_storybook', data: { violations: {}, message: 'Storybook not configured — skipping' } };
+  }
+
+  // Collect changed component 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)$/.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_storybook', data: { violations: {}, message: 'No git diff available' } };
+    }
+  }
+
+  if (!files || files.length === 0) {
+    return { exitCode: 0, skipped: false, name: 'check_storybook', data: { violations: {}, message: 'No frontend files changed' } };
+  }
+
+  // Filter to component files (skip test files, stories, types, utils)
+  const componentFiles = files.filter(f => {
+    if (f.includes('.stories.') || f.includes('.test.') || f.includes('.spec.')) return false;
+    if (f.includes('.d.ts') || f.includes('.types.')) return false;
+    if (f.includes('utils') || f.includes('helpers') || f.includes('lib')) return false;
+    if (f.includes('types') || f.includes('constants')) return false;
+    // Only check files that export a component (capitalized name in filename)
+    const basename = path.basename(f, path.extname(f));
+    return /^[A-Z]/.test(basename);
+  });
+
+  if (componentFiles.length === 0) {
+    return { exitCode: 0, skipped: false, name: 'check_storybook', data: { violations: {}, message: 'No component files changed' } };
+  }
+
+  const violations = {};
+
+  for (const file of componentFiles) {
+    const filePath = path.join(dir, file);
+    if (!fs.existsSync(filePath)) continue;
+
+    // Check if a corresponding .stories.tsx file exists
+    const basename = path.basename(file, path.extname(file));
+    const ext = path.extname(file);
+    const storyFile = path.join(path.dirname(file), `${basename}.stories.${ext.replace('.', '')}`);
+
+    // Also check co-located stories directory pattern
+    const storiesDir = path.join(path.dirname(file), '__stories__', `${basename}.stories${ext}`);
+
+    const hasStory = fs.existsSync(path.join(dir, storyFile)) || fs.existsSync(path.join(dir, storiesDir));
+
+    if (!hasStory) {
+      violations[file] = [{
+        lineNo: 0,
+        rule: 'missing-story',
+        message: `Component "${basename}" has no corresponding Storybook story — create ${basename}.stories.tsx`,
+      }];
+    }
+  }
+
+  const totalCount = Object.values(violations).flat().length;
+  return {
+    exitCode: totalCount > 0 ? 1 : 0,
+    skipped: false,
+    name: 'check_storybook',
+    data: {
+      violations,
+      message: totalCount > 0
+        ? `${totalCount} component(s) missing Storybook stories`
+        : 'All Storybook coverage 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_ui_reuse.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * UI Component Reuse Guard
+ * Verifies @/components/ui/ imports and semantic Tailwind token usage.
+ * 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 checkUiReuse(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|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_ui_reuse', data: { violations: {}, message: 'No git diff available' } };
+    }
+  }
+
+  if (!files || files.length === 0) {
+    return { exitCode: 0, skipped: false, name: 'check_ui_reuse', 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 = [];
+
+    // Check: non-component files importing from @/components/ui/ directly
+    // (components within ui/ are allowed to reference each other)
+    if (!file.includes('components/ui/') && /from\s+['"]@\/components\/ui\//.test(content)) {
+      // This is GOOD — it means the file reuses UI primitives
+      // We only flag when components are defined but NOT using the shared ui/ directory
+    }
+
+    // Check: raw HTML elements that should be replaced with UI primitives
+    // <button without className referencing ui/ or a design system
+    const hasRawButton = /<button\b(?![^>]*className\s*=\s*['"][^'"]*(?:ui-|btn-|button))/i.test(content);
+    if (hasRawButton && !/from\s+['"]@\/components\/ui\//.test(content)) {
+      fileViolations.push({
+        lineNo: 0,
+        rule: 'raw-button',
+        message: 'Raw <button> without UI primitive — consider using @/components/ui/ Button',
+      });
+    }
+
+    // Check: raw <select> without UI primitive
+    if (/<select\b/i.test(content) && !/from\s+['"]@\/components\/ui\//.test(content)) {
+      fileViolations.push({
+        lineNo: 0,
+        rule: 'raw-select',
+        message: 'Raw <select> without UI primitive — consider using @/components/ui/ Select',
+      });
+    }
+
+    // Check: raw <input> without UI primitive (except type=hidden)
+    if (/<input\b(?!.*type\s*=\s*['"]hidden['"])/i.test(content) && !/from\s+['"]@\/components\/ui\//.test(content)) {
+      fileViolations.push({
+        lineNo: 0,
+        rule: 'raw-input',
+        message: 'Raw <input> without UI primitive — consider using @/components/ui/ Input',
+      });
+    }
+
+    // Check: hardcoded colors that should use semantic tokens
+    // Raw Tailwind color classes (bg-blue-500, text-red-600, etc.)
+    const rawColorRegex = /\b(?:bg|text|border|ring|shadow|outline|from|to|via)-(?:red|blue|green|yellow|orange|purple|pink|indigo|teal|cyan|emerald|lime|amber|violet|fuchsia|rose|sky|slate|gray|zinc|neutral|stone)-\d+\b/g;
+    const rawColors = content.match(rawColorRegex);
+    if (rawColors && rawColors.length > 0) {
+      fileViolations.push({
+        lineNo: 0,
+        rule: 'raw-colors',
+        message: `Raw color classes found (${rawColors.slice(0, 3).join(', ')}${rawColors.length > 3 ? '...' : ''}) — use semantic tokens (bg-primary, text-muted-foreground)`,
+      });
+    }
+
+    // Check: inline styles that bypass Tailwind
+    if (/style\s*=\s*\{\s*\{/.test(content)) {
+      fileViolations.push({
+        lineNo: 0,
+        rule: 'inline-styles',
+        message: 'Inline styles detected — prefer Tailwind utility classes for consistency',
+      });
+    }
+
+    if (fileViolations.length > 0) {
+      violations[file] = fileViolations;
+    }
+  }
+
+  const totalCount = Object.values(violations).flat().length;
+  return {
+    exitCode: totalCount > 0 ? 1 : 0,
+    skipped: false,
+    name: 'check_ui_reuse',
+    data: {
+      violations,
+      message: totalCount > 0
+        ? `${totalCount} UI reuse issue(s) found in ${Object.keys(violations).length} file(s)`
+        : 'All UI reuse 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);
+  });
+}