@chemx/create-chemx 26.9.21-8 → 26.9.23-1269

package/cli/audit/ast-visitors.js

@@ -7,8 +7,9 @@ import {
   isZeroDelayTimeout,
   isUnguardedConsoleCall
 } from './rules-predicates.js';
+import { validateHookReturnShape } from './hook-shape-validator.js';
 
-export const createAstVisitors = ({ relativePath, violations }) => {
+export const createAstVisitors = ({ relativePath, violations, hookRegistry }) => {
   return {
     Function(astPath) {
       const isCustomHook = isCustomHookFunction(astPath);
@@ -45,22 +46,14 @@ export const createAstVisitors = ({ relativePath, violations }) => {
       if (isCustomHook) {
         astPath.traverse({
           ReturnStatement(retPath) {
-            if (retPath.getFunctionParent() === astPath && t.isObjectExpression(retPath.node.argument)) {
-              const propCount = retPath.node.argument.properties.length;
-              if (propCount > 5) {
-                const line = retPath.node.loc?.start.line || 1;
-                const meta = RULE_REGISTRY.HOOK_RETURN_OVERLOAD;
-                violations.push({
-                  filePath: relativePath,
-                  line,
-                  column: retPath.node.loc?.start.column || 1,
-                  hazard: `Hook return saturation (${propCount} properties > 5 limit)`,
-                  rule: 'HOOK_RETURN_OVERLOAD',
-                  severity: meta.severity,
-                  pillar: meta.pillar,
-                  directive: meta.directive
-                });
-              }
+            if (retPath.getFunctionParent() === astPath) {
+              validateHookReturnShape({
+                retPath,
+                astPath,
+                relativePath,
+                violations,
+                hookRegistry
+              });
             }
           }
         });

package/cli/audit/autofix.js

@@ -63,7 +63,9 @@ export const autofixContent = (content, options = {}) => {
     }
 
     // 3. AI lazy placeholder comment removal
-    if (!shouldDropLine && shouldFix('AI_SLOP_LAZY_PLACEHOLDER') && TRUNCATION_REGEX.test(line)) {
+    const hasLazyTruncation = TRUNCATION_REGEX.test(line);
+    const isLazyTruncationEligible = !shouldDropLine && shouldFix('AI_SLOP_LAZY_PLACEHOLDER');
+    if (isLazyTruncationEligible && hasLazyTruncation) {
       fixes.push({
         line: lineNumber,
         rule: 'AI_SLOP_LAZY_PLACEHOLDER',
@@ -72,7 +74,9 @@ export const autofixContent = (content, options = {}) => {
       shouldDropLine = true;
     }
 
-    if (!shouldDropLine && shouldFix('TYPOGRAPHY_EM_DASH') && line.includes('\u2014')) {
+    const hasEmDash = line.includes('\u2014');
+    const isEmDashEligible = !shouldDropLine && shouldFix('TYPOGRAPHY_EM_DASH');
+    if (isEmDashEligible && hasEmDash) {
       line = line.replace(/\u2014/g, '-');
       fixes.push({
         line: lineNumber,
@@ -81,6 +85,17 @@ export const autofixContent = (content, options = {}) => {
       });
     }
 
+    const hasTimeoutMacro = /setTimeout\([^,]+,\s*0\)/.test(line);
+    const isTimeoutEligible = !shouldDropLine && shouldFix('MACRO_TASK_OVER_MICRO_TASK');
+    if (isTimeoutEligible && hasTimeoutMacro) {
+      line = line.replace(/setTimeout\(([^,]+),\s*0\)/g, 'queueMicrotask($1)');
+      fixes.push({
+        line: lineNumber,
+        rule: 'MACRO_TASK_OVER_MICRO_TASK',
+        action: 'Replaced setTimeout(fn, 0) with queueMicrotask(fn)'
+      });
+    }
+
     if (!shouldDropLine) {
       resultLines.push(line);
     }

package/cli/audit/clone-detector.js

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { deserializeVector, cosineSimilarity } from '../embeddings/vectorizer.js';
+
+const isSpecOrTest = (filePath) => {
+  if (!filePath || typeof filePath !== 'string') return false;
+  return filePath.includes('.spec.') || filePath.includes('.test.') || filePath.includes('__tests__');
+};
+
+export const detectSemanticClones = (db, options = {}) => {
+  const isValidDb = Boolean(db);
+  if (!isValidDb) return { count: 0, threshold: 0.85, pairs: [] };
+
+  const threshold = typeof options.threshold === 'number' ? options.threshold : 0.85;
+  const limit = options.limit || 50;
+
+  const rows = db.prepare(
+    "SELECT file_path, target_name, vector FROM embeddings WHERE target_type = 'file'"
+  ).all();
+
+  const entries = rows
+    .filter((r) => !isSpecOrTest(r.file_path))
+    .map((r) => ({
+      filePath: r.file_path,
+      name: r.target_name,
+      vec: deserializeVector(r.vector)
+    }));
+
+  const pairs = [];
+
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      const a = entries[i];
+      const b = entries[j];
+
+      const isSameFile = a.filePath === b.filePath;
+      if (isSameFile) continue;
+
+      const sim = cosineSimilarity(a.vec, b.vec);
+      const isClone = sim >= threshold;
+
+      if (isClone) {
+        pairs.push({
+          fileA: a.filePath,
+          fileB: b.filePath,
+          nameA: a.name,
+          nameB: b.name,
+          similarity: Number(sim.toFixed(4)),
+          isExact: sim >= 0.95
+        });
+      }
+    }
+  }
+
+  pairs.sort((p1, p2) => p2.similarity - p1.similarity);
+  const cappedPairs = pairs.slice(0, limit);
+
+  return {
+    count: pairs.length,
+    threshold,
+    exactClones: cappedPairs.filter((p) => p.isExact),
+    nearClones: cappedPairs.filter((p) => !p.isExact),
+    pairs: cappedPairs
+  };
+};

package/cli/audit/clone-detector.spec.js

@@ -0,0 +1,46 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+import { generateEmbedding, serializeVector } from '../embeddings/vectorizer.js';
+import { detectSemanticClones } from './clone-detector.js';
+import { formatCloneReport } from './reporter-clones.js';
+
+test('clone-detector: detects high-similarity clones while ignoring spec companion files', () => {
+  const db = new DatabaseSync(':memory:');
+  db.exec(`
+    CREATE TABLE embeddings (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_path TEXT NOT NULL,
+      target_type TEXT NOT NULL,
+      target_name TEXT NOT NULL,
+      vector BLOB NOT NULL
+    );
+  `);
+
+  const insert = db.prepare('INSERT INTO embeddings (file_path, target_type, target_name, vector) VALUES (?, ?, ?, ?)');
+  const vecA = serializeVector(generateEmbedding('modal window popup backdrop blur close cancel confirm'));
+  const vecB = serializeVector(generateEmbedding('modal dialog popup backdrop blur cancel confirm close'));
+  const vecTest = serializeVector(generateEmbedding('modal window popup backdrop blur close cancel confirm spec test'));
+  const vecDiff = serializeVector(generateEmbedding('database sqlite migration column index'));
+
+  insert.run('src/ui/m-modal-a/m-modal-a.vue', 'file', 'm-modal-a.vue', vecA);
+  insert.run('src/ui/m-modal-b/m-modal-b.vue', 'file', 'm-modal-b.vue', vecB);
+  insert.run('src/ui/m-modal-a/m-modal-a.spec.ts', 'file', 'm-modal-a.spec.ts', vecTest);
+  insert.run('src/db/storage.ts', 'file', 'storage.ts', vecDiff);
+
+  const res = detectSemanticClones(db, { threshold: 0.8 });
+  assert.equal(res.count, 1);
+  assert.equal(res.pairs[0].fileA, 'src/ui/m-modal-a/m-modal-a.vue');
+  assert.equal(res.pairs[0].fileB, 'src/ui/m-modal-b/m-modal-b.vue');
+  assert.ok(res.pairs[0].similarity > 0.85);
+
+  const report = formatCloneReport(res);
+  assert.match(report, /Semantic Clone Detection/);
+  assert.match(report, /m-modal-a\.vue <-> src\/ui\/m-modal-b\/m-modal-b\.vue/);
+});
+
+test('clone-detector: handles empty or invalid db gracefully', () => {
+  assert.equal(detectSemanticClones(null).count, 0);
+  const emptyReport = formatCloneReport({ count: 0, threshold: 0.85, pairs: [] });
+  assert.match(emptyReport, /Zero duplicate clone hazards detected/);
+});

package/cli/audit/hook-shape-validator.js

@@ -0,0 +1,312 @@
+import * as t from '@babel/types';
+import { RULE_REGISTRY } from './rules-registry.js';
+
+const VERB_PREFIX_REGEX = /^(add|remove|toggle|set|get|fetch|load|save|delete|clear|reset|refresh|update|create|edit|send|sync|init|dispose|trigger|post|put|patch|apply|dismiss|select|deselect|filter|sort|search|open|close|show|hide|start|stop|cancel|execute|run|retry|submit|validate|mutate|next|prev|step|increment|decrement|insert|upsert|drop|enable|disable|register|unregister|login|logout|checkout|publish|archive|discard|confirm|undo|redo|claim|complete|acquire|release|download|upload|export|import|handle)([A-Z0-9_].*)?$/;
+
+const STATUS_HEURISTIC_REGEX = /^(is[A-Z]|has[A-Z]|can[A-Z]|should[A-Z])|.*(Error|Status)$/;
+const STATUS_EXACT_NAMES = new Set(['status', 'error', 'loading', 'pending', 'ready']);
+const ACTION_WRAPPER_KEYS = new Set(['actions', 'handlers', 'methods', 'operations']);
+
+const RAW_DOM_REF_REGEX = /^(dom|element|container|input|button|target|root|node)?Ref$|.*(Element|Node|Dom)Ref$/i;
+const INTERMEDIATE_VAL_REGEX = /^(temp|draft|raw|partial|interim|scratch|memoized)([A-Z_].*)?$/i;
+const UNGROUPED_CALLBACK_REGEX = /^(on[A-Z]|callback$|.*Callback$)/;
+
+const MUTUALLY_EXCLUSIVE_STATUSES = new Set([
+  'isloading', 'issuccess', 'iserror', 'isidle', 'isloaded', 'isfetching', 'ispending',
+  'loading', 'success', 'idle'
+]);
+
+export const SEMANTIC_STATUS_CLUSTERS = {
+  LOADING: {
+    canonical: 'isLoading',
+    variants: new Set(['isloading', 'loading', 'ispending', 'pending', 'isfetching', 'fetching'])
+  },
+  ERROR: {
+    canonical: 'error',
+    variants: new Set(['error', 'iserror', 'haserror', 'err', 'errormessage'])
+  },
+  READY: {
+    canonical: 'isReady',
+    variants: new Set(['isready', 'ready', 'isinitialized', 'initialized'])
+  },
+  STATUS: {
+    canonical: 'status',
+    variants: new Set(['status', 'state', 'phase', 'stage'])
+  }
+};
+
+const resolvePropKey = (prop) => {
+  if (t.isIdentifier(prop.key)) return prop.key.name;
+  if (t.isStringLiteral(prop.key)) return prop.key.value;
+  return null;
+};
+
+const isFunctionNode = (node, scope) => {
+  const isDirectFunction = t.isArrowFunctionExpression(node) || t.isFunctionExpression(node);
+  if (isDirectFunction) return true;
+
+  const isIdentifierNode = t.isIdentifier(node);
+  const canInspectScope = isIdentifierNode && Boolean(scope);
+  if (!canInspectScope) return false;
+
+  const binding = scope.getBinding(node.name);
+  if (!binding) return false;
+
+  if (binding.path.isFunctionDeclaration()) return true;
+
+  if (binding.path.isVariableDeclarator()) {
+    const init = binding.path.node.init;
+    const isInitFunction = t.isArrowFunctionExpression(init) || t.isFunctionExpression(init);
+    if (isInitFunction) return true;
+    const isCallbackHook = t.isCallExpression(init) && t.isIdentifier(init.callee, { name: 'useCallback' });
+    if (isCallbackHook) return true;
+  }
+
+  return false;
+};
+
+const hasNestedActions = (objectExpr, scope) => {
+  if (!t.isObjectExpression(objectExpr)) return false;
+  return objectExpr.properties.some((p) => {
+    if (t.isObjectMethod(p)) return true;
+    if (t.isObjectProperty(p)) {
+      const name = resolvePropKey(p);
+      const isVerbNamed = Boolean(name && VERB_PREFIX_REGEX.test(name));
+      if (isVerbNamed) return true;
+      if (isFunctionNode(p.value, scope)) return true;
+    }
+    return false;
+  });
+};
+
+export const createHookShapeRegistry = () => {
+  const entries = [];
+
+  const recordHook = (hookInfo) => {
+    entries.push(hookInfo);
+  };
+
+  const validateCrossHookConsistency = () => {
+    const consistencyViolations = [];
+    if (entries.length < 2) return consistencyViolations;
+
+    for (const [clusterKey, cluster] of Object.entries(SEMANTIC_STATUS_CLUSTERS)) {
+      const occurrences = [];
+      for (const entry of entries) {
+        for (const prop of entry.statusProps) {
+          const lower = prop.name.toLowerCase();
+          if (cluster.variants.has(lower)) {
+            occurrences.push({ ...prop, hookName: entry.hookName, filePath: entry.filePath });
+          }
+        }
+      }
+
+      const uniqueNames = Array.from(new Set(occurrences.map((o) => o.name)));
+      if (uniqueNames.length > 1) {
+        for (const occ of occurrences) {
+          if (occ.name !== cluster.canonical) {
+            const meta = RULE_REGISTRY.HOOK_SHAPE_CONTRACT;
+            consistencyViolations.push({
+              filePath: occ.filePath,
+              line: occ.line,
+              column: occ.column,
+              hazard: `Inconsistent ${clusterKey.toLowerCase()} status property "${occ.name}". Rename to "${cluster.canonical}" to match hook shape conventions.`,
+              rule: 'HOOK_SHAPE_CONTRACT',
+              severity: meta.severity,
+              pillar: meta.pillar,
+              directive: meta.directive
+            });
+          }
+        }
+      }
+    }
+
+    return consistencyViolations;
+  };
+
+  return { recordHook, validateCrossHookConsistency, entries };
+};
+
+export const validateHookReturnShape = ({ retPath, astPath, relativePath, violations, hookRegistry }) => {
+  if (!t.isObjectExpression(retPath.node.argument)) return;
+
+  const properties = retPath.node.argument.properties;
+  const propCount = properties.length;
+  const hookName = astPath.node.id?.name || astPath.parentPath?.node?.id?.name || 'anonymousHook';
+  const meta = RULE_REGISTRY.HOOK_SHAPE_CONTRACT;
+  const overloadMeta = RULE_REGISTRY.HOOK_RETURN_OVERLOAD;
+
+  if (propCount > 5) {
+    violations.push({
+      filePath: relativePath,
+      line: retPath.node.loc?.start.line || 1,
+      column: retPath.node.loc?.start.column || 1,
+      hazard: `Hook return saturation (${propCount} properties > 5 limit; deprecated rule: migrate to HOOK_SHAPE_CONTRACT)`,
+      rule: 'HOOK_RETURN_OVERLOAD',
+      severity: overloadMeta.severity,
+      pillar: overloadMeta.pillar,
+      directive: overloadMeta.directive
+    });
+  }
+
+  const statusProps = [];
+  const mutualStatuses = [];
+
+  for (const prop of properties) {
+    if (t.isSpreadElement(prop)) continue;
+
+    const keyName = resolvePropKey(prop);
+    if (!keyName) continue;
+
+    const line = prop.loc?.start.line || retPath.node.loc?.start.line || 1;
+    const column = prop.loc?.start.column || retPath.node.loc?.start.column || 1;
+
+    const isActionWrapperKey = ACTION_WRAPPER_KEYS.has(keyName);
+    if (isActionWrapperKey) {
+      violations.push({
+        filePath: relativePath,
+        line,
+        column,
+        hazard: `Nested action wrapper detected in hook return ("${keyName}"). Actions must be flat at top level per HOOK_SHAPE_CONTRACT.`,
+        rule: 'HOOK_SHAPE_CONTRACT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+      continue;
+    }
+
+    const isPropObject = t.isObjectProperty(prop) && hasNestedActions(prop.value, astPath.scope);
+    if (isPropObject) {
+      violations.push({
+        filePath: relativePath,
+        line,
+        column,
+        hazard: `Action wrapper detected in property "${keyName}". Actions must be flat at top level per HOOK_SHAPE_CONTRACT.`,
+        rule: 'HOOK_SHAPE_CONTRACT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+      continue;
+    }
+
+    const isMethod = t.isObjectMethod(prop);
+    const isPropFunc = t.isObjectProperty(prop) && isFunctionNode(prop.value, astPath.scope);
+    const isFunction = isMethod || isPropFunc;
+
+    if (isFunction) {
+      const isStatusPredicate = STATUS_HEURISTIC_REGEX.test(keyName);
+      if (isStatusPredicate) {
+        statusProps.push({ name: keyName, line, column });
+        if (MUTUALLY_EXCLUSIVE_STATUSES.has(keyName.toLowerCase())) {
+          mutualStatuses.push(keyName);
+        }
+        continue;
+      }
+
+      const isUngrouped = UNGROUPED_CALLBACK_REGEX.test(keyName);
+      if (isUngrouped) {
+        violations.push({
+          filePath: relativePath,
+          line,
+          column,
+          hazard: `Property "${keyName}" is an invalid hook action. Actions must be verb-prefixed (e.g. addItem, toggleItem) rather than event handlers or callbacks.`,
+          rule: 'HOOK_SHAPE_CONTRACT',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      } else {
+        const isVerbPrefixed = VERB_PREFIX_REGEX.test(keyName);
+        if (!isVerbPrefixed) {
+          violations.push({
+            filePath: relativePath,
+            line,
+            column,
+            hazard: `Function "${keyName}" in hook return is missing an action verb prefix (e.g. addItem, toggleItem).`,
+            rule: 'HOOK_SHAPE_CONTRACT',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
+      continue;
+    }
+
+    const isDomRef = RAW_DOM_REF_REGEX.test(keyName) || keyName === 'ref';
+    if (isDomRef) {
+      violations.push({
+        filePath: relativePath,
+        line,
+        column,
+        hazard: `Property "${keyName}" is a raw DOM ref. Hooks must not return raw DOM element refs.`,
+        rule: 'HOOK_SHAPE_CONTRACT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+      continue;
+    }
+
+    const isIntermediate = INTERMEDIATE_VAL_REGEX.test(keyName);
+    if (isIntermediate) {
+      violations.push({
+        filePath: relativePath,
+        line,
+        column,
+        hazard: `Property "${keyName}" is an intermediate or temporary value. Hooks must return finished domain state.`,
+        rule: 'HOOK_SHAPE_CONTRACT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+      continue;
+    }
+
+    const isCallback = UNGROUPED_CALLBACK_REGEX.test(keyName);
+    if (isCallback) {
+      violations.push({
+        filePath: relativePath,
+        line,
+        column,
+        hazard: `Property "${keyName}" is an ungrouped callback or handler. Actions must be verb-prefixed (e.g. addItem).`,
+        rule: 'HOOK_SHAPE_CONTRACT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+      continue;
+    }
+
+    const isStatus = STATUS_HEURISTIC_REGEX.test(keyName) || STATUS_EXACT_NAMES.has(keyName.toLowerCase());
+    if (isStatus) {
+      statusProps.push({ name: keyName, line, column });
+      if (MUTUALLY_EXCLUSIVE_STATUSES.has(keyName.toLowerCase())) {
+        mutualStatuses.push(keyName);
+      }
+    }
+  }
+
+  if (mutualStatuses.length >= 3) {
+    violations.push({
+      filePath: relativePath,
+      line: retPath.node.loc?.start.line || 1,
+      column: retPath.node.loc?.start.column || 1,
+      hazard: `Mutually exclusive lifecycle states returned as multiple independent booleans (${mutualStatuses.join(', ')}). Prefer a single discriminated status field per Directive 2.B.`,
+      rule: 'HOOK_SHAPE_CONTRACT',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  if (hookRegistry) {
+    hookRegistry.recordHook({
+      hookName,
+      filePath: relativePath,
+      statusProps
+    });
+  }
+};

package/cli/audit/prompts.js

@@ -296,7 +296,7 @@ export const buildHotspotsPrompt = (report, options = {}) => {
   lines.push('1. Pre-Split Pattern Discovery: Audit recurring UI layouts, state machines, and predicates across monoliths first; extract canonical shared capsules before slicing to prevent bespoke pattern duplication.');
   lines.push('2. Molecular Limits: Molecule capsules must strictly remain under 100 lines per file.');
   lines.push('3. Table-of-Contents Views: Top-level page views must be 10 to 20 line declarative Table of Contents assembling molecules via named slots.');
-  lines.push('4. Composable Return Contracts: Custom hooks/composables must strictly limit returns to 3 to 5 properties (State + Status + Actions).');
+  lines.push('4. Composable Return Contracts: Custom hooks/composables must classify returns into flat State, Status, and verb-prefixed Actions buckets (Directive 4.A).');
   lines.push('5. Type Co-location: Co-locate granular types/*.d.ts files inside each feature capsule (< 100 lines per type file) instead of creating type monoliths.');
   lines.push('6. Zero breaking changes to external component APIs, route exports, or existing props.');
   if (!isSubSection) {

package/cli/audit/reporter-clones.js

@@ -0,0 +1,33 @@
+import { ANSI } from '../theme.js';
+
+export const formatCloneReport = (cloneResult) => {
+  const { count, threshold, exactClones = [], nearClones = [], pairs = [] } = cloneResult;
+  const hasPairs = Array.isArray(pairs) && pairs.length > 0;
+  if (!hasPairs) {
+    return `   ${ANSI.LIME}✔ Zero duplicate clone hazards detected (threshold: ${threshold})${ANSI.RESET}\n`;
+  }
+
+  const lines = [
+    `   ${ANSI.BOLD}${ANSI.PINK}Semantic Clone Detection (${count} candidate pairs >= ${threshold})${ANSI.RESET}`
+  ];
+
+  const hasExact = exactClones.length > 0;
+  if (hasExact) {
+    lines.push(`     ${ANSI.RED}${ANSI.BOLD}Hazard: ${exactClones.length} high-similarity duplicate(s) (>= 0.95)${ANSI.RESET}`);
+    for (const p of exactClones) {
+      const simPct = Math.round(p.similarity * 100);
+      lines.push(`       ${ANSI.RED}[${simPct}%]${ANSI.RESET} ${p.fileA} <-> ${p.fileB}`);
+    }
+  }
+
+  const hasNear = nearClones.length > 0;
+  if (hasNear) {
+    lines.push(`     ${ANSI.GOLD}Harmonization Candidates: ${nearClones.length} structural clone(s)${ANSI.RESET}`);
+    for (const p of nearClones) {
+      const simPct = Math.round(p.similarity * 100);
+      lines.push(`       ${ANSI.GOLD}[${simPct}%]${ANSI.RESET} ${p.fileA} <-> ${p.fileB}`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+};

package/cli/audit/reporter-hotspot-graph.js

@@ -0,0 +1,34 @@
+import { ANSI } from '../theme.js';
+
+export const formatHotspotGraphReport = (graphResult) => {
+  const { count, hotspots = [] } = graphResult;
+  const hasHotspots = Array.isArray(hotspots) && hotspots.length > 0;
+  if (!hasHotspots) {
+    return `   ${ANSI.LIME}✔ Zero cascading violation hotspots detected.${ANSI.RESET}\n`;
+  }
+
+  const lines = [
+    `   ${ANSI.BOLD}${ANSI.PINK}Cascading Violation Hotspot Graph (${count} files with propagating debt)${ANSI.RESET}`
+  ];
+
+  for (let idx = 0; idx < hotspots.length; idx++) {
+    const h = hotspots[idx];
+    const rank = idx + 1;
+    const blast = h.blastRadius;
+    const critStr = h.criticalCount > 0 ? `${ANSI.RED}${h.criticalCount} crit${ANSI.RESET}, ` : '';
+    const highStr = h.highCount > 0 ? `${ANSI.GOLD}${h.highCount} high${ANSI.RESET}, ` : '';
+    const medStr = `${h.medCount} med`;
+
+    lines.push(
+      `     ${ANSI.BOLD}#${rank} ${ANSI.CYAN}${h.filePath}${ANSI.RESET} [${h.tier}, ${h.lines} LOC]`
+    );
+    lines.push(
+      `        ${ANSI.RED}Cascading Risk: ${h.cascadingRisk} pts${ANSI.RESET} (Violations: ${critStr}${highStr}${medStr})`
+    );
+    lines.push(
+      `        ${ANSI.DIM}Blast Radius: ${blast.totalImpact} consumers (${blast.directConsumers} direct, ${blast.impactedTests} tests across ${blast.depth} hops)${ANSI.RESET}`
+    );
+  }
+
+  return lines.join('\n') + '\n';
+};

package/cli/audit/rules-registry.js

@@ -117,9 +117,14 @@ export const RULE_REGISTRY = {
     directive: 'Extract related state and effects into dedicated domain hooks'
   },
   HOOK_RETURN_OVERLOAD: {
+    pillar: PILLARS.PILLAR_3,
+    severity: 'MEDIUM',
+    directive: 'Limit hook return values to 3 to 5 properties (Deprecated: use HOOK_SHAPE_CONTRACT)'
+  },
+  HOOK_SHAPE_CONTRACT: {
     pillar: PILLARS.PILLAR_3,
     severity: 'HIGH',
-    directive: 'Limit hook return values to 3 to 5 properties (State + Status + Actions)'
+    directive: 'Structure hook returns into flat State, Status, and verb-prefixed Actions buckets'
   },
   CONTROLLER_VIEW_MISMATCH: {
     pillar: PILLARS.PILLAR_3,

package/cli/audit/rules.js

@@ -19,8 +19,9 @@ import {
   createExtendedVisitors
 } from './extended-visitors.js';
 import { createPatternVisitors, recordTemplatePatterns } from './pattern-detector.js';
+import { createHookShapeRegistry } from './hook-shape-validator.js';
 
-export { PILLARS, RULE_REGISTRY };
+export { PILLARS, RULE_REGISTRY, createHookShapeRegistry };
 
 export const auditCode = (content, filePath, relativePath, options = {}) => {
   const violations = [];
@@ -145,7 +146,8 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
   }
 
   const traverseFn = traverse.default || traverse;
-  const visitors = createAstVisitors({ relativePath, violations });
+  const hookRegistry = options.hookRegistry || createHookShapeRegistry();
+  const visitors = createAstVisitors({ relativePath, violations, hookRegistry });
   const slopVisitors = createAiSlopVisitors({ relativePath, violations });
   const extendedVisitors = createExtendedVisitors({ relativePath, violations });
   const patternVisitors = options.patternRegistry
@@ -169,5 +171,11 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
 
   traverseFn(ast, mergedVisitors);
 
+  const shouldRunLocalConsistency = !options.hookRegistry;
+  if (shouldRunLocalConsistency) {
+    const consistencyViolations = hookRegistry.validateCrossHookConsistency();
+    violations.push(...consistencyViolations);
+  }
+
   return violations;
 };