@lokascript/framework 2.0.0

package/src/index.ts

@@ -0,0 +1,157 @@
+/**
+ * @lokascript/framework - Generic framework for building multilingual DSLs
+ *
+ * This framework provides the building blocks for creating domain-specific languages
+ * that work across multiple human languages (English, Japanese, Spanish, etc.) with
+ * semantic parsing and grammar transformation.
+ *
+ * @example
+ * ```typescript
+ * import { createMultilingualDSL } from '@lokascript/framework';
+ *
+ * const myDSL = createMultilingualDSL({
+ *   schemas: [{ action: 'select', roles: [...] }],
+ *   languages: [{ code: 'en', profile: {...}, tokenizer: {...} }],
+ *   codeGenerator: (node) => generateSQL(node)
+ * });
+ *
+ * myDSL.parse('select name from users', 'en');
+ * myDSL.translate('select name from users', 'en', 'ja');
+ * ```
+ */
+
+// Main API
+export * from './api';
+
+// AOT (generalized ahead-of-time compilation)
+export * from './aot';
+
+// Interfaces (for dependency injection)
+export * from './interfaces';
+
+// Core modules
+export * from './schema';
+export * from './generation';
+
+// Grammar exports - explicitly list to avoid PatternMatcher conflict with core
+export { GrammarTransformer } from './grammar/transformer';
+export type { TransformerConfig } from './grammar/transformer';
+export { reorderRoles, insertMarkers, joinTokens } from './grammar/types';
+export type {
+  LanguageProfile,
+  PatternTransform,
+  ParsedElement,
+  WordOrder,
+  GrammaticalMarker,
+  AdpositionType,
+} from './grammar/types';
+
+// Core - export classes and utilities
+export * from './core';
+
+// Re-export key types for convenience
+export type {
+  ActionType,
+  SemanticRole as SemanticRoleType,
+  SemanticValue,
+  SemanticNode,
+  CommandSemanticNode,
+  EventHandlerSemanticNode,
+  ConditionalSemanticNode,
+  CompoundSemanticNode,
+  LoopSemanticNode,
+  LiteralValue,
+  SelectorValue,
+  ReferenceValue,
+  PropertyPathValue,
+  ExpressionValue,
+  SemanticMetadata,
+  SourcePosition,
+  LanguageToken,
+  TokenStream,
+  LanguageTokenizer,
+  LanguagePattern,
+} from './core/types';
+
+export type { CommandSchema, RoleSpec } from './schema';
+
+// Renderer
+export type {
+  NaturalLanguageRenderer,
+  KeywordTable,
+  MarkerTable,
+  RendererConfig,
+} from './generation/renderer';
+export {
+  lookupKeyword,
+  lookupMarker,
+  buildPhrase,
+  buildTablesFromProfiles,
+  detectWordOrders,
+  createSchemaRenderer,
+} from './generation/renderer';
+
+// Diagnostics
+export type {
+  DiagnosticSeverity,
+  Diagnostic,
+  DiagnosticResult,
+  DiagnosticSummary,
+  DiagnosticCollector,
+  DiagnosticOptions,
+} from './generation/diagnostics';
+export { createDiagnosticCollector, fromError, filterBySeverity } from './generation/diagnostics';
+
+export type {
+  LanguageConfig,
+  DSLConfig,
+  MultilingualDSL,
+  CodeGenerator,
+  ValidationResult,
+  CompileResult,
+  DomainDescriptor,
+  MCPToolDefinition,
+  MCPToolResponse,
+  DispatchResult,
+  CompositeParseResult,
+  CompositeStatement,
+  CompositeError,
+  DispatcherOptions,
+} from './api';
+
+export { DomainRegistry, CrossDomainDispatcher } from './api';
+
+// Re-export helper functions
+export {
+  createLiteral,
+  createSelector,
+  createReference,
+  createPropertyPath,
+  createExpression,
+  createCommandNode,
+  createEventHandlerNode,
+  createConditionalNode,
+  createCompoundNode,
+  createLoopNode,
+  extractValue,
+  extractRoleValue,
+} from './core/types';
+
+export { defineCommand, defineRole } from './schema';
+export { createSimpleTokenizer } from './core/tokenization/base-tokenizer';
+export type { SimpleTokenizerConfig } from './core/tokenization/base-tokenizer';
+
+// Multi-statement parser
+export { createMultiStatementParser, accumulateBlocks } from './parsing/multi-statement';
+export type {
+  MultiStatementParser,
+  MultiStatementConfig,
+  MultiStatementResult,
+  ParsedStatement,
+  StatementError,
+  StatementBlock,
+  BlockConfig,
+  BlockResult,
+  KeywordMap,
+  WordOrderHint,
+} from './parsing/multi-statement';

package/src/interfaces/dictionary.ts

@@ -0,0 +1,123 @@
+/**
+ * Dictionary Interface - Keyword Translation
+ *
+ * Provides keyword translations between languages.
+ * DSLs implement this to provide their domain-specific translations.
+ */
+
+/**
+ * Dictionary provides keyword translations between languages.
+ */
+export interface Dictionary {
+  /**
+   * Look up canonical form from localized keyword.
+   *
+   * @param localizedWord - Word in target language (e.g., 'トグル', 'alternar')
+   * @param language - Language code
+   * @returns Canonical form (e.g., 'toggle') or undefined
+   *
+   * @example
+   * dictionary.lookup('トグル', 'ja') // → 'toggle'
+   * dictionary.lookup('alternar', 'es') // → 'toggle'
+   */
+  lookup(localizedWord: string, language: string): string | undefined;
+
+  /**
+   * Translate canonical keyword to target language.
+   *
+   * @param canonical - Canonical form (e.g., 'toggle')
+   * @param targetLanguage - Target language code
+   * @returns Localized form or undefined
+   *
+   * @example
+   * dictionary.translate('toggle', 'ja') // → 'トグル'
+   * dictionary.translate('toggle', 'es') // → 'alternar'
+   */
+  translate(canonical: string, targetLanguage: string): string | undefined;
+
+  /**
+   * Get all translations of a word across all supported languages.
+   *
+   * @param word - Word to translate
+   * @param sourceLanguage - Source language
+   * @returns Map of language code to translation
+   *
+   * @example
+   * dictionary.getAllTranslations('toggle', 'en')
+   * // → { ja: 'トグル', es: 'alternar', ko: '토글', ... }
+   */
+  getAllTranslations(word: string, sourceLanguage: string): Record<string, string>;
+
+  /**
+   * Optional: Find what category a word belongs to.
+   * Useful for organizing translations by domain (commands, modifiers, events, etc.).
+   */
+  getCategory?(word: string, language: string): string | undefined;
+}
+
+/**
+ * Simple in-memory dictionary implementation.
+ * Suitable for small DSLs or prototyping.
+ */
+export class InMemoryDictionary implements Dictionary {
+  /**
+   * @param translations - Map of language code to canonical→localized mappings
+   *
+   * @example
+   * new InMemoryDictionary({
+   *   en: { select: 'select', insert: 'insert' },
+   *   es: { select: 'seleccionar', insert: 'insertar' },
+   *   ja: { select: '選択', insert: '挿入' }
+   * })
+   */
+  constructor(private translations: Record<string, Record<string, string>>) {}
+
+  lookup(word: string, language: string): string | undefined {
+    const langDict = this.translations[language];
+    if (!langDict) return undefined;
+
+    // Reverse lookup: find key where value = word
+    const wordLower = word.toLowerCase();
+    for (const [canonical, localized] of Object.entries(langDict)) {
+      if (localized.toLowerCase() === wordLower) {
+        return canonical;
+      }
+    }
+    return undefined;
+  }
+
+  translate(canonical: string, targetLanguage: string): string | undefined {
+    return this.translations[targetLanguage]?.[canonical];
+  }
+
+  getAllTranslations(word: string, sourceLanguage: string): Record<string, string> {
+    const canonical = this.lookup(word, sourceLanguage);
+    if (!canonical) return {};
+
+    const result: Record<string, string> = {};
+    for (const [lang, dict] of Object.entries(this.translations)) {
+      const translation = dict[canonical];
+      if (translation) {
+        result[lang] = translation;
+      }
+    }
+    return result;
+  }
+}
+
+/**
+ * Null dictionary - no translations (useful for single-language DSLs).
+ */
+export class NullDictionary implements Dictionary {
+  lookup(word: string, _language: string): string | undefined {
+    return word; // Identity: word is its own canonical form
+  }
+
+  translate(canonical: string, _targetLanguage: string): string | undefined {
+    return canonical; // Identity: no translation
+  }
+
+  getAllTranslations(word: string, _sourceLanguage: string): Record<string, string> {
+    return { en: word }; // Only source language
+  }
+}

package/src/interfaces/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Core interfaces for dependency injection
+ *
+ * These interfaces define pluggable components that DSLs can implement
+ * to customize framework behavior.
+ */
+
+export * from './dictionary';
+export * from './profile-provider';
+export * from './value-extractor';

package/src/interfaces/profile-provider.ts

@@ -0,0 +1,88 @@
+/**
+ * Profile Provider Interface - Language Profile Access
+ *
+ * Provides language profiles for grammar transformation.
+ * DSLs implement this to provide their domain-specific profiles.
+ */
+
+import type { LanguageProfile } from '../grammar';
+
+/**
+ * Provides language profiles for transformation.
+ */
+export interface ProfileProvider {
+  /**
+   * Get language profile by code.
+   *
+   * @param language - ISO 639-1 code (e.g., 'en', 'ja', 'es')
+   * @returns Language profile or undefined if not supported
+   *
+   * @example
+   * const profile = provider.getProfile('ja');
+   * console.log(profile.wordOrder); // 'SOV'
+   */
+  getProfile(language: string): LanguageProfile | undefined;
+
+  /**
+   * Get all supported language codes.
+   *
+   * @returns Array of ISO 639-1 codes
+   *
+   * @example
+   * provider.getSupportedLanguages() // → ['en', 'ja', 'es', 'ko']
+   */
+  getSupportedLanguages(): string[];
+
+  /**
+   * Check if a language is supported.
+   *
+   * @param language - Language code to check
+   * @returns True if language is supported
+   */
+  hasLanguage(language: string): boolean;
+}
+
+/**
+ * Simple in-memory profile provider.
+ */
+export class InMemoryProfileProvider implements ProfileProvider {
+  /**
+   * @param profiles - Map of language code to profile
+   *
+   * @example
+   * new InMemoryProfileProvider({
+   *   en: { code: 'en', wordOrder: 'SVO', ... },
+   *   ja: { code: 'ja', wordOrder: 'SOV', ... }
+   * })
+   */
+  constructor(private profiles: Record<string, LanguageProfile>) {}
+
+  getProfile(language: string): LanguageProfile | undefined {
+    return this.profiles[language];
+  }
+
+  getSupportedLanguages(): string[] {
+    return Object.keys(this.profiles);
+  }
+
+  hasLanguage(language: string): boolean {
+    return language in this.profiles;
+  }
+}
+
+/**
+ * Null profile provider - for DSLs that don't need grammar transformation.
+ */
+export class NullProfileProvider implements ProfileProvider {
+  getProfile(_language: string): LanguageProfile | undefined {
+    return undefined;
+  }
+
+  getSupportedLanguages(): string[] {
+    return [];
+  }
+
+  hasLanguage(_language: string): boolean {
+    return false;
+  }
+}