@chemx/starter-kit 26.9.21-8 → 26.9.23-1269

package/cli/audit/rules.spec.js

@@ -203,3 +203,132 @@ export const debugCount = (itemCount: number) => {
   assert.strictEqual(violation, undefined);
 });
 
+test("Audit Hook Shape Contract: passes flat hook with 4 actions, 2 state fields, 1 status field (7 total)", () => {
+  const code = `
+export const useTodoList = () => {
+  const items = ref([]);
+  const filter = ref("all");
+  const isLoading = ref(false);
+
+  const addItem = (item) => { items.value.push(item); };
+  const toggleItem = (id) => { /* toggle */ };
+  const removeItem = (id) => { /* remove */ };
+  const setFilter = (next) => { filter.value = next; };
+
+  return {
+    items,
+    filter,
+    isLoading,
+    addItem,
+    toggleItem,
+    removeItem,
+    setFilter
+  };
+};
+`;
+  const violations = auditCode(code, "src/useTodoList.ts", "src/useTodoList.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.strictEqual(shapeViolation, undefined, "Expected HOOK_SHAPE_CONTRACT to pass for flat 7-property hook");
+
+  const overloadViolation = violations.find((v) => v.rule === "HOOK_RETURN_OVERLOAD");
+  assert.ok(overloadViolation, "Expected deprecated HOOK_RETURN_OVERLOAD warning");
+  assert.strictEqual(overloadViolation.severity, "MEDIUM", "Expected downgraded warning severity for HOOK_RETURN_OVERLOAD");
+});
+
+test("Audit Hook Shape Contract: fails hook with actions nested under actions wrapper", () => {
+  const code = `
+export const useTodoList = () => {
+  const items = ref([]);
+  const filter = ref("all");
+  const isLoading = ref(false);
+
+  const addItem = (item) => { items.value.push(item); };
+  const toggleItem = (id) => { /* toggle */ };
+  const removeItem = (id) => { /* remove */ };
+  const setFilter = (next) => { filter.value = next; };
+
+  return {
+    items,
+    filter,
+    isLoading,
+    actions: {
+      addItem,
+      toggleItem,
+      removeItem,
+      setFilter
+    }
+  };
+};
+`;
+  const violations = auditCode(code, "src/useTodoList.ts", "src/useTodoList.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.ok(shapeViolation, "Expected HOOK_SHAPE_CONTRACT failure for nested action wrapper");
+  assert.strictEqual(shapeViolation.severity, "HIGH");
+  assert.ok(shapeViolation.hazard.includes("actions"));
+});
+
+test("Audit Hook Shape Contract: flags raw DOM ref in hook return", () => {
+  const code = `
+export const useDropdown = () => {
+  const isOpen = ref(false);
+  const containerRef = ref(null);
+  const toggleDropdown = () => { isOpen.value = !isOpen.value; };
+
+  return {
+    isOpen,
+    containerRef,
+    toggleDropdown
+  };
+};
+`;
+  const violations = auditCode(code, "src/useDropdown.ts", "src/useDropdown.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.ok(shapeViolation, "Expected HOOK_SHAPE_CONTRACT failure for raw DOM ref");
+  assert.strictEqual(shapeViolation.severity, "HIGH");
+  assert.ok(shapeViolation.hazard.includes("containerRef"));
+});
+
+test("Audit Hook Shape Contract: flags non-verb action handler in hook return", () => {
+  const code = `
+export const useCounter = () => {
+  const count = ref(0);
+  const onToggle = () => { count.value += 1; };
+
+  return {
+    count,
+    onToggle
+  };
+};
+`;
+  const violations = auditCode(code, "src/useCounter.ts", "src/useCounter.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.ok(shapeViolation, "Expected HOOK_SHAPE_CONTRACT failure for onToggle");
+  assert.strictEqual(shapeViolation.severity, "HIGH");
+  assert.ok(shapeViolation.hazard.includes("onToggle"));
+});
+
+test("Audit Hook Shape Contract: flags cross-hook naming inconsistency for loading state", () => {
+  const code = `
+export const useFirst = () => {
+  const items = ref([]);
+  const isLoading = ref(false);
+  const fetchItems = () => {};
+  return { items, isLoading, fetchItems };
+};
+
+export const useSecond = () => {
+  const user = ref(null);
+  const loading = ref(false);
+  const fetchUser = () => {};
+  return { user, loading, fetchUser };
+};
+`;
+  const violations = auditCode(code, "src/useMulti.ts", "src/useMulti.ts");
+  const inconsistentViolation = violations.find(
+    (v) => v.rule === "HOOK_SHAPE_CONTRACT" && v.hazard.includes("loading")
+  );
+  assert.ok(inconsistentViolation, "Expected cross-hook naming inconsistency failure for loading vs isLoading");
+  assert.strictEqual(inconsistentViolation.severity, "HIGH");
+  assert.ok(inconsistentViolation.hazard.includes("isLoading"));
+});
+

package/cli/audit-stages.spec.js

@@ -0,0 +1,30 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { runAudit } from './audit.js';
+
+test('audit: options.stage tags the report as draft or strict', () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-audit-stage');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  // Sample file with an inline multi-clause boolean (MEDIUM severity)
+  const code = `export const check = (a: number, b: number, c: number) => {
+  if (a > 0 && b > 0 && c > 0) return true;
+  return false;
+};`;
+  fs.writeFileSync(path.join(tmpDir, 'sample.ts'), code, 'utf-8');
+
+  const draftReport = runAudit(tmpDir, { stage: 'draft' });
+  assert.strictEqual(draftReport.stage, 'draft');
+  assert.ok(draftReport.totalViolations > 0);
+
+  const hasCritical = draftReport.violations.some((v) => v.severity === 'CRITICAL');
+  assert.strictEqual(hasCritical, false, 'Should have 0 critical violations');
+
+  const strictReport = runAudit(tmpDir, { stage: 'strict' });
+  assert.strictEqual(strictReport.stage, 'strict');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});

package/cli/audit.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { auditCode, PILLARS, RULE_REGISTRY } from './audit/rules.js';
+import { auditCode, PILLARS, RULE_REGISTRY, createHookShapeRegistry } from './audit/rules.js';
 import { createPatternRegistry } from './audit/pattern-detector.js';
 import {
   buildRemediationRoadmap,
@@ -116,6 +116,7 @@ const auditFileEntry = (fullPath, relPath, scanOptions) => {
   const hookCount = hookMatches ? hookMatches.length : 0;
   const fileViolations = auditCode(content, fullPath, relPath, {
     patternRegistry: scanOptions.patternRegistry,
+    hookRegistry: scanOptions.hookRegistry,
     fast: scanOptions.fast
   });
 
@@ -174,15 +175,20 @@ export const scanDirectory = (targetDir, baseDir) => {
 };
 
 export const runAudit = (targetDir = 'src', options = {}) => {
-  const cwd = process.cwd();
-  const absoluteTarget = path.resolve(cwd, targetDir);
+  const cwd = options.cwd || process.cwd();
+  const absoluteTarget = path.isAbsolute(targetDir) ? targetDir : path.resolve(cwd, targetDir);
   const patternRegistry = createPatternRegistry();
+  const hookRegistry = createHookShapeRegistry();
   const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd, {
     patternRegistry,
+    hookRegistry,
     fast: Boolean(options.fast),
     fileList: options.fileList || null
   });
 
+  const crossHookViolations = hookRegistry.validateCrossHookConsistency();
+  violations.push(...crossHookViolations);
+
   const scannedFiles = fileStats.length;
   const totalLoc = fileStats.reduce((acc, f) => acc + f.lineCount, 0);
   const avgLoc = scannedFiles > 0 ? Math.round(totalLoc / scannedFiles) : 0;
@@ -226,8 +232,11 @@ export const runAudit = (targetDir = 'src', options = {}) => {
   const patterns = patternRegistry.resolveHarmonizationCandidates(hotspots);
   const roadmap = buildRemediationRoadmap({ hotspots, violations, patterns });
 
+  const stage = options.stage || (options.relax ? 'draft' : 'strict');
+
   const report = {
     targetDir,
+    stage,
     options,
     scannedFiles,
     totalViolations: violations.length,

package/cli/commands/cmd-audit.js

@@ -1,5 +1,5 @@
 /**
- * cmd-audit.js — Audit command orchestrator.
+ * cmd-audit.js: Audit command orchestrator.
  * Single responsibility: run the full AST audit pipeline given CLI args.
  * Extracted from cli/index.js per Directive 1.A (Monolith Decomposition).
  */
@@ -47,6 +47,19 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
   const isPromptOnFail = rawArgs.includes('--prompt-on-fail');
   const isCopyPrompt = rawArgs.includes('--copy-prompt');
 
+  const stageFlag = rawArgs.find((arg) => arg.startsWith('--stage='));
+  let stage = 'strict';
+  if (stageFlag) {
+    stage = stageFlag.split('=')[1];
+  } else if (rawArgs.includes('--relax') || rawArgs.includes('--draft')) {
+    stage = 'draft';
+  } else if (isStrict) {
+    stage = 'strict';
+  } else if (projectConfig.stage) {
+    stage = projectConfig.stage;
+  }
+  const isDraft = stage === 'draft';
+
   const dirFlag = rawArgs.find((arg) => arg.startsWith('--dir='));
   const outputFlag = rawArgs.find((arg) => arg.startsWith('--output=') || arg.startsWith('-o='));
   const outputFile = outputFlag ? outputFlag.split('=')[1] : null;
@@ -88,7 +101,7 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
     fileList = preflight.fileList;
   }
 
-  const auditOptions = { outputFile, model, costPerMillion, fast: isFast, fileList };
+  const auditOptions = { outputFile, model, costPerMillion, fast: isFast, fileList, stage };
   const report = executeAstAudit(targetDir, auditOptions);
   saveAuditSnapshot(report);
   const syncRes = syncSearchIndex(targetDir, process.cwd());
@@ -102,9 +115,35 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
         process.stdout.write(`\x1b[32m✔\x1b[0m Auto-triage generated ${createdTasks.length} team task(s) from audit violations.\n`);
       }
     }
+    if (rawArgs.includes('--clones')) {
+      const { detectSemanticClones } = await import('../audit/clone-detector.js');
+      const { formatCloneReport } = await import('../audit/reporter-clones.js');
+      const cloneThresholdArg = rawArgs.find((a) => a.startsWith('--clone-threshold='));
+      const threshold = cloneThresholdArg ? parseFloat(cloneThresholdArg.split('=')[1]) : 0.85;
+      const clones = detectSemanticClones(syncRes.db, { threshold });
+      if (isJson) {
+        report.clones = clones;
+      } else {
+        process.stdout.write(formatCloneReport(clones));
+      }
+    }
+    if (rawArgs.includes('--hotspot-graph')) {
+      const { calculateCascadingHotspotGraph } = await import('../search-queries-hotspot-graph.js');
+      const { formatHotspotGraphReport } = await import('../audit/reporter-hotspot-graph.js');
+      const limitArg = rawArgs.find((a) => a.startsWith('--limit='));
+      const limit = limitArg ? parseInt(limitArg.split('=')[1], 10) : 10;
+      const graph = calculateCascadingHotspotGraph(syncRes.db, { limit });
+      if (isJson) {
+        report.hotspotGraph = graph;
+      } else {
+        process.stdout.write(formatHotspotGraphReport(graph));
+      }
+    }
   }
 
   // Stage 1: Atomic failure predicates
+  const isCriticalViolation = (v) => v.severity === 'CRITICAL';
+  const hasCritical = report.violations.some(isCriticalViolation);
   const isSevereViolation = (v) => v.severity === 'CRITICAL' || v.severity === 'HIGH';
   const hasCriticalOrHigh = report.violations.some(isSevereViolation);
   const hasViolations = report.violations.length > 0;
@@ -116,7 +155,8 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
   const isDefaultFail = !hasThreshold && !isStrict && hasCriticalOrHigh;
 
   // Stage 2: Unified failure decision
-  const hasFailingViolations = evaluateAuditFailure([isStrictFail, isDefaultFail, isGradeFail, isScoreFail]);
+  const hasStandardFailure = evaluateAuditFailure([isStrictFail, isDefaultFail, isGradeFail, isScoreFail]);
+  const hasFailingViolations = isDraft ? hasCritical : hasStandardFailure;
 
   if (isJson) {
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');

package/cli/commands/cmd-project.js

@@ -0,0 +1,100 @@
+/**
+ * cmd-project.js: Persistent Coordinator and Projects CLI Handler
+ * Dispatches init, status, step, chat, pause, resume, and learnings
+ */
+
+import { openIndexDb } from '../search-db.js';
+import {
+  initProjectSession, getActiveProjectSession, getProjectSession,
+  postProjectMessage, getProjectMessages, updateProjectSession
+} from '../team/team-projects.js';
+import { queryRelevantLearnings, formatLearningsCard } from '../team/team-projects-memory.js';
+import { executeCoordinatorStep } from '../team/team-projects-coordinator.js';
+import { formatProjectStatusCard } from '../team/team-projects-format.js';
+import { listTasks } from '../team/team-db-tasks.js';
+
+export const runProjectCli = async (rawArgs = [], isCli = false, cwd = process.cwd()) => {
+  const db = openIndexDb(cwd);
+  if (!db) {
+    if (isCli) process.stderr.write('\x1b[31m✕ SQLite database unavailable.\x1b[0m\n');
+    return null;
+  }
+
+  const isJson = rawArgs.includes('--json');
+  const nonFlag = rawArgs.filter((a) => !a.startsWith('-'));
+  const subCommand = nonFlag[0] || 'status';
+  const restText = nonFlag.slice(1).join(' ');
+
+  if (subCommand === 'init' || subCommand === 'start') {
+    const goal = restText || 'Autonomous codebase optimization';
+    const session = initProjectSession(db, { goal, title: goal.slice(0, 40) });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(session, null, 2)}\n`);
+      else process.stdout.write(`\x1b[32m✔\x1b[0m Initialized project session #${session.id}: "${session.title}"\n`);
+    }
+    return session;
+  }
+
+  if (subCommand === 'step' || subCommand === 'turn') {
+    const res = executeCoordinatorStep(db, { cwd });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+      else process.stdout.write(`\x1b[36m⚡ [Turn ${res.turn || 0}]\x1b[0m ${res.action || res.status} - Status: ${res.status}\n`);
+    }
+    return res;
+  }
+
+  if (subCommand === 'chat' || subCommand === 'msg') {
+    const active = getActiveProjectSession(db);
+    if (!active) {
+      if (isCli) process.stderr.write('\x1b[31m✕ No active project. Run "chemx project init <goal>" first.\x1b[0m\n');
+      return { error: 'no_active_session' };
+    }
+    const msg = postProjectMessage(db, {
+      projectId: active.id,
+      turnIndex: active.current_turn,
+      authorId: '@user',
+      role: 'user',
+      message: restText || 'Status report'
+    });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(msg, null, 2)}\n`);
+      else process.stdout.write(`\x1b[32m✔\x1b[0m Sent message to coordinator: "${msg.message}"\n`);
+    }
+    return msg;
+  }
+
+  if (subCommand === 'learnings' || subCommand === 'memory') {
+    const learnings = queryRelevantLearnings(db, { limit: 10 });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(learnings, null, 2)}\n`);
+      else process.stdout.write(formatLearningsCard(learnings));
+    }
+    return learnings;
+  }
+
+  if (subCommand === 'pause' || subCommand === 'resume') {
+    const active = getActiveProjectSession(db);
+    if (!active) return null;
+    const newStatus = subCommand === 'pause' ? 'paused' : 'active';
+    const updated = updateProjectSession(db, active.id, { status: newStatus });
+    if (isCli) process.stdout.write(`\x1b[32m✔\x1b[0m Project #${active.id} status updated to: ${newStatus}\n`);
+    return updated;
+  }
+
+  // Default: status
+  const session = getActiveProjectSession(db);
+  const messages = session ? getProjectMessages(db, session.id, 5) : [];
+  const activeTasks = session ? listTasks(db, { status: 'in_progress' }) : [];
+  const learnings = queryRelevantLearnings(db, { limit: 5 });
+
+  if (isJson) {
+    const payload = { session, messages, activeTasks, learnings };
+    if (isCli) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return payload;
+  }
+
+  const card = formatProjectStatusCard({ session, messages, activeTasks, learnings });
+  if (isCli) process.stdout.write(card);
+  return { session, messages, activeTasks, learnings };
+};

package/cli/commands/cmd-router.js

@@ -1,5 +1,5 @@
 /**
- * cmd-router.js — CLI command dispatch table.
+ * cmd-router.js: CLI command dispatch table.
  * Single responsibility: map first-arg tokens to their lazy-loaded command handlers.
  * Extracted from cli/index.js per Directive 1.A (Monolith Decomposition).
  */
@@ -23,6 +23,25 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       runTeamCli(rawArgs.slice(1), true);
       break;
     }
+    case 'project':
+    case 'coordinator': {
+      const { runProjectCli } = await import('./cmd-project.js');
+      await runProjectCli(rawArgs.slice(1), true);
+      break;
+    }
+    case 'tokens':
+    case 'telemetry': {
+      const { runTeamCli } = await import('../team/index.js');
+      runTeamCli(['tokens', ...rawArgs.slice(1)], true);
+      break;
+    }
+    case 'benchmark':
+    case 'ablation':
+    case 'memory': {
+      const { runTeamCli } = await import('../team/index.js');
+      runTeamCli(['benchmark', ...rawArgs.slice(1)], true);
+      break;
+    }
     case 'mcp':
     case 'mcp-server':
     case 'server': {
@@ -31,7 +50,8 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       break;
     }
     case 'read':
-    case 'view': {
+    case 'view':
+    case 'r': {
       const { runReaderCli } = await import('../reader.js');
       runReaderCli(rawArgs.slice(1), true);
       break;
@@ -67,6 +87,12 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       await runAudit(posDir, true);
       break;
     }
+    case 'trend':
+    case 'trends': {
+      const { runTrend } = await import('../trend.js');
+      runTrend(rawArgs.slice(1), process.cwd());
+      break;
+    }
     case 'init': {
       const { runInit } = await import('../scaffold.js');
       await runInit(rawArgs[1] || 'src/chemical-x', rawArgs, runAudit);
@@ -107,6 +133,12 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       await runMutatorCli(rawArgs, true);
       break;
     }
+    case 'explode':
+    case 'unpack': {
+      const { runExplodeCli } = await import('../exploder.js');
+      await runExplodeCli(rawArgs.slice(1), true);
+      break;
+    }
     case 'add': {
       if (['prop', 'state', 'action'].includes(rawArgs[1])) {
         const { runMutatorCli } = await import('../mutators.js');

package/cli/commands-schema.js

@@ -194,5 +194,19 @@ export const COMMANDS_SCHEMA = [
       'npx chemx pillars --preset=recommended',
       'npx chemx pillars --preset=minimal --dry-run'
     ]
+  },
+  {
+    name: 'ui',
+    aliases: ['dashboard', 'preview'],
+    usage: 'npx chemx ui [options]',
+    summary: 'Launch the Chemical X interactive web dashboard.',
+    description: 'Provides real-time Kanban task boards, agent rails, live SQLite Database Studio, and codebase AST tree exploration.',
+    flags: [
+      { flag: '--port=<N>', desc: 'Server port (default: 4173)' }
+    ],
+    examples: [
+      'npx chemx ui',
+      'npx chemx dashboard --port=3000'
+    ]
   }
 ];

package/cli/create.spec.js

@@ -63,7 +63,7 @@ describe('Scaffolding Entrypoint Invocations', () => {
     const result = spawnSync('node', [CREATE_BIN, '--help'], {
       encoding: 'utf-8',
       cwd: tmpBase,
-      timeout: 5000
+      timeout: 15000
     });
 
     assert.equal(result.status, 0, 'Should exit with code 0 on --help');
@@ -78,7 +78,7 @@ describe('Scaffolding Entrypoint Invocations', () => {
     const result = spawnSync('node', [CREATE_BIN, '--version'], {
       encoding: 'utf-8',
       cwd: tmpBase,
-      timeout: 5000
+      timeout: 15000
     });
 
     assert.equal(result.status, 0, 'Should exit with code 0 on --version');