@lokascript/framework 2.0.0 → 2.2.0

package/src/ir/explicit-renderer.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect } from 'vitest';
+import { renderExplicit, renderDocument } from './explicit-renderer';
+import { parseExplicit, parseCompound } from './explicit-parser';
+import {
+  createCommandNode,
+  createSelector,
+  createLiteral,
+  createReference,
+  createFlag,
+  createEventHandlerNode,
+  createCompoundNode,
+} from '../core/types';
+import type { SemanticNode, LSEEnvelope } from '../core/types';
+
+describe('renderExplicit', () => {
+  it('renders a basic command', () => {
+    const node = createCommandNode('toggle', {
+      patient: createSelector('.active'),
+    });
+    expect(renderExplicit(node)).toBe('[toggle patient:.active]');
+  });
+
+  it('renders multiple roles', () => {
+    const node = createCommandNode('put', {
+      patient: createLiteral('hello', 'string'),
+      destination: createSelector('#output', 'id'),
+    });
+    const result = renderExplicit(node);
+    expect(result).toContain('put');
+    expect(result).toContain('patient:"hello"');
+    expect(result).toContain('destination:#output');
+    expect(result.startsWith('[')).toBe(true);
+    expect(result.endsWith(']')).toBe(true);
+  });
+
+  it('renders reference values', () => {
+    const node = createCommandNode('add', {
+      patient: createSelector('.clicked'),
+      destination: createReference('me'),
+    });
+    expect(renderExplicit(node)).toBe('[add patient:.clicked destination:me]');
+  });
+
+  it('renders numeric values', () => {
+    const node = createCommandNode('increment', {
+      destination: createSelector('#count', 'id'),
+      quantity: createLiteral(5, 'number'),
+    });
+    expect(renderExplicit(node)).toBe('[increment destination:#count quantity:5]');
+  });
+
+  it('renders boolean values', () => {
+    const node = createCommandNode('set', {
+      destination: createLiteral('myVar', 'string'),
+      goal: createLiteral(true, 'boolean'),
+    });
+    const result = renderExplicit(node);
+    expect(result).toContain('goal:true');
+  });
+
+  it('renders event handler with body', () => {
+    const bodyNode = createCommandNode('toggle', {
+      patient: createSelector('.active'),
+    });
+    const node = createEventHandlerNode('on', { event: createLiteral('click', 'string') }, [
+      bodyNode,
+    ]);
+    const result = renderExplicit(node);
+    expect(result).toContain('[on event:"click"');
+    expect(result).toContain('body:[toggle patient:.active]');
+  });
+
+  it('renders compound nodes', () => {
+    const node1 = createCommandNode('add', {
+      patient: createSelector('.loading'),
+    });
+    const node2 = createCommandNode('fetch', {
+      source: createLiteral('/api/data', 'string'),
+    });
+    const compound = createCompoundNode([node1, node2], 'then');
+    const result = renderExplicit(compound);
+    expect(result).toBe('[add patient:.loading] then [fetch source:"/api/data"]');
+  });
+});
+
+describe('renderExplicit — flags', () => {
+  it('renders enabled flags as +name', () => {
+    const node = createCommandNode('column', {
+      name: createLiteral('id', 'string'),
+      'primary-key': createFlag('primary-key', true),
+    });
+    const result = renderExplicit(node);
+    expect(result).toContain('+primary-key');
+    expect(result).not.toContain('primary-key:');
+  });
+
+  it('renders disabled flags as ~name', () => {
+    const node = createCommandNode('field', {
+      name: createLiteral('email', 'string'),
+      nullable: createFlag('nullable', false),
+    });
+    const result = renderExplicit(node);
+    expect(result).toContain('~nullable');
+  });
+
+  it('renders flags alongside role:value pairs', () => {
+    const node = createCommandNode('column', {
+      name: createLiteral('id', 'string'),
+      type: createLiteral('uuid', 'string'),
+      'primary-key': createFlag('primary-key', true),
+      'not-null': createFlag('not-null', true),
+    });
+    const result = renderExplicit(node);
+    expect(result).toContain('name:"id"');
+    expect(result).toContain('type:"uuid"');
+    expect(result).toContain('+primary-key');
+    expect(result).toContain('+not-null');
+  });
+});
+
+describe('round-trip: parse → render', () => {
+  const cases = [
+    '[toggle patient:.active]',
+    '[add patient:.highlight destination:#output]',
+    '[increment destination:#count quantity:5]',
+    '[wait duration:500ms]',
+    '[fetch source:/api/data responseType:json]',
+    '[column name:id +primary-key +not-null]',
+    '[field name:email +required ~nullable]',
+  ];
+
+  for (const input of cases) {
+    it(`round-trips: ${input}`, () => {
+      const node = parseExplicit(input);
+      const output = renderExplicit(node);
+      // Re-parse to verify semantic equivalence
+      const reparsed = parseExplicit(output);
+      expect(reparsed.action).toBe(node.action);
+      expect(reparsed.roles.size).toBe(node.roles.size);
+      for (const [role, value] of node.roles) {
+        expect(reparsed.roles.get(role)).toEqual(value);
+      }
+    });
+  }
+});
+
+describe('renderExplicit — annotations', () => {
+  it('renders a node with a single annotation', () => {
+    const node: SemanticNode = {
+      ...createCommandNode('fetch', {
+        source: createLiteral('/api/users', 'string'),
+      }),
+      annotations: [{ name: 'timeout', value: '5s' }],
+    };
+    expect(renderExplicit(node)).toBe('@timeout(5s) [fetch source:"/api/users"]');
+  });
+
+  it('renders annotation without value', () => {
+    const node: SemanticNode = {
+      ...createCommandNode('toggle', {
+        patient: createSelector('.active'),
+      }),
+      annotations: [{ name: 'deprecated' }],
+    };
+    expect(renderExplicit(node)).toBe('@deprecated [toggle patient:.active]');
+  });
+
+  it('renders multiple annotations preserving order', () => {
+    const node: SemanticNode = {
+      ...createCommandNode('fetch', {
+        source: createLiteral('/api/data', 'string'),
+      }),
+      annotations: [
+        { name: 'retry', value: '3' },
+        { name: 'timeout', value: '10s' },
+      ],
+    };
+    const result = renderExplicit(node);
+    expect(result).toBe('@retry(3) @timeout(10s) [fetch source:"/api/data"]');
+  });
+
+  it('renders no prefix when annotations are absent', () => {
+    const node = createCommandNode('toggle', {
+      patient: createSelector('.active'),
+    });
+    expect(renderExplicit(node)).toBe('[toggle patient:.active]');
+  });
+
+  it('annotation round-trip: render → parse → render', () => {
+    const node: SemanticNode = {
+      ...createCommandNode('fetch', {
+        source: createLiteral('/api/users', 'string'),
+      }),
+      annotations: [{ name: 'timeout', value: '5s' }],
+    };
+    const rendered = renderExplicit(node);
+    const reparsed = parseCompound(rendered);
+    const rerendered = renderExplicit(reparsed);
+    expect(rerendered).toBe(rendered);
+  });
+});
+
+describe('renderDocument', () => {
+  it('renders an envelope with version header', () => {
+    const envelope: LSEEnvelope = {
+      lseVersion: '1.2',
+      nodes: [
+        createCommandNode('toggle', { patient: createSelector('.active') }),
+        createCommandNode('add', { patient: createSelector('.highlight') }),
+      ],
+    };
+    const result = renderDocument(envelope);
+    expect(result).toBe('#!lse 1.2\n[toggle patient:.active]\n[add patient:.highlight]');
+  });
+
+  it('omits version header for version 1.0', () => {
+    const envelope: LSEEnvelope = {
+      lseVersion: '1.0',
+      nodes: [createCommandNode('toggle', { patient: createSelector('.active') })],
+    };
+    const result = renderDocument(envelope);
+    expect(result).toBe('[toggle patient:.active]');
+  });
+
+  it('renders empty envelope', () => {
+    const envelope: LSEEnvelope = { lseVersion: '1.2', nodes: [] };
+    expect(renderDocument(envelope)).toBe('#!lse 1.2');
+  });
+});

package/src/ir/explicit-renderer.ts

@@ -0,0 +1,198 @@
+/**
+ * Explicit Syntax Renderer
+ *
+ * Serializes SemanticNode to the universal [command role:value ...] bracket syntax.
+ * Zero dependencies beyond core types — no language-specific logic.
+ *
+ * Also renders annotations (@name(value)) and multi-line documents.
+ */
+
+import type {
+  SemanticNode,
+  SemanticValue,
+  CommandSemanticNode,
+  CompoundSemanticNode,
+  EventHandlerSemanticNode,
+  ConditionalSemanticNode,
+  LoopSemanticNode,
+  LSEEnvelope,
+} from '../core/types';
+
+/**
+ * Render a semantic node as explicit bracket syntax.
+ *
+ * Handles annotations (v1.2) — if the node has annotations, they are
+ * prepended as @name or @name(value) before the bracket output.
+ *
+ * @example
+ * ```typescript
+ * renderExplicit(node) // "[toggle patient:.active destination:#button]"
+ * // With annotations:
+ * renderExplicit(annotatedNode) // "@timeout(5s) [fetch source:\"/api/users\"]"
+ * ```
+ */
+export function renderExplicit(node: SemanticNode): string {
+  let result: string;
+
+  // Handle compound nodes
+  if (node.kind === 'compound') {
+    const compoundNode = node as CompoundSemanticNode;
+    const renderedStatements = compoundNode.statements.map(stmt => renderExplicit(stmt));
+    result = renderedStatements.join(` ${compoundNode.chainType} `);
+  } else {
+    result = renderBracketCommand(node);
+  }
+
+  // Prepend annotations if present
+  if (node.annotations && node.annotations.length > 0) {
+    const annParts = node.annotations.map(ann =>
+      ann.value !== undefined ? `@${ann.name}(${ann.value})` : `@${ann.name}`
+    );
+    return annParts.join(' ') + ' ' + result;
+  }
+
+  return result;
+}
+
+/**
+ * Render an LSEEnvelope as a multi-line document string.
+ *
+ * @example
+ * ```typescript
+ * renderDocument(envelope)
+ * // "#!lse 1.2\n[toggle patient:.active]\n[add patient:.highlight]"
+ * ```
+ */
+export function renderDocument(envelope: LSEEnvelope): string {
+  const lines: string[] = [];
+
+  // Emit version header if not the default
+  if (envelope.lseVersion && envelope.lseVersion !== '1.0') {
+    lines.push(`#!lse ${envelope.lseVersion}`);
+  }
+
+  // Emit each node on its own line
+  for (const node of envelope.nodes) {
+    lines.push(renderExplicit(node));
+  }
+
+  return lines.join('\n');
+}
+
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+
+/**
+ * Render a single bracket command (non-compound node).
+ */
+function renderBracketCommand(node: SemanticNode): string {
+  const parts: string[] = [node.action];
+
+  // Add roles
+  for (const [role, value] of node.roles) {
+    if (value.type === 'flag') {
+      parts.push(value.enabled ? `+${value.name}` : `~${value.name}`);
+    } else {
+      parts.push(`${role}:${valueToString(value)}`);
+    }
+  }
+
+  // Handle event handler body
+  if (node.kind === 'event-handler') {
+    const eventNode = node as EventHandlerSemanticNode;
+    if (eventNode.body && eventNode.body.length > 0) {
+      const bodyParts = eventNode.body.map(n => renderExplicit(n));
+      parts.push(`body:${bodyParts.join(' ')}`);
+    }
+  }
+
+  // Handle conditional branches (v1.1)
+  if (node.kind === 'conditional') {
+    const condNode = node as ConditionalSemanticNode;
+    if (condNode.thenBranch && condNode.thenBranch.length > 0) {
+      const thenParts = condNode.thenBranch.map(n => renderExplicit(n));
+      parts.push(`then:${thenParts.join(' ')}`);
+    }
+    if (condNode.elseBranch && condNode.elseBranch.length > 0) {
+      const elseParts = condNode.elseBranch.map(n => renderExplicit(n));
+      parts.push(`else:${elseParts.join(' ')}`);
+    }
+  }
+
+  // Handle loop body and metadata (v1.1)
+  if (node.kind === 'loop') {
+    const loopNode = node as LoopSemanticNode;
+    if (loopNode.loopVariant) {
+      parts.push(`loop-variant:${loopNode.loopVariant}`);
+    }
+    if (loopNode.loopVariable) {
+      parts.push(`variable:${loopNode.loopVariable}`);
+    }
+    if (loopNode.indexVariable) {
+      parts.push(`index-variable:${loopNode.indexVariable}`);
+    }
+    if (loopNode.body && loopNode.body.length > 0) {
+      const bodyParts = loopNode.body.map(n => renderExplicit(n));
+      parts.push(`loop-body:${bodyParts.join(' ')}`);
+    }
+  }
+
+  // Handle v1.2 command fields (try/catch/finally, async, match)
+  if (node.kind === 'command') {
+    const cmd = node as CommandSemanticNode;
+    if (cmd.body && cmd.body.length > 0) {
+      const bodyParts = cmd.body.map(n => renderExplicit(n));
+      parts.push(`body:${bodyParts.join(' ')}`);
+    }
+    if (cmd.catchBranch && cmd.catchBranch.length > 0) {
+      const catchParts = cmd.catchBranch.map(n => renderExplicit(n));
+      parts.push(`catch:${catchParts.join(' ')}`);
+    }
+    if (cmd.finallyBranch && cmd.finallyBranch.length > 0) {
+      const finallyParts = cmd.finallyBranch.map(n => renderExplicit(n));
+      parts.push(`finally:${finallyParts.join(' ')}`);
+    }
+    if (cmd.asyncVariant) {
+      parts.push(`async-variant:${cmd.asyncVariant}`);
+    }
+    if (cmd.asyncBody && cmd.asyncBody.length > 0) {
+      const asyncParts = cmd.asyncBody.map(n => renderExplicit(n));
+      parts.push(`async-body:${asyncParts.join(' ')}`);
+    }
+  }
+
+  return `[${parts.join(' ')}]`;
+}
+
+/**
+ * Convert a semantic value to its explicit syntax string form.
+ */
+function valueToString(value: SemanticValue): string {
+  switch (value.type) {
+    case 'literal':
+      if (typeof value.value === 'string') {
+        // Quote strings that contain spaces or are explicitly typed as strings
+        if (value.dataType === 'string' || /\s/.test(value.value)) {
+          return `"${value.value}"`;
+        }
+        return value.value;
+      }
+      return String(value.value);
+
+    case 'selector':
+      return value.value;
+
+    case 'reference':
+      return value.value;
+
+    case 'property-path':
+      return `${valueToString(value.object)}'s ${value.property}`;
+
+    case 'expression':
+      return value.raw;
+
+    case 'flag':
+      return value.name;
+  }
+}