@lokascript/framework 2.0.0

package/src/generation/renderer.ts

@@ -0,0 +1,244 @@
+/**
+ * Natural Language Renderer
+ *
+ * Interface and utilities for rendering SemanticNode → human-readable text
+ * in any supported language. This is the inverse of parsing: it converts
+ * a language-neutral semantic representation back to natural-language syntax.
+ *
+ * Every domain that supports `translate()` needs a renderer.
+ */
+
+import type { SemanticNode } from '../core/types';
+import { extractRoleValue } from '../core/types';
+import type { CommandSchema, RoleSpec } from '../schema';
+import type { PatternGenLanguageProfile } from './pattern-generator';
+
+// =============================================================================
+// Renderer Interface
+// =============================================================================
+
+/**
+ * Renders a SemanticNode to human-readable text in a target language.
+ */
+export interface NaturalLanguageRenderer {
+  render(node: SemanticNode, language: string): string;
+}
+
+// =============================================================================
+// Renderer Helpers
+// =============================================================================
+
+/**
+ * Keyword table: action → language → translated keyword.
+ *
+ * @example
+ * ```typescript
+ * const KEYWORDS: KeywordTable = {
+ *   select: { en: 'select', ja: '選択', es: 'seleccionar' },
+ *   insert: { en: 'insert', ja: '挿入', es: 'insertar' },
+ * };
+ * ```
+ */
+export type KeywordTable = Record<string, Record<string, string>>;
+
+/**
+ * Marker table: marker name → language → translated marker.
+ *
+ * @example
+ * ```typescript
+ * const MARKERS: MarkerTable = {
+ *   from: { en: 'from', ja: 'から', es: 'de' },
+ *   into: { en: 'into', ja: 'に', es: 'en' },
+ * };
+ * ```
+ */
+export type MarkerTable = Record<string, Record<string, string>>;
+
+/**
+ * Configuration for building a renderer from schemas and profiles.
+ */
+export interface RendererConfig {
+  /** Command keyword translations per language */
+  readonly keywords: KeywordTable;
+
+  /** Role marker translations per language (prepositions/particles) */
+  readonly markers: MarkerTable;
+
+  /** Languages that use SOV word order */
+  readonly sovLanguages: ReadonlySet<string>;
+
+  /** Languages that use VSO word order (optional, defaults to empty) */
+  readonly vsoLanguages?: ReadonlySet<string>;
+}
+
+/**
+ * Look up a command keyword in the target language.
+ * Falls back to the key itself if no translation found.
+ */
+export function lookupKeyword(keywords: KeywordTable, action: string, language: string): string {
+  return keywords[action]?.[language] ?? action;
+}
+
+/**
+ * Look up a role marker in the target language.
+ * Falls back to the key itself if no translation found.
+ */
+export function lookupMarker(markers: MarkerTable, marker: string, language: string): string {
+  return markers[marker]?.[language] ?? marker;
+}
+
+/**
+ * Build a phrase from parts, filtering empty strings and joining with space.
+ *
+ * @example
+ * ```typescript
+ * buildPhrase('select', '', 'name', 'from', 'users')
+ * // → 'select name from users'
+ * ```
+ */
+export function buildPhrase(...parts: string[]): string {
+  return parts.filter(Boolean).join(' ');
+}
+
+/**
+ * Build keyword and marker tables from schemas and language profiles.
+ * Extracts translations from the profile's keyword definitions and
+ * role marker overrides.
+ *
+ * @example
+ * ```typescript
+ * const { keywords, markers } = buildTablesFromProfiles(schemas, profiles);
+ * ```
+ */
+export function buildTablesFromProfiles(
+  schemas: readonly CommandSchema[],
+  profiles: readonly PatternGenLanguageProfile[]
+): { keywords: KeywordTable; markers: MarkerTable } {
+  const keywords: KeywordTable = {};
+  const markers: MarkerTable = {};
+
+  // Build keyword table from profiles
+  for (const profile of profiles) {
+    for (const [action, kw] of Object.entries(profile.keywords)) {
+      if (!keywords[action]) keywords[action] = {};
+      keywords[action][profile.code] = kw.primary;
+    }
+  }
+
+  // Build marker table from schema markerOverrides
+  for (const schema of schemas) {
+    for (const role of schema.roles) {
+      if (role.markerOverride) {
+        // Use role name as marker key
+        const markerKey = role.role;
+        if (!markers[markerKey]) markers[markerKey] = {};
+        for (const [lang, markerText] of Object.entries(role.markerOverride)) {
+          markers[markerKey][lang] = markerText;
+        }
+      }
+    }
+  }
+
+  // Also extract role markers from profiles
+  for (const profile of profiles) {
+    if (profile.roleMarkers) {
+      for (const [markerKey, markerDef] of Object.entries(profile.roleMarkers)) {
+        if (!markers[markerKey]) markers[markerKey] = {};
+        markers[markerKey][profile.code] = markerDef.primary;
+      }
+    }
+  }
+
+  return { keywords, markers };
+}
+
+/**
+ * Detect word order from language profiles.
+ * Returns sets of SOV and VSO language codes.
+ */
+export function detectWordOrders(profiles: readonly PatternGenLanguageProfile[]): {
+  sovLanguages: Set<string>;
+  vsoLanguages: Set<string>;
+} {
+  const sovLanguages = new Set<string>();
+  const vsoLanguages = new Set<string>();
+
+  for (const profile of profiles) {
+    if (profile.wordOrder === 'SOV') sovLanguages.add(profile.code);
+    if (profile.wordOrder === 'VSO') vsoLanguages.add(profile.code);
+  }
+
+  return { sovLanguages, vsoLanguages };
+}
+
+/**
+ * Create a basic renderer from schemas and profiles.
+ *
+ * This generates a renderer that handles word-order reordering automatically.
+ * For each command, it constructs the output by placing the keyword and
+ * role values in the correct order for the target language.
+ *
+ * For complex domain-specific rendering, implement `NaturalLanguageRenderer`
+ * directly instead.
+ *
+ * @example
+ * ```typescript
+ * const renderer = createSchemaRenderer(schemas, profiles);
+ * renderer.render(node, 'ja');  // → "users から name 選択"
+ * ```
+ */
+export function createSchemaRenderer(
+  schemas: readonly CommandSchema[],
+  profiles: readonly PatternGenLanguageProfile[]
+): NaturalLanguageRenderer {
+  const { keywords, markers } = buildTablesFromProfiles(schemas, profiles);
+  const { sovLanguages } = detectWordOrders(profiles);
+  const schemaMap = new Map<string, CommandSchema>();
+  for (const s of schemas) schemaMap.set(s.action, s);
+
+  return {
+    render(node: SemanticNode, language: string): string {
+      const schema = schemaMap.get(node.action);
+      if (!schema) return node.action;
+
+      const keyword = lookupKeyword(keywords, node.action, language);
+      const isSOV = sovLanguages.has(language);
+
+      // Collect role parts in schema order
+      const roleParts: Array<{ marker?: string; value: string; role: RoleSpec }> = [];
+      for (const role of schema.roles) {
+        const value = extractRoleValue(node, role.role);
+        if (!value && !role.required) continue;
+
+        const markerText =
+          role.markerOverride?.[language] ?? markers[role.role]?.[language] ?? undefined;
+
+        roleParts.push({
+          ...(markerText != null && { marker: markerText }),
+          value: value || '',
+          role,
+        });
+      }
+
+      const parts: string[] = [];
+
+      if (isSOV) {
+        // SOV: roles (with markers after values) then keyword
+        for (const rp of roleParts) {
+          if (rp.value) parts.push(rp.value);
+          if (rp.marker) parts.push(rp.marker);
+        }
+        parts.push(keyword);
+      } else {
+        // SVO/VSO: keyword then roles (with markers before values)
+        parts.push(keyword);
+        for (const rp of roleParts) {
+          if (rp.marker) parts.push(rp.marker);
+          if (rp.value) parts.push(rp.value);
+        }
+      }
+
+      return buildPhrase(...parts);
+    },
+  };
+}

package/src/grammar/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Grammar transformation utilities for multilingual DSLs
+ *
+ * Core utilities for handling word order transformation (SVO/SOV/VSO),
+ * grammatical marker insertion, and role-based reordering.
+ */
+
+export * from './types';
+export * from './transformer';
+
+// Re-export key transformation functions
+export { reorderRoles, insertMarkers, joinTokens } from './types';

package/src/grammar/transformer.ts

@@ -0,0 +1,159 @@
+/**
+ * Grammar Transformer - Dependency Injection Architecture
+ *
+ * Transforms statements between languages using injected dependencies.
+ * This makes the transformer completely domain-agnostic.
+ */
+
+import type { LanguageProfile, ParsedElement, SemanticRole } from './types';
+import { reorderRoles, insertMarkers, joinTokens } from './types';
+import type { Dictionary } from '../interfaces/dictionary';
+import type { ProfileProvider } from '../interfaces/profile-provider';
+
+/**
+ * Configuration for grammar transformer.
+ */
+export interface TransformerConfig {
+  /** Dictionary for keyword translation */
+  readonly dictionary: Dictionary;
+
+  /** Profile provider for grammar rules */
+  readonly profileProvider: ProfileProvider;
+}
+
+/**
+ * Generic grammar transformer using dependency injection.
+ *
+ * @example
+ * const transformer = new GrammarTransformer({
+ *   dictionary: new InMemoryDictionary(translations),
+ *   profileProvider: new InMemoryProfileProvider(profiles)
+ * });
+ *
+ * const japanese = transformer.transform('select name from users', 'en', 'ja');
+ * // → "users から name を 選択"
+ */
+export class GrammarTransformer {
+  private dictionary: Dictionary;
+  private profileProvider: ProfileProvider;
+
+  constructor(config: TransformerConfig) {
+    this.dictionary = config.dictionary;
+    this.profileProvider = config.profileProvider;
+  }
+
+  /**
+   * Transform a statement from one language to another.
+   *
+   * @param input - Statement in source language
+   * @param fromLanguage - Source language code
+   * @param toLanguage - Target language code
+   * @returns Transformed statement in target language
+   *
+   * @throws Error if profiles not found or translation fails
+   */
+  transform(input: string, fromLanguage: string, toLanguage: string): string {
+    // Get language profiles
+    const fromProfile = this.profileProvider.getProfile(fromLanguage);
+    const toProfile = this.profileProvider.getProfile(toLanguage);
+
+    if (!fromProfile) {
+      throw new Error(`No profile found for language: ${fromLanguage}`);
+    }
+    if (!toProfile) {
+      throw new Error(`No profile found for language: ${toLanguage}`);
+    }
+
+    // Parse statement to semantic roles
+    const parsed = this.parseStatement(input, fromLanguage, fromProfile);
+
+    // Translate each word
+    const translated = this.translateRoles(parsed, fromLanguage, toLanguage);
+
+    // Reorder and insert markers
+    const reordered = reorderRoles(translated, toProfile.canonicalOrder);
+
+    const withMarkers = insertMarkers(reordered, toProfile.markers, toProfile.adpositionType);
+
+    return joinTokens(withMarkers);
+  }
+
+  /**
+   * Parse statement into semantic roles.
+   * This is a simplified generic parser - DSLs can provide custom parsers.
+   */
+  private parseStatement(
+    input: string,
+    language: string,
+    profile: LanguageProfile
+  ): Map<SemanticRole, string> {
+    const roles = new Map<SemanticRole, string>();
+    const tokens = input.split(/\s+/);
+
+    // Simple parsing: extract roles based on markers
+    let i = 0;
+    while (i < tokens.length) {
+      const token = tokens[i];
+
+      // Check if token is a marker
+      const marker = profile.markers.find(m => m.form === token);
+
+      if (marker) {
+        // Next token is the value for this role
+        if (i + 1 < tokens.length) {
+          roles.set(marker.role, tokens[i + 1]);
+          i += 2;
+        } else {
+          i++;
+        }
+      } else {
+        // Look up token in dictionary to find its role
+        const canonical = this.dictionary.lookup(token, language);
+
+        if (canonical) {
+          // Assume it's the action (command keyword)
+          roles.set('action', canonical);
+        } else {
+          // Assume it's a value (selector, identifier, etc.)
+          // Try to guess the role based on syntax
+          if (token.startsWith('#') || token.startsWith('.')) {
+            roles.set('patient', token);
+          } else {
+            // Default to patient for unknown values
+            roles.set('patient', token);
+          }
+        }
+
+        i++;
+      }
+    }
+
+    return roles;
+  }
+
+  /**
+   * Translate roles using injected dictionary.
+   * Returns a Map of ParsedElement objects expected by reorderRoles.
+   */
+  private translateRoles(
+    roles: Map<SemanticRole, string>,
+    _fromLanguage: string,
+    toLanguage: string
+  ): Map<SemanticRole, ParsedElement> {
+    const result = new Map<SemanticRole, ParsedElement>();
+
+    for (const [role, value] of roles) {
+      // Translate using dictionary
+      const translated = this.dictionary.translate(value, toLanguage);
+
+      // Create ParsedElement with role, value, and translated
+      result.set(role, {
+        role,
+        value, // Original value
+        translated: translated ?? value, // Translated value or original if no translation
+      });
+    }
+
+    return result;
+  }
+}