@chemx/starter-kit 26.10.4-235 → 26.10.8-344

package/cli/audit/ast-visitors.js

@@ -5,7 +5,12 @@ import {
   isCustomHookFunction,
   resolveStartLine,
   isZeroDelayTimeout,
-  isUnguardedConsoleCall
+  isUnguardedConsoleCall,
+  isSilentGuardClause,
+  isSwallowedCatch,
+  countOptionalChainingDepth,
+  isCombinatorCall,
+  isRawBooleanArg
 } from './rules-predicates.js';
 import { validateHookReturnShape } from './hook-shape-validator.js';
 import { evaluateComponentStructuralWeight } from './structural-weight-evaluator.js';
@@ -117,6 +122,22 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
           });
         }
       }
+
+      const silentGuard = isSilentGuardClause(astPath, t);
+      if (silentGuard) {
+        const line = astPath.node.loc?.start.line || 1;
+        const meta = RULE_REGISTRY.CONTROL_FLOW_SILENT_GUARD;
+        violations.push({
+          filePath: relativePath,
+          line,
+          column: astPath.node.loc?.start.column || 1,
+          hazard: `Silent guard abort detected in ${silentGuard.funcName}: bare return; swallows error condition without logging or error state. Return [null, error] or emit diagnostic per Directive 3.G.`,
+          rule: 'CONTROL_FLOW_SILENT_GUARD',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      }
     },
 
     ConditionalExpression(astPath) {
@@ -299,6 +320,100 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
           directive: meta.directive
         });
       }
+
+      // 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;
+                }
+              }
+            });
+          }
+        }
+        if (!hasCleanup) {
+          const line = astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.LIFECYCLE_ORPHANED_LISTENER;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: astPath.node.loc?.start.column || 1,
+            hazard: 'Raw addEventListener call lacking lifecycle disposer or removeEventListener teardown',
+            rule: 'LIFECYCLE_ORPHANED_LISTENER',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
+
+      // Pillar 2: Combinator Raw Boolean Arguments
+      if (isCombinatorCall(callee, t)) {
+        const hasRawArg = astPath.node.arguments.some((arg) => isRawBooleanArg(arg, t));
+        if (hasRawArg) {
+          const line = astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.COMBINATOR_RAW_BOOLEAN;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: astPath.node.loc?.start.column || 1,
+            hazard: `Raw boolean expression passed to ${callee.name}(). Decompose into named predicate or thunk.`,
+            rule: 'COMBINATOR_RAW_BOOLEAN',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
+    },
+
+    // Pillar 2: Swallowed Exceptions
+    CatchClause(astPath) {
+      if (isSwallowedCatch(astPath, t)) {
+        const line = astPath.node.loc?.start.line || 1;
+        const meta = RULE_REGISTRY.ERROR_SWALLOWED_EXCEPTION;
+        violations.push({
+          filePath: relativePath,
+          line,
+          column: astPath.node.loc?.start.column || 1,
+          hazard: 'Swallowed exception in catch block without active handling, logging, or ResultTuple',
+          rule: 'ERROR_SWALLOWED_EXCEPTION',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      }
+    },
+
+    // Pillar 4: Deep Optional Chaining Churn
+    OptionalMemberExpression(astPath) {
+      const isParentOptional = t.isOptionalMemberExpression(astPath.parent) || t.isOptionalCallExpression(astPath.parent);
+      if (!isParentOptional) {
+        const depth = countOptionalChainingDepth(astPath.node, t);
+        if (depth >= 3) {
+          const line = astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.DATA_FLOW_OPTIONAL_CHAINING_CHURN;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: astPath.node.loc?.start.column || 1,
+            hazard: `Deep optional chaining churn (${depth} chained operators >= 3 limit). Level data shapes line 1.`,
+            rule: 'DATA_FLOW_OPTIONAL_CHAINING_CHURN',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
     },
 
     // Pillar 4: Type Co-location

package/cli/audit/audit-summary.js

@@ -0,0 +1,30 @@
+import { resolveProjectName, resolveCostFigures } from '../navigator-banner-helpers.js';
+
+const countHazards = (violations = []) => {
+  const counts = { critical: 0, highMedium: 0, low: 0 };
+  for (const v of violations) {
+    const isCritical = v.severity === 'CRITICAL';
+    const isHighOrMedium = v.severity === 'HIGH' || v.severity === 'MEDIUM';
+    if (isCritical) counts.critical += 1;
+    else if (isHighOrMedium) counts.highMedium += 1;
+    else counts.low += 1;
+  }
+  return counts;
+};
+
+export const buildAuditSummary = (report, { projectRoot, scope }) => {
+  const gate = report.gate ?? {};
+  const summary = {
+    project: resolveProjectName(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 },
+    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 }
+  };
+  return report.rebaseline ? { ...summary, rebaseline: report.rebaseline } : summary;
+};

package/cli/audit/gate-verdict.js

@@ -0,0 +1,30 @@
+import { readRatchet, evaluateRatchet } from './ratchet.js';
+
+const RATCHET_STATUSES = new Set(['pass', 'fail', 'invalid']);
+
+const isSevereViolation = (v) => v.severity === 'CRITICAL' || v.severity === 'HIGH';
+
+export const evaluateGateVerdict = ({ violations, ratchetEval }) => {
+  const isRatchetBasis = RATCHET_STATUSES.has(ratchetEval.status);
+  if (isRatchetBasis) {
+    return {
+      isPassing: ratchetEval.status === 'pass',
+      basis: 'ratchet',
+      regressions: ratchetEval.regressions,
+      note: ratchetEval.message ?? null
+    };
+  }
+  const hasSevereViolation = violations.some(isSevereViolation);
+  return { isPassing: !hasSevereViolation, basis: 'severity', regressions: [], note: ratchetEval.message ?? null };
+};
+
+const PARTIAL_SCAN_EVAL = {
+  status: 'partial',
+  regressions: [],
+  message: 'Partial scan (--git, --changed, or --fast): the ratchet applies to full scans only; using severity gate.'
+};
+
+export const computeGateVerdict = ({ projectRoot, scope, violations, isPartialScan = false }) => {
+  const ratchetEval = isPartialScan ? PARTIAL_SCAN_EVAL : evaluateRatchet(readRatchet(projectRoot), { scope, violations });
+  return evaluateGateVerdict({ violations, ratchetEval });
+};

package/cli/audit/history.js

@@ -11,10 +11,43 @@ const GREEN = '\x1b[32m';
 const YELLOW = '\x1b[33m';
 const RED = '\x1b[31m';
 
+export const findChemxDir = (startDir = process.cwd()) => {
+  const hasCustomRoot = Boolean(process.env.CHEMX_PROJECT_ROOT);
+  if (hasCustomRoot) {
+    return path.resolve(process.env.CHEMX_PROJECT_ROOT, '.chemx');
+  }
+
+  let current = path.resolve(startDir);
+  let gitRoot = null;
+  while (true) {
+    const candidate = path.join(current, '.chemx');
+    const hasExistingChemx = fs.existsSync(candidate);
+    if (hasExistingChemx) {
+      return candidate;
+    }
+    const hasGit = !gitRoot && fs.existsSync(path.join(current, '.git'));
+    if (hasGit) {
+      gitRoot = current;
+    }
+    const parent = path.dirname(current);
+    const isRootReached = parent === current;
+    if (isRootReached) break;
+    current = parent;
+  }
+
+  const hasDiscoveredGitRoot = Boolean(gitRoot);
+  if (hasDiscoveredGitRoot) {
+    return path.join(gitRoot, '.chemx');
+  }
+
+  return path.resolve(startDir, '.chemx');
+};
+
 export const ensureChemxDir = (cwd = process.cwd()) => {
-  const dir = path.resolve(cwd, '.chemx');
+  const dir = findChemxDir(cwd);
   try {
-    if (!fs.existsSync(dir)) {
+    const isDirMissing = !fs.existsSync(dir);
+    if (isDirMissing) {
       fs.mkdirSync(dir, { recursive: true });
     }
   } catch {
@@ -22,17 +55,21 @@ export const ensureChemxDir = (cwd = process.cwd()) => {
   }
 
   // Ensure .chemx is gitignored if git repo exists
-  const gitDir = path.resolve(cwd, '.git');
-  if (fs.existsSync(gitDir)) {
-    const gitignorePath = path.resolve(cwd, '.gitignore');
+  const targetParent = path.dirname(dir);
+  const gitDir = path.resolve(targetParent, '.git');
+  const hasGit = fs.existsSync(gitDir);
+  if (hasGit) {
+    const gitignorePath = path.resolve(targetParent, '.gitignore');
     try {
-      let content = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf-8') : '';
-      if (!content.includes('.chemx')) {
-        const trailingNewline = content.endsWith('\n') || content.length === 0 ? '' : '\n';
+      const hasGitignore = fs.existsSync(gitignorePath);
+      let content = hasGitignore ? fs.readFileSync(gitignorePath, 'utf-8') : '';
+      const hasChemxEntry = content.includes('.chemx');
+      if (!hasChemxEntry) {
+        const hasTrailingNewline = content.endsWith('\n') || content.length === 0;
+        const trailingNewline = hasTrailingNewline ? '' : '\n';
         fs.appendFileSync(gitignorePath, `${trailingNewline}# Chemical X local telemetry & audit history\n.chemx/\n`, 'utf-8');
       }
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
+    } catch {
       return dir;
     }
   }

package/cli/audit/ratchet.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const RATCHET_FILE = 'chemx-ratchet.json';
+const RATCHET_VERSION = 1;
+
+export const countViolationsByRule = (violations = []) => {
+  const counts = {};
+  for (const v of violations) counts[v.rule] = (counts[v.rule] ?? 0) + 1;
+  return counts;
+};
+
+const sortKeys = (record) => Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+
+const isRatchetShape = (value) => {
+  const isObject = value !== null && typeof value === 'object';
+  return isObject && typeof value.scope === 'string' && typeof value.rules === 'object' && value.rules !== null;
+};
+
+export const readRatchet = (projectRoot) => {
+  const file = path.join(projectRoot, RATCHET_FILE);
+  const isMissing = !fs.existsSync(file);
+  if (isMissing) return { status: 'absent' };
+  try {
+    const ratchet = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    const isValid = isRatchetShape(ratchet);
+    if (isValid) return { status: 'ok', ratchet };
+    return { status: 'invalid', message: `${RATCHET_FILE} is missing "scope" or "rules".` };
+  } catch (err) {
+    return { status: 'invalid', message: `${RATCHET_FILE} is not valid JSON: ${err.message}` };
+  }
+};
+
+export const writeRatchet = (projectRoot, { scope, violations }) => {
+  const ratchet = { version: RATCHET_VERSION, scope, rules: sortKeys(countViolationsByRule(violations)) };
+  fs.writeFileSync(path.join(projectRoot, RATCHET_FILE), JSON.stringify(ratchet, null, 2) + '\n', 'utf-8');
+  return ratchet;
+};
+
+const findRegressions = (rules, violations) => {
+  const current = countViolationsByRule(violations);
+  return Object.entries(current)
+    .map(([rule, count]) => ({ rule, baseline: rules[rule] ?? 0, current: count }))
+    .filter((r) => r.current > r.baseline)
+    .sort((a, b) => a.rule.localeCompare(b.rule));
+};
+
+export const evaluateRatchet = (readResult, { scope, violations }) => {
+  const isUnusable = readResult.status !== 'ok';
+  if (isUnusable) return { status: readResult.status, regressions: [], message: readResult.message ?? null };
+
+  const recordedScope = readResult.ratchet.scope;
+  const isScopeMismatch = recordedScope !== scope;
+  if (isScopeMismatch) {
+    return {
+      status: 'scope-mismatch',
+      regressions: [],
+      message: `${RATCHET_FILE} was recorded for scope "${recordedScope}", not "${scope}"; using severity gate.`
+    };
+  }
+  const regressions = findRegressions(readResult.ratchet.rules, violations);
+  const hasRegressions = regressions.length > 0;
+  return { status: hasRegressions ? 'fail' : 'pass', regressions, message: null };
+};

package/cli/audit/rules-predicates.js

@@ -138,3 +138,203 @@ export const isNonInteractiveSession = (rawArgs, env = process.env) => {
   const isNotTTY = Boolean(process.stdout && process.stdout.isTTY === false);
   return [hasCliFlag, hasOutputFlag, hasFormatFlag, hasCiEnv, isNotTTY].some(Boolean);
 };
+
+const EXEMPT_TEST_PATTERNS = [
+  /abort/i,
+  /signal/i,
+  /mounted/i,
+  /unmount/i,
+  /destroy/i,
+  /cleanup/i,
+  /timer/i,
+  /timeout/i,
+  /interval/i,
+  /debounce/i,
+  /throttle/i,
+  /\bon[A-Z]/,
+  /\bcall(?:back|backFn)?\b/i,
+  /\bcb\b/i,
+  /\bhandler\b/i
+];
+
+const MUTATING_FUNCTION_PATTERNS = [
+  /^handle[A-Z]/,
+  /^on[A-Z]/,
+  /^(?:save|update|delete|remove|create|add|insert|post|send|process|submit|dispatch|execute|mutate|checkout|charge|sync|write)/i
+];
+
+const PURE_PREDICATE_PATTERNS = [
+  /^(?:is|has|can|should|check)[A-Z]/
+];
+
+const isDiagnosticOrErrorStatement = (stmt, t) => {
+  if (t.isThrowStatement(stmt)) return true;
+  if (t.isExpressionStatement(stmt)) {
+    const expr = stmt.expression;
+    if (t.isCallExpression(expr)) {
+      const callee = expr.callee;
+      if (t.isMemberExpression(callee)) {
+        const objName = t.isIdentifier(callee.object) ? callee.object.name : '';
+        const propName = t.isIdentifier(callee.property) ? callee.property.name : '';
+        if (['console', 'logger', 'log'].includes(objName)) return true;
+        if (/^(?:error|warn|info|trace|notify|alert)/i.test(propName)) return true;
+      }
+      if (t.isIdentifier(callee) && /^(?:report|notify|alert|set.*Error|handleError)/i.test(callee.name)) return true;
+    }
+    if (t.isAssignmentExpression(expr)) {
+      const left = expr.left;
+      if (t.isMemberExpression(left) && t.isIdentifier(left.property) && /error/i.test(left.property.name)) return true;
+      if (t.isIdentifier(left) && /error/i.test(left.name)) return true;
+    }
+  }
+  return false;
+};
+
+export const isSilentGuardClause = (ifPath, t) => {
+  const node = ifPath.node;
+  if (!node || node.alternate) return false;
+
+  let hasBareReturn = false;
+  let hasDiagnosticOrHandling = false;
+
+  const checkStatement = (stmt) => {
+    if (t.isReturnStatement(stmt)) {
+      const isBare = !stmt.argument || (t.isIdentifier(stmt.argument) && stmt.argument.name === 'undefined');
+      if (isBare) hasBareReturn = true;
+    } else if (isDiagnosticOrErrorStatement(stmt, t)) {
+      hasDiagnosticOrHandling = true;
+    }
+  };
+
+  if (t.isReturnStatement(node.consequent)) {
+    checkStatement(node.consequent);
+  } else if (t.isBlockStatement(node.consequent)) {
+    for (const stmt of node.consequent.body) {
+      checkStatement(stmt);
+    }
+  }
+
+  if (!hasBareReturn || hasDiagnosticOrHandling) return false;
+
+  const collectTestIdentifiers = (n) => {
+    const names = [];
+    const walk = (item) => {
+      if (!item) return;
+      if (t.isIdentifier(item)) {
+        names.push(item.name);
+      } else if (t.isMemberExpression(item)) {
+        walk(item.object);
+        walk(item.property);
+      } else if (t.isUnaryExpression(item)) {
+        walk(item.argument);
+      } else if (t.isLogicalExpression(item) || t.isBinaryExpression(item)) {
+        walk(item.left);
+        walk(item.right);
+      } else if (t.isCallExpression(item)) {
+        walk(item.callee);
+        for (const arg of item.arguments) walk(arg);
+      }
+    };
+    walk(n);
+    return names;
+  };
+
+  const testIdentifiers = collectTestIdentifiers(node.test);
+  const isExemptTest = testIdentifiers.some((name) => EXEMPT_TEST_PATTERNS.some((pat) => pat.test(name)));
+  if (isExemptTest) return false;
+
+  const funcParent = ifPath.getFunctionParent();
+  if (!funcParent) return false;
+
+  let funcName = '';
+  if (funcParent.node.id?.name) {
+    funcName = funcParent.node.id.name;
+  } else if (funcParent.parentPath?.isVariableDeclarator() && t.isIdentifier(funcParent.parentPath.node.id)) {
+    funcName = funcParent.parentPath.node.id.name;
+  } else if (t.isIdentifier(funcParent.node.key)) {
+    funcName = funcParent.node.key.name;
+  }
+
+  const isAsync = Boolean(funcParent.node.async);
+  const isMutatingName = MUTATING_FUNCTION_PATTERNS.some((pat) => pat.test(funcName));
+  const isPurePredicate = PURE_PREDICATE_PATTERNS.some((pat) => pat.test(funcName));
+
+  if (isPurePredicate && !isAsync && !isMutatingName) return false;
+
+  const isTargetFunction = isAsync || isMutatingName;
+  if (!isTargetFunction) return false;
+
+  return { funcName: funcName || (isAsync ? 'async operation' : 'command handler') };
+};
+
+export const isSwallowedCatch = (astPath, t) => {
+  const body = astPath.node.body?.body || [];
+  if (body.length === 0) return true;
+
+  const nonNoopStatements = body.filter((stmt) => !t.isEmptyStatement(stmt));
+  if (nonNoopStatements.length === 0) return true;
+
+  let hasActiveHandling = false;
+  astPath.traverse({
+    ThrowStatement() {
+      hasActiveHandling = true;
+    },
+    ReturnStatement(retPath) {
+      if (retPath.node.argument !== null) {
+        hasActiveHandling = true;
+      }
+    },
+    CallExpression(callPath) {
+      const callee = callPath.node.callee;
+      if (t.isMemberExpression(callee)) {
+        const objName = t.isIdentifier(callee.object) ? callee.object.name : '';
+        const propName = t.isIdentifier(callee.property) ? callee.property.name : '';
+        const isLogger = ['console', 'logger', 'log', 'telemetry', 'reportError'].includes(objName);
+        const isHandlingMethod = ['error', 'warn', 'info', 'captureException', 'track'].includes(propName);
+        const isProcessStderr = t.isMemberExpression(callee.object) &&
+          t.isIdentifier(callee.object.object, { name: 'process' }) &&
+          t.isIdentifier(callee.object.property, { name: 'stderr' });
+        if (isLogger || isHandlingMethod || isProcessStderr) {
+          hasActiveHandling = true;
+        }
+      } else if (t.isIdentifier(callee)) {
+        const isHandler = ['handleError', 'reportError', 'captureException', 'toResult'].includes(callee.name);
+        if (isHandler) {
+          hasActiveHandling = true;
+        }
+      }
+    }
+  });
+
+  return !hasActiveHandling;
+};
+
+export const countOptionalChainingDepth = (node, t) => {
+  let count = 0;
+  let curr = node;
+  while (curr && (t.isOptionalMemberExpression(curr) || t.isOptionalCallExpression(curr) || t.isMemberExpression(curr))) {
+    if (curr.optional) {
+      count++;
+    }
+    curr = curr.object || curr.callee;
+  }
+  return count;
+};
+
+const COMBINATOR_NAMES = new Set(['all', 'any', 'none', 'allPass', 'anyPass', 'nonePass']);
+
+export const isCombinatorCall = (callee, t) => {
+  if (t.isIdentifier(callee)) {
+    return COMBINATOR_NAMES.has(callee.name);
+  }
+  return false;
+};
+
+export const isRawBooleanArg = (arg, t) => {
+  if (t.isBinaryExpression(arg)) return true;
+  if (t.isLogicalExpression(arg)) return true;
+  if (t.isBooleanLiteral(arg)) return true;
+  if (t.isUnaryExpression(arg, { operator: '!' })) return true;
+  return false;
+};
+

package/cli/audit/rules-registry.js

@@ -111,6 +111,21 @@ export const RULE_REGISTRY = {
     severity: 'MEDIUM',
     directive: 'Replace repetitive dispatch switch with an O(1) keyed dictionary or method map (Directive 3.E)'
   },
+  CONTROL_FLOW_SILENT_GUARD: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'MEDIUM',
+    directive: 'Replace silent bare return in side-effecting logic with explicit ResultTuple, logger diagnostic, or error state (Directive 3.G)'
+  },
+  ERROR_SWALLOWED_EXCEPTION: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'CRITICAL',
+    directive: 'Do not swallow caught exceptions silently; log with error context or return explicit ResultTuple error (Directive 3.B)'
+  },
+  COMBINATOR_RAW_BOOLEAN: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'MEDIUM',
+    directive: 'Do not pass inline boolean expressions or raw booleans into logical combinators; use named predicates or thunks (Directive 3.A)'
+  },
   HOOK_SATURATION: {
     pillar: PILLARS.PILLAR_3,
     severity: 'HIGH',
@@ -141,6 +156,11 @@ export const RULE_REGISTRY = {
     severity: 'CRITICAL',
     directive: 'Replace render-hack setTimeout(0) with await nextTick() or RAF'
   },
+  LIFECYCLE_ORPHANED_LISTENER: {
+    pillar: PILLARS.PILLAR_6,
+    severity: 'HIGH',
+    directive: 'Wrap event listeners in self-cleaning disposers or register pairing removeEventListener (Directive 3.F)'
+  },
   TYPE_COLOCATION: {
     pillar: PILLARS.PILLAR_4,
     severity: 'MEDIUM',
@@ -156,6 +176,11 @@ export const RULE_REGISTRY = {
     severity: 'MEDIUM',
     directive: 'Use live API data or explicit empty states instead of mock placeholders'
   },
+  DATA_FLOW_OPTIONAL_CHAINING_CHURN: {
+    pillar: PILLARS.PILLAR_4,
+    severity: 'LOW',
+    directive: 'Level incoming data shapes line 1 using sentinels or normalizeArray instead of deep optional chaining churn (Directive 4.D)'
+  },
   RAW_INLINE_STYLE: {
     pillar: PILLARS.PILLAR_5,
     severity: 'MEDIUM',

package/cli/audit-scope.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { findAndLoadConfigFile } from './config/loader.js';
+
+export const SOURCE_ROOT_CANDIDATES = ['src', 'lib', 'app', 'cli', 'packages', 'blueprints'];
+
+const isDirectory = (dir) => fs.existsSync(dir) && fs.statSync(dir).isDirectory();
+
+export const toRelDir = (projectRoot, dir) => path.relative(projectRoot, dir).split(path.sep).join('/') || '.';
+
+const scopeFromPath = (projectRoot, requested, source) => {
+  const dir = path.resolve(projectRoot, requested);
+  const isMissing = !isDirectory(dir);
+  if (isMissing) {
+    const origin = source === 'config' ? 'Configured scope' : 'Audit directory';
+    return { ok: false, reason: 'missing', message: `${origin} "${requested}" does not exist (resolved to ${dir}).`, candidates: [] };
+  }
+  return { ok: true, dir, relDir: toRelDir(projectRoot, dir), source };
+};
+
+const readConfiguredScope = (projectRoot) => {
+  const scope = findAndLoadConfigFile(projectRoot).raw?.scope;
+  const isUsable = typeof scope === 'string' && scope.length > 0;
+  return isUsable ? scope : null;
+};
+
+export const resolveAuditScope = ({ projectRoot, explicitDir = null }) => {
+  if (explicitDir) return scopeFromPath(projectRoot, explicitDir, 'explicit');
+
+  const configuredScope = readConfiguredScope(projectRoot);
+  if (configuredScope) return scopeFromPath(projectRoot, configuredScope, 'config');
+
+  const candidates = SOURCE_ROOT_CANDIDATES.filter((name) => isDirectory(path.join(projectRoot, name))).sort();
+  const isAmbiguous = candidates.length >= 2;
+  if (isAmbiguous) {
+    return {
+      ok: false,
+      reason: 'ambiguous',
+      message: `Ambiguous audit scope: found ${candidates.join(', ')}. Pass --dir=<path> or set "scope" in .chemxrc.`,
+      candidates
+    };
+  }
+  return { ok: true, dir: projectRoot, relDir: '.', source: 'root' };
+};

package/cli/build/detector.js

@@ -18,8 +18,6 @@ export const findProjectRoot = (startDir = process.cwd()) => {
   if (pkgFile) return path.dirname(pkgFile);
   const chemxDir = findFileUpward('.chemx', startDir);
   if (chemxDir) return path.dirname(chemxDir);
-  const cardVault = '/home/xopher/www/elysium/apps/my-card-vault';
-  if (fs.existsSync(cardVault)) return cardVault;
   return startDir;
 };