@timmeck/brain 1.2.0 → 1.8.0

package/src/api/server.ts

@@ -0,0 +1,321 @@
+import http from 'node:http';
+import { getLogger } from '../utils/logger.js';
+import type { IpcRouter } from '../ipc/router.js';
+
+export interface ApiServerOptions {
+  port: number;
+  router: IpcRouter;
+  apiKey?: string;
+}
+
+interface RouteDefinition {
+  method: string;
+  pattern: RegExp;
+  ipcMethod: string;
+  extractParams: (match: RegExpMatchArray, query: URLSearchParams, body?: unknown) => unknown;
+}
+
+export class ApiServer {
+  private server: http.Server | null = null;
+  private logger = getLogger();
+  private routes: RouteDefinition[];
+
+  constructor(private options: ApiServerOptions) {
+    this.routes = this.buildRoutes();
+  }
+
+  start(): void {
+    const { port, apiKey } = this.options;
+
+    this.server = http.createServer((req, res) => {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-API-Key');
+
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      if (apiKey) {
+        const provided = (req.headers['x-api-key'] as string) ??
+          req.headers.authorization?.replace('Bearer ', '');
+        if (provided !== apiKey) {
+          this.json(res, 401, { error: 'Unauthorized', message: 'Invalid or missing API key' });
+          return;
+        }
+      }
+
+      this.handleRequest(req, res).catch((err) => {
+        this.logger.error('API error:', err);
+        this.json(res, 500, {
+          error: 'Internal Server Error',
+          message: err instanceof Error ? err.message : String(err),
+        });
+      });
+    });
+
+    this.server.listen(port, () => {
+      this.logger.info(`REST API server started on http://localhost:${port}`);
+    });
+  }
+
+  stop(): void {
+    this.server?.close();
+    this.server = null;
+    this.logger.info('REST API server stopped');
+  }
+
+  private async handleRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const pathname = url.pathname;
+    const method = req.method ?? 'GET';
+    const query = url.searchParams;
+
+    // Health check
+    if (pathname === '/api/v1/health') {
+      this.json(res, 200, { status: 'ok', timestamp: new Date().toISOString() });
+      return;
+    }
+
+    // List all available methods
+    if (pathname === '/api/v1/methods' && method === 'GET') {
+      const methods = this.options.router.listMethods();
+      this.json(res, 200, {
+        methods,
+        rpcEndpoint: '/api/v1/rpc',
+        usage: 'POST /api/v1/rpc with body { "method": "<method>", "params": {...} }',
+      });
+      return;
+    }
+
+    // Generic RPC endpoint — the universal gateway
+    if (pathname === '/api/v1/rpc' && method === 'POST') {
+      const body = await this.readBody(req);
+      if (!body) {
+        this.json(res, 400, { error: 'Bad Request', message: 'Empty request body' });
+        return;
+      }
+
+      const parsed = JSON.parse(body);
+
+      // Batch RPC support
+      if (Array.isArray(parsed)) {
+        const results = parsed.map((call: { method: string; params?: unknown; id?: string | number }) => {
+          try {
+            const result = this.options.router.handle(call.method, call.params ?? {});
+            return { id: call.id, result };
+          } catch (err) {
+            return { id: call.id, error: err instanceof Error ? err.message : String(err) };
+          }
+        });
+        this.json(res, 200, results);
+        return;
+      }
+
+      if (!parsed.method) {
+        this.json(res, 400, { error: 'Bad Request', message: 'Missing "method" field' });
+        return;
+      }
+
+      try {
+        const result = this.options.router.handle(parsed.method, parsed.params ?? {});
+        this.json(res, 200, { result });
+      } catch (err) {
+        this.json(res, 400, { error: err instanceof Error ? err.message : String(err) });
+      }
+      return;
+    }
+
+    // RESTful routes
+    let body: unknown = undefined;
+    if (method === 'POST' || method === 'PUT') {
+      try {
+        const raw = await this.readBody(req);
+        body = raw ? JSON.parse(raw) : {};
+      } catch {
+        this.json(res, 400, { error: 'Bad Request', message: 'Invalid JSON body' });
+        return;
+      }
+    }
+
+    for (const route of this.routes) {
+      if (route.method !== method) continue;
+      const match = pathname.match(route.pattern);
+      if (!match) continue;
+
+      try {
+        const params = route.extractParams(match, query, body);
+        const result = this.options.router.handle(route.ipcMethod, params);
+        this.json(res, method === 'POST' ? 201 : 200, { result });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const status = msg.startsWith('Unknown method') ? 404 : 400;
+        this.json(res, status, { error: msg });
+      }
+      return;
+    }
+
+    this.json(res, 404, { error: 'Not Found', message: `No route for ${method} ${pathname}` });
+  }
+
+  private buildRoutes(): RouteDefinition[] {
+    return [
+      // ─── Errors ────────────────────────────────────────────
+      { method: 'POST', pattern: /^\/api\/v1\/errors$/, ipcMethod: 'error.report',
+        extractParams: (_m, _q, body) => body },
+      { method: 'GET', pattern: /^\/api\/v1\/errors$/, ipcMethod: 'error.query',
+        extractParams: (_m, q) => ({
+          search: q.get('search') ?? '',
+          projectId: q.get('projectId') ? Number(q.get('projectId')) : undefined,
+        }) },
+      { method: 'GET', pattern: /^\/api\/v1\/errors\/(\d+)$/, ipcMethod: 'error.get',
+        extractParams: (m) => ({ id: Number(m[1]) }) },
+      { method: 'GET', pattern: /^\/api\/v1\/errors\/(\d+)\/match$/, ipcMethod: 'error.match',
+        extractParams: (m) => ({ errorId: Number(m[1]) }) },
+      { method: 'GET', pattern: /^\/api\/v1\/errors\/(\d+)\/chain$/, ipcMethod: 'error.chain',
+        extractParams: (m) => ({ errorId: Number(m[1]) }) },
+      { method: 'POST', pattern: /^\/api\/v1\/errors\/(\d+)\/resolve$/, ipcMethod: 'error.resolve',
+        extractParams: (m, _q, body) => ({ errorId: Number(m[1]), ...(body as object) }) },
+
+      // ─── Solutions ─────────────────────────────────────────
+      { method: 'POST', pattern: /^\/api\/v1\/solutions$/, ipcMethod: 'solution.report',
+        extractParams: (_m, _q, body) => body },
+      { method: 'GET', pattern: /^\/api\/v1\/solutions$/, ipcMethod: 'solution.query',
+        extractParams: (_m, q) => ({
+          errorId: q.get('errorId') ? Number(q.get('errorId')) : undefined,
+        }) },
+      { method: 'POST', pattern: /^\/api\/v1\/solutions\/rate$/, ipcMethod: 'solution.rate',
+        extractParams: (_m, _q, body) => body },
+      { method: 'GET', pattern: /^\/api\/v1\/solutions\/efficiency$/, ipcMethod: 'solution.efficiency',
+        extractParams: () => ({}) },
+
+      // ─── Projects ──────────────────────────────────────────
+      { method: 'GET', pattern: /^\/api\/v1\/projects$/, ipcMethod: 'project.list',
+        extractParams: () => ({}) },
+
+      // ─── Code ──────────────────────────────────────────────
+      { method: 'POST', pattern: /^\/api\/v1\/code\/analyze$/, ipcMethod: 'code.analyze',
+        extractParams: (_m, _q, body) => body },
+      { method: 'POST', pattern: /^\/api\/v1\/code\/find$/, ipcMethod: 'code.find',
+        extractParams: (_m, _q, body) => body },
+      { method: 'POST', pattern: /^\/api\/v1\/code\/similarity$/, ipcMethod: 'code.similarity',
+        extractParams: (_m, _q, body) => body },
+      { method: 'GET', pattern: /^\/api\/v1\/code\/modules$/, ipcMethod: 'code.modules',
+        extractParams: (_m, q) => ({
+          projectId: q.get('projectId') ? Number(q.get('projectId')) : undefined,
+          language: q.get('language') ?? undefined,
+          limit: q.get('limit') ? Number(q.get('limit')) : undefined,
+        }) },
+      { method: 'GET', pattern: /^\/api\/v1\/code\/(\d+)$/, ipcMethod: 'code.get',
+        extractParams: (m) => ({ id: Number(m[1]) }) },
+
+      // ─── Prevention ────────────────────────────────────────
+      { method: 'POST', pattern: /^\/api\/v1\/prevention\/check$/, ipcMethod: 'prevention.check',
+        extractParams: (_m, _q, body) => body },
+      { method: 'POST', pattern: /^\/api\/v1\/prevention\/antipatterns$/, ipcMethod: 'prevention.antipatterns',
+        extractParams: (_m, _q, body) => body },
+      { method: 'POST', pattern: /^\/api\/v1\/prevention\/code$/, ipcMethod: 'prevention.checkCode',
+        extractParams: (_m, _q, body) => body },
+
+      // ─── Synapses ─────────────────────────────────────────
+      { method: 'GET', pattern: /^\/api\/v1\/synapses\/context\/(\d+)$/, ipcMethod: 'synapse.context',
+        extractParams: (m) => ({ errorId: Number(m[1]) }) },
+      { method: 'POST', pattern: /^\/api\/v1\/synapses\/path$/, ipcMethod: 'synapse.path',
+        extractParams: (_m, _q, body) => body },
+      { method: 'POST', pattern: /^\/api\/v1\/synapses\/related$/, ipcMethod: 'synapse.related',
+        extractParams: (_m, _q, body) => body },
+      { method: 'GET', pattern: /^\/api\/v1\/synapses\/stats$/, ipcMethod: 'synapse.stats',
+        extractParams: () => ({}) },
+
+      // ─── Research ──────────────────────────────────────────
+      { method: 'GET', pattern: /^\/api\/v1\/research\/insights$/, ipcMethod: 'research.insights',
+        extractParams: (_m, q) => ({
+          type: q.get('type') ?? undefined,
+          limit: q.get('limit') ? Number(q.get('limit')) : 20,
+          activeOnly: q.get('activeOnly') !== 'false',
+        }) },
+      { method: 'POST', pattern: /^\/api\/v1\/research\/insights\/(\d+)\/rate$/, ipcMethod: 'insight.rate',
+        extractParams: (m, _q, body) => ({ id: Number(m[1]), ...(body as object) }) },
+      { method: 'GET', pattern: /^\/api\/v1\/research\/suggest$/, ipcMethod: 'research.suggest',
+        extractParams: (_m, q) => ({
+          context: q.get('context') ?? '',
+          limit: 10,
+          activeOnly: true,
+        }) },
+      { method: 'GET', pattern: /^\/api\/v1\/research\/trends$/, ipcMethod: 'research.trends',
+        extractParams: (_m, q) => ({
+          projectId: q.get('projectId') ? Number(q.get('projectId')) : undefined,
+          windowDays: q.get('windowDays') ? Number(q.get('windowDays')) : undefined,
+        }) },
+
+      // ─── Notifications ────────────────────────────────────
+      { method: 'GET', pattern: /^\/api\/v1\/notifications$/, ipcMethod: 'notification.list',
+        extractParams: (_m, q) => ({
+          projectId: q.get('projectId') ? Number(q.get('projectId')) : undefined,
+        }) },
+      { method: 'POST', pattern: /^\/api\/v1\/notifications\/(\d+)\/ack$/, ipcMethod: 'notification.ack',
+        extractParams: (m) => ({ id: Number(m[1]) }) },
+
+      // ─── Analytics ─────────────────────────────────────────
+      { method: 'GET', pattern: /^\/api\/v1\/analytics\/summary$/, ipcMethod: 'analytics.summary',
+        extractParams: (_m, q) => ({
+          projectId: q.get('projectId') ? Number(q.get('projectId')) : undefined,
+        }) },
+      { method: 'GET', pattern: /^\/api\/v1\/analytics\/network$/, ipcMethod: 'analytics.network',
+        extractParams: (_m, q) => ({
+          limit: q.get('limit') ? Number(q.get('limit')) : undefined,
+        }) },
+      { method: 'GET', pattern: /^\/api\/v1\/analytics\/health$/, ipcMethod: 'analytics.health',
+        extractParams: (_m, q) => ({
+          projectId: q.get('projectId') ? Number(q.get('projectId')) : undefined,
+        }) },
+      { method: 'GET', pattern: /^\/api\/v1\/analytics\/timeline$/, ipcMethod: 'analytics.timeline',
+        extractParams: (_m, q) => ({
+          projectId: q.get('projectId') ? Number(q.get('projectId')) : undefined,
+          days: q.get('days') ? Number(q.get('days')) : undefined,
+        }) },
+      { method: 'GET', pattern: /^\/api\/v1\/analytics\/explain\/(\d+)$/, ipcMethod: 'analytics.explain',
+        extractParams: (m) => ({ errorId: Number(m[1]) }) },
+
+      // ─── Git ───────────────────────────────────────────────
+      { method: 'GET', pattern: /^\/api\/v1\/git\/context$/, ipcMethod: 'git.context',
+        extractParams: (_m, q) => ({ cwd: q.get('cwd') ?? undefined }) },
+      { method: 'POST', pattern: /^\/api\/v1\/git\/link-error$/, ipcMethod: 'git.linkError',
+        extractParams: (_m, _q, body) => body },
+      { method: 'GET', pattern: /^\/api\/v1\/git\/errors\/(\d+)\/commits$/, ipcMethod: 'git.errorCommits',
+        extractParams: (m) => ({ errorId: Number(m[1]) }) },
+      { method: 'GET', pattern: /^\/api\/v1\/git\/commits\/([a-f0-9]+)\/errors$/, ipcMethod: 'git.commitErrors',
+        extractParams: (m) => ({ commitHash: m[1] }) },
+      { method: 'GET', pattern: /^\/api\/v1\/git\/diff$/, ipcMethod: 'git.diff',
+        extractParams: (_m, q) => ({ cwd: q.get('cwd') ?? undefined }) },
+
+      // ─── Terminal ──────────────────────────────────────────
+      { method: 'POST', pattern: /^\/api\/v1\/terminal\/register$/, ipcMethod: 'terminal.register',
+        extractParams: (_m, _q, body) => body },
+      { method: 'POST', pattern: /^\/api\/v1\/terminal\/heartbeat$/, ipcMethod: 'terminal.heartbeat',
+        extractParams: (_m, _q, body) => body },
+      { method: 'POST', pattern: /^\/api\/v1\/terminal\/disconnect$/, ipcMethod: 'terminal.disconnect',
+        extractParams: (_m, _q, body) => body },
+
+      // ─── Learning ──────────────────────────────────────────
+      { method: 'POST', pattern: /^\/api\/v1\/learning\/run$/, ipcMethod: 'learning.run',
+        extractParams: () => ({}) },
+    ];
+  }
+
+  private json(res: http.ServerResponse, status: number, data: unknown): void {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(data));
+  }
+
+  private readBody(req: http.IncomingMessage): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      req.on('data', (chunk: Buffer) => chunks.push(chunk));
+      req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+      req.on('error', reject);
+    });
+  }
+}

package/src/brain.ts

@@ -30,6 +30,7 @@ import { SynapseService } from './services/synapse.service.js';
 import { ResearchService } from './services/research.service.js';
 import { NotificationService } from './services/notification.service.js';
 import { AnalyticsService } from './services/analytics.service.js';
+import { GitService } from './services/git.service.js';
 
 // Synapses
 import { SynapseManager } from './synapses/synapse-manager.js';
@@ -42,9 +43,19 @@ import { ResearchEngine } from './research/research-engine.js';
 import { IpcRouter, type Services } from './ipc/router.js';
 import { IpcServer } from './ipc/server.js';
 
+// API & MCP HTTP
+import { ApiServer } from './api/server.js';
+import { McpHttpServer } from './mcp/http-server.js';
+
+// Embeddings
+import { EmbeddingEngine } from './embeddings/engine.js';
+
 export class BrainCore {
   private db: Database.Database | null = null;
   private ipcServer: IpcServer | null = null;
+  private apiServer: ApiServer | null = null;
+  private mcpHttpServer: McpHttpServer | null = null;
+  private embeddingEngine: EmbeddingEngine | null = null;
   private learningEngine: LearningEngine | null = null;
   private researchEngine: ResearchEngine | null = null;
   private cleanupTimer: ReturnType<typeof setInterval> | null = null;
@@ -89,7 +100,7 @@ export class BrainCore {
 
     // 7. Services
     const services: Services = {
-      error: new ErrorService(errorRepo, projectRepo, synapseManager),
+      error: new ErrorService(errorRepo, projectRepo, synapseManager, config.matching),
       solution: new SolutionService(solutionRepo, synapseManager),
       terminal: new TerminalService(terminalRepo, config.terminal.staleTimeout),
       prevention: new PreventionService(ruleRepo, antipatternRepo, synapseManager),
@@ -102,9 +113,19 @@ export class BrainCore {
         ruleRepo, antipatternRepo, insightRepo,
         synapseManager,
       ),
+      git: new GitService(this.db!, synapseManager),
     };
 
-    // 8. Learning Engine
+    // 8. Embedding Engine (local vector search)
+    if (config.embeddings.enabled) {
+      this.embeddingEngine = new EmbeddingEngine(config.embeddings, this.db!);
+      this.embeddingEngine.start();
+      // Wire embedding engine into error service for hybrid search
+      services.error.setEmbeddingEngine(this.embeddingEngine);
+      logger.info('Embedding engine started (model will load in background)');
+    }
+
+    // 9. Learning Engine
     this.learningEngine = new LearningEngine(
       config.learning, errorRepo, solutionRepo,
       ruleRepo, antipatternRepo, synapseManager,
@@ -112,7 +133,7 @@ export class BrainCore {
     this.learningEngine.start();
     logger.info(`Learning engine started (interval: ${config.learning.intervalMs}ms)`);
 
-    // 9. Research Engine
+    // 10. Research Engine
     this.researchEngine = new ResearchEngine(
       config.research, errorRepo, solutionRepo, projectRepo,
       codeModuleRepo, synapseRepo, insightRepo, synapseManager,
@@ -123,24 +144,42 @@ export class BrainCore {
     // Expose learning engine to IPC
     services.learning = this.learningEngine;
 
-    // 10. IPC Server
+    // 11. IPC Server
     const router = new IpcRouter(services);
     this.ipcServer = new IpcServer(router, config.ipc.pipeName);
     this.ipcServer.start();
 
-    // 11. Terminal cleanup timer
+    // 11a. REST API Server
+    if (config.api.enabled) {
+      this.apiServer = new ApiServer({
+        port: config.api.port,
+        router,
+        apiKey: config.api.apiKey,
+      });
+      this.apiServer.start();
+      logger.info(`REST API enabled on port ${config.api.port}`);
+    }
+
+    // 11b. MCP HTTP Server (SSE transport for Cursor, Windsurf, Cline, Continue)
+    if (config.mcpHttp.enabled) {
+      this.mcpHttpServer = new McpHttpServer(config.mcpHttp.port, router);
+      this.mcpHttpServer.start();
+      logger.info(`MCP HTTP (SSE) enabled on port ${config.mcpHttp.port}`);
+    }
+
+    // 12. Terminal cleanup timer
     this.cleanupTimer = setInterval(() => {
       services.terminal.cleanup();
     }, 60_000);
 
-    // 12. Event listeners (synapse wiring)
+    // 13. Event listeners (synapse wiring)
     this.setupEventListeners(services, synapseManager);
 
-    // 13. PID file
+    // 14. PID file
     const pidPath = path.join(path.dirname(config.dbPath), 'brain.pid');
     fs.writeFileSync(pidPath, String(process.pid));
 
-    // 14. Graceful shutdown
+    // 15. Graceful shutdown
     process.on('SIGINT', () => this.stop());
     process.on('SIGTERM', () => this.stop());
 
@@ -157,7 +196,10 @@ export class BrainCore {
     }
 
     this.researchEngine?.stop();
+    this.embeddingEngine?.stop();
     this.learningEngine?.stop();
+    this.mcpHttpServer?.stop();
+    this.apiServer?.stop();
     this.ipcServer?.stop();
     this.db?.close();
 

package/src/cli/commands/dashboard.ts

@@ -9,6 +9,8 @@ export function dashboardCommand(): Command {
     .description('Generate and open the Brain dashboard with live data')
     .option('-o, --output <path>', 'Output HTML file path')
     .option('--no-open', 'Generate without opening in browser')
+    .option('-l, --live', 'Start live dashboard server with SSE updates')
+    .option('-p, --port <number>', 'Port for live dashboard', '7420')
     .action(async (opts) => {
       await withIpc(async (client) => {
         console.log(`${icons.chart}  ${c.info('Fetching data from Brain...')}`);

package/src/cli/commands/explain.ts

@@ -0,0 +1,83 @@
+import { Command } from 'commander';
+import { withIpc } from '../ipc-helper.js';
+import { c, icons } from '../colors.js';
+
+export function explainCommand(): Command {
+  return new Command('explain')
+    .description('Show everything Brain knows about an error')
+    .argument('<errorId>', 'Error ID to explain')
+    .action(async (errorId) => {
+      const id = parseInt(errorId, 10);
+      if (isNaN(id)) {
+        console.error(`${icons.error} Invalid error ID: ${errorId}`);
+        process.exit(1);
+      }
+
+      await withIpc(async (client) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result: any = await client.request('analytics.explain', { errorId: id });
+
+        if (!result.error) {
+          console.error(`${icons.error} Error #${id} not found.`);
+          return;
+        }
+
+        const err = result.error;
+        console.log();
+        console.log(`${icons.brain}  ${c.heading(`Error #${err.id} — ${err.type}`)}`);
+        console.log(`${c.dim('─'.repeat(60))}`);
+        console.log(`  ${c.label('Message:')}   ${err.message}`);
+        console.log(`  ${c.label('File:')}      ${err.file_path ?? 'unknown'}`);
+        console.log(`  ${c.label('Context:')}   ${err.context ?? 'none'}`);
+        console.log(`  ${c.label('Seen:')}      ${err.occurrence_count}x (first: ${err.first_seen}, last: ${err.last_seen})`);
+        console.log(`  ${c.label('Resolved:')}  ${err.resolved ? c.success('Yes') : c.error('No')}`);
+        console.log(`  ${c.label('Synapses:')}  ${result.synapseConnections} connections`);
+
+        // Error Chain
+        if (result.chain.parents.length > 0 || result.chain.children.length > 0) {
+          console.log();
+          console.log(`  ${c.heading('Error Chain:')}`);
+          for (const p of result.chain.parents) {
+            console.log(`    ${c.dim('↑')} Caused by: #${p.id} ${p.type}: ${p.message.slice(0, 60)}`);
+          }
+          console.log(`    ${c.info('→')} #${err.id} ${err.type}`);
+          for (const ch of result.chain.children) {
+            console.log(`    ${c.dim('↓')} Led to: #${ch.id} ${ch.type}: ${ch.message.slice(0, 60)}`);
+          }
+        }
+
+        // Solutions
+        if (result.solutions.length > 0) {
+          console.log();
+          console.log(`  ${c.heading('Solutions:')}`);
+          for (const s of result.solutions) {
+            const rate = `${Math.round(s.successRate * 100)}%`;
+            console.log(`    ${icons.ok} #${s.id}: ${s.description.slice(0, 80)} (success: ${rate}, confidence: ${s.confidence.toFixed(2)})`);
+          }
+        } else {
+          console.log();
+          console.log(`  ${c.dim('No solutions found.')}`);
+        }
+
+        // Related Errors
+        if (result.relatedErrors.length > 0) {
+          console.log();
+          console.log(`  ${c.heading('Related Errors:')}`);
+          for (const r of result.relatedErrors.slice(0, 5)) {
+            console.log(`    ${c.dim('~')} #${r.id} ${r.type}: ${r.message.slice(0, 60)} (${Math.round(r.similarity * 100)}%)`);
+          }
+        }
+
+        // Rules
+        if (result.rules.length > 0) {
+          console.log();
+          console.log(`  ${c.heading('Applicable Rules:')}`);
+          for (const r of result.rules) {
+            console.log(`    ${icons.gear} #${r.id}: ${r.action} (confidence: ${r.confidence.toFixed(2)})`);
+          }
+        }
+
+        console.log();
+      });
+    });
+}

package/src/code/analyzer.ts

@@ -10,6 +10,7 @@ export interface AnalysisResult {
   isPure: boolean;
   hasTypeAnnotations: boolean;
   linesOfCode: number;
+  complexity: number;
 }
 
 const SIDE_EFFECT_PATTERNS = [
@@ -37,6 +38,7 @@ export function analyzeCode(source: string, language: string): AnalysisResult {
   const isPure = checkPurity(source);
   const typed = parser.hasTypeAnnotations(source);
   const linesOfCode = source.split('\n').filter(l => l.trim().length > 0).length;
+  const complexity = computeCyclomaticComplexity(source, language);
 
   return {
     exports,
@@ -45,9 +47,47 @@ export function analyzeCode(source: string, language: string): AnalysisResult {
     isPure,
     hasTypeAnnotations: typed,
     linesOfCode,
+    complexity,
   };
 }
 
+/**
+ * Computes cyclomatic complexity: counts decision points in the code.
+ * CC = 1 + number of decision points (if, else if, for, while, case, catch, &&, ||, ?:)
+ */
+export function computeCyclomaticComplexity(source: string, language: string): number {
+  // Remove comments and strings to avoid false positives
+  const cleaned = source
+    .replace(/\/\/.*$/gm, '')           // single-line comments
+    .replace(/\/\*[\s\S]*?\*\//g, '')   // multi-line comments
+    .replace(/#.*$/gm, '')              // Python comments
+    .replace(/(["'`])(?:(?!\1|\\).|\\.)*\1/g, '""'); // strings
+
+  let complexity = 1; // Base complexity
+
+  // Language-agnostic decision point patterns
+  const patterns = [
+    /\bif\b/g,
+    /\belse\s+if\b/g,
+    /\belif\b/g,
+    /\bfor\b/g,
+    /\bwhile\b/g,
+    /\bcase\b/g,
+    /\bcatch\b/g,
+    /\bexcept\b/g,
+    /&&/g,
+    /\|\|/g,
+    /\?\s*[^:]/g, // ternary operator (not type annotations)
+  ];
+
+  for (const pattern of patterns) {
+    const matches = cleaned.match(pattern);
+    if (matches) complexity += matches.length;
+  }
+
+  return complexity;
+}
+
 export function checkPurity(source: string): boolean {
   return !SIDE_EFFECT_PATTERNS.some(p => source.includes(p));
 }