@lokascript/framework 4.6.0 → 4.8.0

package/dist/testing/gate/round-trip.d.ts

@@ -0,0 +1,184 @@
+/**
+ * The round-trip gate kit (domains rethink Phase 4.6, `docs-internal/DOMAINS_RETHINK.md`): every
+ * command of a grammar, written in each of its languages by its own renderer and read back by its own
+ * parser. Moved from lokascript-domains' `packages/domains/gate/round-trip.ts` (the domain gate, Phase
+ * 2), so any grammar on the framework runs the same gate; the domains repo keeps its fixtures
+ * (`gate/values.ts`), baselines and regen tool.
+ *
+ * A case is a command (bracket syntax, parsed in English) and a language:
+ *
+ * - **round trip**: `render(ref, lang)`, then `parse`. `pass` when the parse is the reference node, or,
+ *   for a grammar whose compiled output does not depend on the language, when the text compiles to what
+ *   the command itself (its bracket form) compiles to (a parser may keep a translated word that the
+ *   generator normalizes: bdd ja `#box0 が 表示 前提` is `visible`). English is a lane like the others.
+ *   `refused` when the render is null or the parse throws: the caller is told. `silent` otherwise: it
+ *   reads, or compiles to, something else.
+ * - **leftover**: the same render plus one unknown word. `refused` is the expected outcome: the parse
+ *   throws, or the input does not compile. `pass` where the word is READ: the parse is the text's own
+ *   with the word in one role (an open-text role extended by it, `where active zzqx`, or a role the
+ *   text left empty, `list zzqx`), and the word is in the code (for a command that never compiles on
+ *   its own, `englishDoesNotCompile`, the parse alone). `silent` otherwise: the input is accepted and
+ *   read as something else (`when clicks zzqx`: actor `clicks`, action `zzqx`), or the word goes
+ *   nowhere (voice `back zzqx` compiles as `back`).
+ *
+ * The outcomes are the command-shape gate's (hyperfixi `testing-framework`). A baseline lists every
+ * case that is not at its best outcome; `compare` reports a case worse than listed and one better than
+ * listed, so a gate built on it only shrinks.
+ */
+export type Outcome = 'pass' | 'refused' | 'silent';
+export type CaseKind = 'roundTrip' | 'leftover';
+/** Best first. A round trip's best is `pass`; leftover input's is `refused`. */
+export declare const RANK: Record<CaseKind, Record<Outcome, number>>;
+export declare const BEST: Record<CaseKind, Outcome>;
+/** Appended for the leftover cases: a word no grammar's vocabulary has. */
+export declare const UNKNOWN_WORD = "zzqx";
+export interface CaseResult {
+    /** The grammar (a domain's name). */
+    grammar: string;
+    kind: CaseKind;
+    /** The command, in bracket syntax (read in English). */
+    source: string;
+    lang: string;
+    outcome: Outcome;
+    /** What the renderer wrote (plus the unknown word, for leftover). */
+    text?: string;
+    /** Why it is not `pass`: the error, or what the parse read instead. */
+    why?: string;
+    /** The round trip's parse, summarized (`summarize`); absent when it was refused. */
+    read?: string;
+}
+/** What the gate reads of a role in a schema. */
+export interface GateRoleSpec {
+    readonly role: string;
+    readonly required?: boolean;
+    readonly expectedTypes?: readonly string[];
+}
+/** What the gate reads of a command schema. */
+export interface GateSchema {
+    readonly action: string;
+    readonly roles: readonly GateRoleSpec[];
+}
+/** What the gate reads of a parse. */
+export interface GateNode {
+    readonly action: string;
+    readonly roles: ReadonlyMap<string, unknown> | Readonly<Record<string, unknown>>;
+}
+/** The grammar's DSL, as the gate drives it. */
+export interface GateDSL {
+    parse(input: string, language: string): GateNode;
+    compile(input: string, language: string): {
+        ok: boolean;
+        code?: string;
+        errors?: string[];
+    };
+    render?(node: GateNode, language: string): string | null;
+    getSupportedLanguages(): string[];
+}
+/**
+ * The values the gate writes into each role. A role not listed gets a plain name no vocabulary uses
+ * (`v0x`, or `#box0` where only a selector fits): its value must come back verbatim. A role that takes
+ * FIXED words lists every word the grammar's renderer and generator know, in English: the gate writes
+ * the command once per word, in every language, so a word one of the two tables lacks fails in the
+ * languages where it is missing.
+ */
+export interface GateFixture {
+    /**
+     * `compile`: a round trip also passes when the text compiles to the command's own code (the grammar
+     * compiles to something that does not depend on the language). `node`: only the parse counts (a
+     * grammar that compiles to a sentence in each language).
+     */
+    oracle: 'compile' | 'node';
+    /** Keys are `<action>.<role>` or `<role>` (every action). The first value is the one the other cases use. */
+    values: Record<string, string[]>;
+    /**
+     * Commands (bracket syntax) written besides the generated ones, where one role's value depends on
+     * another's and no single list fits both: behaviorspec's `[given subject:#box value:visible]` beside
+     * `[given subject:viewport value:1024x768]`.
+     */
+    commands?: string[];
+    /**
+     * Actions that do not compile on their own (a gate may check every other one does). Leftover input
+     * in such a command is judged by its parse alone.
+     */
+    englishDoesNotCompile?: string[];
+}
+/**
+ * The commands a grammar is checked on: for each schema, its required roles alone and all its roles
+ * (each with its first value), then each further value of a role that takes fixed words, alone.
+ */
+export declare function commandsFor(schemas: readonly GateSchema[], fixture: GateFixture): string[];
+/** A parse as one line: `action role:type=value …`, roles sorted. What the parse snapshot records. */
+export declare function summarize(node: GateNode): string;
+/**
+ * Whether `read`, the parse of a text plus `word`, is `back`, the text's own parse, with the word read
+ * into it: the same action and roles, except one role, whose value is its value in `back` followed by
+ * the word (an open-text role at the end: sql `where active zzqx`) or, where `back` has no such role,
+ * the word itself (todo `list zzqx`).
+ */
+export declare function readsWord(back: GateNode, read: GateNode, word: string): boolean;
+/** What a command (bracket syntax) compiles to; null when it does not compile on its own. */
+export declare function referenceCode(dsl: GateDSL, source: string): string | null;
+/** Run every case of one grammar: each command of `commandsFor` in each of the DSL's languages. */
+export declare function runRoundTrip(grammar: string, dsl: GateDSL, schemas: readonly GateSchema[], fixture: GateFixture): CaseResult[];
+export interface ListedCase {
+    outcome: Exclude<Outcome, 'pass'>;
+    text?: string;
+    why?: string;
+}
+export interface GateBaseline {
+    /** The upstream packages this was measured on (the grammar's lockfile). */
+    upstream: Record<string, string>;
+    /** Per grammar and kind: cases and outcomes. Written by the regen tool for the reader; not checked. */
+    counts: Record<string, Record<CaseKind, Record<Outcome | 'cases', number>>>;
+    /** Per grammar, command and language: every round trip that is not `pass`. */
+    roundTrip: Record<string, Record<string, Record<string, ListedCase>>>;
+    /** Per grammar and command: the languages whose leftover case was accepted (`silent`). */
+    leftover: Record<string, Record<string, string[]>>;
+}
+export interface DriftCase {
+    kind: CaseKind;
+    source: string;
+    lang: string;
+    listed: Outcome;
+    now: Outcome;
+    text?: string;
+    why?: string;
+}
+export interface Drift {
+    worse: DriftCase[];
+    better: DriftCase[];
+    /** Listed cases that are no longer cases at all. */
+    stale: {
+        kind: CaseKind;
+        source: string;
+        lang: string;
+    }[];
+}
+/** How one grammar's results moved against the baseline. */
+export declare function compare(grammar: string, results: CaseResult[], baseline: GateBaseline): Drift;
+/** The baseline entries for one grammar's results. */
+export declare function listingOf(results: CaseResult[]): {
+    roundTrip: Record<string, Record<string, ListedCase>>;
+    leftover: Record<string, string[]>;
+};
+export declare function countsOf(results: CaseResult[]): Record<CaseKind, Record<Outcome | 'cases', number>>;
+/**
+ * Every round trip's parse, so a change that moves a parse shows it, whether or not an outcome moved
+ * (a value's type, a role a passing case gained, what a silent case reads now). `refused` where the
+ * parse threw. Leftover cases are not in it: their outcome is the baseline's.
+ */
+export interface ParseSnapshot {
+    upstream: Record<string, string>;
+    /** Per grammar, command and language. */
+    parses: Record<string, Record<string, Record<string, string>>>;
+}
+export declare function snapshotOf(results: CaseResult[]): Record<string, Record<string, string>>;
+export interface SnapshotChange {
+    source: string;
+    lang: string;
+    was?: string;
+    now?: string;
+}
+/** Every round trip whose parse differs from the snapshot's, for one grammar. */
+export declare function snapshotChanges(grammar: string, results: CaseResult[], snapshot: ParseSnapshot): SnapshotChange[];
+//# sourceMappingURL=round-trip.d.ts.map

package/dist/testing/gate/round-trip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-trip.d.ts","sourceRoot":"","sources":["../../../src/testing/gate/round-trip.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lokascript/framework",
-  "version": "4.6.0",
+  "version": "4.8.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,7 +100,7 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@lokascript/intent": "^4.6.0"
+    "@lokascript/intent": "^4.8.0"
   },
   "devDependencies": {
     "@lokascript/domains": "^4.0.0",

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

@@ -13,6 +13,7 @@ import {
   getDefaultExtractors,
   type SemanticNode,
   type MultilingualDSL,
+  type DSLConfig,
 } from '../../index';
 
 // =============================================================================
@@ -168,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: [
@@ -190,7 +196,7 @@ export function createSQLDSL(): MultilingualDSL {
     codeGenerator: {
       generate: generateSQL,
     },
-  });
+  };
 }
 
 // =============================================================================

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

@@ -0,0 +1,150 @@
+/**
+ * `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. A role
+ * with a word list reads only its words.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { createMultilingualDSL, UnreadInputError, type DSLConfig } from './create-dsl';
+import { defineCommand, defineRole } from '../schema';
+import { BaseTokenizer, getDefaultExtractors } from '../index';
+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"');
+  });
+});
+
+describe('a role with a word list, on the core', () => {
+  class WordTokenizer extends BaseTokenizer {
+    readonly language = 'en';
+    readonly direction = 'ltr' as const;
+    constructor() {
+      super();
+      this.registerExtractors(getDefaultExtractors());
+    }
+    classifyToken(token: string): 'keyword' | 'identifier' {
+      return token.toLowerCase() === 'when' ? 'keyword' : 'identifier';
+    }
+  }
+  // behaviorspec's `when [actor] action`: both are bare words.
+  const when = defineCommand({
+    action: 'when',
+    primaryRole: 'action',
+    roles: [
+      defineRole({ role: 'actor', required: false, expectedTypes: ['expression'], svoPosition: 2 }),
+      defineRole({
+        role: 'action',
+        required: true,
+        expectedTypes: ['expression'],
+        svoPosition: 1,
+        words: { '*': ['clicks', 'types'] },
+      }),
+    ],
+  });
+  const dsl = createMultilingualDSL({
+    name: 'when',
+    schemas: [when],
+    languages: [
+      {
+        code: 'en',
+        name: 'English',
+        nativeName: 'English',
+        tokenizer: new WordTokenizer(),
+        patternProfile: {
+          code: 'en',
+          wordOrder: 'SVO',
+          keywords: { when: { primary: 'when' } },
+          roleMarkers: {},
+        },
+      },
+    ],
+    engine: 'core',
+  });
+
+  it('reads a listed word, with or without the optional role before it', () => {
+    expect(reading(dsl.parse('when clicks', 'en'))).toBe('when action=clicks');
+    expect(reading(dsl.parse('when user clicks', 'en'))).toBe('when actor=user action=clicks');
+  });
+
+  it('refuses a word it does not list, rather than reading the listed word as the role before it', () => {
+    // Without the list: actor `clicks`, action `zzqx`.
+    expect(() => dsl.parse('when clicks zzqx', 'en')).toThrow(UnreadInputError);
+    // A listed word is not part of a longer value, so the refusal does not say to quote it.
+    expect(() => dsl.parse('when clicks zzqx', 'en')).toThrow(/leaving "zzqx" unread$/);
+    expect(() => dsl.parse('when user frobs', 'en')).toThrow();
+  });
+});

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

@@ -449,6 +449,13 @@ describe('MultilingualDSL: Explicit Syntax Support', () => {
       expect(refusal.message).toMatch(/leaving "banana" unread/);
     });
 
+    it('says when the bare word read last and the next may be one value, to be quoted', () => {
+      const dsl = createTestDSL();
+      expect(() => dsl.parse('select name from users banana', 'en')).toThrow(
+        /unread; if "users banana" is one value, quote it$/
+      );
+    });
+
     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');