@lokascript/framework 4.5.0 → 4.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lokascript/framework",
-  "version": "4.5.0",
+  "version": "4.7.0",
   "description": "Generic framework for building multilingual DSLs with semantic parsing and grammar transformation",
   "type": "module",
   "main": "dist/index.cjs",
@@ -56,6 +56,10 @@
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"
     },
+    "./testing/gate": {
+      "types": "./dist/testing/gate/index.d.ts",
+      "import": "./dist/testing/gate/index.js"
+    },
     "./ir": {
       "types": "./dist/ir/index.d.ts",
       "import": "./dist/ir/index.js"
@@ -96,10 +100,10 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@lokascript/intent": "^4.5.0"
+    "@lokascript/intent": "^4.7.0"
   },
   "devDependencies": {
-    "@lokascript/domains": "^3.0.1",
+    "@lokascript/domains": "^4.0.0",
     "@types/node": "^26.6.3",
     "@vitest/coverage-v8": "^5.0.0",
     "tsup": "^8.0.0",

package/src/__test__/fixtures/sql-dsl.ts

@@ -13,6 +13,7 @@ import {
   getDefaultExtractors,
   type SemanticNode,
   type MultilingualDSL,
+  type DSLConfig,
 } from '../../index';
 
 // =============================================================================
@@ -47,6 +48,9 @@ export const selectCommand = defineCommand({
       description: 'WHERE clause condition',
       required: false,
       expectedTypes: ['expression'],
+      // As in domain-sql: the condition is the rest of the input (`age > 18`). Without it the
+      // condition read `age` and dropped `> 18`, which parse accepted until it refused unread input.
+      greedy: true,
       svoPosition: 0,
       sovPosition: 0,
       markerOverride: { en: 'where', es: 'donde' },
@@ -165,7 +169,12 @@ function generateSQL(node: SemanticNode): string {
 // =============================================================================
 
 export function createSQLDSL(): MultilingualDSL {
-  return createMultilingualDSL({
+  return createMultilingualDSL(sqlDSLConfig());
+}
+
+/** The fixture's config, for a test that builds the DSL with another factory. */
+export function sqlDSLConfig(): DSLConfig {
+  return {
     name: 'SQL DSL Test Fixture',
     schemas: [selectCommand],
     languages: [
@@ -187,7 +196,7 @@ export function createSQLDSL(): MultilingualDSL {
     codeGenerator: {
       generate: generateSQL,
     },
-  });
+  };
 }
 
 // =============================================================================

package/src/__test__/sql-integration.test.ts

@@ -46,8 +46,8 @@ describe('SQL DSL Integration', () => {
       const condition = result.roles.get('condition');
       expect(condition).toBeDefined();
       if (condition && 'raw' in condition) {
-        // The condition role captures the expression after WHERE
-        expect(condition.raw).toBeTruthy();
+        // The condition role captures the whole expression after WHERE
+        expect(condition.raw).toBe('age > 18');
       }
     });
   });

package/src/api/create-dsl-engine.test.ts

@@ -0,0 +1,86 @@
+/**
+ * `engine: 'core'` (domains rethink Phase 4.7): the same config and DSL as the
+ * classic engine, read by the core. framework's SQL fixture reads, compiles and
+ * translates as it does on the classic engine, refuses what it does not read,
+ * and renders through its own patterns where no renderer is configured.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { createMultilingualDSL, UnreadInputError, type DSLConfig } from './create-dsl';
+import { sqlDSLConfig, testQueries, expectedSQL } from '../__test__/fixtures/sql-dsl';
+import type { SemanticNode } from '../core/types';
+import { generatePattern } from '../generation/pattern-generator';
+import { createSchemaPatternGenerator } from '../generation/schema-patterns';
+
+// Pass-through spies. On the SQL fixture the two engines read, compile and render alike, so
+// these are what show which engine a DSL was built on.
+vi.mock('../generation/pattern-generator', async importOriginal => {
+  const actual = await importOriginal<typeof import('../generation/pattern-generator')>();
+  return { ...actual, generatePattern: vi.fn(actual.generatePattern) };
+});
+vi.mock('../generation/schema-patterns', async importOriginal => {
+  const actual = await importOriginal<typeof import('../generation/schema-patterns')>();
+  return { ...actual, createSchemaPatternGenerator: vi.fn(actual.createSchemaPatternGenerator) };
+});
+
+const core = createMultilingualDSL({ ...sqlDSLConfig(), engine: 'core' });
+const classic = createMultilingualDSL(sqlDSLConfig());
+
+const reading = (node: SemanticNode) =>
+  [
+    node.action,
+    ...[...node.roles].map(
+      ([role, v]) =>
+        `${role}=${String((v as { value?: unknown; raw?: unknown }).value ?? (v as { raw?: unknown }).raw)}`
+    ),
+  ].join(' ');
+
+describe("createMultilingualDSL with engine: 'core'", () => {
+  const queries = [
+    ['en', testQueries.english.simple, expectedSQL.simple],
+    ['en', testQueries.english.withWhere, expectedSQL.withWhere],
+    ['es', testQueries.spanish.simple, 'SELECT nombre FROM usuarios'],
+    ['es', testQueries.spanish.withWhere, 'SELECT nombre FROM usuarios WHERE edad > 18'],
+  ] as const;
+
+  it.each(queries)('reads and compiles %s `%s` as the classic engine does', (lang, input, sql) => {
+    expect(reading(core.parse(input, lang))).toBe(reading(classic.parse(input, lang)));
+    expect(core.compile(input, lang).code).toBe(sql);
+  });
+
+  it.each(queries)('translates %s `%s` as the classic engine does', (lang, input) => {
+    const to = lang === 'en' ? 'es' : 'en';
+    expect(core.translate(input, lang, to)).toBe(classic.translate(input, lang, to));
+  });
+
+  it('refuses input it does not read', () => {
+    expect(() => core.parse('select name from users banana', 'en')).toThrow(UnreadInputError);
+    expect(core.validate('select name from users banana', 'en')).toMatchObject({
+      valid: false,
+      errorCode: 'unread-input',
+    });
+  });
+
+  it('renders through its patterns, in each language, what it reads back', () => {
+    const node = core.parse(testQueries.english.withWhere, 'en');
+    expect(core.render?.(node, 'en')).toBe('select name from users where age > 18');
+    expect(core.render?.(node, 'es')).toBe('seleccionar name de users donde age > 18');
+    expect(reading(core.parse(core.render!(node, 'es')!, 'es'))).toBe(reading(node));
+  });
+
+  it.each([
+    ['core', { engine: 'core' }],
+    ['classic', { engine: 'classic' }],
+    ['classic', {}],
+  ] as const)('builds on the %s engine with %o', (expected, option) => {
+    vi.mocked(generatePattern).mockClear();
+    vi.mocked(createSchemaPatternGenerator).mockClear();
+    createMultilingualDSL({ ...sqlDSLConfig(), ...option }).parse(testQueries.english.simple, 'en');
+    expect(vi.mocked(createSchemaPatternGenerator).mock.calls.length > 0).toBe(expected === 'core');
+    expect(vi.mocked(generatePattern).mock.calls.length > 0).toBe(expected === 'classic');
+  });
+
+  it('throws on an engine it does not know, rather than reading with the classic one', () => {
+    const misspelled = { ...sqlDSLConfig(), engine: 'cor' } as unknown as DSLConfig;
+    expect(() => createMultilingualDSL(misspelled)).toThrow('Unknown DSL engine "cor"');
+  });
+});

package/src/api/create-dsl.test.ts

@@ -13,6 +13,8 @@ import {
   defineRole,
   BaseTokenizer,
   getDefaultExtractors,
+  UnreadInputError,
+  TranslationReadBackError,
   type SemanticNode,
 } from '../index';
 
@@ -156,6 +158,35 @@ function createBilingualTestDSL() {
   });
 }
 
+/** The bilingual DSL with a custom renderer (and, optionally, a code generator). */
+function createBilingualTestDSLWith(
+  renderer: (node: SemanticNode, language: string) => string | null,
+  codeGenerator?: { generate(node: SemanticNode): string }
+) {
+  return createMultilingualDSL({
+    name: 'TestSQL-rendered',
+    schemas: [selectSchema, insertSchema],
+    languages: [
+      {
+        code: 'en',
+        name: 'English',
+        nativeName: 'English',
+        tokenizer: new EnglishTestTokenizer(),
+        patternProfile: englishProfile,
+      },
+      {
+        code: 'es',
+        name: 'Spanish',
+        nativeName: 'Español',
+        tokenizer: new SpanishTestTokenizer(),
+        patternProfile: spanishProfile,
+      },
+    ],
+    renderer,
+    ...(codeGenerator ? { codeGenerator } : {}),
+  });
+}
+
 function createTestDSL() {
   return createMultilingualDSL({
     name: 'TestSQL',
@@ -396,4 +427,93 @@ describe('MultilingualDSL: Explicit Syntax Support', () => {
       expect(result.code).toContain('SELECT');
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // Input left unread (DOMAINS_RETHINK.md, Phase 3)
+  // ---------------------------------------------------------------------------
+
+  describe('input left unread', () => {
+    it('refuses a parse that reads the command only by dropping what follows it', () => {
+      const dsl = createTestDSL();
+      let error: unknown;
+      try {
+        dsl.parse('select name from users banana', 'en');
+      } catch (e) {
+        error = e;
+      }
+      expect(error).toBeInstanceOf(UnreadInputError);
+      const refusal = error as UnreadInputError;
+      expect(refusal.code).toBe('unread-input');
+      expect(refusal.unread).toBe('banana');
+      expect(refusal.reading.action).toBe('select');
+      expect(refusal.message).toMatch(/leaving "banana" unread/);
+    });
+
+    it('compile and validate report the refusal instead of compiling the shorter reading', () => {
+      const dsl = createTestDSL();
+      const compiled = dsl.compile('select name from users banana banana', 'en');
+      expect(compiled.ok).toBe(false);
+      expect(compiled.errors?.[0]).toMatch(/leaving "banana banana" unread/);
+      expect(dsl.validate('select name from users banana', 'en').valid).toBe(false);
+    });
+
+    it('translate refuses too, rather than translating the shorter reading', () => {
+      const dsl = createBilingualTestDSL();
+      expect(() => dsl.translate('select name from users banana', 'en', 'es')).toThrow(
+        UnreadInputError
+      );
+    });
+
+    it('a translation that does not read back is refused, unless { lossy: "allow" }', () => {
+      // A renderer that drops the required source: the Spanish does not parse at all.
+      const dropsSource = createBilingualTestDSLWith(node =>
+        node.action === 'select' ? 'seleccionar nombre' : null
+      );
+      let error: unknown;
+      try {
+        dropsSource.translate('select nombre from users', 'en', 'es');
+      } catch (e) {
+        error = e;
+      }
+      expect(error).toBeInstanceOf(TranslationReadBackError);
+      const refusal = error as TranslationReadBackError;
+      expect(refusal.code).toBe('translation-does-not-read-back');
+      expect(refusal.partial).toBe('seleccionar nombre');
+      expect(refusal.reading).toBeNull();
+      expect(
+        dropsSource.translate('select nombre from users', 'en', 'es', { lossy: 'allow' })
+      ).toBe('seleccionar nombre');
+    });
+
+    it('a translation that reads with a value changed is refused, naming the role', () => {
+      const changesSource = createBilingualTestDSLWith(node =>
+        node.action === 'select' ? 'seleccionar nombre de clientes' : null
+      );
+      expect(() => changesSource.translate('select nombre from users', 'en', 'es')).toThrow(
+        /source: users → clientes/
+      );
+    });
+
+    it('a difference the code generator normalizes still reads back', () => {
+      // Upper case in the render, lower case in the generator: the nodes differ, the code does not.
+      const shouts = createBilingualTestDSLWith(
+        node => (node.action === 'select' ? 'seleccionar NOMBRE de USERS' : null),
+        {
+          generate: node =>
+            `${node.action} ${[...node.roles.values()]
+              .map(v => String((v as { raw?: unknown }).raw ?? '').toLowerCase())
+              .join(' ')}`,
+        }
+      );
+      expect(shouts.translate('select nombre from users', 'en', 'es')).toBe(
+        'seleccionar NOMBRE de USERS'
+      );
+    });
+
+    it('input read whole still parses, and nothing matching at all is still "No pattern matched"', () => {
+      const dsl = createTestDSL();
+      expect(dsl.parse('select name from users', 'en').action).toBe('select');
+      expect(() => dsl.parse('banana', 'en')).toThrow(/No pattern matched/);
+    });
+  });
 });