@lokascript/framework 2.0.0

package/src/api/dispatcher.ts

@@ -0,0 +1,222 @@
+/**
+ * Cross-Domain Dispatcher
+ *
+ * Routes natural-language input to the correct domain by trying all registered
+ * domains and picking the highest-confidence match. Supports auto-detection,
+ * composite multi-line parsing, and confidence-based routing.
+ *
+ * @example
+ * ```typescript
+ * import { DomainRegistry, CrossDomainDispatcher } from '@lokascript/framework';
+ *
+ * const registry = new DomainRegistry();
+ * registry.register(sqlDescriptor);
+ * registry.register(bddDescriptor);
+ *
+ * const dispatcher = new CrossDomainDispatcher(registry);
+ *
+ * // Auto-detect which domain handles the input
+ * const result = await dispatcher.detect('select name from users', 'en');
+ * // → { domain: 'sql', node: ..., confidence: 0.95, dsl: ... }
+ *
+ * // Parse multi-line input across domains
+ * const composite = await dispatcher.parseComposite(`
+ *   select name from users
+ *   given page http://localhost
+ * `, 'en');
+ * ```
+ */
+
+import type { SemanticNode } from '../core/types';
+import type { MultilingualDSL, CompileResult, ValidationResult } from './create-dsl';
+import { DomainRegistry } from './domain-registry';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Result of domain auto-detection */
+export interface DispatchResult {
+  /** The domain that matched */
+  readonly domain: string;
+  /** Parsed semantic node */
+  readonly node: SemanticNode;
+  /** Confidence score (0-1) */
+  readonly confidence: number;
+  /** The DSL instance that parsed it */
+  readonly dsl: MultilingualDSL;
+}
+
+/** A single statement in a composite parse result */
+export interface CompositeStatement {
+  readonly line: number;
+  readonly input: string;
+  readonly domain: string;
+  readonly node: SemanticNode;
+  readonly confidence: number;
+}
+
+/** An error from a composite parse */
+export interface CompositeError {
+  readonly line: number;
+  readonly input: string;
+  readonly message: string;
+}
+
+/** Result of multi-domain composite parsing */
+export interface CompositeParseResult {
+  /** Successfully parsed statements */
+  readonly statements: readonly CompositeStatement[];
+  /** Lines that could not be matched to any domain */
+  readonly errors: readonly CompositeError[];
+}
+
+/** Dispatcher configuration options */
+export interface DispatcherOptions {
+  /** Minimum confidence to accept a match (default: 0.5) */
+  readonly minConfidence?: number;
+  /** Domain priority order — earlier domains win on confidence ties */
+  readonly priority?: readonly string[];
+}
+
+// =============================================================================
+// Comment line detection
+// =============================================================================
+
+const COMMENT_PATTERN = /^\s*(\/\/|--|#)/;
+
+function isSkippableLine(line: string): boolean {
+  const trimmed = line.trim();
+  return trimmed === '' || COMMENT_PATTERN.test(trimmed);
+}
+
+// =============================================================================
+// CrossDomainDispatcher
+// =============================================================================
+
+/**
+ * Dispatcher that routes input to the correct domain by confidence scoring.
+ *
+ * Built on top of DomainRegistry — uses registered domains' DSL instances
+ * to try parsing input and picks the highest-confidence match.
+ */
+export class CrossDomainDispatcher {
+  private registry: DomainRegistry;
+  private minConfidence: number;
+  private priority: readonly string[];
+
+  constructor(registry: DomainRegistry, options?: DispatcherOptions) {
+    this.registry = registry;
+    this.minConfidence = options?.minConfidence ?? 0.5;
+    this.priority = options?.priority ?? [];
+  }
+
+  /**
+   * Auto-detect which domain handles the input.
+   * Tries all registered domains and returns the highest-confidence match.
+   * Returns null if no domain matches above minConfidence.
+   */
+  async detect(input: string, language = 'en'): Promise<DispatchResult | null> {
+    const domainNames = this.registry.getDomainNames();
+    if (domainNames.length === 0) return null;
+
+    const candidates: DispatchResult[] = [];
+
+    for (const name of domainNames) {
+      const dsl = await this.registry.getDSLForDomain(name);
+      if (!dsl) continue;
+
+      try {
+        const { node, confidence } = dsl.parseWithConfidence(input, language);
+        if (confidence >= this.minConfidence) {
+          candidates.push({ domain: name, node, confidence, dsl });
+        }
+      } catch {
+        // Domain could not parse this input — skip
+      }
+    }
+
+    if (candidates.length === 0) return null;
+
+    // Sort by confidence descending, break ties by priority order
+    candidates.sort((a, b) => {
+      if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+      return this.getPriorityIndex(a.domain) - this.getPriorityIndex(b.domain);
+    });
+
+    return candidates[0];
+  }
+
+  /**
+   * Parse multi-line input where each line may belong to a different domain.
+   * Empty lines and comment lines (starting with //, --, or #) are skipped.
+   */
+  async parseComposite(input: string, language = 'en'): Promise<CompositeParseResult> {
+    const lines = input.split('\n');
+    const statements: CompositeStatement[] = [];
+    const errors: CompositeError[] = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (isSkippableLine(line)) continue;
+
+      const trimmed = line.trim();
+      const result = await this.detect(trimmed, language);
+
+      if (result) {
+        statements.push({
+          line: i + 1,
+          input: trimmed,
+          domain: result.domain,
+          node: result.node,
+          confidence: result.confidence,
+        });
+      } else {
+        errors.push({
+          line: i + 1,
+          input: trimmed,
+          message: 'No domain matched this input',
+        });
+      }
+    }
+
+    return { statements, errors };
+  }
+
+  /**
+   * Compile input using auto-detected domain.
+   * Returns the compilation result with the domain name.
+   */
+  async compile(
+    input: string,
+    language = 'en'
+  ): Promise<(CompileResult & { domain: string }) | null> {
+    const detected = await this.detect(input, language);
+    if (!detected) return null;
+
+    const result = detected.dsl.compile(input, language);
+    return { ...result, domain: detected.domain };
+  }
+
+  /**
+   * Validate input against all domains, returning the best match.
+   */
+  async validate(input: string, language = 'en'): Promise<ValidationResult & { domain?: string }> {
+    const detected = await this.detect(input, language);
+    if (!detected) {
+      return { valid: false, errors: ['No domain matched this input'] };
+    }
+
+    const result = detected.dsl.validate(input, language);
+    return { ...result, domain: detected.domain };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private
+  // ---------------------------------------------------------------------------
+
+  private getPriorityIndex(domain: string): number {
+    const idx = this.priority.indexOf(domain);
+    return idx === -1 ? this.priority.length : idx;
+  }
+}

package/src/api/domain-registry.test.ts

@@ -0,0 +1,336 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { DomainRegistry } from './domain-registry';
+import type { DomainDescriptor, MCPToolDefinition } from './domain-registry';
+import type { MultilingualDSL } from './create-dsl';
+import type { SemanticNode } from '../core/types';
+
+// =============================================================================
+// Test Helpers
+// =============================================================================
+
+function createMockDSL(): MultilingualDSL {
+  return {
+    parse(input: string, language: string): SemanticNode {
+      return {
+        kind: 'command',
+        action: input.split(/\s+/)[0].toLowerCase(),
+        roles: new Map([['raw', { type: 'expression' as const, raw: input }]]),
+        metadata: { sourceLanguage: language },
+      };
+    },
+    parseWithConfidence(input: string, language: string) {
+      return { node: this.parse(input, language), confidence: 0.9 };
+    },
+    validate(input: string, language: string) {
+      try {
+        this.parse(input, language);
+        return { valid: true };
+      } catch {
+        return { valid: false, errors: ['Parse failed'] };
+      }
+    },
+    compile(input: string, language: string) {
+      try {
+        const node = this.parse(input, language);
+        return { ok: true, code: `compiled(${input})`, node };
+      } catch {
+        return { ok: false, errors: ['Compile failed'] };
+      }
+    },
+    translate(input: string, fromLanguage: string, toLanguage: string) {
+      return `[${toLanguage}] ${input}`;
+    },
+    getSupportedLanguages() {
+      return ['en', 'ja'];
+    },
+  };
+}
+
+function mockRenderer(node: SemanticNode, language: string): string {
+  return `[${language}] ${node.action}`;
+}
+
+function createTestDescriptor(overrides?: Partial<DomainDescriptor>): DomainDescriptor {
+  return {
+    name: 'test',
+    description: 'Test domain',
+    languages: ['en', 'ja'],
+    inputLabel: 'query',
+    inputDescription: 'Test query',
+    getDSL: () => createMockDSL(),
+    getRenderer: () => mockRenderer,
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Registration
+// =============================================================================
+
+describe('DomainRegistry', () => {
+  let registry: DomainRegistry;
+
+  beforeEach(() => {
+    registry = new DomainRegistry();
+  });
+
+  describe('register', () => {
+    it('registers a domain', () => {
+      registry.register(createTestDescriptor());
+      expect(registry.getDomainNames()).toEqual(['test']);
+    });
+
+    it('throws on duplicate registration', () => {
+      registry.register(createTestDescriptor());
+      expect(() => registry.register(createTestDescriptor())).toThrow(
+        'Domain already registered: test'
+      );
+    });
+
+    it('registers multiple domains', () => {
+      registry.register(createTestDescriptor({ name: 'sql' }));
+      registry.register(createTestDescriptor({ name: 'bdd' }));
+      expect(registry.getDomainNames()).toEqual(['sql', 'bdd']);
+    });
+  });
+
+  describe('getDescriptor', () => {
+    it('returns descriptor for registered domain', () => {
+      registry.register(createTestDescriptor());
+      const desc = registry.getDescriptor('test');
+      expect(desc?.name).toBe('test');
+    });
+
+    it('returns undefined for unknown domain', () => {
+      expect(registry.getDescriptor('nope')).toBeUndefined();
+    });
+  });
+
+  // =============================================================================
+  // Tool Definition Generation
+  // =============================================================================
+
+  describe('getToolDefinitions', () => {
+    it('generates 4 standard tools per domain', () => {
+      registry.register(createTestDescriptor());
+      const tools = registry.getToolDefinitions();
+      expect(tools).toHaveLength(4);
+
+      const names = tools.map(t => t.name);
+      expect(names).toContain('parse_test');
+      expect(names).toContain('compile_test');
+      expect(names).toContain('validate_test');
+      expect(names).toContain('translate_test');
+    });
+
+    it('uses domain inputLabel in tool schemas', () => {
+      registry.register(createTestDescriptor({ inputLabel: 'scenario' }));
+      const tools = registry.getToolDefinitions();
+      const parseTool = tools.find(t => t.name === 'parse_test')!;
+      expect(parseTool.inputSchema.properties).toHaveProperty('scenario');
+      expect(parseTool.inputSchema.required).toContain('scenario');
+    });
+
+    it('includes language list in descriptions', () => {
+      registry.register(createTestDescriptor({ languages: ['en', 'es', 'ja'] }));
+      const tools = registry.getToolDefinitions();
+      expect(tools[0].description).toContain('en, es, ja');
+    });
+
+    it('respects tools subset', () => {
+      registry.register(createTestDescriptor({ tools: ['parse', 'validate'] }));
+      const tools = registry.getToolDefinitions();
+      expect(tools).toHaveLength(2);
+      const names = tools.map(t => t.name);
+      expect(names).toContain('parse_test');
+      expect(names).toContain('validate_test');
+      expect(names).not.toContain('compile_test');
+    });
+
+    it('generates tools for multiple domains', () => {
+      registry.register(createTestDescriptor({ name: 'sql' }));
+      registry.register(createTestDescriptor({ name: 'bdd' }));
+      const tools = registry.getToolDefinitions();
+      expect(tools).toHaveLength(8); // 4 per domain
+    });
+  });
+
+  // =============================================================================
+  // canHandle
+  // =============================================================================
+
+  describe('canHandle', () => {
+    it('returns true for registered domain tools', () => {
+      registry.register(createTestDescriptor({ name: 'sql' }));
+      expect(registry.canHandle('parse_sql')).toBe(true);
+      expect(registry.canHandle('compile_sql')).toBe(true);
+      expect(registry.canHandle('validate_sql')).toBe(true);
+      expect(registry.canHandle('translate_sql')).toBe(true);
+    });
+
+    it('returns false for unregistered domains', () => {
+      expect(registry.canHandle('parse_sql')).toBe(false);
+    });
+
+    it('returns false for non-matching tool names', () => {
+      registry.register(createTestDescriptor({ name: 'sql' }));
+      expect(registry.canHandle('analyze_complexity')).toBe(false);
+      expect(registry.canHandle('sql_parse')).toBe(false);
+    });
+  });
+
+  // =============================================================================
+  // Tool Call Dispatch
+  // =============================================================================
+
+  describe('handleToolCall', () => {
+    it('returns null for unrecognized tool names', async () => {
+      registry.register(createTestDescriptor());
+      const result = await registry.handleToolCall('unknown_tool', {});
+      expect(result).toBeNull();
+    });
+
+    it('returns null for unregistered domains', async () => {
+      const result = await registry.handleToolCall('parse_sql', { query: 'test' });
+      expect(result).toBeNull();
+    });
+
+    describe('parse', () => {
+      it('parses input and returns semantic representation', async () => {
+        registry.register(createTestDescriptor());
+        const result = await registry.handleToolCall('parse_test', {
+          query: 'select name',
+          language: 'en',
+        });
+
+        expect(result).not.toBeNull();
+        const data = JSON.parse(result!.content[0].text);
+        expect(data.action).toBe('select');
+        expect(data.language).toBe('en');
+        expect(data.query).toBe('select name');
+      });
+
+      it('returns error for missing input', async () => {
+        registry.register(createTestDescriptor());
+        const result = await registry.handleToolCall('parse_test', {});
+        expect(result!.isError).toBe(true);
+      });
+
+      it('defaults language to en', async () => {
+        registry.register(createTestDescriptor());
+        const result = await registry.handleToolCall('parse_test', { query: 'test' });
+        const data = JSON.parse(result!.content[0].text);
+        expect(data.language).toBe('en');
+      });
+    });
+
+    describe('compile', () => {
+      it('compiles input to target code', async () => {
+        registry.register(createTestDescriptor());
+        const result = await registry.handleToolCall('compile_test', {
+          query: 'select name',
+          language: 'en',
+        });
+
+        const data = JSON.parse(result!.content[0].text);
+        expect(data.ok).toBe(true);
+        expect(data.code).toBe('compiled(select name)');
+      });
+    });
+
+    describe('validate', () => {
+      it('validates input', async () => {
+        registry.register(createTestDescriptor());
+        const result = await registry.handleToolCall('validate_test', {
+          query: 'select name',
+          language: 'en',
+        });
+
+        const data = JSON.parse(result!.content[0].text);
+        expect(data.valid).toBe(true);
+      });
+    });
+
+    describe('translate', () => {
+      it('translates between languages', async () => {
+        registry.register(createTestDescriptor());
+        const result = await registry.handleToolCall('translate_test', {
+          query: 'select name',
+          from: 'en',
+          to: 'ja',
+        });
+
+        const data = JSON.parse(result!.content[0].text);
+        expect(data.input.query).toBe('select name');
+        expect(data.input.language).toBe('en');
+        expect(data.rendered.text).toBe('[ja] select');
+        expect(data.rendered.language).toBe('ja');
+      });
+
+      it('returns error when from/to missing', async () => {
+        registry.register(createTestDescriptor());
+
+        const result1 = await registry.handleToolCall('translate_test', {
+          query: 'test',
+          to: 'ja',
+        });
+        expect(result1!.isError).toBe(true);
+
+        const result2 = await registry.handleToolCall('translate_test', {
+          query: 'test',
+          from: 'en',
+        });
+        expect(result2!.isError).toBe(true);
+      });
+
+      it('works without renderer', async () => {
+        registry.register(createTestDescriptor({ getRenderer: undefined }));
+        const result = await registry.handleToolCall('translate_test', {
+          query: 'select name',
+          from: 'en',
+          to: 'ja',
+        });
+
+        const data = JSON.parse(result!.content[0].text);
+        expect(data.semantic.action).toBe('select');
+        // No rendered field when renderer is missing
+        expect(data.rendered).toBeUndefined();
+      });
+    });
+
+    describe('error handling', () => {
+      it('catches and reports domain errors', async () => {
+        registry.register(
+          createTestDescriptor({
+            getDSL: () => {
+              throw new Error('Module not found');
+            },
+          })
+        );
+
+        const result = await registry.handleToolCall('parse_test', { query: 'test' });
+        expect(result!.isError).toBe(true);
+        const data = JSON.parse(result!.content[0].text);
+        expect(data.error).toContain('Module not found');
+      });
+    });
+
+    describe('DSL caching', () => {
+      it('reuses DSL instance across calls', async () => {
+        let callCount = 0;
+        registry.register(
+          createTestDescriptor({
+            getDSL: () => {
+              callCount++;
+              return createMockDSL();
+            },
+          })
+        );
+
+        await registry.handleToolCall('parse_test', { query: 'a' });
+        await registry.handleToolCall('parse_test', { query: 'b' });
+        expect(callCount).toBe(1);
+      });
+    });
+  });
+});