@lokascript/framework 3.1.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lokascript/framework",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Generic framework for building multilingual DSLs with semantic parsing and grammar transformation",
   "type": "module",
   "main": "dist/index.cjs",
@@ -96,15 +96,15 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@lokascript/intent": "^3.1.0"
+    "@lokascript/intent": "^3.2.0"
   },
   "devDependencies": {
-    "@lokascript/domains": "^2.11.1",
-    "@types/node": "^26.1.2",
-    "@vitest/coverage-v8": "^4.0.17",
+    "@lokascript/domains": "^3.0.0",
+    "@types/node": "^26.6.3",
+    "@vitest/coverage-v8": "^5.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^4.1.5"
+    "vitest": "^5.0.2"
   },
   "files": [
     "dist",

package/src/core/tokenization/apostrophe-possessive.test.ts

@@ -25,6 +25,18 @@ describe('StringLiteralExtractor: apostrophe after a word character', () => {
     expect(extractor.canExtract(input, position)).toBe(false);
   });
 
+  // A word can end in a combining mark: bn, hi and th write `event` with a
+  // final vowel sign or tone mark (PR 109: `ঘটনা's target's id` lexed `'s
+  // target'` as one string).
+  it.each(["ঘটনা's target's id", "घटना's target's id", "เหตุการณ์'s target's id"])(
+    'does not open a string after a combining mark in %s',
+    input => {
+      for (let i = input.indexOf("'"); i >= 0; i = input.indexOf("'", i + 1)) {
+        expect(extractor.canExtract(input, i)).toBe(false);
+      }
+    }
+  );
+
   it.each([
     ["put 'hello' into me", 4],
     ["log 'a' + 'b'", 4],

package/src/interfaces/value-extractor.ts

@@ -92,7 +92,11 @@ export class StringLiteralExtractor implements ValueExtractor {
     // literal, which swallowed the operator and hid the property noun from
     // translation in every language that renders `'s`. A quote that opens a
     // string always follows whitespace, punctuation, or the start of input.
-    if (char === "'" && position > 0 && /[\p{L}\p{N}_)\]]/u.test(input[position - 1])) {
+    // A word can end in a combining mark: bn `ঘটনা`, hi `घटना` and th
+    // `เหตุการณ์` (event) end in a vowel sign or a tone mark, and without
+    // `\p{M}` their `'s` paired with the next one (`ঘটনা's target's id` lexed
+    // `'s target'` as a string).
+    if (char === "'" && position > 0 && /[\p{L}\p{M}\p{N}_)\]]/u.test(input[position - 1])) {
       return false;
     }
     return (

package/src/ir/from-interchange.test.ts

@@ -627,17 +627,31 @@ describe('fromInterchangeNode: control flow', () => {
     expect(node.roles.get('condition')).toEqual({ type: 'literal', value: 'running' });
   });
 
-  it('converts RepeatNode (until)', () => {
+  // The event is the EVENT, not an until condition: `until "done"` would test a
+  // truthy string and end at once.
+  it('converts RepeatNode (until event), keeping the event and where it listens', () => {
     const node = fromInterchangeNode({
       type: 'repeat',
       untilEvent: 'done',
+      untilEventTarget: { type: 'selector', value: '#b' },
       body: [],
     });
 
     expect(node.kind).toBe('loop');
     const loop = node as { loopVariant: string };
     expect(loop.loopVariant).toBe('until');
-    expect(node.roles.get('condition')).toEqual({ type: 'literal', value: 'done' });
+    expect(node.roles.get('loopType')).toEqual({ type: 'literal', value: 'until-event' });
+    expect(node.roles.get('event')).toEqual({ type: 'literal', value: 'done' });
+    expect(node.roles.get('source')).toMatchObject({ type: 'selector', value: '#b' });
+    expect(node.roles.has('condition')).toBe(false);
+  });
+
+  it.each([
+    { type: 'repeat', count: 3, indexName: 'i', body: [] },
+    { type: 'while', condition: { type: 'identifier', value: 'x' }, indexName: 'i', body: [] },
+  ])('keeps `index i` on a $type loop', interchange => {
+    const loop = fromInterchangeNode(interchange) as { indexVariable?: string };
+    expect(loop.indexVariable).toBe('i');
   });
 
   it('converts ForEachNode', () => {

package/src/ir/from-interchange.ts

@@ -216,13 +216,26 @@ function convertRepeat(node: INode): SemanticNode {
     variant = 'while';
     roles.condition = convertValue(node.whileCondition as INode);
   } else if (typeof node.untilEvent === 'string') {
+    // `repeat until event e from t`: the event and where it listens, as the
+    // semantic parser holds them, plus the exact form `loopVariant` folds into
+    // `until`. The event name was the CONDITION, an `until "e"` loop that a
+    // truthy string ends at once.
     variant = 'until';
-    roles.condition = createLiteral(node.untilEvent);
+    roles.loopType = createLiteral('until-event');
+    roles.event = createLiteral(node.untilEvent);
+    if (node.untilEventTarget && typeof node.untilEventTarget === 'object') {
+      roles.source = convertValue(node.untilEventTarget as INode);
+    }
   } else {
     variant = 'forever';
   }
 
-  return createLoopNode('repeat', roles, variant, body);
+  return createLoopNode('repeat', roles, variant, body, undefined, indexNameOf(node));
+}
+
+/** `index i`, which every loop form can name. */
+function indexNameOf(node: INode): string | undefined {
+  return typeof node.indexName === 'string' ? node.indexName : undefined;
 }
 
 function convertForEach(node: INode): SemanticNode {
@@ -235,9 +248,8 @@ function convertForEach(node: INode): SemanticNode {
   }
 
   const itemName = typeof node.itemName === 'string' ? node.itemName : undefined;
-  const indexName = typeof node.indexName === 'string' ? node.indexName : undefined;
 
-  return createLoopNode('repeat', roles, 'for', body, itemName, indexName);
+  return createLoopNode('repeat', roles, 'for', body, itemName, indexNameOf(node));
 }
 
 function convertWhile(node: INode): SemanticNode {
@@ -249,7 +261,7 @@ function convertWhile(node: INode): SemanticNode {
     roles.condition = convertValue(node.condition as INode);
   }
 
-  return createLoopNode('repeat', roles, 'while', body);
+  return createLoopNode('repeat', roles, 'while', body, undefined, indexNameOf(node));
 }
 
 // =============================================================================

package/src/ir/to-runtime-ast.test.ts

@@ -0,0 +1,113 @@
+/**
+ * `semanticNodeToRuntimeAST` writes a loop in the shape core's parser builds:
+ * the form in `modifiers.loopType`, the operands in `for`/`in`, `times`,
+ * `while`/`until`, `event`/`from` and `index`, the body the one block.
+ *
+ * It wrote `args: [count]` with `loopVariant` and `body` beside it, a shape
+ * core's `repeat` has not read since the slot migration, so every loop through
+ * `evalLSE` threw "repeat command requires a loop type". core's
+ * `lse/loop-lse.test.ts` RUNS these; this pins the shape where it is written.
+ */
+import { describe, it, expect } from 'vitest';
+import { semanticNodeToRuntimeAST } from './to-runtime-ast';
+import { parseExplicit } from './explicit-parser';
+import { createLoopNode, createLiteral, createCommandNode } from '../core/types';
+
+const slot = (value: string) => ({ type: 'string', value });
+const TOGGLE = '[toggle patient:.a]';
+
+function loop(explicit: string): Record<string, unknown> {
+  return semanticNodeToRuntimeAST(parseExplicit(explicit)) as unknown as Record<string, unknown>;
+}
+
+describe('a loop becomes core’s slot-shaped repeat', () => {
+  it('counted', () => {
+    expect(loop(`[repeat quantity:3 loop-variant:times loop-body:${TOGGLE}]`)).toEqual({
+      type: 'command',
+      name: 'repeat',
+      args: [{ type: 'block', commands: [expect.objectContaining({ name: 'toggle' })] }],
+      modifiers: { loopType: slot('times'), times: { type: 'literal', value: 3 } },
+    });
+  });
+
+  it('for-in', () => {
+    expect(
+      loop(`[for source:.i variable:p loop-variant:for loop-body:${TOGGLE}]`).modifiers
+    ).toEqual({
+      loopType: slot('for'),
+      for: slot('p'),
+      in: { type: 'selector', value: '.i' },
+    });
+  });
+
+  it.each(['while', 'until'])('%s', form => {
+    const modifiers = loop(`[repeat condition:done loop-variant:${form} loop-body:${TOGGLE}]`)
+      .modifiers as Record<string, unknown>;
+    expect(modifiers.loopType).toEqual(slot(form));
+    expect(modifiers[form]).toBeDefined();
+  });
+
+  // `loopVariant` folds `until event` into `until`; the loopType role keeps it.
+  it('until event, from a target', () => {
+    expect(
+      loop(
+        `[repeat loop-variant:until loopType:until-event event:stop source:#b loop-body:${TOGGLE}]`
+      ).modifiers
+    ).toEqual({
+      loopType: slot('until-event'),
+      event: slot('stop'),
+      from: { type: 'selector', value: '#b' },
+    });
+  });
+
+  it('forever', () => {
+    expect(loop(`[repeat loop-variant:forever loop-body:${TOGGLE}]`).modifiers).toEqual({
+      loopType: slot('forever'),
+    });
+  });
+
+  it('`index i`', () => {
+    const modifiers = loop(
+      `[repeat quantity:2 loop-variant:times index-variable:i loop-body:${TOGGLE}]`
+    ).modifiers as Record<string, unknown>;
+    expect(modifiers.index).toEqual(slot('i'));
+  });
+
+  it('reads a count from `patient`, as the old shape did', () => {
+    const node = createLoopNode('repeat', { patient: createLiteral(4, 'number') }, 'times', [
+      createCommandNode('toggle', {}),
+    ]);
+    const ast = semanticNodeToRuntimeAST(node) as unknown as Record<string, unknown>;
+    expect((ast.modifiers as Record<string, unknown>).times).toEqual({
+      type: 'literal',
+      value: 4,
+    });
+  });
+});
+
+describe('an if becomes core’s args-shaped if', () => {
+  it('with its then- and else-blocks', () => {
+    const ast = semanticNodeToRuntimeAST(
+      parseExplicit('[if condition:true then:[toggle patient:.a] else:[toggle patient:.b]]')
+    ) as unknown as Record<string, unknown>;
+    expect(ast).toEqual({
+      type: 'command',
+      name: 'if',
+      args: [
+        { type: 'literal', value: true },
+        { type: 'block', commands: [expect.objectContaining({ name: 'toggle' })] },
+        { type: 'block', commands: [expect.objectContaining({ name: 'toggle' })] },
+      ],
+    });
+  });
+
+  it('without an else-block when there is none', () => {
+    const ast = semanticNodeToRuntimeAST(parseExplicit(`[if condition:true then:${TOGGLE}]`));
+    expect((ast as unknown as { args: unknown[] }).args).toHaveLength(2);
+  });
+
+  it('with empty args when it has no condition, so core refuses it', () => {
+    const ast = semanticNodeToRuntimeAST(parseExplicit(`[if then:${TOGGLE}]`));
+    expect((ast as unknown as { args: unknown[] }).args).toEqual([]);
+  });
+});

package/src/ir/to-runtime-ast.ts

@@ -128,29 +128,97 @@ function convertCommand(node: SemanticNode): RuntimeCommandNode {
   };
 }
 
+/** A body as core's parser holds one: a block of commands. */
+function block(nodes: readonly SemanticNode[] | undefined): RuntimeASTNode {
+  return { type: 'block', commands: (nodes ?? []).map(semanticNodeToRuntimeAST) };
+}
+
+/**
+ * An `if` as core's parser builds it: `args: [condition, then-block,
+ * else-block?]`. This wrote the branches beside `args: [condition]`, so every
+ * `if` through `evalLSE` threw "if command requires "then" branch with
+ * commands".
+ */
 function convertConditional(node: ConditionalSemanticNode): RuntimeASTNode {
+  const name = node.action === 'unless' ? 'unless' : 'if';
   const conditionValue = node.roles.get('condition');
+  // No condition is malformed: empty args make core say so.
+  if (!conditionValue) return { type: 'command', name, args: [] };
   return {
     type: 'command',
-    name: 'if',
-    args: conditionValue ? [semanticValueToAST(conditionValue)] : [],
-    condition: conditionValue ? semanticValueToAST(conditionValue) : undefined,
-    thenBranch: (node.thenBranch ?? []).map(semanticNodeToRuntimeAST),
-    elseBranch: (node.elseBranch ?? []).map(semanticNodeToRuntimeAST),
+    name,
+    args: [
+      semanticValueToAST(conditionValue),
+      block(node.thenBranch),
+      ...(node.elseBranch && node.elseBranch.length > 0 ? [block(node.elseBranch)] : []),
+    ],
   };
 }
 
+/** The loop forms core's `repeat` runs: its parser's `loopType`. */
+const LOOP_FORMS = new Set(['for', 'times', 'while', 'until', 'until-event', 'forever']);
+
+/** The text of a name-like value: a loop form, an event name. */
+function valueText(value: SemanticValue | undefined): string | undefined {
+  if (!value) return undefined;
+  if (value.type === 'literal') return String(value.value);
+  if (value.type === 'expression') return value.raw;
+  if (value.type === 'reference' || value.type === 'selector') return value.value;
+  return undefined;
+}
+
+/**
+ * A loop as core's parser builds it (Arc 3 step 3): the form in
+ * `modifiers.loopType`, the operands in `for`/`in`, `times`, `while`/`until`,
+ * `event`/`from` and `index`, the body the one positional block.
+ *
+ * This emitted `args: [count]` with the variant and body beside it, a shape
+ * `repeat` has not read since the slot migration, so every loop through
+ * `evalLSE` / `compileLSE` threw "repeat command requires a loop type". The
+ * form comes from a `loopType` role when it names one, since it keeps the
+ * exact form (`until-event`) that `loopVariant` folds into `until`.
+ */
 function convertLoop(node: LoopSemanticNode): RuntimeASTNode {
-  const countValue = node.roles.get('patient') || node.roles.get('count');
-  return {
-    type: 'command',
-    name: 'repeat',
-    args: countValue ? [semanticValueToAST(countValue)] : [],
-    loopVariant: node.loopVariant ?? 'forever',
-    body: (node.body ?? []).map(semanticNodeToRuntimeAST),
-    loopVariable: node.loopVariable,
-    indexVariable: node.indexVariable,
+  const text = (value: string): RuntimeASTNode => ({ type: 'string', value });
+  const operand = (role: string): RuntimeASTNode | undefined => {
+    const value = node.roles.get(role);
+    return value ? semanticValueToAST(value) : undefined;
+  };
+  const declared = valueText(node.roles.get('loopType'));
+  const form =
+    node.action === 'for'
+      ? 'for'
+      : declared && LOOP_FORMS.has(declared)
+        ? declared
+        : (node.loopVariant ?? 'forever');
+
+  const modifiers: Record<string, RuntimeASTNode> = { loopType: text(form) };
+  const slot = (name: string, value: RuntimeASTNode | undefined) => {
+    if (value) modifiers[name] = value;
   };
+  switch (form) {
+    case 'for':
+      if (node.loopVariable) slot('for', text(node.loopVariable));
+      slot('in', operand('source'));
+      break;
+    case 'times':
+      // `patient` and `count` are what this read before the slot shape.
+      slot('times', operand('quantity') ?? operand('patient') ?? operand('count'));
+      break;
+    case 'while':
+    case 'until':
+      slot(form, operand('condition'));
+      break;
+    case 'until-event': {
+      const event = valueText(node.roles.get('event'));
+      if (event) slot('event', text(event));
+      slot('from', operand('source'));
+      break;
+    }
+  }
+  if (node.indexVariable) slot('index', text(node.indexVariable));
+
+  return { type: 'command', name: 'repeat', args: [block(node.body)], modifiers };
 }
 
 /**