@massu/core 0.1.0 → 0.1.1

package/src/__tests__/validation-engine.test.ts

@@ -0,0 +1,300 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Database from 'better-sqlite3';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import {
+  getValidationToolDefinitions,
+  isValidationTool,
+  validateFile,
+  storeValidationResult,
+  handleValidationToolCall,
+  type ValidationCheck,
+} from '../validation-engine.ts';
+
+function createTestDb(): Database.Database {
+  const db = new Database(':memory:');
+  db.pragma('journal_mode = WAL');
+
+  db.exec(`
+    CREATE TABLE sessions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT UNIQUE NOT NULL,
+      started_at TEXT NOT NULL,
+      started_at_epoch INTEGER NOT NULL
+    );
+
+    CREATE TABLE validation_results (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT,
+      file_path TEXT NOT NULL,
+      validation_type TEXT NOT NULL,
+      passed INTEGER NOT NULL DEFAULT 1,
+      details TEXT,
+      rules_violated TEXT,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+  `);
+
+  return db;
+}
+
+describe('validation-engine', () => {
+  let db: Database.Database;
+  let testDir: string;
+
+  beforeEach(() => {
+    db = createTestDb();
+    testDir = join('/tmp', 'massu-test-' + Math.random().toString(36).slice(2));
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    db.close();
+    try {
+      rmSync(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('getValidationToolDefinitions', () => {
+    it('should return tool definitions for validation tools', () => {
+      const defs = getValidationToolDefinitions();
+      expect(defs.length).toBe(2);
+
+      const names = defs.map(d => d.name);
+      expect(names.some(n => n.includes('validation_check'))).toBe(true);
+      expect(names.some(n => n.includes('validation_report'))).toBe(true);
+
+      for (const def of defs) {
+        expect(def.name).toBeTruthy();
+        expect(def.description).toBeTruthy();
+        expect(def.inputSchema).toBeTruthy();
+        expect(def.inputSchema.type).toBe('object');
+      }
+    });
+  });
+
+  describe('isValidationTool', () => {
+    it('should return true for validation tools', () => {
+      expect(isValidationTool('massu_validation_check')).toBe(true);
+      expect(isValidationTool('massu_validation_report')).toBe(true);
+    });
+
+    it('should return false for non-validation tools', () => {
+      expect(isValidationTool('massu_cost_session')).toBe(false);
+      expect(isValidationTool('massu_quality_score')).toBe(false);
+      expect(isValidationTool('random_tool')).toBe(false);
+    });
+
+    it('should handle base names without prefix', () => {
+      expect(isValidationTool('validation_check')).toBe(true);
+      expect(isValidationTool('validation_report')).toBe(true);
+    });
+  });
+
+  describe('validateFile', () => {
+    it('should return error check for non-existent file', () => {
+      const filePath = join(testDir, 'nonexistent.ts');
+      const checks = validateFile(filePath, testDir);
+
+      expect(checks.length).toBeGreaterThan(0);
+      const fileCheck = checks.find(c => c.name === 'file_exists');
+      expect(fileCheck).toBeDefined();
+      expect(fileCheck?.severity).toBe('error');
+    });
+
+    it('should block path traversal attempts', () => {
+      const filePath = '../../../etc/passwd';
+      const checks = validateFile(filePath, testDir);
+
+      expect(checks.length).toBeGreaterThan(0);
+      const pathCheck = checks.find(c => c.name === 'path_traversal');
+      expect(pathCheck).toBeDefined();
+      expect(pathCheck?.severity).toBe('critical');
+    });
+
+    it('should validate existing file', () => {
+      const filePath = join(testDir, 'test.ts');
+      writeFileSync(filePath, `
+// Simple test file
+export function hello() {
+  return "world";
+}
+      `.trim());
+
+      const checks = validateFile(filePath, testDir);
+
+      // Should not have critical errors
+      const criticalErrors = checks.filter(c => c.severity === 'critical' || c.severity === 'error');
+      expect(criticalErrors.length).toBe(0);
+    });
+
+    it('should detect import hallucinations', () => {
+      const filePath = join(testDir, 'imports.ts');
+      writeFileSync(filePath, `
+import { something } from './nonexistent.ts';
+import { other } from '@/fake-module.ts';
+      `.trim());
+
+      const checks = validateFile(filePath, testDir);
+
+      const importErrors = checks.filter(c => c.name === 'import_hallucination');
+      expect(importErrors.length).toBeGreaterThan(0);
+      expect(importErrors[0].severity).toBe('error');
+    });
+  });
+
+  describe('storeValidationResult', () => {
+    it('should store validation result in database', () => {
+      const sessionId = 'test-session-1';
+      db.prepare('INSERT INTO sessions (session_id, started_at, started_at_epoch) VALUES (?, ?, ?)').run(
+        sessionId,
+        new Date().toISOString(),
+        Math.floor(Date.now() / 1000)
+      );
+
+      const checks: ValidationCheck[] = [
+        {
+          name: 'import_hallucination',
+          severity: 'error',
+          message: 'Import not found',
+          line: 1,
+          file: 'test.ts',
+        },
+        {
+          name: 'rule_compliance',
+          severity: 'warning',
+          message: 'Rule violation',
+          file: 'test.ts',
+        },
+      ];
+
+      storeValidationResult(db, 'test.ts', checks, sessionId);
+
+      const results = db.prepare('SELECT * FROM validation_results WHERE session_id = ?').all(sessionId) as Array<Record<string, unknown>>;
+      expect(results.length).toBe(1);
+      expect(results[0].file_path).toBe('test.ts');
+      expect(results[0].passed).toBe(0); // Has errors
+      expect(results[0].details).toBeTruthy();
+
+      const details = JSON.parse(results[0].details as string);
+      expect(details.length).toBe(2);
+    });
+
+    it('should mark as passed when no errors', () => {
+      const sessionId = 'test-session-2';
+      db.prepare('INSERT INTO sessions (session_id, started_at, started_at_epoch) VALUES (?, ?, ?)').run(
+        sessionId,
+        new Date().toISOString(),
+        Math.floor(Date.now() / 1000)
+      );
+
+      const checks: ValidationCheck[] = [
+        {
+          name: 'rule_applicable',
+          severity: 'info',
+          message: 'Rule applies',
+          file: 'test.ts',
+        },
+      ];
+
+      storeValidationResult(db, 'test.ts', checks, sessionId);
+
+      const results = db.prepare('SELECT * FROM validation_results WHERE session_id = ?').all(sessionId) as Array<Record<string, unknown>>;
+      expect(results.length).toBe(1);
+      expect(results[0].passed).toBe(1); // No errors
+    });
+
+    it('should record violated rules', () => {
+      const sessionId = 'test-session-3';
+      db.prepare('INSERT INTO sessions (session_id, started_at, started_at_epoch) VALUES (?, ?, ?)').run(
+        sessionId,
+        new Date().toISOString(),
+        Math.floor(Date.now() / 1000)
+      );
+
+      const checks: ValidationCheck[] = [
+        {
+          name: 'import_hallucination',
+          severity: 'error',
+          message: 'Import not found',
+          file: 'test.ts',
+        },
+        {
+          name: 'db_access_pattern',
+          severity: 'warning',
+          message: 'Wrong pattern',
+          file: 'test.ts',
+        },
+      ];
+
+      storeValidationResult(db, 'test.ts', checks, sessionId);
+
+      const results = db.prepare('SELECT * FROM validation_results WHERE session_id = ?').all(sessionId) as Array<Record<string, unknown>>;
+      expect(results[0].rules_violated).toBeTruthy();
+      expect((results[0].rules_violated as string).includes('import_hallucination')).toBe(true);
+      expect((results[0].rules_violated as string).includes('db_access_pattern')).toBe(true);
+    });
+  });
+
+  describe('handleValidationToolCall', () => {
+    it('should handle validation_check tool call for non-existent file', () => {
+      const filePath = join(testDir, 'nonexistent.ts');
+      const result = handleValidationToolCall('massu_validation_check', { file: filePath }, db);
+
+      expect(result.content).toBeDefined();
+      expect(result.content.length).toBeGreaterThan(0);
+      expect(result.content[0].type).toBe('text');
+      const text = result.content[0].text;
+      expect(text).toContain('Validation');
+      expect(text).toContain('Errors');
+    });
+
+    it('should return error for missing file parameter', () => {
+      const result = handleValidationToolCall('massu_validation_check', {}, db);
+
+      expect(result.content).toBeDefined();
+      expect(result.content[0].type).toBe('text');
+      expect(result.content[0].text).toContain('Usage');
+    });
+
+    it('should handle validation_report tool call', () => {
+      const sessionId = 'report-session';
+      db.prepare('INSERT INTO sessions (session_id, started_at, started_at_epoch) VALUES (?, ?, ?)').run(
+        sessionId,
+        new Date().toISOString(),
+        Math.floor(Date.now() / 1000)
+      );
+
+      const checks: ValidationCheck[] = [
+        {
+          name: 'test_error',
+          severity: 'error',
+          message: 'Test error',
+          file: 'test.ts',
+        },
+      ];
+
+      storeValidationResult(db, 'test.ts', checks, sessionId);
+
+      const result = handleValidationToolCall('massu_validation_report', { days: 7 }, db);
+
+      expect(result.content).toBeDefined();
+      expect(result.content[0].type).toBe('text');
+      const text = result.content[0].text;
+      expect(text).toContain('Validation Report');
+    });
+
+    it('should handle unknown tool name', () => {
+      const result = handleValidationToolCall('massu_unknown_validation_tool', {}, db);
+
+      expect(result.content).toBeDefined();
+      expect(result.content[0].type).toBe('text');
+      expect(result.content[0].text).toContain('Unknown validation tool');
+    });
+  });
+});

package/src/adr-generator.ts

@@ -0,0 +1,285 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+import type Database from 'better-sqlite3';
+import type { ToolDefinition, ToolResult } from './tool-helpers.ts';
+import { p, text } from './tool-helpers.ts';
+import { getConfig } from './config.ts';
+
+// ============================================================
+// ADR (Architecture Decision Record) Auto-Generation
+// ============================================================
+
+/** Default decision detection phrases. Configurable via governance.adr.detection_phrases */
+const DEFAULT_DETECTION_PHRASES = ['chose', 'decided', 'switching to', 'moving from', 'going with'];
+
+/**
+ * Get decision detection phrases from config or defaults.
+ */
+function getDetectionPhrases(): string[] {
+  return getConfig().governance?.adr?.detection_phrases ?? DEFAULT_DETECTION_PHRASES;
+}
+
+/**
+ * Detect decision patterns in text.
+ */
+export function detectDecisionPatterns(text: string): boolean {
+  const phrases = getDetectionPhrases();
+  const lower = text.toLowerCase();
+  return phrases.some(phrase => lower.includes(phrase));
+}
+
+/**
+ * Extract alternatives from a decision description.
+ */
+export function extractAlternatives(description: string): string[] {
+  const alternatives: string[] = [];
+
+  // Pattern: "X over Y"
+  const overMatch = description.match(/(\w[\w\s-]+)\s+over\s+(\w[\w\s-]+)/i);
+  if (overMatch) {
+    alternatives.push(overMatch[1].trim());
+    alternatives.push(overMatch[2].trim());
+  }
+
+  // Pattern: "X instead of Y"
+  const insteadMatch = description.match(/(\w[\w\s-]+)\s+instead\s+of\s+(\w[\w\s-]+)/i);
+  if (insteadMatch) {
+    alternatives.push(insteadMatch[1].trim());
+    alternatives.push(insteadMatch[2].trim());
+  }
+
+  // Pattern: "switching from X to Y"
+  const switchMatch = description.match(/switching\s+from\s+(\w[\w\s-]+)\s+to\s+(\w[\w\s-]+)/i);
+  if (switchMatch) {
+    alternatives.push(switchMatch[2].trim()); // Chosen
+    alternatives.push(switchMatch[1].trim()); // Rejected
+  }
+
+  return [...new Set(alternatives)];
+}
+
+/**
+ * Store an architecture decision.
+ */
+export function storeDecision(
+  db: Database.Database,
+  decision: {
+    title: string;
+    context: string;
+    decision: string;
+    alternatives: string[];
+    consequences: string;
+    sessionId?: string;
+    status?: string;
+  }
+): number {
+  const result = db.prepare(`
+    INSERT INTO architecture_decisions
+    (title, context, decision, alternatives, consequences, session_id, status)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    decision.title,
+    decision.context,
+    decision.decision,
+    JSON.stringify(decision.alternatives),
+    decision.consequences,
+    decision.sessionId ?? null,
+    decision.status ?? 'accepted'
+  );
+
+  return Number(result.lastInsertRowid);
+}
+
+// ============================================================
+// MCP Tool Definitions & Handlers
+// ============================================================
+
+export function getAdrToolDefinitions(): ToolDefinition[] {
+  return [
+    {
+      name: p('adr_list'),
+      description: 'List all recorded architecture decisions. Filter by status or search text.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          status: { type: 'string', description: 'Filter by status: accepted, superseded, deprecated' },
+          search: { type: 'string', description: 'Search in title and context' },
+        },
+        required: [],
+      },
+    },
+    {
+      name: p('adr_detail'),
+      description: 'Get full details of a specific architecture decision by ID.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          id: { type: 'number', description: 'ADR ID' },
+        },
+        required: ['id'],
+      },
+    },
+    {
+      name: p('adr_create'),
+      description: 'Generate an ADR from a description. Extracts alternatives, context, and consequences.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: 'Decision title' },
+          context: { type: 'string', description: 'Why was this decision needed?' },
+          decision: { type: 'string', description: 'What was decided?' },
+          consequences: { type: 'string', description: 'What are the consequences?' },
+        },
+        required: ['title', 'decision'],
+      },
+    },
+  ];
+}
+
+const ADR_BASE_NAMES = new Set(['adr_list', 'adr_detail', 'adr_create']);
+
+export function isAdrTool(name: string): boolean {
+  const pfx = getConfig().toolPrefix + '_';
+  const baseName = name.startsWith(pfx) ? name.slice(pfx.length) : name;
+  return ADR_BASE_NAMES.has(baseName);
+}
+
+export function handleAdrToolCall(
+  name: string,
+  args: Record<string, unknown>,
+  memoryDb: Database.Database
+): ToolResult {
+  try {
+    const pfx = getConfig().toolPrefix + '_';
+    const baseName = name.startsWith(pfx) ? name.slice(pfx.length) : name;
+
+    switch (baseName) {
+      case 'adr_list':
+        return handleAdrList(args, memoryDb);
+      case 'adr_detail':
+        return handleAdrDetail(args, memoryDb);
+      case 'adr_create':
+        return handleAdrGenerate(args, memoryDb);
+      default:
+        return text(`Unknown ADR tool: ${name}`);
+    }
+  } catch (error) {
+    return text(`Error in ${name}: ${error instanceof Error ? error.message : String(error)}\n\nUsage: ${p('adr_list')} {}, ${p('adr_create')} { title: "...", decision: "..." }`);
+  }
+}
+
+function handleAdrList(args: Record<string, unknown>, db: Database.Database): ToolResult {
+  let sql = 'SELECT id, title, status, created_at FROM architecture_decisions WHERE 1=1';
+  const params: string[] = [];
+
+  if (args.status) {
+    sql += ' AND status = ?';
+    params.push(args.status as string);
+  }
+
+  if (args.search) {
+    sql += ' AND (title LIKE ? OR context LIKE ?)';
+    const searchTerm = `%${args.search}%`;
+    params.push(searchTerm, searchTerm);
+  }
+
+  sql += ' ORDER BY created_at DESC';
+
+  const decisions = db.prepare(sql).all(...params) as Array<Record<string, unknown>>;
+
+  if (decisions.length === 0) {
+    return text(`No architecture decisions found. Decisions are recorded when you use ${p('adr_create')} during design discussions. Try: ${p('adr_create')} { title: "Use Redis for caching", decision: "We chose Redis over Memcached" }`);
+  }
+
+  const lines = [
+    `## Architecture Decisions (${decisions.length})`,
+    '',
+    '| ID | Title | Status | Date |',
+    '|----|-------|--------|------|',
+  ];
+
+  for (const d of decisions) {
+    lines.push(`| ${d.id} | ${d.title} | ${d.status} | ${(d.created_at as string).slice(0, 10)} |`);
+  }
+
+  return text(lines.join('\n'));
+}
+
+function handleAdrDetail(args: Record<string, unknown>, db: Database.Database): ToolResult {
+  const id = args.id as number;
+  if (!id) return text(`Usage: ${p('adr_detail')} { id: 1 } - Get full details of an architecture decision.`);
+
+  const decision = db.prepare(
+    'SELECT * FROM architecture_decisions WHERE id = ?'
+  ).get(id) as Record<string, unknown> | undefined;
+
+  if (!decision) {
+    return text(`ADR #${id} not found. Decisions are stored when created via ${p('adr_create')}. Try: ${p('adr_list')} {} to see all recorded decisions.`);
+  }
+
+  const alternatives = JSON.parse((decision.alternatives as string) || '[]') as string[];
+
+  const lines = [
+    `# ADR-${decision.id}: ${decision.title}`,
+    `Status: ${decision.status}`,
+    `Date: ${(decision.created_at as string).slice(0, 10)}`,
+    '',
+    '## Context',
+    decision.context as string || 'Not specified',
+    '',
+    '## Decision',
+    decision.decision as string,
+    '',
+  ];
+
+  if (alternatives.length > 0) {
+    lines.push('## Alternatives Considered');
+    for (const alt of alternatives) {
+      lines.push(`- ${alt}`);
+    }
+    lines.push('');
+  }
+
+  if (decision.consequences) {
+    lines.push('## Consequences');
+    lines.push(decision.consequences as string);
+  }
+
+  return text(lines.join('\n'));
+}
+
+function handleAdrGenerate(args: Record<string, unknown>, db: Database.Database): ToolResult {
+  const title = args.title as string;
+  const decisionText = args.decision as string;
+  if (!title || !decisionText) return text(`Usage: ${p('adr_create')} { title: "Use Redis for caching", decision: "We chose Redis over Memcached for caching", context: "...", consequences: "..." }`);
+
+  const context = (args.context as string) ?? '';
+  const consequences = (args.consequences as string) ?? '';
+
+  // Extract alternatives from the decision text
+  const alternatives = extractAlternatives(decisionText);
+
+  const id = storeDecision(db, {
+    title,
+    context,
+    decision: decisionText,
+    alternatives,
+    consequences,
+  });
+
+  const lines = [
+    `## ADR-${id} Created: ${title}`,
+    '',
+    `**Status**: accepted`,
+    `**Decision**: ${decisionText}`,
+    alternatives.length > 0 ? `**Alternatives**: ${alternatives.join(', ')}` : '',
+    context ? `**Context**: ${context}` : '',
+    consequences ? `**Consequences**: ${consequences}` : '',
+    '',
+    `View full details: ${p('adr_detail')} { id: ${id} }`,
+  ];
+
+  return text(lines.filter(Boolean).join('\n'));
+}
+