@lokascript/framework 2.0.0 → 2.1.0

package/src/ir/explicit-parser.ts

@@ -0,0 +1,419 @@
+/**
+ * Explicit Syntax Parser
+ *
+ * Parses the universal [command role:value ...] bracket syntax.
+ * Domain-agnostic — schema validation is injectable via ParseExplicitOptions.
+ *
+ * Syntax:
+ *   [command role1:value1 role2:value2 ...]
+ *
+ * Examples:
+ *   [toggle patient:.active destination:#button]
+ *   [put patient:"hello" destination:#output]
+ *   [on event:click body:[toggle patient:.active]]
+ *   [select patient:name source:users condition:age>25]
+ */
+
+import type {
+  SemanticNode,
+  SemanticValue,
+  SemanticRole,
+  ActionType,
+  LoopVariant,
+} from '../core/types';
+import {
+  createCommandNode,
+  createEventHandlerNode,
+  createConditionalNode,
+  createLoopNode,
+  createSelector,
+  createLiteral,
+  createReference,
+  createFlag,
+} from '../core/types';
+import type { ParseExplicitOptions } from './types';
+import { isValidReference, DEFAULT_REFERENCES } from './references';
+
+/** Structural role names whose bracket-enclosed values may be nested commands. */
+export const STRUCTURAL_ROLES = new Set([
+  'body',
+  'then',
+  'else',
+  'condition',
+  'loop-body',
+  'variable',
+  'catch', // v1.2: try/catch/finally
+  'finally', // v1.2: try/catch/finally
+]);
+
+/**
+ * Checks whether a bracket-enclosed value is a nested command (vs. an attribute selector).
+ * A value starting with `[` is a nested command if the inner content (after stripping
+ * outer `[]`) contains at least one ASCII space or `:` at bracket-depth 0.
+ */
+function isNestedCommand(value: string): boolean {
+  const inner = value.slice(1, -1);
+  let depth = 0;
+  for (const ch of inner) {
+    if (ch === '[') depth++;
+    else if (ch === ']') depth--;
+    else if (depth === 0 && (ch === ' ' || ch === ':')) return true;
+  }
+  return false;
+}
+
+// =============================================================================
+// Explicit Syntax Parser
+// =============================================================================
+
+/**
+ * Parse explicit bracket syntax into a semantic node.
+ *
+ * When `options.schemaLookup` is provided, validates roles against the
+ * command's schema. When omitted, accepts any role names.
+ */
+export function parseExplicit(input: string, options: ParseExplicitOptions = {}): SemanticNode {
+  const trimmed = input.trim();
+
+  if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) {
+    throw new Error('Explicit syntax must be wrapped in brackets: [command role:value ...]');
+  }
+
+  const content = trimmed.slice(1, -1).trim();
+  if (!content) {
+    throw new Error('Empty explicit statement');
+  }
+
+  const tokens = tokenizeExplicit(content);
+  if (tokens.length === 0) {
+    throw new Error('No command specified in explicit statement');
+  }
+
+  const command = tokens[0].toLowerCase() as ActionType;
+  const roles = new Map<SemanticRole, SemanticValue>();
+  const refSet = options.referenceSet ?? DEFAULT_REFERENCES;
+
+  // Look up schema for role validation (undefined = skip validation)
+  const schema = options.schemaLookup?.getSchema(command);
+  const validRoleNames = schema ? new Set(schema.roles.map(r => r.role)) : null;
+
+  // Parse role:value pairs and flags
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i];
+
+    // Boolean flag: +flag-name or ~flag-name
+    if (token.startsWith('+') || token.startsWith('~')) {
+      const enabled = token.startsWith('+');
+      const flagName = token.slice(1);
+      if (!flagName) {
+        throw new Error(`Empty flag name: "${token}"`);
+      }
+      if (validRoleNames && !validRoleNames.has(flagName as SemanticRole)) {
+        const roleList = [...validRoleNames].join(', ');
+        throw new Error(
+          `Unknown flag "${flagName}" for command "${command}". Valid roles: ${roleList}`
+        );
+      }
+      roles.set(flagName as SemanticRole, createFlag(flagName, enabled));
+      continue;
+    }
+
+    const colonIndex = token.indexOf(':');
+
+    if (colonIndex === -1) {
+      throw new Error(`Invalid role format: "${token}". Expected role:value or +flag`);
+    }
+
+    const roleName = token.slice(0, colonIndex);
+
+    // Validate role name against schema (skip for structural roles)
+    if (
+      validRoleNames &&
+      !STRUCTURAL_ROLES.has(roleName) &&
+      !validRoleNames.has(roleName as SemanticRole)
+    ) {
+      const roleList = [...validRoleNames].join(', ');
+      throw new Error(
+        `Unknown role "${roleName}" for command "${command}". Valid roles: ${roleList}`
+      );
+    }
+
+    const role = roleName as SemanticRole;
+    const valueStr = token.slice(colonIndex + 1);
+
+    // Handle nested explicit syntax for structural roles (body, then, else, condition, loop-body, variable)
+    if (STRUCTURAL_ROLES.has(roleName) && valueStr.startsWith('[') && isNestedCommand(valueStr)) {
+      const nestedEnd = findMatchingBracket(token, colonIndex + 1);
+      const nestedSyntax = token.slice(colonIndex + 1, nestedEnd + 1);
+      roles.set(role, { type: 'expression', raw: nestedSyntax });
+      continue;
+    }
+
+    const value = parseExplicitValue(valueStr, refSet);
+    roles.set(role, value);
+  }
+
+  // Validate required roles are present (skip for event handlers — handled below)
+  if (schema && command !== 'on') {
+    for (const roleSpec of schema.roles) {
+      if (roleSpec.required && !roles.has(roleSpec.role as SemanticRole) && !roleSpec.default) {
+        throw new Error(
+          `Missing required role "${roleSpec.role}" for command "${command}": ${roleSpec.description}`
+        );
+      }
+    }
+  }
+
+  // Build appropriate node type based on action name
+  switch (command) {
+    case 'on': {
+      const eventValue = roles.get('event');
+      if (!eventValue) {
+        throw new Error('Event handler requires event role: [on event:click ...]');
+      }
+
+      // Parse body if present
+      const body = extractStructuralBody(roles, 'body', options);
+      roles.delete('body' as SemanticRole);
+
+      return createEventHandlerNode('on', roles, body, {
+        sourceLanguage: 'explicit',
+      });
+    }
+
+    case 'if': {
+      // Extract structural roles for conditional
+      const thenBranch = extractStructuralBody(roles, 'then', options);
+      const elseBranch = extractStructuralBody(roles, 'else', options);
+      roles.delete('then' as SemanticRole);
+      roles.delete('else' as SemanticRole);
+
+      return createConditionalNode(
+        command,
+        roles,
+        thenBranch,
+        elseBranch.length > 0 ? elseBranch : undefined,
+        {
+          sourceLanguage: 'explicit',
+        }
+      );
+    }
+
+    case 'repeat': {
+      // Extract loop structural roles
+      const loopBody = extractStructuralBody(roles, 'loop-body', options);
+      const loopVariantValue = roles.get('loop-variant' as SemanticRole);
+      const variableValue = roles.get('variable' as SemanticRole);
+      const indexVariableValue = roles.get('index-variable' as SemanticRole);
+
+      roles.delete('loop-body' as SemanticRole);
+      roles.delete('loop-variant' as SemanticRole);
+      roles.delete('variable' as SemanticRole);
+      roles.delete('index-variable' as SemanticRole);
+
+      // Determine loop variant: explicit > inferred from roles
+      let variant: LoopVariant;
+      if (
+        loopVariantValue &&
+        loopVariantValue.type === 'literal' &&
+        typeof loopVariantValue.value === 'string'
+      ) {
+        variant = loopVariantValue.value as LoopVariant;
+      } else if (roles.has('quantity' as SemanticRole)) {
+        variant = 'times';
+      } else if (roles.has('source' as SemanticRole)) {
+        variant = 'for';
+      } else if (roles.has('condition' as SemanticRole)) {
+        variant = 'while';
+      } else {
+        variant = 'forever';
+      }
+
+      const loopVariable =
+        variableValue?.type === 'literal' && typeof variableValue.value === 'string'
+          ? variableValue.value
+          : variableValue?.type === 'expression'
+            ? variableValue.raw
+            : undefined;
+      const indexVariable =
+        indexVariableValue?.type === 'literal' && typeof indexVariableValue.value === 'string'
+          ? indexVariableValue.value
+          : undefined;
+
+      return createLoopNode(command, roles, variant, loopBody, loopVariable, indexVariable, {
+        sourceLanguage: 'explicit',
+      });
+    }
+
+    default:
+      return createCommandNode(command, roles, {
+        sourceLanguage: 'explicit',
+      });
+  }
+}
+
+/**
+ * Check if input is explicit bracket syntax.
+ */
+export function isExplicitSyntax(input: string): boolean {
+  const trimmed = input.trim();
+  return trimmed.startsWith('[') && trimmed.endsWith(']');
+}
+
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+
+/**
+ * Extract and parse a structural role (body, then, else, loop-body) into SemanticNode[].
+ * Returns an empty array if the role is not present.
+ */
+function extractStructuralBody(
+  roles: Map<SemanticRole, SemanticValue>,
+  roleName: string,
+  options: ParseExplicitOptions
+): SemanticNode[] {
+  const value = roles.get(roleName as SemanticRole);
+  if (!value) return [];
+  if (value.type === 'expression') {
+    return [parseExplicit(value.raw, options)];
+  }
+  return [];
+}
+
+/**
+ * Infer selectorKind from a CSS selector string.
+ */
+function inferSelectorKind(
+  value: string
+): 'id' | 'class' | 'attribute' | 'element' | 'complex' | undefined {
+  if (!value) return undefined;
+  if (value.startsWith('#')) return 'id';
+  if (value.startsWith('.')) return 'class';
+  if (value.startsWith('[')) return 'attribute';
+  if (value.startsWith('<') || value.startsWith('*')) return 'element';
+  if (/[>+~ ]/.test(value) && value.length > 1) return 'complex';
+  return undefined;
+}
+
+/**
+ * Tokenize explicit syntax content (space-separated, respecting quotes and brackets).
+ */
+function tokenizeExplicit(content: string): string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let inString = false;
+  let stringChar = '';
+  let bracketDepth = 0;
+
+  for (let i = 0; i < content.length; i++) {
+    const char = content[i];
+
+    if (inString) {
+      current += char;
+      if (char === stringChar && content[i - 1] !== '\\') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      inString = true;
+      stringChar = char;
+      current += char;
+      continue;
+    }
+
+    if (char === '[') {
+      bracketDepth++;
+      current += char;
+      continue;
+    }
+
+    if (char === ']') {
+      bracketDepth--;
+      current += char;
+      continue;
+    }
+
+    if (char === ' ' && bracketDepth === 0) {
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (current) {
+    tokens.push(current);
+  }
+
+  return tokens;
+}
+
+/**
+ * Parse a value string into a SemanticValue.
+ */
+function parseExplicitValue(valueStr: string, referenceSet: ReadonlySet<string>): SemanticValue {
+  // CSS selector
+  if (
+    valueStr.startsWith('#') ||
+    valueStr.startsWith('.') ||
+    valueStr.startsWith('[') ||
+    valueStr.startsWith('@') ||
+    valueStr.startsWith('*')
+  ) {
+    return createSelector(valueStr, inferSelectorKind(valueStr));
+  }
+
+  // String literal
+  if (valueStr.startsWith('"') || valueStr.startsWith("'")) {
+    const inner = valueStr.slice(1, -1);
+    return createLiteral(inner, 'string');
+  }
+
+  // Boolean
+  if (valueStr === 'true') return createLiteral(true, 'boolean');
+  if (valueStr === 'false') return createLiteral(false, 'boolean');
+
+  // Reference
+  const lowerRef = valueStr.toLowerCase();
+  if (isValidReference(lowerRef, referenceSet)) {
+    return createReference(lowerRef);
+  }
+
+  // Number (possibly with duration suffix)
+  const numMatch = valueStr.match(/^(-?\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+  if (numMatch) {
+    const num = parseFloat(numMatch[1]);
+    const suffix = numMatch[2];
+    if (suffix) {
+      return createLiteral(valueStr, 'duration');
+    }
+    return createLiteral(num, 'number');
+  }
+
+  // Default to untyped string literal (no dataType — avoids spurious quoting on round-trip).
+  // Only explicitly-quoted values (handled above) get dataType: 'string'.
+  return createLiteral(valueStr);
+}
+
+/**
+ * Find the matching closing bracket.
+ */
+function findMatchingBracket(str: string, start: number): number {
+  let depth = 0;
+
+  for (let i = start; i < str.length; i++) {
+    if (str[i] === '[') depth++;
+    else if (str[i] === ']') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+
+  return str.length - 1;
+}

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

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest';
+import { renderExplicit } from './explicit-renderer';
+import { parseExplicit } from './explicit-parser';
+import {
+  createCommandNode,
+  createSelector,
+  createLiteral,
+  createReference,
+  createFlag,
+  createEventHandlerNode,
+  createCompoundNode,
+} 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);
+      }
+    });
+  }
+});

package/src/ir/explicit-renderer.ts

@@ -0,0 +1,146 @@
+/**
+ * Explicit Syntax Renderer
+ *
+ * Serializes SemanticNode to the universal [command role:value ...] bracket syntax.
+ * Zero dependencies beyond core types — no language-specific logic.
+ */
+
+import type {
+  SemanticNode,
+  SemanticValue,
+  CommandSemanticNode,
+  CompoundSemanticNode,
+  EventHandlerSemanticNode,
+  ConditionalSemanticNode,
+  LoopSemanticNode,
+} from '../core/types';
+
+/**
+ * Render a semantic node as explicit bracket syntax.
+ *
+ * @example
+ * ```typescript
+ * renderExplicit(node) // "[toggle patient:.active destination:#button]"
+ * ```
+ */
+export function renderExplicit(node: SemanticNode): string {
+  // Handle compound nodes
+  if (node.kind === 'compound') {
+    const compoundNode = node as CompoundSemanticNode;
+    const renderedStatements = compoundNode.statements.map(stmt => renderExplicit(stmt));
+    return renderedStatements.join(` ${compoundNode.chainType} `);
+  }
+
+  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(' ')}]`;
+}
+
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+
+/**
+ * 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;
+  }
+}