@lokascript/framework 2.9.4 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lokascript/framework",
-  "version": "2.9.4",
+  "version": "2.11.0",
   "description": "Generic framework for building multilingual DSLs with semantic parsing and grammar transformation",
   "type": "module",
   "main": "dist/index.cjs",
@@ -96,9 +96,10 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@lokascript/intent": "^2.9.4"
+    "@lokascript/intent": "^2.11.0"
   },
   "devDependencies": {
+    "@lokascript/domains": "^2.11.1",
     "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "^4.0.17",
     "tsup": "^8.0.0",

package/src/__tests__/api-surface.test.ts

@@ -0,0 +1,35 @@
+/**
+ * API-surface snapshot: the third-party extension contract.
+ *
+ * Domain packages now live OUTSIDE this repo (lokascript-domains, published as
+ * @lokascript/domains), so a signature change here no longer breaks anything
+ * in-tree at build time — this test is what makes an accidental change to the
+ * promised surface fail loudly instead. DOMAIN_AUTHOR_GUIDE.md documents the
+ * promise; docs/API_SURFACE.md is the committed snapshot.
+ *
+ * On a DELIBERATE contract change: regenerate with
+ * `npx tsx scripts/api-surface-report.ts`, commit the diff, and note the
+ * change in DOMAIN_AUTHOR_GUIDE.md.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractApiSurface } from '../../scripts/api-surface-lib';
+
+const PKG_ROOT = path.resolve(__dirname, '..', '..');
+
+describe('extension-contract API surface', () => {
+  it('matches the committed docs/API_SURFACE.md snapshot', () => {
+    const committed = readFileSync(path.join(PKG_ROOT, 'docs', 'API_SURFACE.md'), 'utf8');
+    const current = extractApiSurface(PKG_ROOT) + '\n';
+    expect(
+      current,
+      'API surface drifted from docs/API_SURFACE.md — if deliberate, regenerate with `npx tsx scripts/api-surface-report.ts` and update DOMAIN_AUTHOR_GUIDE.md'
+    ).toBe(committed);
+  });
+
+  it('the snapshot pins every promised export (no MISSING markers)', () => {
+    const committed = readFileSync(path.join(PKG_ROOT, 'docs', 'API_SURFACE.md'), 'utf8');
+    expect(committed).not.toContain('MISSING');
+  });
+});

package/src/aot/registry-bridge.test.ts

@@ -12,7 +12,7 @@ describe('registryToAOTBackends', () => {
       languages: ['en'],
       inputLabel: 'input',
       inputDescription: 'Test input',
-      getDSL: () => import('@lokascript/domain-sql').then(m => m.createSQLDSL()),
+      getDSL: () => import('@lokascript/domains/sql').then(m => m.createSQLDSL()),
       scanConfig: {
         attributes: ['data-test'],
         scriptTypes: ['text/test'],
@@ -38,7 +38,7 @@ describe('registryToAOTBackends', () => {
       languages: ['en'],
       inputLabel: 'input',
       inputDescription: 'Test',
-      getDSL: () => import('@lokascript/domain-sql').then(m => m.createSQLDSL()),
+      getDSL: () => import('@lokascript/domains/sql').then(m => m.createSQLDSL()),
       scanConfig: {
         attributes: ['data-with'],
         defaultLanguage: 'en',
@@ -51,7 +51,7 @@ describe('registryToAOTBackends', () => {
       languages: ['en'],
       inputLabel: 'input',
       inputDescription: 'Test',
-      getDSL: () => import('@lokascript/domain-sql').then(m => m.createSQLDSL()),
+      getDSL: () => import('@lokascript/domains/sql').then(m => m.createSQLDSL()),
       // no scanConfig
     });
 
@@ -69,7 +69,7 @@ describe('registryToAOTBackends', () => {
       languages: ['en'],
       inputLabel: 'input',
       inputDescription: 'Test',
-      getDSL: () => import('@lokascript/domain-sql').then(m => m.createSQLDSL()),
+      getDSL: () => import('@lokascript/domains/sql').then(m => m.createSQLDSL()),
     });
 
     const backends = await registryToAOTBackends(registry);
@@ -85,7 +85,7 @@ describe('registryToAOTBackends', () => {
       languages: ['en'],
       inputLabel: 'input',
       inputDescription: 'Test',
-      getDSL: () => import('@lokascript/domain-sql').then(m => m.createSQLDSL()),
+      getDSL: () => import('@lokascript/domains/sql').then(m => m.createSQLDSL()),
       scanConfig: {
         attributes: ['data-gen'],
         defaultLanguage: 'en',

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

@@ -39,7 +39,7 @@ const selectSchema = defineCommand({
       required: true,
       expectedTypes: ['expression'],
       svoPosition: 1,
-      markerOverride: { en: 'from' },
+      markerOverride: { en: 'from', es: 'de' },
     }),
   ],
 });
@@ -100,6 +100,62 @@ const englishProfile = {
   roleMarkers: {},
 };
 
+class SpanishTestTokenizer extends BaseTokenizer {
+  readonly language = 'es';
+  readonly direction = 'ltr' as const;
+
+  constructor() {
+    super();
+    this.registerExtractors(getDefaultExtractors());
+  }
+
+  classifyToken(token: string): 'keyword' | 'identifier' | 'literal' | 'operator' {
+    const keywords = ['seleccionar', 'insertar', 'de', 'en'];
+    if (keywords.includes(token.toLowerCase())) return 'keyword';
+    return 'identifier';
+  }
+}
+
+const spanishProfile = {
+  code: 'es',
+  name: 'Spanish',
+  nativeName: 'Español',
+  wordOrder: 'SVO' as const,
+  direction: 'ltr' as const,
+  caseMarking: 'preposition' as const,
+  keywords: {
+    select: { primary: 'seleccionar', aliases: [] },
+    insert: { primary: 'insertar', aliases: [] },
+    from: { primary: 'de', aliases: [] },
+    into: { primary: 'en', aliases: [] },
+  },
+  roleMarkers: {},
+};
+
+/** Two languages, NO grammarProfile on either — the nine-domains shape. */
+function createBilingualTestDSL() {
+  return createMultilingualDSL({
+    name: 'TestSQL-bilingual',
+    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,
+      },
+    ],
+  });
+}
+
 function createTestDSL() {
   return createMultilingualDSL({
     name: 'TestSQL',
@@ -273,23 +329,49 @@ describe('MultilingualDSL: Explicit Syntax Support', () => {
   // translate
   // ---------------------------------------------------------------------------
 
-  describe('translate', () => {
+  describe('translate (parse→render)', () => {
     it('returns explicit syntax unchanged', () => {
       const dsl = createTestDSL();
       const result = dsl.translate('[select columns:name source:users]', 'en', 'ja');
       expect(result).toBe('[select columns:name source:users]');
     });
 
-    // The test DSL configures no `grammarProfile`, which is legal for
-    // parse/validate/compile but not for translate. The error must name the
+    it('translates between configured languages with NO grammar profiles (the nine-domains shape)', () => {
+      const dsl = createBilingualTestDSL();
+      const result = dsl.translate('select name from users', 'en', 'es');
+      expect(result).toContain('seleccionar');
+      expect(result).toContain('name');
+      expect(result).toContain('users');
+      // The rendered Spanish is real DSL surface — it re-parses.
+      expect(dsl.validate(result, 'es').valid).toBe(true);
+    });
+
+    it('round-trips to the source language through the schema renderer', () => {
+      const dsl = createTestDSL();
+      const result = dsl.translate('select name from users', 'en', 'en');
+      expect(result.toLowerCase()).toContain('select');
+      expect(result).toContain('name');
+      expect(result).toContain('users');
+      expect(dsl.validate(result, 'en').valid).toBe(true);
+    });
+
+    // No renderer coverage for 'ja' (not a configured language) and no
+    // grammarProfile for the transformer fallback: the error must name the
     // field to set rather than leaving the caller with "No profile found".
-    it('throws an error naming grammarProfile when the profile is missing', () => {
+    it('throws an error naming grammarProfile when render cannot cover the target', () => {
       const dsl = createTestDSL();
       expect(() => dsl.translate('select name from users', 'en', 'ja')).toThrow(/grammarProfile/);
       expect(() => dsl.translate('select name from users', 'en', 'ja')).toThrow(
         /parse\/validate\/compile do not need it/
       );
     });
+
+    it('propagates the parse error for unparseable input when no fallback exists', () => {
+      const dsl = createTestDSL();
+      expect(() => dsl.translate('gibberish matching nothing', 'en', 'en')).toThrow(
+        /No pattern matched/
+      );
+    });
   });
 
   // ---------------------------------------------------------------------------

package/src/api/create-dsl.ts

@@ -35,8 +35,10 @@ export interface LanguageConfig {
   /**
    * Language profile for grammar transformation.
    *
-   * Optional for `parse()`, `validate()` and `compile()`, but **required for
-   * `translate()`** — omitting it makes `translate()` throw for this language.
+   * Optional everywhere: `translate()` primarily works parse→render through
+   * the schema-driven renderer, which needs no grammar profile. Configure this
+   * only to enable the whole-string GrammarTransformer FALLBACK for input the
+   * pattern matcher cannot parse (or actions render() cannot cover).
    */
   readonly grammarProfile?: GrammarProfile;
 }
@@ -407,23 +409,47 @@ class MultilingualDSLImpl implements MultilingualDSL {
     // Explicit syntax is language-agnostic — return unchanged
     if (isExplicitSyntax(input)) return input;
 
-    // translate() is the only path that needs grammar profiles; parse/validate/
-    // compile work without them. `grammarProfile` is optional on LanguageConfig,
-    // so omitting it fails here rather than at construction — name the missing
-    // field instead of leaving the transformer's bare "No profile found".
-    for (const language of [fromLanguage, toLanguage]) {
-      if (!this.profileProvider.getProfile(language)) {
-        throw new Error(
-          `translate() requires a grammar profile for language "${language}", but none is ` +
-            `configured. Set 'grammarProfile' on the LanguageConfig for "${language}" in ` +
-            `createMultilingualDSL() (parse/validate/compile do not need it), or inject a ` +
-            `custom 'profileProvider'.`
-        );
+    // Primary route: parse in the source language, render in the target — the
+    // same parse→render path DomainRegistry.translate uses. The schema-driven
+    // renderer covers every configured language, so this needs NO grammar
+    // profiles (before 2026-08 translate() required them and therefore threw
+    // for every domain in the family — none configures one).
+    let node: SemanticNode;
+    try {
+      node = this.parseWithConfidence(input, fromLanguage).node;
+    } catch (parseError) {
+      // Whole-string grammar transformation can sometimes translate input the
+      // pattern matcher cannot parse — but only when profiles are configured.
+      if (this.hasGrammarProfile(fromLanguage) && this.hasGrammarProfile(toLanguage)) {
+        return this.transformer.transform(input, fromLanguage, toLanguage);
       }
+      throw parseError;
     }
 
-    // Use injected grammar transformer
-    return this.transformer.transform(input, fromLanguage, toLanguage);
+    // Only consult render() for a CONFIGURED target language — the schema
+    // renderer's lookup tables fall back to raw action/marker names for
+    // unknown languages, which would silently return wrong-language output.
+    const rendered = this.registry.getSupportedLanguages().includes(toLanguage)
+      ? this.render(node, toLanguage)
+      : null;
+    if (rendered != null) return rendered;
+
+    // render() covered nothing for this action/language pair; fall back to the
+    // grammar transformer when profiles exist, otherwise name both remedies.
+    if (this.hasGrammarProfile(fromLanguage) && this.hasGrammarProfile(toLanguage)) {
+      return this.transformer.transform(input, fromLanguage, toLanguage);
+    }
+    throw new Error(
+      `translate() could not render action "${node.action}" in language "${toLanguage}": no ` +
+        `custom renderer, domain renderer, or schema pattern covers it, and no grammar ` +
+        `profile is configured for the transformer fallback. Either add "${toLanguage}" to ` +
+        `the DSL's languages/renderer, or set 'grammarProfile' on its LanguageConfig in ` +
+        `createMultilingualDSL() (parse/validate/compile do not need it).`
+    );
+  }
+
+  private hasGrammarProfile(language: string): boolean {
+    return this.profileProvider.getProfile(language) != null;
   }
 
   compile(input: string, language: string): CompileResult {

package/src/api/domain-registry.ts

@@ -117,7 +117,7 @@ export interface DomainDescriptor {
 }
 
 // =============================================================================
-// MCP Tool Types (minimal — compatible with @modelcontextprotocol/sdk)
+// MCP Tool Types (minimal — compatible with @modelcontextprotocol/server)
 // =============================================================================
 
 /**