@chemx/starter-kit 26.9.24-393 → 26.9.25-1337

package/cli/audit/pattern-detector.js

@@ -29,15 +29,17 @@ export const createPatternRegistry = () => {
     });
   };
 
-  const resolveHarmonizationCandidates = (hotspots = []) => {
+  const resolveHarmonizationCandidates = (hotspots = [], options = {}) => {
     const hotspotFiles = new Set(hotspots.map((h) => h.filePath));
     const candidates = [];
+    const minFiles = options.ruleOfThree ? 3 : 2;
 
     for (const [key, bucket] of buckets.entries()) {
       const uniqueFiles = Array.from(new Set(bucket.occurrences.map((o) => o.filePath)));
-      if (uniqueFiles.length < 2) continue;
-
       const hasHotspot = uniqueFiles.some((f) => hotspotFiles.has(f));
+      const isCandidateEligible = hasHotspot ? uniqueFiles.length >= 2 : uniqueFiles.length >= minFiles;
+      if (!isCandidateEligible) continue;
+
       const impactScore = uniqueFiles.length * (hasHotspot ? 3 : 1.5) + bucket.occurrences.length;
 
       let label = 'Recurring Pattern';

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

@@ -94,3 +94,20 @@ test('categorizeUiStructure: maps semantic AST topologies to specialized capsule
   assert.equal(fallbackRes.suggestedCapsule, 'm-feature-card');
 });
 
+test('Rule of Three: requires pattern across 3+ files unless a hotspot is involved', () => {
+  const registry = createPatternRegistry();
+  const template = `<template><v-sheet><x-btn>1</x-btn><x-btn>2</x-btn></v-sheet></template>`;
+
+  recordTemplatePatterns(registry, template, 'src/components/A.vue');
+  recordTemplatePatterns(registry, template, 'src/components/B.vue');
+
+  // With Rule of Three enabled and no hotspots, 2 files do not trigger premature abstraction
+  const strictCandidates = registry.resolveHarmonizationCandidates([], { ruleOfThree: true });
+  assert.equal(strictCandidates.length, 0, '2 occurrences without hotspot should not trigger premature abstraction');
+
+  // When a 3rd file adopts the pattern, Rule of Three threshold is satisfied
+  recordTemplatePatterns(registry, template, 'src/components/C.vue');
+  const satisfiedCandidates = registry.resolveHarmonizationCandidates([], { ruleOfThree: true });
+  assert.equal(satisfiedCandidates.length, 1, '3 occurrences should satisfy Rule of Three threshold');
+});
+

package/cli/audit/reporter-grades.js

@@ -267,6 +267,7 @@ export const formatGradeASection = (report) => {
     lines.push(`   ${GREEN}✔${RESET} Low Context Hazard & Token Burn Risk`);
   }
 
+  lines.push(`\n   ${DIM}ℹ Notice: Architectural grade measures AST rules only. Run chemx verify for full typecheck and test verification.${RESET}`);
   lines.push(`\n${GREEN}======================================================================${RESET}\n`);
   return lines.join('\n');
 };

package/cli/audit/reporter-markdown.js

@@ -39,6 +39,8 @@ export const generateMarkdownReport = (report) => {
     lines.push('');
   }
   lines.push('> *Comprehensive static analysis report enforcing Chemical X Molecular Architecture standards.*');
+  lines.push('> ');
+  lines.push('> **Notice**: Architectural grades measure AST rule compliance only. Run `chemx verify` for full production readiness (typecheck + test suite).');
   lines.push('');
   lines.push('## 1. Executive Summary & Scorecard');
   lines.push('');

package/cli/audit/reporter-sections.js

@@ -72,6 +72,9 @@ export const formatScorecardSection = (report, themeColor = null) => {
   lines.push(`   Largest File:        ${BOLD}${metrics.largestFile.filePath || 'None'}${RESET} (${metrics.largestFile.lineCount} lines)`);
   lines.push(`   Molecule Capsules:   ${metrics.moleculeCount} found (${metrics.moleculeCompliantPct}% compliant < 100 lines of code)`);
   lines.push(`   Custom Hooks:        ${metrics.hookCount} detected`);
+  lines.push(`   ${sectionColor}----------------------------------------------------------------------${RESET}`);
+  lines.push(`   ${DIM}ℹ Notice: Architectural grade measures AST rules only.${RESET}`);
+  lines.push(`   ${DIM}  Run ${RESET}${BOLD}chemx verify${RESET}${DIM} for full typecheck and test verification.${RESET}`);
   lines.push(`${sectionColor}======================================================================${RESET}\n`);
 
   return lines.join('\n');

package/cli/audit/rules-registry.js

@@ -215,5 +215,32 @@ export const RULE_REGISTRY = {
     pillar: 'AI Slop & Code Authenticity',
     severity: 'LOW',
     directive: 'Inline redundant single-use passthrough assignments directly into return expressions'
+  },
+
+  // Greybeard Pragmatic: Structural Weight & Bounded Context
+  STRUCTURAL_WEIGHT_EXCEEDED: {
+    pillar: PILLARS.PILLAR_1,
+    severity: 'HIGH',
+    directive: 'Reduce component responsibility density: extract domain hooks, decompose branching, or flatten render tree'
+  },
+  COMPLEXITY_CYCLOMATIC_HIGH: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'HIGH',
+    directive: 'Decompose high cyclomatic complexity into pure helper functions or table dispatch'
+  },
+  HOOK_STATE_SATURATION: {
+    pillar: PILLARS.PILLAR_3,
+    severity: 'HIGH',
+    directive: 'Extract co-located state and effects into a dedicated domain hook or reducer'
+  },
+  RENDER_TREE_DEPTH_EXCEEDED: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'HIGH',
+    directive: 'Extract nested JSX ternaries into computed descriptor objects or early returns'
+  },
+  PROP_SURFACE_BLOAT: {
+    pillar: PILLARS.PILLAR_4,
+    severity: 'MEDIUM',
+    directive: 'Encapsulate flat primitive props into a cohesive domain type or composable'
   }
 };

package/cli/audit/rules.js

@@ -20,6 +20,8 @@ import {
 } from './extended-visitors.js';
 import { createPatternVisitors, recordTemplatePatterns } from './pattern-detector.js';
 import { createHookShapeRegistry } from './hook-shape-validator.js';
+import { isBabelParsable, getLanguageForFile } from '../languages.js';
+import { analyzeCSharpCode } from './csharp-analyzer.js';
 
 export { PILLARS, RULE_REGISTRY, createHookShapeRegistry };
 
@@ -34,7 +36,11 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
   const isView = relativePath.includes('/views/') || relativePath.includes('/pages/') || /View\.[tj]sx?$/.test(baseName);
   const isRootTypeFile = baseName === 'types.ts' || baseName === 'global.d.ts';
 
+  const config = options.config?.rules || options.config || {};
+  const enforceFileLength = config.enforceFileLength === true || config.profile === 'atomic-strict';
+
   // Pillar 1: Sliding Scale Monolith Detection
+  const moleculeLimit = enforceFileLength ? 100 : (config.maxLineCountWarning || 250);
   if (lineCount > 500) {
     const tier = resolveMonolithTier(lineCount);
     violations.push({
@@ -47,7 +53,7 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
       pillar: PILLARS.PILLAR_1,
       directive: tier.directive
     });
-  } else if (isMolecule && lineCount > 100) {
+  } else if (isMolecule && lineCount > moleculeLimit) {
     const tier = resolveMoleculeTier(lineCount);
     violations.push({
       filePath: relativePath,
@@ -103,7 +109,12 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
   // Pillars 8-11: Extended Fast Checks (A11y, Security secrets, Fake tests, Co-located specs)
   checkExtendedTextPatterns(content, lines, relativePath, filePath, violations);
 
-  if (options.fast) {
+  const lang = getLanguageForFile(filePath);
+  if (lang?.id === 'csharp') {
+    analyzeCSharpCode(content, relativePath, violations);
+  }
+
+  if (options.fast || !isBabelParsable(filePath)) {
     return violations;
   }
 
@@ -147,7 +158,7 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
 
   const traverseFn = traverse.default || traverse;
   const hookRegistry = options.hookRegistry || createHookShapeRegistry();
-  const visitors = createAstVisitors({ relativePath, violations, hookRegistry });
+  const visitors = createAstVisitors({ relativePath, violations, hookRegistry, config });
   const slopVisitors = createAiSlopVisitors({ relativePath, violations });
   const extendedVisitors = createExtendedVisitors({ relativePath, violations });
   const patternVisitors = options.patternRegistry

package/cli/audit/rules.spec.js

@@ -1,6 +1,9 @@
 import test from "node:test";
 import assert from "node:assert";
 import { auditCode } from "./rules.js";
+import { formatScorecardSection } from './reporter-sections.js';
+import { formatGradeASection } from './reporter-grades.js';
+import { generateMarkdownReport } from './reporter-markdown.js';
 
 test("Audit Rules: flags repetitive dispatch switch statement as CONTROL_FLOW_DISPATCH_SWITCH", () => {
   const code = `
@@ -332,3 +335,27 @@ export const useSecond = () => {
   assert.ok(inconsistentViolation.hazard.includes("isLoading"));
 });
 
+test("Audit Reporter: includes explicit architectural health notice distinguishing from production readiness", () => {
+  const mockReport = {
+    metrics: { scannedFiles: 5, totalLoc: 200, avgLoc: 40, largestFile: { filePath: 'src/a.ts', lineCount: 50 }, moleculeCount: 2, moleculeCompliantPct: 100, hookCount: 1 },
+    health: { score: 100, grade: 'A+', label: 'Pristine' },
+    pillars: { 'Pillar 1': { status: 'PASSED', violations: 0, critical: 0, high: 0, medium: 0, low: 0 } },
+    hotspots: [],
+    contextAnalysis: { riskLevel: 'LOW', estimatedTokens: 1000, estimatedExcessTokens: 0, potentialSavingsPct: 0 },
+    violations: [],
+    aiSlop: { score: 100, grade: 'A+', label: 'Pure Artisanal' }
+  };
+
+  const scorecard = formatScorecardSection(mockReport);
+  assert.ok(scorecard.includes('Architectural grade measures AST rules only'));
+  assert.ok(scorecard.includes('chemx verify'));
+
+  const gradeA = formatGradeASection(mockReport);
+  assert.ok(gradeA.includes('Architectural grade measures AST rules only'));
+  assert.ok(gradeA.includes('chemx verify'));
+
+  const markdown = generateMarkdownReport(mockReport);
+  assert.ok(markdown.includes('Architectural grades measure AST rule compliance only'));
+  assert.ok(markdown.includes('chemx verify'));
+});
+

package/cli/audit/structural-weight-evaluator.js

@@ -0,0 +1,121 @@
+import * as t from '@babel/types';
+import { RULE_REGISTRY } from './rules-registry.js';
+import {
+  countBranchingDecisions,
+  countHookCalls,
+  findNestedTernary,
+  countDestructuredProps
+} from './structural-weight.js';
+
+const isComponentOrHook = (funcPath, relativePath = '') => {
+  const isComponentFile = /\.(jsx|tsx|vue|svelte)$/.test(relativePath) ||
+    relativePath.includes('/components/') ||
+    relativePath.includes('/molecules/') ||
+    relativePath.includes('/atoms/') ||
+    relativePath.includes('/organisms/') ||
+    relativePath.includes('/views/') ||
+    relativePath.includes('/hooks/') ||
+    relativePath.includes('/composables/');
+
+  if (isComponentFile) return true;
+
+  const id = funcPath.node.id;
+  if (id && t.isIdentifier(id)) {
+    if (/^[A-Z]/.test(id.name) || /^use[A-Z0-9]/.test(id.name)) {
+      return true;
+    }
+  }
+
+  let returnsJsx = false;
+  funcPath.traverse({
+    ReturnStatement(ret) {
+      if (ret.getFunctionParent() === funcPath) {
+        const arg = ret.node.argument;
+        if (t.isJSXElement(arg) || t.isJSXFragment(arg)) {
+          returnsJsx = true;
+        }
+      }
+    }
+  });
+
+  return returnsJsx;
+};
+
+export const evaluateComponentStructuralWeight = ({
+  funcPath,
+  relativePath,
+  violations,
+  config = {}
+}) => {
+  if (!isComponentOrHook(funcPath, relativePath)) return null;
+
+  const maxComplexity = config.maxCyclomaticComplexity || 12;
+  const maxHooks = config.maxHookDensity || 4;
+  const maxProps = config.maxPropCount || 7;
+
+  const complexity = countBranchingDecisions(funcPath);
+  const hooks = countHookCalls(funcPath);
+  const propCount = countDestructuredProps(funcPath);
+  const startLoc = funcPath.node.loc?.start;
+  const line = startLoc?.line || 1;
+  const column = startLoc?.column || 1;
+
+  if (complexity > maxComplexity) {
+    const meta = RULE_REGISTRY.COMPLEXITY_CYCLOMATIC_HIGH;
+    violations.push({
+      filePath: relativePath,
+      line,
+      column,
+      hazard: `High cyclomatic complexity (${complexity} > ${maxComplexity} threshold)`,
+      rule: 'COMPLEXITY_CYCLOMATIC_HIGH',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  if (hooks > maxHooks) {
+    const meta = RULE_REGISTRY.HOOK_STATE_SATURATION;
+    violations.push({
+      filePath: relativePath,
+      line,
+      column,
+      hazard: `Excessive hook & state density (${hooks} hooks > ${maxHooks} threshold)`,
+      rule: 'HOOK_STATE_SATURATION',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  if (propCount > maxProps) {
+    const meta = RULE_REGISTRY.PROP_SURFACE_BLOAT;
+    violations.push({
+      filePath: relativePath,
+      line,
+      column,
+      hazard: `Prop surface area bloat (${propCount} props > ${maxProps} threshold)`,
+      rule: 'PROP_SURFACE_BLOAT',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  const nestedTernary = findNestedTernary(funcPath);
+  if (nestedTernary) {
+    const meta = RULE_REGISTRY.CONTROL_FLOW_NESTED_TERNARY;
+    violations.push({
+      filePath: relativePath,
+      line: nestedTernary.loc?.start.line || line,
+      column: nestedTernary.loc?.start.column || column,
+      hazard: 'Nested ternary expression detected in component logic',
+      rule: 'CONTROL_FLOW_NESTED_TERNARY',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  return { complexity, hooks, propCount };
+};

package/cli/audit/structural-weight.js

@@ -0,0 +1,92 @@
+import * as t from '@babel/types';
+
+export const countBranchingDecisions = (funcPath) => {
+  let complexity = 1;
+  funcPath.traverse({
+    IfStatement(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    ConditionalExpression(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    SwitchCase(p) {
+      if (p.getFunctionParent() === funcPath && p.node.test !== null) complexity += 1;
+    },
+    LogicalExpression(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    ForStatement(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    ForInStatement(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    ForOfStatement(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    WhileStatement(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    CatchClause(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    }
+  });
+  return complexity;
+};
+
+export const countHookCalls = (funcPath) => {
+  let hooks = 0;
+  funcPath.traverse({
+    CallExpression(p) {
+      if (p.getFunctionParent() !== funcPath) return;
+      const callee = p.node.callee;
+      const isHookIdentifier = t.isIdentifier(callee) && /^use[A-Z0-9]/.test(callee.name);
+      if (isHookIdentifier) {
+        hooks += 1;
+      }
+    }
+  });
+  return hooks;
+};
+
+export const findNestedTernary = (astPath) => {
+  let nested = null;
+  astPath.traverse({
+    ConditionalExpression(p) {
+      if (nested) return;
+      const parentCond = p.findParent((parent) => t.isConditionalExpression(parent.node));
+      if (parentCond) {
+        nested = p.node;
+      }
+    }
+  });
+  return nested;
+};
+
+export const countDestructuredProps = (funcPath) => {
+  const firstParam = funcPath.node.params?.[0];
+  const isObjectPattern = t.isObjectPattern(firstParam);
+  if (isObjectPattern) {
+    return firstParam.properties.length;
+  }
+  return 0;
+};
+
+export const measureJsxDepth = (jsxElementPath) => {
+  let maxDepth = 1;
+  const walk = (node, depth) => {
+    if (depth > maxDepth) maxDepth = depth;
+    const isJsxContainer = t.isJSXElement(node) || t.isJSXFragment(node);
+    if (isJsxContainer) {
+      const children = node.children || [];
+      for (const child of children) {
+        const isChildElement = t.isJSXElement(child) || t.isJSXFragment(child);
+        if (isChildElement) {
+          walk(child, depth + 1);
+        }
+      }
+    }
+  };
+  walk(jsxElementPath.node, 1);
+  return maxDepth;
+};

package/cli/audit/structural-weight.spec.js

@@ -0,0 +1,116 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { auditCode } from './rules.js';
+
+describe('AST Structural Weight & Pragmatic Profile Audit', () => {
+  it('does NOT flag a 120-line cohesive molecule in default pragmatic mode', () => {
+    // Generate a cohesive 115-line component with low complexity
+    const staticRows = Array.from({ length: 100 }, (_, i) => `    { id: ${i}, label: 'Item ${i}' },`).join('\n');
+    const code = `
+export const SimpleTable = () => {
+  const items = [
+${staticRows}
+  ];
+  return items.length;
+};
+`;
+    const violations = auditCode(code, 'src/components/molecules/m-table.js', 'src/components/molecules/m-table.js', {
+      config: { profile: 'pragmatic', enforceFileLength: false }
+    });
+
+    const moleculeLineViolation = violations.find((v) => v.rule === 'LINE_BUDGET_MOLECULE');
+    assert.strictEqual(moleculeLineViolation, undefined, 'Pragmatic mode should not flag a cohesive molecule under 250 lines');
+  });
+
+  it('strictly flags a 105-line molecule when profile is atomic-strict', () => {
+    const staticRows = Array.from({ length: 102 }, (_, i) => `    { id: ${i} },`).join('\n');
+    const code = `
+export const StrictCard = () => {
+  const rows = [
+${staticRows}
+  ];
+  return rows.length;
+};
+`;
+    const violations = auditCode(code, 'src/components/molecules/m-card.js', 'src/components/molecules/m-card.js', {
+      config: { profile: 'atomic-strict', enforceFileLength: true }
+    });
+
+    const moleculeLineViolation = violations.find((v) => v.rule === 'LINE_BUDGET_MOLECULE');
+    assert.ok(moleculeLineViolation, 'Atomic-strict mode should enforce 100-line molecule cap');
+  });
+
+  it('detects high cyclomatic complexity (CC > 12) via COMPLEXITY_CYCLOMATIC_HIGH', () => {
+    const code = `
+export function ComplexComponent(a, b, c, d, e, f, g) {
+  if (a === 1) return 1;
+  if (b === 2) return 2;
+  if (c === 3) return 3;
+  if (d === 4) return 4;
+  if (e === 5) return 5;
+  if (f === 6) return 6;
+  if (g === 7) return 7;
+  if (a && b) return 8;
+  if (c && d) return 9;
+  if (e && f) return 10;
+  if (a || g) return 11;
+  if (b || c) return 12;
+  if (d || e) return 13;
+  return 0;
+}
+`;
+    const violations = auditCode(code, 'src/components/ComplexComponent.jsx', 'src/components/ComplexComponent.jsx', {
+      config: { maxCyclomaticComplexity: 12 }
+    });
+
+    const complexityViolation = violations.find((v) => v.rule === 'COMPLEXITY_CYCLOMATIC_HIGH');
+    assert.ok(complexityViolation, 'Should detect cyclomatic complexity exceeding threshold');
+    assert.strictEqual(complexityViolation.severity, 'HIGH');
+  });
+
+  it('detects hook & state saturation (hooks > 4) via HOOK_STATE_SATURATION', () => {
+    const code = `
+import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
+
+export function MonolithicComponent() {
+  const [s1, setS1] = useState(1);
+  const [s2, setS2] = useState(2);
+  const [s3, setS3] = useState(3);
+  useEffect(() => {}, []);
+  const m1 = useMemo(() => s1 + s2, [s1, s2]);
+  return null;
+}
+`;
+    const violations = auditCode(code, 'src/Component.jsx', 'src/Component.jsx', {
+      config: { maxHookDensity: 4 }
+    });
+
+    const hookViolation = violations.find((v) => v.rule === 'HOOK_STATE_SATURATION');
+    assert.ok(hookViolation, 'Should detect excessive hook density without domain encapsulation');
+  });
+
+  it('detects nested ternaries via CONTROL_FLOW_NESTED_TERNARY', () => {
+    const code = `
+export const BadTernary = (props) => {
+  return props.a ? (props.b ? 'X' : 'Y') : 'Z';
+};
+`;
+    const violations = auditCode(code, 'src/Ternary.jsx', 'src/Ternary.jsx');
+    const ternaryViolation = violations.find((v) => v.rule === 'CONTROL_FLOW_NESTED_TERNARY');
+    assert.ok(ternaryViolation, 'Should detect nested ternary expression');
+  });
+
+  it('detects prop surface area bloat (props > 7) via PROP_SURFACE_BLOAT', () => {
+    const code = `
+export const BloatedProps = ({ p1, p2, p3, p4, p5, p6, p7, p8, p9 }) => {
+  return p1;
+};
+`;
+    const violations = auditCode(code, 'src/Props.jsx', 'src/Props.jsx', {
+      config: { maxPropCount: 7 }
+    });
+
+    const propViolation = violations.find((v) => v.rule === 'PROP_SURFACE_BLOAT');
+    assert.ok(propViolation, 'Should detect prop count exceeding threshold');
+  });
+});

package/cli/audit-preflight-scope.js

@@ -3,7 +3,10 @@ import path from 'node:path';
 import { hasGum, gumChoose, gumInput, promptQuestion } from './terminal.js';
 import { resolveGitAuditScope } from './audit-preflight-git.js';
 
-const CANDIDATE_NAMES = ['src', 'app', 'cli', 'components', 'lib', 'packages', 'modules'];
+const CANDIDATE_NAMES = [
+  'src', 'app', 'cli', 'components', 'lib', 'packages', 'modules',
+  'server', 'backend', 'api', 'Services', 'Controllers', 'Handlers', 'Domain', 'pkg', 'cmd', 'internal'
+];
 
 export const detectCandidateDirectories = (cwd = process.cwd()) => {
   return CANDIDATE_NAMES.filter((name) => {

package/cli/audit.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { isSourceFile as isPolyglotSourceFile } from './languages.js';
+import { loadProjectConfig } from './config/index.js';
 import { auditCode, PILLARS, RULE_REGISTRY, createHookShapeRegistry } from './audit/rules.js';
 import { createPatternRegistry } from './audit/pattern-detector.js';
 import {
@@ -82,14 +84,8 @@ const IGNORED_DIRS = new Set([
   'out'
 ]);
 
-const EXCLUDED_NAME_PATTERNS = ['.test.', '.spec.', '.min.'];
-
 const isSourceFile = (name) => {
-  const isExtensionValid = /\.(tsx|ts|jsx|js|vue)$/.test(name);
-  if (!isExtensionValid) return false;
-  if (name.endsWith('.d.ts')) return false;
-  const isExcluded = EXCLUDED_NAME_PATTERNS.some((pat) => name.includes(pat));
-  return !isExcluded;
+  return isPolyglotSourceFile(name, { includeTests: false });
 };
 
 export const auditFile = (filePath, relativePath) => {
@@ -117,7 +113,8 @@ const auditFileEntry = (fullPath, relPath, scanOptions) => {
   const fileViolations = auditCode(content, fullPath, relPath, {
     patternRegistry: scanOptions.patternRegistry,
     hookRegistry: scanOptions.hookRegistry,
-    fast: scanOptions.fast
+    fast: scanOptions.fast,
+    config: scanOptions.config
   });
 
   return { fileStat, hookCount, fileViolations };
@@ -179,11 +176,13 @@ export const runAudit = (targetDir = 'src', options = {}) => {
   const absoluteTarget = path.isAbsolute(targetDir) ? targetDir : path.resolve(cwd, targetDir);
   const patternRegistry = createPatternRegistry();
   const hookRegistry = createHookShapeRegistry();
+  const config = options.config || loadProjectConfig(cwd);
   const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd, {
     patternRegistry,
     hookRegistry,
     fast: Boolean(options.fast),
-    fileList: options.fileList || null
+    fileList: options.fileList || null,
+    config
   });
 
   const crossHookViolations = hookRegistry.validateCrossHookConsistency();
@@ -229,7 +228,7 @@ export const runAudit = (targetDir = 'src', options = {}) => {
   const contextAnalysis = calculateTokenBurnAnalytics(fileStats, options);
   const hotspots = calculateHotspots(violations, fileStats, 5);
   const aiSlop = calculateAiSlopScore(violations, scannedFiles);
-  const patterns = patternRegistry.resolveHarmonizationCandidates(hotspots);
+  const patterns = patternRegistry.resolveHarmonizationCandidates(hotspots, { ruleOfThree: config?.rules?.ruleOfThreeAbstractions ?? config?.ruleOfThreeAbstractions ?? true });
   const roadmap = buildRemediationRoadmap({ hotspots, violations, patterns });
 
   const stage = options.stage || (options.relax ? 'draft' : 'strict');

package/cli/commands/cmd-audit.js

@@ -101,7 +101,7 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
     fileList = preflight.fileList;
   }
 
-  const auditOptions = { outputFile, model, costPerMillion, fast: isFast, fileList, stage };
+  const auditOptions = { outputFile, model, costPerMillion, fast: isFast, fileList, stage, config: projectConfig };
   const report = executeAstAudit(targetDir, auditOptions);
   saveAuditSnapshot(report);
   try {

package/cli/commands/cmd-router.js

@@ -94,12 +94,26 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       break;
     }
     case 'init': {
+      const isHelpRequested = rawArgs.includes('--help') || rawArgs.includes('-h') || rawArgs[1] === 'help';
+      if (isHelpRequested) {
+        const { printInitHelp } = await import('../help.js');
+        printInitHelp();
+        break;
+      }
+      const nonFlagArgs = rawArgs.slice(1).filter((arg) => !arg.startsWith('-'));
+      const targetSubDir = nonFlagArgs[0] || 'src/chemical-x';
       const { runInit } = await import('../scaffold.js');
-      await runInit(rawArgs[1] || 'src/chemical-x', rawArgs, runAudit);
+      await runInit(targetSubDir, rawArgs, runAudit);
       break;
     }
     case 'create':
     case 'scaffold': {
+      const isHelpRequested = rawArgs.includes('--help') || rawArgs.includes('-h') || rawArgs[1] === 'help';
+      if (isHelpRequested) {
+        const { printScaffoldHelp } = await import('../help.js');
+        printScaffoldHelp();
+        break;
+      }
       const { runScaffold } = await import('../scaffold.js');
       const nonFlagArgs = rawArgs.slice(1).filter((arg) => !arg.startsWith('-'));
       await runScaffold(nonFlagArgs[0], rawArgs, runAudit);
@@ -202,7 +216,8 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       const port = portArg ? parseInt(portArg.split('=')[1], 10) : 4173;
       const hostArg = rawArgs.find((a) => a.startsWith('--host='));
       const host = hostArg ? hostArg.split('=')[1] : '0.0.0.0';
-      const { server } = await startUiServer({ port, host, isCli: true, cwd: process.cwd() });
+      const isDev = rawArgs.includes('--dev') || rawArgs.includes('-d') || process.env.CHEMX_UI_DEV === '1';
+      const { server } = await startUiServer({ port, host, dev: isDev, isCli: true, cwd: process.cwd() });
       await new Promise((resolve) => {
         const shutdown = () => {
           server.close(() => resolve());