@lokascript/semantic 1.0.0

package/src/core-bridge.ts

@@ -0,0 +1,372 @@
+/**
+ * Core Parser Bridge
+ *
+ * Provides the SemanticAnalyzer interface that integrates semantic parsing
+ * into the core hyperscript parser. This bridge enables confidence-driven
+ * fallback between semantic and traditional parsing.
+ */
+
+import type {
+  SemanticNode,
+  SemanticValue,
+  ActionType,
+  PatternMatchResult,
+  SemanticRole,
+} from './types';
+import { PatternMatcher } from './parser/pattern-matcher';
+import { getTokenizer } from './tokenizers';
+// Import from registry for tree-shaking (registry uses directly-registered patterns first)
+import { getPatternsForLanguage, getRegisteredLanguages } from './registry';
+import { SemanticCache, semanticCache, type SemanticCacheConfig, type CacheStats } from './cache';
+
+// =============================================================================
+// SemanticAnalyzer Interface
+// =============================================================================
+
+/**
+ * Result of semantic analysis.
+ */
+export interface SemanticAnalysisResult {
+  /** Confidence score (0-1) for this analysis */
+  readonly confidence: number;
+  /** The parsed command info (if successful) */
+  readonly command?: {
+    readonly name: ActionType;
+    readonly roles: ReadonlyMap<SemanticRole, SemanticValue>;
+  };
+  /** The full semantic node (if successful) */
+  readonly node?: SemanticNode;
+  /** Any errors encountered */
+  readonly errors?: string[];
+  /** Number of tokens consumed */
+  readonly tokensConsumed?: number;
+}
+
+/**
+ * Interface for semantic analysis that can be integrated into the core parser.
+ * This allows the core parser to optionally use semantic parsing with
+ * confidence-based fallback to traditional parsing.
+ */
+export interface SemanticAnalyzer {
+  /**
+   * Analyze input in the specified language.
+   *
+   * @param input The input string to analyze
+   * @param language ISO 639-1 language code
+   * @returns Analysis result with confidence score
+   */
+  analyze(input: string, language: string): SemanticAnalysisResult;
+
+  /**
+   * Check if semantic parsing is available for a language.
+   */
+  supportsLanguage(language: string): boolean;
+
+  /**
+   * Get the list of supported languages.
+   */
+  supportedLanguages(): string[];
+
+  /**
+   * Get cache statistics.
+   */
+  getCacheStats(): CacheStats;
+
+  /**
+   * Clear the result cache.
+   */
+  clearCache(): void;
+
+  /**
+   * Configure the cache.
+   */
+  configureCache(config: Partial<SemanticCacheConfig>): void;
+}
+
+// =============================================================================
+// SemanticAnalyzer Implementation
+// =============================================================================
+
+/**
+ * Options for creating a SemanticAnalyzer.
+ */
+export interface SemanticAnalyzerOptions {
+  /** Cache configuration. Pass false to disable caching. */
+  cache?: SemanticCacheConfig | false;
+}
+
+/**
+ * Implementation of SemanticAnalyzer that wraps the semantic parser.
+ * Includes LRU caching for performance optimization on repeated inputs.
+ */
+export class SemanticAnalyzerImpl implements SemanticAnalyzer {
+  private readonly patternMatcher: PatternMatcher;
+  private readonly languages: Set<string>;
+  private readonly cache: SemanticCache;
+
+  constructor(options: SemanticAnalyzerOptions = {}) {
+    this.patternMatcher = new PatternMatcher();
+    // Get all registered languages from the registry (dynamically updated as languages are loaded)
+    this.languages = new Set(getRegisteredLanguages());
+
+    // Initialize cache
+    if (options.cache === false) {
+      this.cache = new SemanticCache({ enabled: false });
+    } else {
+      this.cache = options.cache ? new SemanticCache(options.cache) : semanticCache;
+    }
+  }
+
+  analyze(input: string, language: string): SemanticAnalysisResult {
+    // Check language support
+    if (!this.supportsLanguage(language)) {
+      return {
+        confidence: 0,
+        errors: [`Language '${language}' is not supported for semantic parsing`],
+      };
+    }
+
+    // Check cache first
+    const cached = this.cache.get(input, language);
+    if (cached) {
+      return cached;
+    }
+
+    // Perform analysis
+    const result = this.analyzeUncached(input, language);
+
+    // Cache successful results
+    this.cache.set(input, language, result);
+
+    return result;
+  }
+
+  /**
+   * Perform analysis without cache lookup.
+   */
+  private analyzeUncached(input: string, language: string): SemanticAnalysisResult {
+    try {
+      // Tokenize
+      const tokenizer = getTokenizer(language);
+      if (!tokenizer) {
+        return {
+          confidence: 0,
+          errors: [`No tokenizer available for language '${language}'`],
+        };
+      }
+
+      const tokenStream = tokenizer.tokenize(input);
+
+      // Get patterns for this language
+      const patterns = getPatternsForLanguage(language);
+      if (patterns.length === 0) {
+        return {
+          confidence: 0,
+          errors: [`No patterns available for language '${language}'`],
+        };
+      }
+
+      // Try to match patterns
+      const match = this.patternMatcher.matchBest(tokenStream, patterns);
+
+      if (!match) {
+        return {
+          confidence: 0,
+          errors: ['No pattern matched the input'],
+        };
+      }
+
+      // Build semantic node from match
+      const node = this.buildSemanticNode(match);
+
+      return {
+        confidence: match.confidence,
+        command: {
+          name: match.pattern.command,
+          roles: match.captured,
+        },
+        node,
+        tokensConsumed: match.consumedTokens,
+      };
+    } catch (error) {
+      return {
+        confidence: 0,
+        errors: [error instanceof Error ? error.message : String(error)],
+      };
+    }
+  }
+
+  supportsLanguage(language: string): boolean {
+    return this.languages.has(language);
+  }
+
+  supportedLanguages(): string[] {
+    return Array.from(this.languages);
+  }
+
+  getCacheStats(): CacheStats {
+    return this.cache.getStats();
+  }
+
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  configureCache(config: Partial<SemanticCacheConfig>): void {
+    this.cache.configure(config);
+  }
+
+  private buildSemanticNode(match: PatternMatchResult): SemanticNode {
+    return {
+      kind: 'command',
+      action: match.pattern.command,
+      roles: match.captured,
+      metadata: {
+        patternId: match.pattern.id,
+      },
+    };
+  }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/**
+ * Create a SemanticAnalyzer instance.
+ *
+ * @param options - Configuration options including cache settings
+ * @returns A new SemanticAnalyzer
+ *
+ * @example
+ * // Default: uses shared global cache
+ * const analyzer = createSemanticAnalyzer();
+ *
+ * @example
+ * // Custom cache size
+ * const analyzer = createSemanticAnalyzer({ cache: { maxSize: 500 } });
+ *
+ * @example
+ * // Disable caching
+ * const analyzer = createSemanticAnalyzer({ cache: false });
+ */
+export function createSemanticAnalyzer(options?: SemanticAnalyzerOptions): SemanticAnalyzer {
+  return new SemanticAnalyzerImpl(options);
+}
+
+// Re-export cache types for convenience
+export type { SemanticCacheConfig, CacheStats } from './cache';
+
+// =============================================================================
+// Confidence Thresholds
+// =============================================================================
+
+/**
+ * Default confidence threshold for preferring semantic parsing.
+ * If confidence is above this, use semantic result; otherwise fallback.
+ */
+export const DEFAULT_CONFIDENCE_THRESHOLD = 0.5;
+
+/**
+ * High confidence threshold for very certain matches.
+ */
+export const HIGH_CONFIDENCE_THRESHOLD = 0.8;
+
+// =============================================================================
+// Integration Helpers
+// =============================================================================
+
+/**
+ * Determine if semantic analysis should be used based on confidence.
+ */
+export function shouldUseSemanticResult(
+  result: SemanticAnalysisResult,
+  threshold: number = DEFAULT_CONFIDENCE_THRESHOLD
+): boolean {
+  return result.confidence >= threshold && result.command !== undefined;
+}
+
+/**
+ * Convert semantic roles to the format expected by core parser commands.
+ * This maps semantic roles to the positional/modifier structure used by
+ * the core command implementations.
+ *
+ * Role to preposition mapping:
+ * - patient → first positional arg
+ * - event → first positional arg
+ * - destination → 'into' (put) or 'on' (others)
+ * - source → 'from'
+ * - quantity → 'by'
+ * - duration → 'over' or 'for'
+ * - method → 'as'
+ * - style → 'with'
+ * - condition → 'if'
+ */
+export function rolesToCommandArgs(
+  roles: ReadonlyMap<SemanticRole, SemanticValue>,
+  command: ActionType
+): {
+  args: SemanticValue[];
+  modifiers: Record<string, SemanticValue>;
+} {
+  const args: SemanticValue[] = [];
+  const modifiers: Record<string, SemanticValue> = {};
+
+  for (const [role, value] of roles) {
+    switch (role) {
+      // Primary arguments (positional)
+      case 'patient':
+      case 'event':
+        args.push(value);
+        break;
+
+      // Destination: context-dependent preposition
+      case 'destination':
+        if (command === 'put') {
+          modifiers['into'] = value;
+        } else {
+          modifiers['on'] = value;
+        }
+        break;
+
+      // Source: always 'from'
+      case 'source':
+        modifiers['from'] = value;
+        break;
+
+      // Quantitative roles
+      case 'quantity':
+        modifiers['by'] = value;
+        break;
+
+      case 'duration':
+        modifiers['over'] = value;
+        break;
+
+      // Adverbial roles
+      case 'method':
+        modifiers['as'] = value;
+        break;
+
+      case 'style':
+        modifiers['with'] = value;
+        break;
+
+      // Conditional
+      case 'condition':
+        modifiers['if'] = value;
+        break;
+
+      // Agent (for future multi-actor systems)
+      case 'agent':
+        modifiers['agent'] = value;
+        break;
+
+      default:
+        // Unknown roles become modifiers using role name as key
+        modifiers[role] = value;
+    }
+  }
+
+  return { args, modifiers };
+}

package/src/explicit/converter.ts

@@ -0,0 +1,258 @@
+/**
+ * Bidirectional Converter
+ *
+ * Converts between natural language syntax and explicit syntax,
+ * and between different natural languages.
+ */
+
+import type { SemanticNode } from '../types';
+import { parse } from '../parser';
+import { render, renderExplicit } from './renderer';
+import { parseExplicit, isExplicitSyntax } from './parser';
+
+// =============================================================================
+// Bidirectional Conversion
+// =============================================================================
+
+/**
+ * Convert natural language hyperscript to explicit syntax.
+ *
+ * @param input Natural language hyperscript
+ * @param sourceLanguage Source language code
+ * @returns Explicit syntax string
+ *
+ * @example
+ * toExplicit('toggle .active on #button', 'en')
+ * // → '[toggle patient:.active destination:#button]'
+ *
+ * toExplicit('#button の .active を 切り替え', 'ja')
+ * // → '[toggle patient:.active destination:#button]'
+ */
+export function toExplicit(input: string, sourceLanguage: string): string {
+  // If already explicit, return as-is
+  if (isExplicitSyntax(input)) {
+    return input;
+  }
+
+  const node = parse(input, sourceLanguage);
+  return renderExplicit(node);
+}
+
+/**
+ * Convert explicit syntax to natural language.
+ *
+ * @param explicit Explicit syntax string
+ * @param targetLanguage Target language code
+ * @returns Natural language hyperscript
+ *
+ * @example
+ * fromExplicit('[toggle patient:.active destination:#button]', 'en')
+ * // → 'toggle .active on #button'
+ *
+ * fromExplicit('[toggle patient:.active destination:#button]', 'ja')
+ * // → '#button の .active を 切り替え'
+ */
+export function fromExplicit(explicit: string, targetLanguage: string): string {
+  const node = parseExplicit(explicit);
+  return render(node, targetLanguage);
+}
+
+/**
+ * Translate hyperscript from one language to another.
+ *
+ * @param input Natural language hyperscript
+ * @param sourceLanguage Source language code
+ * @param targetLanguage Target language code
+ * @returns Translated hyperscript
+ *
+ * @example
+ * translate('toggle .active on #button', 'en', 'ja')
+ * // → '#button の .active を 切り替え'
+ *
+ * translate('#button の .active を 切り替え', 'ja', 'ar')
+ * // → 'بدّل .active على #button'
+ */
+export function translate(input: string, sourceLanguage: string, targetLanguage: string): string {
+  // Handle explicit syntax
+  if (isExplicitSyntax(input)) {
+    return fromExplicit(input, targetLanguage);
+  }
+
+  // Parse source language
+  const node = parse(input, sourceLanguage);
+
+  // Render in target language
+  return render(node, targetLanguage);
+}
+
+/**
+ * Parse input (either explicit or natural language) to semantic node.
+ *
+ * @param input Hyperscript input (explicit or natural)
+ * @param language Language code (required for natural, ignored for explicit)
+ * @returns Semantic node
+ */
+export function parseAny(input: string, language: string): SemanticNode {
+  if (isExplicitSyntax(input)) {
+    return parseExplicit(input);
+  }
+  return parse(input, language);
+}
+
+/**
+ * Round-trip validation: parse and re-render to verify consistency.
+ *
+ * When called with 2 arguments, returns an object with validation info.
+ * When called with 3 arguments, returns the rendered string directly.
+ *
+ * @param input Original input
+ * @param sourceLanguage Source language code
+ * @param targetLanguage Target language code (optional, if provided returns string only)
+ * @returns Object with original, semantic, re-rendered, and match status (or just string if targetLanguage provided)
+ */
+export function roundTrip(
+  input: string,
+  sourceLanguage: string,
+  targetLanguage?: string
+):
+  | string
+  | {
+      original: string;
+      semantic: SemanticNode;
+      rendered: string;
+      matches: boolean;
+    } {
+  const semantic = parseAny(input, sourceLanguage);
+  const outputLanguage = targetLanguage ?? sourceLanguage;
+  const rendered = isExplicitSyntax(input)
+    ? renderExplicit(semantic)
+    : render(semantic, outputLanguage);
+
+  // If target language is explicitly provided, return just the rendered string
+  if (targetLanguage !== undefined) {
+    return rendered;
+  }
+
+  // Normalize for comparison (trim whitespace, lowercase)
+  const normalizedOriginal = input.trim().toLowerCase();
+  const normalizedRendered = rendered.trim().toLowerCase();
+
+  return {
+    original: input,
+    semantic,
+    rendered,
+    matches: normalizedOriginal === normalizedRendered,
+  };
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Get all translations of a hyperscript statement.
+ *
+ * @param input Hyperscript input
+ * @param sourceLanguage Source language (or 'explicit')
+ * @param targetLanguages List of target language codes (defaults to all 13 supported languages)
+ * @returns Object mapping language codes to translations
+ */
+export function getAllTranslations(
+  input: string,
+  sourceLanguage: string,
+  targetLanguages: string[] = [
+    'en',
+    'ja',
+    'ar',
+    'es',
+    'ko',
+    'zh',
+    'tr',
+    'pt',
+    'fr',
+    'de',
+    'id',
+    'qu',
+    'sw',
+  ]
+): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  // Parse once
+  const node = parseAny(input, sourceLanguage);
+
+  // Render for each target language
+  for (const lang of targetLanguages) {
+    result[lang] = render(node, lang);
+  }
+
+  // Also include explicit
+  result['explicit'] = renderExplicit(node);
+
+  return result;
+}
+
+/**
+ * Validate that a translation is semantically equivalent.
+ *
+ * @param original Original hyperscript
+ * @param translated Translated hyperscript
+ * @param originalLang Original language
+ * @param translatedLang Translated language
+ * @returns true if semantically equivalent
+ */
+export function validateTranslation(
+  original: string,
+  translated: string,
+  originalLang: string,
+  translatedLang: string
+): boolean {
+  try {
+    const originalNode = parseAny(original, originalLang);
+    const translatedNode = parseAny(translated, translatedLang);
+
+    // Compare semantic content
+    if (originalNode.action !== translatedNode.action) {
+      return false;
+    }
+
+    // Compare roles
+    for (const [role, value] of originalNode.roles) {
+      const translatedValue = translatedNode.roles.get(role);
+      if (!translatedValue) {
+        return false;
+      }
+
+      // Deep compare values
+      if (!semanticValuesEqual(value, translatedValue)) {
+        return false;
+      }
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if two semantic values are equal.
+ */
+function semanticValuesEqual(a: any, b: any): boolean {
+  if (a.type !== b.type) return false;
+
+  switch (a.type) {
+    case 'literal':
+      return a.value === b.value;
+    case 'selector':
+      return a.value === b.value;
+    case 'reference':
+      return a.value === b.value;
+    case 'property-path':
+      return semanticValuesEqual(a.object, b.object) && a.property === b.property;
+    case 'expression':
+      return a.raw === b.raw;
+    default:
+      return false;
+  }
+}

package/src/explicit/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Explicit Mode Module
+ *
+ * Provides the explicit [command role:value] syntax for learning,
+ * debugging, and language-neutral representation.
+ */
+
+export { parseExplicit, isExplicitSyntax } from './parser';
+export { SemanticRendererImpl, semanticRenderer, render, renderExplicit } from './renderer';
+export {
+  toExplicit,
+  fromExplicit,
+  translate,
+  parseAny,
+  roundTrip,
+  getAllTranslations,
+  validateTranslation,
+} from './converter';