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

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

@@ -202,7 +202,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());

package/cli/config/config.spec.js

@@ -0,0 +1,51 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { DEFAULT_PROFILE, getProfileDefaults, loadProjectConfig } from './index.js';
+
+describe('Chemical X Configuration & Profiles', () => {
+  it('defines pragmatic as the default profile with greybeard staff thresholds', () => {
+    assert.strictEqual(DEFAULT_PROFILE, 'pragmatic');
+    const defaults = getProfileDefaults('pragmatic');
+    assert.strictEqual(defaults.profile, 'pragmatic');
+    assert.strictEqual(defaults.enforceFileLength, false);
+    assert.strictEqual(defaults.ruleOfThreeAbstractions, true);
+    assert.strictEqual(defaults.maxCyclomaticComplexity, 12);
+    assert.strictEqual(defaults.maxHookDensity, 4);
+    assert.strictEqual(defaults.preferDesignTokens, 'warning');
+  });
+
+  it('defines atomic-strict profile with strict 100-line capsule limit', () => {
+    const strict = getProfileDefaults('atomic-strict');
+    assert.strictEqual(strict.profile, 'atomic-strict');
+    assert.strictEqual(strict.enforceFileLength, true);
+    assert.strictEqual(strict.ruleOfThreeAbstractions, false);
+    assert.strictEqual(strict.maxLineCountWarning, 100);
+    assert.strictEqual(strict.preferDesignTokens, 'error');
+  });
+
+  it('defines loose profile with permissive thresholds', () => {
+    const loose = getProfileDefaults('loose');
+    assert.strictEqual(loose.profile, 'loose');
+    assert.strictEqual(loose.enforceFileLength, false);
+    assert.strictEqual(loose.maxCyclomaticComplexity, 25);
+    assert.strictEqual(loose.preferDesignTokens, 'off');
+  });
+
+  it('falls back to default profile for unknown profile names', () => {
+    const fallback = getProfileDefaults('unknown-profile');
+    assert.strictEqual(fallback.profile, 'pragmatic');
+  });
+
+  it('parses --profile CLI argument and overrides file config', () => {
+    const cfg = loadProjectConfig(process.cwd(), ['--profile=atomic-strict']);
+    assert.strictEqual(cfg.profile, 'atomic-strict');
+    assert.strictEqual(cfg.rules.enforceFileLength, true);
+  });
+
+  it('defaults to pragmatic profile when no flags or config files specify otherwise', () => {
+    const cfg = loadProjectConfig('/tmp/non-existent-dir-for-chemx-test');
+    assert.strictEqual(cfg.profile, 'pragmatic');
+    assert.strictEqual(cfg.rules.enforceFileLength, false);
+    assert.strictEqual(cfg.rules.maxCyclomaticComplexity, 12);
+  });
+});

package/cli/config/index.js

@@ -0,0 +1,37 @@
+import { PROFILES, DEFAULT_PROFILE, getProfileDefaults } from './profiles.js';
+import { findAndLoadConfigFile } from './loader.js';
+
+const parseCliProfile = (rawArgs = []) => {
+  const profileArg = rawArgs.find((arg) => arg.startsWith('--profile='));
+  if (profileArg) {
+    const parts = profileArg.split('=');
+    return parts[1]?.trim()?.toLowerCase() || null;
+  }
+  return null;
+};
+
+export const loadProjectConfig = (cwd = process.cwd(), rawArgs = []) => {
+  const fileConfig = findAndLoadConfigFile(cwd);
+  const cliProfile = parseCliProfile(rawArgs);
+
+  const isCliProfileExplicit = Boolean(cliProfile);
+  const selectedProfile = cliProfile || fileConfig.profile || DEFAULT_PROFILE;
+  const profileDefaults = getProfileDefaults(selectedProfile);
+
+  const effectiveRules = {
+    ...profileDefaults,
+    ...(isCliProfileExplicit ? {} : fileConfig.rules)
+  };
+
+  return {
+    source: fileConfig.source,
+    profile: selectedProfile,
+    rules: effectiveRules,
+    overrides: fileConfig.overrides || [],
+    raw: fileConfig.raw || {},
+    stage: fileConfig.raw?.stage || 'strict'
+  };
+};
+
+export { PROFILES, DEFAULT_PROFILE, getProfileDefaults, findAndLoadConfigFile };
+export default loadProjectConfig;