@lokascript/domain-learn 2.1.0

package/src/__tests__/sentence-generation.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Sentence Generation Tests — Verify morphology rendering across languages
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  createLearnDSL,
+  generateForFunction,
+  generateAllFunctions,
+  generateCrossLingual,
+  generateGloss,
+  renderLearn,
+  ALL_VERBS,
+  ALL_FUNCTIONS,
+} from '../index';
+import type { MultilingualDSL } from '@lokascript/framework';
+
+describe('Sentence Generation', () => {
+  let learn: MultilingualDSL;
+
+  beforeAll(() => {
+    learn = createLearnDSL();
+  });
+
+  describe('English Sentences', () => {
+    it('should render commanding form', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'commanding', 'en');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('add');
+      expect(result!.sentence).toContain('.active');
+      expect(result!.sentence).toContain('#button');
+      expect(result!.function).toBe('commanding');
+    });
+
+    it('should render describing form with thirdPerson', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'describing', 'en');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('adds');
+      expect(result!.sentence).toContain('the system');
+    });
+
+    it('should render narrating form with past tense', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'narrating', 'en');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('added');
+    });
+
+    it('should render questioning form', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'questioning', 'en');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('Did');
+    });
+
+    it('should render negating form', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'negating', 'en');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('did not');
+    });
+
+    it('should render planning form', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'planning', 'en');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('will');
+    });
+
+    it('should render progressing form', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'progressing', 'en');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('adding');
+    });
+
+    it('should handle irregular verbs correctly', () => {
+      const node = learn.parse('[go destination:#page]', 'explicit');
+      const past = generateForFunction(node, 'narrating', 'en');
+      expect(past).not.toBeNull();
+      expect(past!.sentence).toContain('went');
+    });
+
+    it('should handle source-role verbs', () => {
+      const node = learn.parse('[remove patient:.active source:#button]', 'explicit');
+      const result = generateForFunction(node, 'commanding', 'en');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('from');
+    });
+  });
+
+  describe('Japanese Sentences (SOV)', () => {
+    it('should render te-form command', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'commanding', 'ja');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('追加して');
+    });
+
+    it('should render polite present (masu)', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'describing', 'ja');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('追加します');
+      expect(result!.sentence).toContain('システム');
+    });
+
+    it('should place verb last in SOV order', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'commanding', 'ja');
+      expect(result).not.toBeNull();
+      // Verb should be at the end
+      const sentence = result!.sentence;
+      expect(sentence.endsWith('追加して')).toBe(true);
+    });
+  });
+
+  describe('Arabic Sentences (VSO)', () => {
+    it('should render imperative', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const result = generateForFunction(node, 'commanding', 'ar');
+      expect(result).not.toBeNull();
+      expect(result!.sentence).toContain('أضِف');
+    });
+  });
+
+  describe('All Languages x All Functions', () => {
+    const languages = ['en', 'ja', 'es', 'ar', 'zh', 'ko', 'fr', 'tr', 'de', 'pt'];
+
+    it('should generate sentences for all 70 language x function combinations', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      let count = 0;
+      for (const lang of languages) {
+        for (const fn of ALL_FUNCTIONS) {
+          const result = generateForFunction(node, fn, lang);
+          expect(result).not.toBeNull();
+          expect(result!.sentence.length).toBeGreaterThan(0);
+          count++;
+        }
+      }
+      expect(count).toBe(70);
+    });
+  });
+
+  describe('generateAllFunctions', () => {
+    it('should return 7 sentences for English', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const results = generateAllFunctions(node, 'en');
+      expect(results).toHaveLength(7);
+    });
+  });
+
+  describe('generateCrossLingual', () => {
+    it('should return sentences for all registered languages', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const results = generateCrossLingual(node, 'commanding');
+      expect(results.length).toBe(10);
+    });
+  });
+
+  describe('renderLearn', () => {
+    it('should render DSL text in English', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const text = renderLearn(node, 'en');
+      expect(text).toContain('add');
+      expect(text).toContain('.active');
+    });
+
+    it('should render DSL text in Japanese', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const text = renderLearn(node, 'ja');
+      expect(text).toContain('追加して');
+    });
+  });
+
+  describe('generateGloss', () => {
+    it('should produce interlinear gloss for add', () => {
+      const node = learn.parse('[add patient:.active destination:#button]', 'explicit');
+      const gloss = generateGloss(node, 'commanding', 'ja');
+      expect(gloss).not.toBeNull();
+      expect(gloss!.tokens.length).toBeGreaterThan(0);
+      expect(gloss!.roles.length).toBe(gloss!.tokens.length);
+      expect(gloss!.english.length).toBe(gloss!.tokens.length);
+      expect(gloss!.roles).toContain('VERB');
+    });
+  });
+});

package/src/generators/gloss-generator.ts

@@ -0,0 +1,145 @@
+/**
+ * Gloss Generator — Interlinear Gloss for Learning
+ *
+ * Produces interlinear glosses from a SemanticNode, showing:
+ *   tokens:  target language tokens  ["#buttonに", ".activeを", "追加して"]
+ *   roles:   grammatical labels      ["DEST", "PAT", "VERB"]
+ *   english: English gloss           ["to #button", ".active", "add (imperative)"]
+ *
+ * Glosses help ESL students understand the grammatical function of each
+ * word/particle in context, and help code students understand the mapping
+ * between natural language and programming operations.
+ */
+
+import type { SemanticNode } from '@lokascript/framework';
+import { extractRoleValue } from '@lokascript/framework';
+import type { InterlinearGloss, CommunicativeFunction } from '../types';
+import { resolveMarker, attachMarker, getProfile } from './sentence-generator';
+
+/** Abbreviated role labels for gloss display */
+const ROLE_LABELS: Record<string, string> = {
+  patient: 'PAT',
+  destination: 'DEST',
+  source: 'SRC',
+  instrument: 'INST',
+  style: 'STYLE',
+  manner: 'MANNER',
+};
+
+const FUNCTION_LABELS: Record<string, string> = {
+  commanding: 'imperative',
+  describing: 'present',
+  narrating: 'past',
+  questioning: 'question',
+  negating: 'negative',
+  planning: 'future',
+  progressing: 'progressive',
+};
+
+/** SOV languages where particles attach to nouns */
+const POSTPOSITIONAL = new Set(['ja', 'ko']);
+
+/** Command profiles for gloss generation */
+const PROFILES: Record<string, { hasPatient: boolean; targetRole: string | null }> = {
+  add: { hasPatient: true, targetRole: 'destination' },
+  remove: { hasPatient: true, targetRole: 'source' },
+  toggle: { hasPatient: true, targetRole: 'destination' },
+  put: { hasPatient: true, targetRole: 'destination' },
+  set: { hasPatient: true, targetRole: 'destination' },
+  show: { hasPatient: true, targetRole: null },
+  hide: { hasPatient: true, targetRole: null },
+  get: { hasPatient: false, targetRole: 'source' },
+  wait: { hasPatient: true, targetRole: null },
+  fetch: { hasPatient: false, targetRole: 'source' },
+  send: { hasPatient: true, targetRole: 'destination' },
+  go: { hasPatient: false, targetRole: 'destination' },
+  increment: { hasPatient: true, targetRole: null },
+  decrement: { hasPatient: true, targetRole: null },
+  take: { hasPatient: true, targetRole: 'source' },
+};
+
+/**
+ * Generate an interlinear gloss for a SemanticNode.
+ */
+export function generateGloss(
+  node: SemanticNode,
+  fn: CommunicativeFunction,
+  language: string
+): InterlinearGloss | null {
+  const profile = getProfile(language);
+  if (!profile) return null;
+
+  const verb = node.action;
+  const cmdProfile = PROFILES[verb];
+  if (!cmdProfile) return null;
+
+  const forms = profile.morphologyTable[verb];
+  if (!forms) return null;
+
+  const frame = profile.frames.frames.find(f => f.function === fn);
+  if (!frame) return null;
+
+  const tokens: string[] = [];
+  const roles: string[] = [];
+  const english: string[] = [];
+
+  const patientValue = extractRoleValue(node, 'patient') || '';
+  const targetRole = cmdProfile.targetRole;
+  const targetValue = targetRole ? extractRoleValue(node, targetRole) || '' : '';
+
+  const isSOV = profile.frames.wordOrder === 'SOV';
+
+  if (isSOV) {
+    // SOV order: target, patient, verb
+    if (targetValue && targetRole) {
+      const marker = resolveMarker(verb, targetRole, language);
+      tokens.push(attachMarker(targetValue, marker));
+      roles.push(ROLE_LABELS[targetRole] || targetRole.toUpperCase());
+      english.push(attachMarker(targetValue, resolveMarker(verb, targetRole, 'en')));
+    }
+    if (patientValue && cmdProfile.hasPatient) {
+      const marker = resolveMarker(verb, 'patient', language);
+      tokens.push(attachMarker(patientValue, marker));
+      roles.push(ROLE_LABELS.patient);
+      english.push(patientValue);
+    }
+  } else {
+    // SVO order: patient, target (verb is handled separately)
+    if (patientValue && cmdProfile.hasPatient) {
+      const marker = resolveMarker(verb, 'patient', language);
+      tokens.push(attachMarker(patientValue, marker));
+      roles.push(ROLE_LABELS.patient);
+      english.push(patientValue);
+    }
+    if (targetValue && targetRole) {
+      const marker = resolveMarker(verb, targetRole, language);
+      tokens.push(attachMarker(targetValue, marker));
+      roles.push(ROLE_LABELS[targetRole] || targetRole.toUpperCase());
+      english.push(attachMarker(targetValue, resolveMarker(verb, targetRole, 'en')));
+    }
+  }
+
+  // Resolve verb form
+  const verbFormPath = frame.verbForm;
+  const parts = verbFormPath.split('.');
+  let verbValue: unknown = forms;
+  for (const part of parts) {
+    if (verbValue == null || typeof verbValue !== 'object') break;
+    verbValue = (verbValue as Record<string, unknown>)[part];
+  }
+  const verbStr = typeof verbValue === 'string' ? verbValue : verb;
+
+  if (isSOV) {
+    // Verb last in SOV
+    tokens.push(verbStr);
+    roles.push('VERB');
+    english.push(`${verb} (${FUNCTION_LABELS[fn] || fn})`);
+  } else {
+    // Verb first in SVO — prepend
+    tokens.unshift(verbStr);
+    roles.unshift('VERB');
+    english.unshift(`${verb} (${FUNCTION_LABELS[fn] || fn})`);
+  }
+
+  return { tokens, roles, english };
+}

package/src/generators/learn-renderer.ts

@@ -0,0 +1,291 @@
+/**
+ * Learn Renderer — SemanticNode → DSL text in any language
+ *
+ * Inverse of the parser: converts a parsed SemanticNode back to
+ * natural-language DSL text. Used for cross-language translation
+ * exercises and round-trip verification.
+ */
+
+import type { SemanticNode } from '@lokascript/framework';
+import { extractRoleValue } from '@lokascript/framework';
+
+/** Verb keyword translations: action → language → native keyword */
+const COMMAND_KEYWORDS: Record<string, Record<string, string>> = {
+  add: {
+    en: 'add',
+    ja: '追加して',
+    es: 'agrega',
+    ar: 'أضف',
+    zh: '添加',
+    ko: '추가해',
+    fr: 'ajoute',
+    tr: 'ekle',
+    de: 'füge hinzu',
+    pt: 'adicione',
+  },
+  remove: {
+    en: 'remove',
+    ja: '削除して',
+    es: 'elimina',
+    ar: 'أزل',
+    zh: '移除',
+    ko: '제거해',
+    fr: 'supprime',
+    tr: 'kaldır',
+    de: 'entferne',
+    pt: 'remova',
+  },
+  toggle: {
+    en: 'toggle',
+    ja: '切り替えて',
+    es: 'alterna',
+    ar: 'بدّل',
+    zh: '切换',
+    ko: '전환해',
+    fr: 'bascule',
+    tr: 'değiştir',
+    de: 'schalte um',
+    pt: 'alterne',
+  },
+  put: {
+    en: 'put',
+    ja: '置いて',
+    es: 'pon',
+    ar: 'ضع',
+    zh: '放置',
+    ko: '넣어',
+    fr: 'mets',
+    tr: 'koy',
+    de: 'setze',
+    pt: 'coloque',
+  },
+  set: {
+    en: 'set',
+    ja: '設定して',
+    es: 'establece',
+    ar: 'عيّن',
+    zh: '设置',
+    ko: '설정해',
+    fr: 'définis',
+    tr: 'ayarla',
+    de: 'stelle ein',
+    pt: 'defina',
+  },
+  show: {
+    en: 'show',
+    ja: '表示して',
+    es: 'muestra',
+    ar: 'أظهر',
+    zh: '显示',
+    ko: '표시해',
+    fr: 'affiche',
+    tr: 'göster',
+    de: 'zeige',
+    pt: 'mostre',
+  },
+  hide: {
+    en: 'hide',
+    ja: '隠して',
+    es: 'oculta',
+    ar: 'أخفِ',
+    zh: '隐藏',
+    ko: '숨겨',
+    fr: 'masque',
+    tr: 'gizle',
+    de: 'verberge',
+    pt: 'esconda',
+  },
+  get: {
+    en: 'get',
+    ja: '取得して',
+    es: 'obtén',
+    ar: 'احصل',
+    zh: '获取',
+    ko: '가져와',
+    fr: 'obtiens',
+    tr: 'al',
+    de: 'rufe ab',
+    pt: 'obtenha',
+  },
+  wait: {
+    en: 'wait',
+    ja: '待って',
+    es: 'espera',
+    ar: 'انتظر',
+    zh: '等待',
+    ko: '기다려',
+    fr: 'attends',
+    tr: 'bekle',
+    de: 'warte',
+    pt: 'espere',
+  },
+  fetch: {
+    en: 'fetch',
+    ja: '取得して',
+    es: 'busca',
+    ar: 'اجلب',
+    zh: '获取',
+    ko: '가져와',
+    fr: 'récupère',
+    tr: 'getir',
+    de: 'rufe ab',
+    pt: 'busque',
+  },
+  send: {
+    en: 'send',
+    ja: '送って',
+    es: 'envía',
+    ar: 'أرسل',
+    zh: '发送',
+    ko: '보내',
+    fr: 'envoie',
+    tr: 'gönder',
+    de: 'sende',
+    pt: 'envie',
+  },
+  go: {
+    en: 'go',
+    ja: '行って',
+    es: 've',
+    ar: 'اذهب',
+    zh: '前往',
+    ko: '이동해',
+    fr: 'va',
+    tr: 'git',
+    de: 'gehe',
+    pt: 'vá',
+  },
+  increment: {
+    en: 'increment',
+    ja: '増加して',
+    es: 'incrementa',
+    ar: 'زد',
+    zh: '增加',
+    ko: '증가시켜',
+    fr: 'incrémente',
+    tr: 'artır',
+    de: 'erhöhe',
+    pt: 'incremente',
+  },
+  decrement: {
+    en: 'decrement',
+    ja: '減少して',
+    es: 'decrementa',
+    ar: 'أنقص',
+    zh: '减少',
+    ko: '감소시켜',
+    fr: 'décrémente',
+    tr: 'azalt',
+    de: 'verringere',
+    pt: 'decremente',
+  },
+  take: {
+    en: 'take',
+    ja: '取って',
+    es: 'toma',
+    ar: 'خذ',
+    zh: '取走',
+    ko: '가져가',
+    fr: 'prends',
+    tr: 'al',
+    de: 'nimm',
+    pt: 'pegue',
+  },
+};
+
+/** Role marker translations for DSL text rendering */
+const MARKERS: Record<string, Record<string, string>> = {
+  to: {
+    en: 'to',
+    ja: 'に',
+    es: 'a',
+    ar: 'إلى',
+    zh: '到',
+    ko: '에',
+    fr: 'à',
+    tr: 'a',
+    de: 'zu',
+    pt: 'a',
+  },
+  from: {
+    en: 'from',
+    ja: 'から',
+    es: 'de',
+    ar: 'من',
+    zh: '从',
+    ko: '에서',
+    fr: 'de',
+    tr: 'dan',
+    de: 'von',
+    pt: 'de',
+  },
+  into: {
+    en: 'into',
+    ja: 'に',
+    es: 'en',
+    ar: 'في',
+    zh: '到',
+    ko: '에',
+    fr: 'dans',
+    tr: 'a',
+    de: 'in',
+    pt: 'em',
+  },
+  on: {
+    en: 'on',
+    ja: 'で',
+    es: 'en',
+    ar: 'على',
+    zh: '在',
+    ko: '에',
+    fr: 'sur',
+    tr: 'da',
+    de: 'auf',
+    pt: 'em',
+  },
+};
+
+const SOV_LANGUAGES = new Set(['ja', 'ko', 'tr']);
+
+/**
+ * Render a SemanticNode as DSL text in the target language.
+ * Produces the commanding form (imperative) of the command.
+ */
+export function renderLearn(node: SemanticNode, language: string): string {
+  const keyword = COMMAND_KEYWORDS[node.action]?.[language] ?? node.action;
+  const patient = extractRoleValue(node, 'patient') || '';
+  const destination = extractRoleValue(node, 'destination') || '';
+  const source = extractRoleValue(node, 'source') || '';
+
+  const parts: string[] = [];
+
+  if (SOV_LANGUAGES.has(language)) {
+    // SOV: target markers patient markers verb
+    if (destination) {
+      const marker = MARKERS.to[language] || '';
+      parts.push(marker ? `${destination}${marker}` : destination);
+    }
+    if (source) {
+      const marker = MARKERS.from[language] || '';
+      parts.push(marker ? `${source}${marker}` : source);
+    }
+    if (patient) parts.push(patient);
+    parts.push(keyword);
+  } else {
+    // SVO/VSO: verb patient marker target
+    parts.push(keyword);
+    if (patient) parts.push(patient);
+    if (destination) {
+      const marker = MARKERS.to[language] || '';
+      if (marker) parts.push(marker);
+      parts.push(destination);
+    }
+    if (source) {
+      const marker = MARKERS.from[language] || '';
+      if (marker) parts.push(marker);
+      parts.push(source);
+    }
+  }
+
+  return parts.filter(Boolean).join(' ');
+}