@nebulacomponents/citable 1.16.0 → 1.17.0

package/src/commands/compatibility.js

@@ -0,0 +1,205 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { readJson, nowIso } from '../shared/io.js';
+import { buildContext } from './context.js';
+import { runDetectors } from '../detectors/framework.js';
+import { selectDetectors, ALL_DETECTORS } from '../detectors/index.js';
+
+const PKG = readJson(new URL('../../package.json', import.meta.url));
+const SCHEMA_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'schemas');
+
+function checkModule(name) {
+  try {
+    execFileSync(process.execPath, ['--input-type=module', '-e', `await import('${name}')`], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 15000,
+      env: { ...process.env, NODE_OPTIONS: '' },
+    });
+    return { present: true, importable: true };
+  } catch (err) {
+    const notFound = /Cannot find (package|module)/.test(String(err.stderr || err.message));
+    return { present: !notFound, importable: false, note: notFound ? 'not installed (optional peer dependency)' : 'installed but failed to import — adapter mismatch' };
+  }
+}
+
+function engineSatisfied(range, actual) {
+  const m = range.match(/>=\s*(\d+)/);
+  if (!m) return { satisfied: true, note: `unrecognized range "${range}"` };
+  const major = Number.parseInt(actual.split('.')[0], 10);
+  return { satisfied: major >= Number(m[1]), note: `requires Node >= ${m[1]}, found ${actual}` };
+}
+
+/**
+ * `citable compatibility` — pre-flight diagnosis of environment, optional
+ * adapters, project framework, registry freshness, and generated-code
+ * constraints. Every check states its evidence; absence of an optional
+ * adapter is reported, never assumed.
+ */
+export async function compatibilityCommand(root, options = {}) {
+  const checks = [];
+
+  const engine = engineSatisfied(PKG.engines?.node || '>=0', process.versions.node);
+  checks.push({
+    check_id: 'NODE-ENGINE',
+    passed: engine.satisfied,
+    severity: engine.satisfied ? 'pass' : 'blocker',
+    detail: engine.note,
+  });
+
+  const peers = ['playwright', 'lighthouse', 'chrome-launcher', 'tesseract.js'];
+  const adapterResults = {};
+  for (const name of peers) {
+    const declared = Boolean(PKG.peerDependencies?.[name]);
+    const res = checkModule(name);
+    adapterResults[name] = { declared_optional_peer: declared, ...res };
+    checks.push({
+      check_id: `ADAPTER-${name.toUpperCase().replace('.', '-')}`,
+      passed: true, // absence of an optional adapter is a report, not a failure
+      severity: res.importable ? 'pass' : 'advisory',
+      detail: res.importable ? `${name} importable` : `${name}: ${res.note}`,
+    });
+  }
+
+  // Browser dependency: presence of a Chrome executable is only verified when
+  // chrome-launcher is importable; otherwise reported as unknown (fail open in
+  // reporting, fail closed in any feature that needs it).
+  if (adapterResults['chrome-launcher']?.importable) {
+    let browser = 'unknown';
+    try {
+      const mod = await import('chrome-launcher');
+      browser = mod.getChromePath?.() ? 'found' : 'not found';
+    } catch { browser = 'lookup failed'; }
+    checks.push({
+      check_id: 'BROWSER-CHROME',
+      passed: browser === 'found',
+      severity: browser === 'found' ? 'pass' : 'advisory',
+      detail: `Chrome executable: ${browser} (required for observe render / preview evidence; presence does not prove a successful launch)`,
+    });
+  }
+
+  // Project framework detection (for remediation format matching)
+  let frameworks = [];
+  const pkgFile = path.join(root, 'package.json');
+  if (fs.existsSync(pkgFile)) {
+    try {
+      const deps = { ...readJson(pkgFile).dependencies, ...readJson(pkgFile).devDependencies };
+      if (deps.next) frameworks.push('next');
+      if (deps.react) frameworks.push('react');
+      if (deps.vue || deps.nuxt) frameworks.push('vue');
+      if (deps.svelte || deps['@sveltejs/kit']) frameworks.push('svelte');
+    } catch { /* unreadable package.json reported below */ }
+  }
+  checks.push({
+    check_id: 'PROJECT-FRAMEWORK',
+    passed: true,
+    severity: 'pass',
+    detail: frameworks.length ? `detected: ${frameworks.join(', ')}; remediation templates available: react, vue, html` : 'no framework dependencies detected; component templates remain available as standalone HTML',
+  });
+
+  // Registry freshness
+  const citableDir = path.join(root, '.citable');
+  if (!fs.existsSync(citableDir)) {
+    checks.push({ check_id: 'REGISTRIES-PRESENT', passed: false, severity: 'advisory', detail: '.citable/ not found — run citable init' });
+  } else {
+    const yamlFiles = fs.readdirSync(citableDir).filter((f) => f.endsWith('.yaml'));
+    checks.push({ check_id: 'REGISTRIES-PRESENT', passed: true, severity: 'pass', detail: `${yamlFiles.length} registry/config YAML file(s) found; run citable validate registries for full referential validation` });
+    const registrySchemas = fs.readdirSync(SCHEMA_DIR).filter((f) => f.endsWith('.schema.json'));
+    checks.push({
+      check_id: 'SCHEMA-CONTRACTS',
+      passed: true,
+      severity: 'pass',
+      detail: `${registrySchemas.length} schema contracts shipped by citable ${PKG.version}; registries validated against them by citable validate registries`,
+    });
+  }
+
+  // Generated-code constraints (advisory, documented limits)
+  const edgeDir = path.join(root, '.citable', 'edge');
+  if (fs.existsSync(edgeDir)) {
+    for (const f of fs.readdirSync(edgeDir)) {
+      const size = fs.statSync(path.join(edgeDir, f)).size;
+      const limit = 1024 * 1024;
+      checks.push({
+        check_id: `EDGE-SIZE-${f}`,
+        passed: size <= limit,
+        severity: size <= limit ? 'pass' : 'blocker',
+        detail: `${f}: ${(size / 1024).toFixed(1)} KiB — Cloudflare Workers free plan limits the worker to ~1 MiB before compression (verify against your plan; this is a documented platform limit, not a measurement)`,
+      });
+    }
+  }
+
+  const blockers = checks.filter((c) => c.severity === 'blocker' && !c.passed);
+  return {
+    ok: blockers.length === 0,
+    timestamp: nowIso(),
+    tool_version: PKG.version,
+    node: process.versions.node,
+    engines: PKG.engines?.node || null,
+    framework: frameworks,
+    adapters: adapterResults,
+    checks,
+    blocker_count: blockers.length,
+    note: 'compatibility reports current environment facts; it cannot prove that a browser launch, API authorization, or collection will succeed',
+  };
+}
+
+/**
+ * `citable verify page <page>` — run the full deterministic detector set
+ * scoped to one page subject and return a posture verdict.
+ * pass = no detector currently reports this page; never an outcome guarantee.
+ */
+export async function verifyPage(root, pageRef, { target, baseUrl, refDate, viewport = null } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate, viewport });
+  if (!ctx.site) throw new Error('verify page requires a site target (built output directory or URL)');
+  const norm = (s) => String(s || '').replace(/\/+$/, '');
+  const candidates = [pageRef, pageRef.replace(/\/index\.html?$/i, '/'), pageRef.replace(/^\/+/, '')];
+  const wanted = pageRef.startsWith('/') ? `${norm(ctx.site.baseUrl)}${pageRef}` : pageRef;
+  const page = ctx.site.pages.find((p) => {
+    if (norm(p.url) === norm(wanted) || p.sourceFile === pageRef) return true;
+    if (candidates.some((c) => norm(p.url) === norm(pageRef.startsWith('/') ? `${norm(ctx.site.baseUrl)}${c}` : c))) return true;
+    if (norm(p.url).endsWith(norm(wanted))) return true;
+    return false;
+  });
+  if (!page) {
+    throw new Error(`page not found in audited output: ${pageRef}`);
+  }
+
+  const { findings, detectorsRun, detectorsSkipped, errors } = runDetectors(
+    selectDetectors({ namespaces: ALL_DETECTORS.map((d) => d.namespace).filter((v, i, a) => a.indexOf(v) === i) }),
+    { ...ctx, site: { ...ctx.site, pages: [page] } }
+  );
+  const pageFindings = findings.filter((f) => (f.subject?.url === page.url) || (f.subject?.identifier === page.url) || (f.subject?.source_file && f.subject.source_file === page.sourceFile));
+
+  const bySeverity = { critical: 0, high: 0, medium: 0, low: 0, informational: 0 };
+  for (const f of pageFindings) {
+    const s = f.classification?.severity;
+    if (s in bySeverity) bySeverity[s]++;
+  }
+  const status = errors.length ? 'blocked' : (bySeverity.critical > 0 || bySeverity.high > 0) ? 'attention' : pageFindings.length ? 'attention' : 'pass';
+
+  return {
+    page: page.url,
+    source_file: page.sourceFile,
+    status,
+    finding_count: pageFindings.length,
+    by_severity: bySeverity,
+    findings: pageFindings.map((f) => ({
+      detector_id: f.detector_id,
+      severity: f.classification.severity,
+      confidence: f.classification.confidence,
+      summary: f.observation.summary,
+      provenance: f.provenance,
+    })),
+    provenance: {
+      command: 'verify page',
+      timestamp: nowIso(),
+      tool_version: PKG.version,
+      viewport: ctx.viewport ?? null,
+      detectors_run: detectorsRun,
+      detectors_skipped: detectorsSkipped,
+      errors,
+      definition: 'pass means no detector currently reports this page; it is not a guarantee of crawling, indexing, ranking, citation, or conversion',
+    },
+  };
+}

package/src/commands/context.js

@@ -5,7 +5,7 @@ import { loadRegistries } from '../registries/index.js';
 import { buildSiteFromDir, buildSiteFromUrl } from '../extractor/site.js';
 
 /** Assemble the shared execution context used by audit-family commands. */
-export async function buildContext(root, { target, baseUrl, refDate } = {}) {
+export async function buildContext(root, { target, baseUrl, refDate, viewport = null } = {}) {
   const warnings = [];
   const configFile = path.join(root, '.citable', 'config.yaml');
   const config = fs.existsSync(configFile) ? readYaml(configFile) : { version: 1 };
@@ -71,6 +71,7 @@ export async function buildContext(root, { target, baseUrl, refDate } = {}) {
     observations: observations.length ? observations : null,
     snapshots,
     refDate: parseRefDate(refDate),
+    viewport,
     hashPage: (p) => sha256(p.text),
     warnings,
   };

package/src/commands/edgeRules.js

@@ -1,11 +1,14 @@
 import path from "node:path";
+import fs from "node:fs";
 import { loadRegistries } from "../registries/index.js";
+import { auditEdgeCode } from "./edgeSecurity.js";
 
 /**
  * Generates edge rules (redirects, Cloudflare WAF expressions, or Worker scripts)
  * from Citable registries.
  */
-export async function exportEdgeRules(root, { format = "cloudflare-redirects", output = null } = {}) {
+export async function exportEdgeRules(root, options = {}) {
+  const { format = "cloudflare-redirects", output = null, remediation = null } = options;
   const { registries } = loadRegistries(root);
   const crawlers = registries?.crawlers?.entries || [];
   const pages = registries?.pages?.entries || [];
@@ -32,8 +35,42 @@ export async function exportEdgeRules(root, { format = "cloudflare-redirects", o
     } else {
       content = "# Cloudflare Custom WAF Expression\n# No crawlers marked as blocked in crawlers.yaml\n";
     }
-  } else if (format === "cloudflare-worker") {
-    content = `// Cloudflare Worker generated by Citable Edge Adapter
+  } else if (format === "cloudflare-worker" || format === "cloudflare-cro" || (format === "cloudflare-worker" && options.remediation === "cro")) {
+    if (format === "cloudflare-cro" || options.remediation === "cro") {
+      content = `// Cloudflare Worker with HTMLRewriter CRO Remediation generated by Citable
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    const response = await fetch(request);
+    const contentType = response.headers.get("content-type") || "";
+    if (!contentType.includes("text/html")) return response;
+
+    const rewriter = new HTMLRewriter()
+      // Remediate CRO-007: Inject W3C autocomplete tokens
+      .on("input[name*='name']", { element(e) { if (!e.hasAttribute("autocomplete")) e.setAttribute("autocomplete", "name"); } })
+      .on("input[type='email'], input[name*='email']", { element(e) { if (!e.hasAttribute("autocomplete")) e.setAttribute("autocomplete", "email"); } })
+      .on("input[type='tel'], input[name*='phone']", { element(e) { if (!e.hasAttribute("autocomplete")) e.setAttribute("autocomplete", "tel"); } })
+      // Remediate CRO-015: Enforce 48px min touch target
+      .on("button, a.cta-button", { element(e) {
+        const style = e.getAttribute("style") || "";
+        if (!style.includes("min-height")) e.setAttribute("style", style + "; min-height: 48px; min-width: 48px; touch-action: manipulation;");
+      }})
+      // Remediate CRO-014: Ensure noindex on confirmation receipt pages
+      .on("head", { element(e) {
+        if (/\\/(confirmation|receipt|order-complete|success)/i.test(url.pathname)) {
+          e.append('<meta name="robots" content="noindex, nofollow" />', { html: true });
+        }
+      }})
+      // Remediate CRO-011: Inject sticky mobile CTA dock before body close
+      .on("body", { element(e) {
+        e.append('<aside id="nebula-sticky-dock" style="display:none;" class="sm:hidden fixed bottom-0 left-0 right-0 z-50 p-3 bg-white border-t"><a href="/signup" class="block w-full text-center py-3 bg-blue-600 text-white font-bold rounded-lg">Get Started</a></aside>', { html: true });
+      }});
+
+    return rewriter.transform(response);
+  },
+};\n`;
+    } else {
+      content = `// Cloudflare Worker generated by Citable Edge Adapter
 export default {
   async fetch(request, env, ctx) {
     const url = new URL(request.url);
@@ -58,8 +95,46 @@ export default {
     });
   },
 };\n`;
+    }
+  } else if (format === "vercel-middleware") {
+    content = `// Vercel Edge Middleware generated by Citable
+import { NextResponse } from 'next/server';
+
+export function middleware(request) {
+  const url = request.nextUrl;
+  const response = NextResponse.next();
+
+  // Enforce security headers & canonical routing
+  response.headers.set('X-Content-Type-Options', 'nosniff');
+  if (url.pathname === '/llms.txt') {
+    return NextResponse.rewrite(new URL('/resources/citable/llms.txt', request.url));
+  }
+  return response;
+}
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};\n`;
+  } else if (format === "shopify-snippet") {
+    content = `{% comment %}
+  Nebula Components CRO Remediation Snippet for Shopify
+  Add {% render 'nebula-cro-remediation' %} to theme.liquid before </body>
+{% endcomment %}
+<script>
+(function() {
+  document.addEventListener('DOMContentLoaded', function() {
+    // CRO-007: Inject autocomplete attributes
+    document.querySelectorAll('input[name*="name"]').forEach(function(i) { if (!i.autocomplete) i.autocomplete = 'name'; });
+    document.querySelectorAll('input[type="email"], input[name*="email"]').forEach(function(i) { if (!i.autocomplete) i.autocomplete = 'email'; });
+    // CRO-015: Enforce 48px touch targets
+    document.querySelectorAll('button[type="submit"], .btn').forEach(function(b) {
+      if (b.offsetHeight < 44) b.style.minHeight = '48px';
+    });
+  });
+})();
+</script>\n`;
   } else {
-    throw new Error(`unsupported edge format "${format}". Supported: cloudflare-redirects, cloudflare-waf, cloudflare-worker`);
+    throw new Error(`unsupported edge format "${format}". Supported: cloudflare-redirects, cloudflare-waf, cloudflare-worker, cloudflare-cro, vercel-middleware, shopify-snippet`);
   }
 
   if (output) {
@@ -71,6 +146,7 @@ export default {
     output_path: output,
     content,
     rules_count: content.split("\n").filter((l) => l && !l.startsWith("#")).length,
+    security: auditEdgeCode(content, { format, name: `edge-export:${format}` }),
   };
 }
 

package/src/commands/edgeSecurity.js

@@ -0,0 +1,192 @@
+/**
+ * Security audit for generated and user-supplied edge code.
+ *
+ * Findings are deterministic pattern checks over the code text. A clean
+ * result means no listed risk pattern was found; it is not a substitute for
+ * human security review of deployed code.
+ */
+
+const WORKER_SIZE_LIMIT_BYTES = 1024 * 1024; // Cloudflare Workers ~1 MiB before compression (documented platform limit)
+
+const RULES = [
+  {
+    rule_id: 'EDGSEC-001',
+    name: 'Inline script requires CSP unsafe-inline',
+    applies: ['shopify-snippet', 'html'],
+    check(content) {
+      const inline = /<script(?![^>]*\ssrc\s*=)[^>]*>/i.test(content);
+      if (!inline) return null;
+      return {
+        severity: 'advisory',
+        summary: 'Generated code contains an inline <script> block; sites with a strict Content-Security-Policy will block it unless a nonce or hash is added.',
+        remediation: 'Prefer an external script file, or add the script hash/nonce to the CSP. Record the CSP implication in deployment notes.',
+      };
+    },
+  },
+  {
+    rule_id: 'EDGSEC-002',
+    name: 'HTMLRewriter html-mode append/setAttribute with dynamic content',
+    applies: ['cloudflare-worker', 'cloudflare-cro'],
+    check(content) {
+      const dynamicAppend = /\.append\(\s*(?!['"`]\s*[<A-Za-z])[^,)]*?,\s*\{\s*html:\s*true/i.test(content)
+        || /\.append\(\s*[A-Za-z_$][\w$.\[\]]*\s*,\s*\{\s*html:\s*true/i.test(content);
+      if (!dynamicAppend) return null;
+      return {
+        severity: 'high',
+        summary: 'HTMLRewriter append uses html:true with a non-literal argument; untrusted data reaching this sink becomes HTML injection.',
+        remediation: 'Only append static string literals with html:true, or escape all interpolated values with a strict HTML escaper before insertion.',
+      };
+    },
+  },
+  {
+    rule_id: 'EDGSEC-003',
+    name: 'Unescaped interpolation into HTML or script context',
+    applies: ['cloudflare-worker', 'cloudflare-cro', 'vercel-middleware', 'shopify-snippet', 'html'],
+    check(content, { format }) {
+      const problems = [];
+      // JS template literals inside generated HTML strings
+      const htmlTemplateLiteral = /`[^`]*<(?:div|span|aside|a|p|script)[^>]*>\$\{[^}]*\}/i.test(content);
+      if (htmlTemplateLiteral) problems.push('template literal interpolated into HTML markup');
+      // Liquid object output without escape filter inside script blocks (script context never auto-escapes)
+      if (format === 'shopify-snippet') {
+        const scripts = content.match(/<script\b[^>]*>[\s\S]*?<\/script[^>]*>/gi) || [];
+        for (const block of scripts) {
+          for (const m of block.matchAll(/\{\{[^}]*\}\}/g)) {
+            if (!/\|\s*escape|json/.test(m[0])) problems.push(`Liquid output ${m[0]} inside <script> without escape filter`);
+          }
+        }
+        // also Liquid anywhere with raw/unsafe filters
+        for (const m of content.matchAll(/\{\{[^}]*(?:\|\s*raw|\|\s*strip_html)[^}]*\}\}/g)) {
+          problems.push(`Liquid output ${m[0]} uses a filter that disables escaping`);
+        }
+      }
+      if (problems.length === 0) return null;
+      return {
+        severity: 'high',
+        summary: `Unescaped dynamic interpolation in output context: ${problems.join('; ')}`,
+        remediation: 'Escape all dynamic values for the exact output context (HTML body, attribute, or JS string) or use static literals only.',
+      };
+    },
+  },
+  {
+    rule_id: 'EDGSEC-004',
+    name: 'Untrusted referral data written into the DOM',
+    applies: ['cloudflare-worker', 'cloudflare-cro', 'vercel-middleware', 'shopify-snippet', 'html'],
+    check(content) {
+      const readsReferral = /document\.referrer|location\.hash|searchParams\.get|URLSearchParams|\?~:text=:~:text/i.test(content)
+        || /:~:text=/i.test(content);
+      const dangerousSink = /innerHTML\s*=|document\.write\s*\(|insertAdjacentHTML\s*\(/.test(content);
+      if (readsReferral && dangerousSink) {
+        return {
+          severity: 'high',
+          summary: 'Code reads user-controlled referral data (referrer, URL hash, or text fragment) and also writes to HTML-parsing DOM sinks; referral fragments are attacker-controllable input.',
+          remediation: 'Render referral-derived values with textContent/createTextNode only, or never write them into the DOM. Treat referral fragments as untrusted data.',
+        };
+      }
+      if (readsReferral) {
+        return {
+          severity: 'advisory',
+          summary: 'Code reads user-controlled referral data (referrer or text fragment). Confirmed safe sinks in the current template, but any future change must keep this data out of HTML-parsing sinks and must not persist or transmit it without a documented consent basis.',
+          remediation: 'Keep referral fragments out of innerHTML/document.write; do not log, store, or transmit referral content; label analytics derived from it as untrusted input.',
+        };
+      }
+      return null;
+    },
+  },
+  {
+    rule_id: 'EDGSEC-005',
+    name: 'Potential PII collected by telemetry',
+    applies: ['cloudflare-worker', 'cloudflare-cro', 'vercel-middleware', 'shopify-snippet', 'html'],
+    check(content) {
+      // PII matters when used as data (object keys, assignments, values), not
+      // when it appears inside autocomplete/CSS selector hints.
+      const patterns = [
+        /\b(email|e_mail|fullname|first_name|last_name|phone|address|postal_code|postcode|ip_address|user_agent|birthdate|date_of_birth)\b\s*[:=]/gi,
+        /[:\{,]\s*["'](email|e_mail|fullname|first_name|last_name|phone|address|postal_code|postcode|ip_address|user_agent|birthdate|date_of_birth)["']\s*:/gi,
+      ];
+      const found = [];
+      for (const rx of patterns) {
+        for (const m of content.matchAll(rx)) found.push(m[0].trim());
+      }
+      if (found.length === 0) return null;
+      const unique = [...new Set(found)];
+      return {
+        severity: 'high',
+        summary: `Telemetry or edge code references potential PII fields (${unique.join(', ')}); accidental collection creates GDPR/CCPA exposure.`,
+        remediation: 'Remove PII from generated telemetry payloads; collect only aggregate experiment identifiers with a documented consent basis.',
+      };
+    },
+  },
+  {
+    rule_id: 'EDGSEC-006',
+    name: 'Per-request response variance without cache guidance',
+    applies: ['cloudflare-worker', 'cloudflare-cro', 'vercel-middleware'],
+    check(content) {
+      const variesOnRequest = /request\.headers\.get\(|cookies|cf-connecting-ip/i.test(content);
+      const setsCacheControl = /cache-control/i.test(content);
+      if (variesOnRequest && !setsCacheControl) {
+        return {
+          severity: 'medium',
+          summary: 'Edge code varies behavior per request (headers/cookies/IP) without setting explicit Cache-Control guidance; a shared cache may serve one visitor’s personalized response to others (cache poisoning of personalized variants).',
+        remediation: 'Add explicit Cache-Control (e.g. private, no-store for personalized responses) or move variance behind cacheable segmentation.',
+        };
+      }
+      return null;
+    },
+  },
+  {
+    rule_id: 'EDGSEC-007',
+    name: 'Worker size above documented platform limit',
+    applies: ['cloudflare-worker', 'cloudflare-cro'],
+    check(content) {
+      const size = Buffer.byteLength(content, 'utf8');
+      if (size <= WORKER_SIZE_LIMIT_BYTES) return null;
+      return {
+        severity: 'medium',
+        summary: `Generated worker is ${(size / 1024).toFixed(1)} KiB; Cloudflare Workers limit scripts to ~1 MiB before compression on many plans (documented platform limit, not a measurement).`,
+        remediation: 'Split the worker or strip unused remediations before deployment.',
+      };
+    },
+  },
+];
+
+/**
+ * Audit one edge/snippet code string. Returns findings with full provenance
+ * fields so results are citable evidence, not terminal commentary.
+ */
+export function auditEdgeCode(rawContent, { format = 'html', name = 'generated-edge-code', toolVersion = null, rules = RULES } = {}) {
+  const content = typeof rawContent === 'string' ? rawContent : String(rawContent);
+  const findings = [];
+  for (const rule of rules) {
+    if (rule.applies.length && !rule.applies.includes(format)) continue;
+    let hit = null;
+    try {
+      hit = rule.check(content, { format });
+    } catch (err) {
+      findings.push({
+        rule_id: `${rule.rule_id}-ERROR`,
+        severity: 'high',
+        summary: `security rule error: ${err.message}`,
+        remediation: 'Fix the audit rule before trusting a clean result (fail closed).',
+      });
+      continue;
+    }
+    if (hit) {
+      findings.push({ rule_id: rule.rule_id, rule_name: rule.name, ...hit });
+    }
+  }
+  const severityRank = { high: 0, medium: 1, advisory: 2 };
+  findings.sort((a, b) => severityRank[a.severity] - severityRank[b.severity]);
+  return {
+    target: name,
+    format,
+    byte_size: Buffer.byteLength(content, 'utf8'),
+    finding_count: findings.length,
+    high: findings.filter((f) => f.severity === 'high').length,
+    medium: findings.filter((f) => f.severity === 'medium').length,
+    advisory: findings.filter((f) => f.severity === 'advisory').length,
+    findings,
+    methodology: 'deterministic pattern audit of generated code; a clean result is not a substitute for human security review',
+    tool_version: toolVersion,
+  };
+}