@chemx/starter-kit 26.10.8-344 → 26.10.10-75

package/cli/audit/ast-passes.js

@@ -0,0 +1,52 @@
+/**
+ * Babel visitor passes for script code (a plain module or an SFC script overlay).
+ * Parsing, with the per-block fallback for SFCs whose combined overlay does not
+ * parse, lives in cli/sfc/script-asts.js so Forge's standalone path reads the same trees.
+ */
+import traverse from '@babel/traverse';
+import { createAstVisitors } from './ast-visitors.js';
+import { createAiSlopVisitors } from './ai-slop-detector.js';
+import { createExtendedVisitors } from './extended-visitors.js';
+import { createPatternVisitors } from './pattern-detector.js';
+import { createHookShapeRegistry } from './hook-shape-validator.js';
+import { createJsxRenderDepthVisitor } from './render-depth.js';
+import { createFingerprintVisitors } from '../forge/fingerprint-visitors.js';
+
+export { parseScriptAsts } from '../sfc/script-asts.js';
+
+const traverseFn = traverse.default || traverse;
+
+const mergeVisitorSets = (visitorSets) => {
+  const merged = {};
+  for (const visitorSet of visitorSets) {
+    for (const [key, fn] of Object.entries(visitorSet)) {
+      const previous = merged[key];
+      merged[key] = previous ? (p, s) => { previous(p, s); fn(p, s); } : fn;
+    }
+  }
+  return merged;
+};
+
+/**
+ * Runs every AST visitor family over the parsed script ASTs. options.fingerprint (a Forge collector)
+ * fills its binding index in the same traverse and fingerprints each AST right after it; the legacy
+ * pattern visitors still run alongside until Forge replaces them.
+ */
+export const runAstPasses = (asts, { relativePath, violations, ruleConfig, options, code = '' }) => {
+  const hookRegistry = options.hookRegistry || createHookShapeRegistry();
+  const fingerprint = options.fingerprint || null;
+  for (const ast of asts) {
+    const visitorSets = [
+      createAstVisitors({ relativePath, violations, hookRegistry, config: ruleConfig }),
+      createAiSlopVisitors({ relativePath, violations }),
+      createExtendedVisitors({ relativePath, violations }),
+      createJsxRenderDepthVisitor({ relativePath, violations, config: ruleConfig }),
+      options.patternRegistry ? createPatternVisitors(options.patternRegistry, relativePath) : {},
+      fingerprint ? createFingerprintVisitors(fingerprint) : {}
+    ];
+    traverseFn(ast, mergeVisitorSets(visitorSets));
+    if (fingerprint) fingerprint.addScriptAst(ast, code);
+  }
+  const shouldRunLocalConsistency = !options.hookRegistry;
+  if (shouldRunLocalConsistency) violations.push(...hookRegistry.validateCrossHookConsistency());
+};

package/cli/audit/ast-visitors.js

@@ -1,22 +1,35 @@
 import * as t from '@babel/types';
 import { RULE_REGISTRY } from './rules-registry.js';
-import { countLogicalOperators } from './rules-helpers.js';
 import {
   isCustomHookFunction,
   resolveStartLine,
   isZeroDelayTimeout,
   isUnguardedConsoleCall,
   isSilentGuardClause,
-  isSwallowedCatch,
   countOptionalChainingDepth,
   isCombinatorCall,
-  isRawBooleanArg
+  isRawBooleanArg,
+  isGuardClause
 } from './rules-predicates.js';
+import { isSwallowedCatch } from './catch-predicates.js';
+import { resolveCatchEscalation, resolveCatchSpan } from './shallow-catch-escalation.js';
+import { isNamedCondition, countJunctionOperators, resolveIfChainLength } from './lexicon-predicates.js';
+import { narrowsMutableRef, MUTABLE_REF_REMEDY } from './mutable-ref-predicate.js';
+import { collectTeardowns, classifyTimerDisposal, isListenerDisposed } from './lifecycle-predicates.js';
 import { validateHookReturnShape } from './hook-shape-validator.js';
 import { evaluateComponentStructuralWeight } from './structural-weight-evaluator.js';
 
+const LOOKUP_CHAIN_MIN_BRANCHES = 3;
+const MAX_TEMPLATE_JUNCTIONS = 2;
+const TIMER_SEVERITY_BY_KIND = { setInterval: 'CRITICAL', setTimeout: 'LOW' };
+
 export const createAstVisitors = ({ relativePath, violations, hookRegistry, config }) => {
+  let teardowns = { clearedHandles: new Set(), removedListeners: [] };
   return {
+    Program(programPath) {
+      teardowns = collectTeardowns(programPath);
+    },
+
     Function(astPath) {
       evaluateComponentStructuralWeight({
         funcPath: astPath,
@@ -37,16 +50,19 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
       astPath.traverse({
         CallExpression(callPath) {
           const callee = callPath.node.callee;
-          if (t.isIdentifier(callee) && /^use[A-Z0-9]/.test(callee.name)) {
+          const isHookCall = t.isIdentifier(callee) && /^use[A-Z0-9]/.test(callee.name);
+          if (isHookCall) {
             const isExcluded = CONTROLLER_WRAPPER_EXCLUSIONS.has(callee.name);
-            if (!isExcluded && callPath.getFunctionParent() === astPath) {
+            const isOwnHookCall = !isExcluded && callPath.getFunctionParent() === astPath;
+            if (isOwnHookCall) {
               hookCount += 1;
             }
           }
         }
       });
 
-      if (hookCount > 5) {
+      const isHookSaturated = hookCount > 5;
+      if (isHookSaturated) {
         const line = astPath.node.loc?.start.line || 1;
         const meta = RULE_REGISTRY.HOOK_SATURATION;
         violations.push({
@@ -65,7 +81,8 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
       if (isCustomHook) {
         astPath.traverse({
           ReturnStatement(retPath) {
-            if (retPath.getFunctionParent() === astPath) {
+            const isOwnReturn = retPath.getFunctionParent() === astPath;
+            if (isOwnReturn) {
               validateHookReturnShape({
                 retPath,
                 astPath,
@@ -82,9 +99,11 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
     // Pillar 2: Control Flow Complexity
     JSXExpressionContainer(astPath) {
       const expr = astPath.node.expression;
-      if (t.isLogicalExpression(expr) || t.isUnaryExpression(expr)) {
-        const opCount = countLogicalOperators(expr);
-        if (opCount > 2) {
+      const isBooleanExpression = t.isLogicalExpression(expr) || t.isUnaryExpression(expr);
+      if (isBooleanExpression) {
+        const opCount = countJunctionOperators(expr);
+        const hasTooManyJunctions = opCount > MAX_TEMPLATE_JUNCTIONS;
+        if (hasTooManyJunctions) {
           const line = resolveStartLine(expr, astPath.node, 1);
           const meta = RULE_REGISTRY.CONTROL_FLOW_INLINE_BOOLEAN;
           violations.push({
@@ -103,24 +122,24 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
 
     IfStatement(astPath) {
       const expr = astPath.node.test;
-      if (t.isLogicalExpression(expr)) {
-        const opCount = countLogicalOperators(expr);
-        const hasBinaryClauses = (t.isBinaryExpression(expr.left) || t.isLogicalExpression(expr.left)) &&
-                                 (t.isBinaryExpression(expr.right) || t.isLogicalExpression(expr.right));
-        if (opCount > 2 || (opCount >= 2 && hasBinaryClauses)) {
-          const line = resolveStartLine(expr, astPath.node, 1);
-          const meta = RULE_REGISTRY.CONTROL_FLOW_INLINE_BOOLEAN;
-          violations.push({
-            filePath: relativePath,
-            line,
-            column: expr.loc?.start.column || 1,
-            hazard: `Inline multi-clause boolean comparison in if statement (${opCount} operators). Decompose into 2-stage booleans per Directive 3.A.`,
-            rule: 'CONTROL_FLOW_INLINE_BOOLEAN',
-            severity: meta.severity,
-            pillar: meta.pillar,
-            directive: meta.directive
-          });
-        }
+      const isLookupChain = resolveIfChainLength(astPath) >= LOOKUP_CHAIN_MIN_BRANCHES;
+      const isUnnamedTest = !isNamedCondition(expr);
+      const shouldFlagTest = isUnnamedTest && !isLookupChain;
+      if (shouldFlagTest) {
+        const line = resolveStartLine(expr, astPath.node, 1);
+        const meta = RULE_REGISTRY.CONTROL_FLOW_INLINE_BOOLEAN;
+        const isMutableNarrowing = narrowsMutableRef(astPath.get('test'), astPath.get('consequent'));
+        const remedy = isMutableNarrowing ? ` ${MUTABLE_REF_REMEDY}` : '';
+        violations.push({
+          filePath: relativePath,
+          line,
+          column: expr.loc?.start.column || 1,
+          hazard: `The if asks instead of reading a named condition. Name the question first (Directive 3.A).${remedy}`,
+          rule: 'CONTROL_FLOW_INLINE_BOOLEAN',
+          severity: countJunctionOperators(expr) > 0 ? meta.severity : 'LOW',
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
       }
 
       const silentGuard = isSilentGuardClause(astPath, t);
@@ -141,7 +160,10 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
     },
 
     ConditionalExpression(astPath) {
-      if (t.isConditionalExpression(astPath.node.consequent) || t.isConditionalExpression(astPath.node.alternate)) {
+      const isOutermostOfChain = !astPath.parentPath?.isConditionalExpression();
+      const hasNestedBranch = t.isConditionalExpression(astPath.node.consequent) || t.isConditionalExpression(astPath.node.alternate);
+      const isNestedTernaryRoot = hasNestedBranch && isOutermostOfChain;
+      if (isNestedTernaryRoot) {
         const line = astPath.node.loc?.start.line || 1;
         const meta = RULE_REGISTRY.CONTROL_FLOW_NESTED_TERNARY;
         violations.push({
@@ -159,18 +181,22 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
 
     SwitchStatement(astPath) {
       const cases = astPath.node.cases || [];
-      if (cases.length < 3) return;
+      const hasTooFewCases = cases.length < 3;
+      if (hasTooFewCases) return;
 
       const isDispatchConsequent = (statements) => {
-        if (!statements || statements.length === 0) return false;
-        if (statements.length === 1) {
+        const isEmptyConsequent = !statements || statements.length === 0;
+        if (isEmptyConsequent) return false;
+        const isSingleStatement = statements.length === 1;
+        if (isSingleStatement) {
           const s = statements[0];
           if (t.isReturnStatement(s)) return true;
           if (t.isBlockStatement(s)) {
             return s.body.length === 1 && t.isReturnStatement(s.body[0]);
           }
         }
-        if (statements.length === 2) {
+        const isStatementPair = statements.length === 2;
+        if (isStatementPair) {
           const [first, second] = statements;
           if (t.isBreakStatement(second)) {
             return t.isExpressionStatement(first) || t.isAssignmentExpression(first);
@@ -183,7 +209,8 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
       let nonDefaultCount = 0;
 
       for (const switchCase of cases) {
-        if (!switchCase.test) continue;
+        const isDefaultCase = !switchCase.test;
+        if (isDefaultCase) continue;
         nonDefaultCount += 1;
         if (isDispatchConsequent(switchCase.consequent)) {
           dispatchCaseCount += 1;
@@ -207,14 +234,62 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
       }
     },
 
+    BlockStatement(astPath) {
+      const body = astPath.node.body;
+      const hasTooFewStatements = !body || body.length < 3;
+      if (hasTooFewStatements) return;
+
+      let currentGuards = [];
+
+      // A cascade is 3+ bail-out guards followed by the action they protect (Directive 3.H);
+      // a run of guards that ends the block protects nothing and is not reported.
+      const flushCluster = (isFollowedByAction) => {
+        const hasCascade = isFollowedByAction && currentGuards.length >= 3;
+        if (hasCascade) {
+          const firstGuard = currentGuards[0];
+          const guardCount = currentGuards.length;
+          const line = firstGuard.loc?.start.line || 1;
+          const column = firstGuard.loc?.start.column || 1;
+          const meta = RULE_REGISTRY.CONTROL_FLOW_CASCADE_GUARDS;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column,
+            hazard: `Cascading guard clauses detected (${guardCount} guards >= 3 limit). Suggestion: Extract into a domain validator using ruleTree({ scope: { ... } }) with a 1-line callback return per Directive 3.H.`,
+            rule: 'CONTROL_FLOW_CASCADE_GUARDS',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+        currentGuards = [];
+      };
+
+      for (const stmt of body) {
+        const isGuard = isGuardClause(stmt, t);
+        if (isGuard) {
+          currentGuards.push(stmt);
+        } else if (t.isVariableDeclaration(stmt)) {
+          continue;
+        } else {
+          flushCluster(true);
+        }
+      }
+      flushCluster(false);
+    },
+
     // Pillar 5: Design System & Inline Styles
     JSXAttribute(astPath) {
       const attrName = astPath.node.name?.name;
-      if (attrName === 'style') {
+      const isStyleAttr = attrName === 'style';
+      const isClassAttr = attrName === 'className' || attrName === 'class';
+      if (isStyleAttr) {
         const value = astPath.node.value;
-        if (t.isJSXExpressionContainer(value) && t.isObjectExpression(value.expression)) {
+        const isObjectStyle = t.isJSXExpressionContainer(value) && t.isObjectExpression(value.expression);
+        if (isObjectStyle) {
           const preferTokens = config?.preferDesignTokens || 'warning';
-          if (preferTokens !== 'off') {
+          const isTokenCheckEnabled = preferTokens !== 'off';
+          if (isTokenCheckEnabled) {
             const line = astPath.node.loc?.start.line || 1;
             const meta = RULE_REGISTRY.RAW_INLINE_STYLE;
             const severity = preferTokens === 'error' ? 'HIGH' : meta.severity;
@@ -230,11 +305,13 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
             });
           }
         }
-      } else if (attrName === 'className' || attrName === 'class') {
+      } else if (isClassAttr) {
         const value = astPath.node.value;
         const strVal = t.isStringLiteral(value) ? value.value : '';
-        if (strVal && (strVal.includes('fa-') || strVal.includes('fa '))) {
-          if (/\btext-(primary|secondary|danger|warning|success|info|light|dark|\w+)\b/.test(strVal)) {
+        const hasFontAwesomeClass = Boolean(strVal && (strVal.includes('fa-') || strVal.includes('fa ')));
+        if (hasFontAwesomeClass) {
+          const hasTextColorClass = /\btext-(primary|secondary|danger|warning|success|info|light|dark|\w+)\b/.test(strVal);
+          if (hasTextColorClass) {
             const line = astPath.node.loc?.start.line || 1;
             const meta = RULE_REGISTRY.ICON_SVG_STYLE_LEAK;
             violations.push({
@@ -257,7 +334,8 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
       const callee = astPath.node.callee;
 
       // Timer Discipline
-      if (t.isIdentifier(callee) && (callee.name === 'setInterval' || callee.name === 'setTimeout')) {
+      const isTimerCall = t.isIdentifier(callee) && (callee.name === 'setInterval' || callee.name === 'setTimeout');
+      if (isTimerCall) {
         const args = astPath.node.arguments;
         const delayArg = args[1];
 
@@ -277,28 +355,19 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
           });
         }
 
-        const fnParent = astPath.getFunctionParent();
-        let hasCleanup = false;
-        if (fnParent) {
-          fnParent.traverse({
-            ReturnStatement(retPath) {
-              if (retPath.node.argument) {
-                hasCleanup = true;
-              }
-            }
-          });
-        }
-
-        if (!hasCleanup) {
+        const disposal = classifyTimerDisposal(astPath, teardowns);
+        const isUndisposed = disposal === 'held' || disposal === 'unheld';
+        if (isUndisposed) {
           const line = astPath.node.loc?.start.line || 1;
           const meta = RULE_REGISTRY.TIMER_DISCIPLINE;
+          const clearName = callee.name === 'setInterval' ? 'clearInterval' : 'clearTimeout';
           violations.push({
             filePath: relativePath,
             line,
             column: astPath.node.loc?.start.column || 1,
-            hazard: `Raw ${callee.name} lacking lifecycle scope disposal`,
+            hazard: `Raw ${callee.name} with no ${clearName} for its handle anywhere in this module (Directive 6.C)`,
             rule: 'TIMER_DISCIPLINE',
-            severity: meta.severity,
+            severity: TIMER_SEVERITY_BY_KIND[callee.name] || meta.severity,
             pillar: meta.pillar,
             directive: meta.directive
           });
@@ -322,24 +391,9 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
       }
 
       // Pillar 6: Orphaned Event Listener
-      if (t.isMemberExpression(callee) && t.isIdentifier(callee.property, { name: 'addEventListener' })) {
-        const fnParent = astPath.getFunctionParent();
-        let hasCleanup = false;
-        if (fnParent) {
-          const fnName = fnParent.node.id?.name || '';
-          if (fnName === 'listen') {
-            hasCleanup = true;
-          } else {
-            fnParent.traverse({
-              CallExpression(innerCall) {
-                const innerCallee = innerCall.node.callee;
-                if (t.isMemberExpression(innerCallee) && t.isIdentifier(innerCallee.property, { name: 'removeEventListener' })) {
-                  hasCleanup = true;
-                }
-              }
-            });
-          }
-        }
+      const isAddListenerCall = t.isMemberExpression(callee) && t.isIdentifier(callee.property, { name: 'addEventListener' });
+      if (isAddListenerCall) {
+        const hasCleanup = isListenerDisposed(astPath, teardowns);
         if (!hasCleanup) {
           const line = astPath.node.loc?.start.line || 1;
           const meta = RULE_REGISTRY.LIFECYCLE_ORPHANED_LISTENER;
@@ -378,16 +432,18 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
 
     // Pillar 2: Swallowed Exceptions
     CatchClause(astPath) {
-      if (isSwallowedCatch(astPath, t)) {
-        const line = astPath.node.loc?.start.line || 1;
+      if (isSwallowedCatch(astPath)) {
         const meta = RULE_REGISTRY.ERROR_SWALLOWED_EXCEPTION;
+        const { severity, binding } = resolveCatchEscalation(astPath);
+        const finding = binding
+          ? `Swallowed exception leaves "${binding}" unset; it is read after the try (silent undefined propagation)`
+          : 'Swallowed exception in catch block without active handling, logging, or ResultTuple';
         violations.push({
           filePath: relativePath,
-          line,
-          column: astPath.node.loc?.start.column || 1,
-          hazard: 'Swallowed exception in catch block without active handling, logging, or ResultTuple',
+          ...resolveCatchSpan(astPath),
+          hazard: `${finding}. Annotate intentional cases with // chemx-allow: best-effort <reason>`,
           rule: 'ERROR_SWALLOWED_EXCEPTION',
-          severity: meta.severity,
+          severity,
           pillar: meta.pillar,
           directive: meta.directive
         });
@@ -399,7 +455,8 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
       const isParentOptional = t.isOptionalMemberExpression(astPath.parent) || t.isOptionalCallExpression(astPath.parent);
       if (!isParentOptional) {
         const depth = countOptionalChainingDepth(astPath.node, t);
-        if (depth >= 3) {
+        const isDeepChain = depth >= 3;
+        if (isDeepChain) {
           const line = astPath.node.loc?.start.line || 1;
           const meta = RULE_REGISTRY.DATA_FLOW_OPTIONAL_CHAINING_CHURN;
           violations.push({
@@ -418,8 +475,10 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
 
     // Pillar 4: Type Co-location
     TSTypeLiteral(astPath) {
-      if (astPath.node.members.length > 3) {
-        if (!astPath.findParent((p) => p.isTSTypeAliasDeclaration() || p.isTSInterfaceDeclaration())) {
+      const isLargeLiteral = astPath.node.members.length > 3;
+      if (isLargeLiteral) {
+        const isInlinedType = !astPath.findParent((p) => p.isTSTypeAliasDeclaration() || p.isTSInterfaceDeclaration());
+        if (isInlinedType) {
           const line = astPath.node.loc?.start.line || 1;
           const meta = RULE_REGISTRY.TYPE_COLOCATION;
           violations.push({

package/cli/audit/audit-plain.js

@@ -0,0 +1,26 @@
+// Plain-text audit card for pipes, CI logs and agents: the facts of the dashboard banner
+// without ASCII art, borders or color. Input is buildAuditSummary() output.
+
+const formatGate = (gate) => {
+  const isUnknown = gate.passing === null;
+  if (isUnknown) return 'gate: not evaluated';
+  const verdict = gate.passing ? 'pass' : 'fail';
+  const basis = gate.basis ? ` (${gate.basis})` : '';
+  const note = gate.note ? `: ${gate.note}` : '';
+  return `gate: ${verdict}${basis}${note}`;
+};
+
+export const formatPlainAuditSummary = (summary) => {
+  const { critical, highMedium, low } = summary.hazards;
+  const total = critical + highMedium + low;
+  const lines = [
+    `chemx audit ${summary.scope}: grade ${summary.health.grade} (${summary.health.score}/100), ${total} hazards: ${critical} critical, ${highMedium} high/medium, ${low} low`,
+    `${summary.files} files, ${summary.loc.toLocaleString('en-US')} LOC, ~${summary.tokens.estimate.toLocaleString('en-US')} tokens`,
+    formatGate(summary.gate)
+  ];
+  for (const { rule, baseline, current } of summary.gate.regressions ?? []) {
+    lines.push(`  regression: ${rule} ${baseline} -> ${current}`);
+  }
+  lines.push('detail: chemx audit --json | chemx audit --unroll | chemx q --hazards');
+  return `${lines.join('\n')}\n`;
+};

package/cli/audit/audit-summary.js

@@ -1,4 +1,4 @@
-import { resolveProjectName, resolveCostFigures } from '../navigator-banner-helpers.js';
+import { resolveProjectName, resolveCostFigures } from './project-figures.js';
 
 const countHazards = (violations = []) => {
   const counts = { critical: 0, highMedium: 0, low: 0 };
@@ -12,6 +12,12 @@ const countHazards = (violations = []) => {
   return counts;
 };
 
+const summarizeCoverageForCard = (coverage) => {
+  if (!coverage) return null;
+  const { files, astPct, parseErrors, textOnly, isPartial, sfc } = coverage;
+  return { files, astPct, parseErrors, textOnly, isPartial, sfcTemplates: sfc?.templatesParsed ?? 0 };
+};
+
 export const buildAuditSummary = (report, { projectRoot, scope }) => {
   const gate = report.gate ?? {};
   const summary = {
@@ -20,11 +26,18 @@ export const buildAuditSummary = (report, { projectRoot, scope }) => {
     files: report.metrics?.scannedFiles ?? 0,
     loc: report.metrics?.totalLoc ?? 0,
     tokens: { estimate: report.contextAnalysis?.estimatedTokens ?? 0, savingsPct: report.contextAnalysis?.potentialSavingsPct ?? 0 },
-    health: { score: report.health.score, grade: report.health.grade, label: report.health.label ?? null },
+    health: { score: report.health.score, grade: report.health.grade, label: report.health.label ?? null, density: report.health.density ?? null, scoreModel: report.health.scoreModel ?? null },
     aiSlop: { score: report.aiSlop?.score ?? 100, grade: report.aiSlop?.grade ?? 'A+' },
     hazards: countHazards(report.violations),
     cost: resolveCostFigures(report.contextAnalysis),
-    gate: { passing: gate.isPassing ?? null, basis: gate.basis ?? null, regressions: (gate.regressions ?? []).slice(0, 5), note: gate.note ?? null }
+    gate: {
+      passing: gate.isPassing ?? null,
+      basis: gate.basis ?? null,
+      regressions: (gate.regressions ?? []).slice(0, 5),
+      adopted: (gate.adopted ?? []).map((a) => a.rule),
+      note: gate.note ?? null
+    },
+    coverage: summarizeCoverageForCard(report.coverage)
   };
   return report.rebaseline ? { ...summary, rebaseline: report.rebaseline } : summary;
 };

package/cli/audit/autofix-content.js

@@ -0,0 +1,122 @@
+/**
+ * Token-aware mechanical fixes for one file's content.
+ *
+ * Only comments are edited, located by a real tokenizer (see comment-ranges.js): string
+ * literals, template literals, JSX text and Vue/Svelte templates are never touched. A comment
+ * flagged as AI residue is removed whole (never just its first line). Leaked Markdown fences
+ * are removed only as the first/last non-blank line of a JS/TS file, and only when the result
+ * parses (a fence pair can parse as tagged templates, so the original is not required to fail). setTimeout(fn, 0) is reported as a suggestion, never rewritten.
+ */
+import { findSourceRanges } from '../comment-ranges.js';
+import { parseSource, langForPath } from '../source-parse.js';
+import { lineOfIndex } from '../literal-replace.js';
+
+const RESIDUE_PATTERNS = [
+  ['hope this', 'helps'].join(' '),
+  ['feel free', 'to tweak'].join(' '),
+  ['let me know', 'if you need'].join(' '),
+  ['as an ai', 'language model'].join(' ')
+];
+const RESIDUE_REGEX = new RegExp(`\\b(?:${RESIDUE_PATTERNS.join('|')})\\b`, 'i');
+const PREAMBLE_REGEX = /\b(?:here(?:'s| is) the (?:complete|updated|refactored|full) (?:code|implementation|file|component|version))\b/i;
+const TRUNCATION_REGEX = /^(?:\/\/|\/\*)\s*\.\.\.\s*(?:existing|rest of|remaining)\s+(?:code|implementation|logic|imports)/i;
+const FENCE_LINE_REGEX = /^\s*```(?:typescript|javascript|tsx|jsx|vue|js|ts|html|css|scss)?\s*$/;
+const TIMER_REGEX = /setTimeout\([^,]+,\s*0\)/g;
+const EM_DASH = String.fromCharCode(0x2014);
+
+const insideAny = (ranges, index) => ranges.some((r) => index >= r.start && index < r.end);
+
+const stripEdgeFences = (content, filePath, fixes) => {
+  const isScript = Boolean(langForPath(filePath));
+  if (!isScript) return content;
+  const lines = content.split('\n');
+  const nonBlank = lines.map((l, i) => (l.trim() ? i : -1)).filter((i) => i >= 0);
+  const edges = [nonBlank[0], nonBlank[nonBlank.length - 1]].filter((i) => i !== undefined && FENCE_LINE_REGEX.test(lines[i]));
+  const fenceLines = [...new Set(edges)];
+  const candidate = lines.filter((_, i) => !fenceLines.includes(i)).join('\n');
+  const isRepaired = fenceLines.length > 0 && parseSource(candidate, filePath).ok;
+  if (!isRepaired) return content;
+  fenceLines.forEach((i) => fixes.push({ line: i + 1, rule: 'AI_SLOP_CONVERSATIONAL_ARTIFACT', action: 'Removed leaked markdown code fence' }));
+  return candidate;
+};
+
+const wholeCommentSpan = (content, comment) => {
+  const lineStart = content.lastIndexOf('\n', comment.start - 1) + 1;
+  const nextNewline = content.indexOf('\n', comment.end);
+  const lineEnd = nextNewline === -1 ? content.length : nextNewline;
+  const isAloneOnLines = content.slice(lineStart, comment.start).trim() === '' && content.slice(comment.end, lineEnd).trim() === '';
+  const isLastLine = nextNewline === -1;
+  const lineSpanStart = isLastLine && lineStart > 0 ? lineStart - 1 : lineStart;
+  if (isAloneOnLines) return { start: lineSpanStart, end: isLastLine ? lineEnd : lineEnd + 1 };
+  let start = comment.start;
+  while (start > lineStart && /[ \t]/.test(content[start - 1])) start--;
+  return { start, end: comment.end };
+};
+
+const classifyComment = (text, shouldFix) => {
+  const isResidue = PREAMBLE_REGEX.test(text) || RESIDUE_REGEX.test(text);
+  const shouldRemoveResidue = isResidue && shouldFix('AI_SLOP_CONVERSATIONAL_ARTIFACT');
+  if (shouldRemoveResidue) return { rule: 'AI_SLOP_CONVERSATIONAL_ARTIFACT', action: 'Removed AI conversational residue comment' };
+  const isPlaceholder = TRUNCATION_REGEX.test(text.trim());
+  const shouldRemovePlaceholder = isPlaceholder && shouldFix('AI_SLOP_LAZY_PLACEHOLDER');
+  if (shouldRemovePlaceholder) return { rule: 'AI_SLOP_LAZY_PLACEHOLDER', action: 'Removed lazy AI truncation placeholder comment' };
+  return null;
+};
+
+const commentEdits = (content, ranges, shouldFix, fixes) => {
+  const edits = [];
+  for (const comment of [...ranges.comments].sort((a, b) => a.start - b.start)) {
+    const text = content.slice(comment.start, comment.end);
+    const removal = classifyComment(text, shouldFix);
+    const isRemoved = Boolean(removal);
+    if (isRemoved) {
+      edits.push({ ...wholeCommentSpan(content, comment), text: '' });
+      fixes.push({ line: lineOfIndex(content, comment.start), ...removal });
+      continue;
+    }
+    const hasEmDash = text.includes(EM_DASH) && shouldFix('TYPOGRAPHY_EM_DASH');
+    if (!hasEmDash) continue;
+    edits.push({ start: comment.start, end: comment.end, text: text.split(EM_DASH).join('-') });
+    const dashLines = new Set([...text.matchAll(new RegExp(EM_DASH, 'g'))].map((m) => lineOfIndex(content, comment.start + m.index)));
+    dashLines.forEach((line) => fixes.push({ line, rule: 'TYPOGRAPHY_EM_DASH', action: 'Replaced em dash with standard hyphen in a comment' }));
+  }
+  return edits;
+};
+
+const timerSuggestions = (content, ranges, shouldFix) => {
+  const isTimerRuleOn = shouldFix('MACRO_TASK_OVER_MICRO_TASK');
+  if (!isTimerRuleOn) return [];
+  const skip = [...ranges.comments, ...ranges.literals];
+  return [...content.matchAll(TIMER_REGEX)]
+    .filter((m) => insideAny(ranges.codeRegions, m.index) && !insideAny(skip, m.index))
+    .map((m) => ({
+      line: lineOfIndex(content, m.index),
+      rule: 'MACRO_TASK_OVER_MICRO_TASK',
+      suggestion: 'Consider queueMicrotask(fn) if the timer id is never cleared (not applied: queueMicrotask returns undefined, so clearTimeout(id) would stop working).'
+    }));
+};
+
+/**
+ * @param {string} content File content.
+ * @param {object} [options] { filePath = 'file.ts', rules }
+ * @returns {{ fixedContent: string, fixes: object[], suggestions: object[], skipped: string|null }}
+ */
+export const autofixContent = (content, options = {}) => {
+  const filePath = options.filePath || 'file.ts';
+  const allowedRules = options.rules ? new Set(options.rules) : null;
+  const shouldFix = (rule) => !allowedRules || allowedRules.has(rule);
+  const fixes = [];
+
+  const fenceShouldRun = shouldFix('AI_SLOP_CONVERSATIONAL_ARTIFACT');
+  const base = fenceShouldRun ? stripEdgeFences(content, filePath, fixes) : content;
+  const ranges = findSourceRanges(base, filePath);
+  const isTokenized = Boolean(ranges);
+  if (!isTokenized) return { fixedContent: base, fixes, suggestions: [], skipped: 'no tokenizer for this file type, or it does not parse' };
+
+  const edits = commentEdits(base, ranges, shouldFix, fixes);
+  let fixedContent = base;
+  for (const edit of edits.sort((a, b) => b.start - a.start)) {
+    fixedContent = fixedContent.slice(0, edit.start) + edit.text + fixedContent.slice(edit.end);
+  }
+  return { fixedContent, fixes, suggestions: timerSuggestions(base, ranges, shouldFix), skipped: null };
+};