@lokascript/framework 2.1.0 → 2.2.0

package/src/ir/explicit-parser.ts

@@ -4,14 +4,15 @@
  * Parses the universal [command role:value ...] bracket syntax.
  * Domain-agnostic — schema validation is injectable via ParseExplicitOptions.
  *
+ * Three parsing levels matching the ABNF grammar:
+ *   parseDocument()  → parseCompound()  → parseExplicit()
+ *   (multi-line)       (chain ops)         (single bracket)
+ *
  * 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]
+ *   [cmd1 ...] then [cmd2 ...]
+ *   @annotation(value) [command ...]
+ *   #!lse 1.2\n[cmd1 ...]\n[cmd2 ...]
  */
 
 import type {
@@ -20,17 +21,22 @@ import type {
   SemanticRole,
   ActionType,
   LoopVariant,
+  Annotation,
+  LSEEnvelope,
+  CompoundSemanticNode,
 } from '../core/types';
 import {
   createCommandNode,
   createEventHandlerNode,
   createConditionalNode,
   createLoopNode,
+  createCompoundNode,
   createSelector,
   createLiteral,
   createReference,
   createFlag,
 } from '../core/types';
+import type { Diagnostic } from '../generation/diagnostics';
 import type { ParseExplicitOptions } from './types';
 import { isValidReference, DEFAULT_REFERENCES } from './references';
 
@@ -74,6 +80,8 @@ function isNestedCommand(value: string): boolean {
  */
 export function parseExplicit(input: string, options: ParseExplicitOptions = {}): SemanticNode {
   const trimmed = input.trim();
+  const collect = options.collectDiagnostics === true;
+  const diagnostics: Diagnostic[] = [];
 
   if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) {
     throw new Error('Explicit syntax must be wrapped in brackets: [command role:value ...]');
@@ -106,10 +114,31 @@ export function parseExplicit(input: string, options: ParseExplicitOptions = {})
       const enabled = token.startsWith('+');
       const flagName = token.slice(1);
       if (!flagName) {
+        if (collect) {
+          diagnostics.push({
+            severity: 'error',
+            code: 'EMPTY_FLAG',
+            message: `Empty flag name: "${token}"`,
+            source: 'schema',
+          });
+          continue;
+        }
         throw new Error(`Empty flag name: "${token}"`);
       }
       if (validRoleNames && !validRoleNames.has(flagName as SemanticRole)) {
         const roleList = [...validRoleNames].join(', ');
+        if (collect) {
+          diagnostics.push({
+            severity: 'error',
+            code: 'UNKNOWN_FLAG',
+            message: `Unknown flag "${flagName}" for command "${command}"`,
+            source: 'schema',
+            suggestions: [...validRoleNames].map(r => `+${r}`),
+          });
+          // Still add the flag so the node is usable
+          roles.set(flagName as SemanticRole, createFlag(flagName, enabled));
+          continue;
+        }
         throw new Error(
           `Unknown flag "${flagName}" for command "${command}". Valid roles: ${roleList}`
         );
@@ -121,6 +150,15 @@ export function parseExplicit(input: string, options: ParseExplicitOptions = {})
     const colonIndex = token.indexOf(':');
 
     if (colonIndex === -1) {
+      if (collect) {
+        diagnostics.push({
+          severity: 'error',
+          code: 'INVALID_ROLE_FORMAT',
+          message: `Invalid role format: "${token}". Expected role:value or +flag`,
+          source: 'schema',
+        });
+        continue;
+      }
       throw new Error(`Invalid role format: "${token}". Expected role:value or +flag`);
     }
 
@@ -133,9 +171,20 @@ export function parseExplicit(input: string, options: ParseExplicitOptions = {})
       !validRoleNames.has(roleName as SemanticRole)
     ) {
       const roleList = [...validRoleNames].join(', ');
-      throw new Error(
-        `Unknown role "${roleName}" for command "${command}". Valid roles: ${roleList}`
-      );
+      if (collect) {
+        diagnostics.push({
+          severity: 'error',
+          code: 'UNKNOWN_ROLE',
+          message: `Unknown role "${roleName}" for command "${command}"`,
+          source: 'schema',
+          suggestions: [...validRoleNames],
+        });
+        // Still parse and add the role so the node is usable
+      } else {
+        throw new Error(
+          `Unknown role "${roleName}" for command "${command}". Valid roles: ${roleList}`
+        );
+      }
     }
 
     const role = roleName as SemanticRole;
@@ -157,18 +206,47 @@ export function parseExplicit(input: string, options: ParseExplicitOptions = {})
   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}`
-        );
+        if (collect) {
+          diagnostics.push({
+            severity: 'error',
+            code: 'MISSING_REQUIRED_ROLE',
+            message: `Missing required role "${roleSpec.role}" for command "${command}": ${roleSpec.description}`,
+            source: 'schema',
+          });
+        } else {
+          throw new Error(
+            `Missing required role "${roleSpec.role}" for command "${command}": ${roleSpec.description}`
+          );
+        }
       }
     }
   }
 
+  // Helper: attach diagnostics to a node if any were collected
+  const attachDiagnostics = (node: SemanticNode): SemanticNode => {
+    if (diagnostics.length === 0) return node;
+    return { ...node, diagnostics };
+  };
+
   // Build appropriate node type based on action name
   switch (command) {
     case 'on': {
       const eventValue = roles.get('event');
       if (!eventValue) {
+        if (collect) {
+          diagnostics.push({
+            severity: 'error',
+            code: 'MISSING_EVENT_ROLE',
+            message: 'Event handler requires event role: [on event:click ...]',
+            source: 'schema',
+          });
+          // Return a stub event handler with diagnostics
+          return attachDiagnostics(
+            createEventHandlerNode('on', roles, [], {
+              sourceLanguage: 'explicit',
+            })
+          );
+        }
         throw new Error('Event handler requires event role: [on event:click ...]');
       }
 
@@ -176,9 +254,11 @@ export function parseExplicit(input: string, options: ParseExplicitOptions = {})
       const body = extractStructuralBody(roles, 'body', options);
       roles.delete('body' as SemanticRole);
 
-      return createEventHandlerNode('on', roles, body, {
-        sourceLanguage: 'explicit',
-      });
+      return attachDiagnostics(
+        createEventHandlerNode('on', roles, body, {
+          sourceLanguage: 'explicit',
+        })
+      );
     }
 
     case 'if': {
@@ -188,14 +268,16 @@ export function parseExplicit(input: string, options: ParseExplicitOptions = {})
       roles.delete('then' as SemanticRole);
       roles.delete('else' as SemanticRole);
 
-      return createConditionalNode(
-        command,
-        roles,
-        thenBranch,
-        elseBranch.length > 0 ? elseBranch : undefined,
-        {
-          sourceLanguage: 'explicit',
-        }
+      return attachDiagnostics(
+        createConditionalNode(
+          command,
+          roles,
+          thenBranch,
+          elseBranch.length > 0 ? elseBranch : undefined,
+          {
+            sourceLanguage: 'explicit',
+          }
+        )
       );
     }
 
@@ -240,15 +322,19 @@ export function parseExplicit(input: string, options: ParseExplicitOptions = {})
           ? indexVariableValue.value
           : undefined;
 
-      return createLoopNode(command, roles, variant, loopBody, loopVariable, indexVariable, {
-        sourceLanguage: 'explicit',
-      });
+      return attachDiagnostics(
+        createLoopNode(command, roles, variant, loopBody, loopVariable, indexVariable, {
+          sourceLanguage: 'explicit',
+        })
+      );
     }
 
     default:
-      return createCommandNode(command, roles, {
-        sourceLanguage: 'explicit',
-      });
+      return attachDiagnostics(
+        createCommandNode(command, roles, {
+          sourceLanguage: 'explicit',
+        })
+      );
   }
 }
 
@@ -260,6 +346,294 @@ export function isExplicitSyntax(input: string): boolean {
   return trimmed.startsWith('[') && trimmed.endsWith(']');
 }
 
+// =============================================================================
+// Compound Statement Parsing
+// =============================================================================
+
+/** Chain operators per ABNF: "then" / "and" / "async" / "sequential" / "|>" */
+const CHAIN_KEYWORDS = new Set(['then', 'and', 'async', 'sequential']);
+
+/**
+ * Split input into bracket-command segments separated by chain operators.
+ * Returns segments and the chain operator found (first one wins for mixed).
+ */
+function splitCompoundSegments(input: string): {
+  segments: string[];
+  chainType: CompoundSemanticNode['chainType'] | null;
+} {
+  const segments: string[] = [];
+  let chainType: CompoundSemanticNode['chainType'] | null = null;
+  let current = '';
+  let bracketDepth = 0;
+  let inString = false;
+  let stringChar = '';
+
+  for (let i = 0; i < input.length; i++) {
+    const char = input[i];
+
+    if (inString) {
+      current += char;
+      if (char === stringChar && input[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;
+
+      // At depth 0 after closing bracket, check for chain operator
+      if (bracketDepth === 0) {
+        const rest = input.slice(i + 1);
+        // Check for |> pipe operator
+        const pipeMatch = rest.match(/^\s*\|>\s*/);
+        if (pipeMatch) {
+          segments.push(current.trim());
+          current = '';
+          chainType ??= 'pipe';
+          i += pipeMatch[0].length;
+          continue;
+        }
+        // Check for keyword chain operators
+        const keywordMatch = rest.match(/^\s+(then|and|async|sequential)\s+/);
+        if (keywordMatch && CHAIN_KEYWORDS.has(keywordMatch[1])) {
+          segments.push(current.trim());
+          current = '';
+          chainType ??= keywordMatch[1] as CompoundSemanticNode['chainType'];
+          i += keywordMatch[0].length;
+          continue;
+        }
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (current.trim()) {
+    segments.push(current.trim());
+  }
+
+  return { segments, chainType };
+}
+
+/**
+ * Parse a compound statement (one or more bracket commands chained with operators).
+ *
+ * ABNF: compound-stmt = bracket-cmd *( chain-op bracket-cmd )
+ *
+ * Single commands pass through to parseExplicit(). Multiple commands produce
+ * a CompoundSemanticNode.
+ *
+ * Also handles annotations (@name or @name(value)) before the first bracket.
+ *
+ * @example
+ * ```typescript
+ * // Single command — passthrough
+ * parseCompound('[toggle patient:.active]')
+ *
+ * // Compound statement
+ * parseCompound('[add patient:.loading] then [fetch source:/api/data]')
+ *
+ * // With annotation
+ * parseCompound('@timeout(5s) [fetch source:/api/users]')
+ * ```
+ */
+export function parseCompound(input: string, options?: ParseExplicitOptions): SemanticNode {
+  const trimmed = input.trim();
+
+  // Extract annotations before the first bracket
+  const { annotations, remainder } = extractAnnotations(trimmed);
+
+  const { segments, chainType } = splitCompoundSegments(remainder);
+
+  let node: SemanticNode;
+  if (segments.length <= 1) {
+    // Single command — delegate to parseExplicit
+    node = parseExplicit(segments[0] || remainder, options);
+  } else {
+    // Multiple commands — create compound node
+    const statements = segments.map(seg => parseExplicit(seg, options));
+    node = createCompoundNode(statements, chainType ?? 'sequential');
+  }
+
+  // Attach annotations if any
+  if (annotations.length > 0) {
+    return { ...node, annotations };
+  }
+  return node;
+}
+
+// =============================================================================
+// Annotation Parsing
+// =============================================================================
+
+/**
+ * Extract @name and @name(value) annotations from before the first bracket.
+ * Per ABNF, annotations precede the compound statement on the same line.
+ */
+function extractAnnotations(input: string): { annotations: Annotation[]; remainder: string } {
+  const annotations: Annotation[] = [];
+  let pos = 0;
+
+  while (pos < input.length) {
+    // Skip whitespace
+    while (pos < input.length && (input[pos] === ' ' || input[pos] === '\t')) {
+      pos++;
+    }
+
+    // If we hit '[' or end of string, we're done with annotations
+    if (pos >= input.length || input[pos] !== '@') {
+      break;
+    }
+
+    // Parse @name
+    pos++; // skip @
+    const nameStart = pos;
+    while (pos < input.length && /[A-Za-z0-9\-_]/.test(input[pos])) {
+      pos++;
+    }
+    const name = input.slice(nameStart, pos);
+    if (!name) break;
+
+    // Check for (value)
+    let value: string | undefined;
+    if (pos < input.length && input[pos] === '(') {
+      pos++; // skip (
+      const valueStart = pos;
+      // Handle quoted strings inside annotation values
+      if (pos < input.length && (input[pos] === '"' || input[pos] === "'")) {
+        const quote = input[pos];
+        pos++; // skip opening quote
+        while (pos < input.length && input[pos] !== quote) {
+          if (input[pos] === '\\') pos++; // skip escape
+          pos++;
+        }
+        pos++; // skip closing quote
+        value = input.slice(valueStart + 1, pos - 1); // strip quotes
+      } else {
+        // Plain value chars: ALPHA / DIGIT / "-" / "_" / "." / "/" / ":"
+        while (pos < input.length && input[pos] !== ')') {
+          pos++;
+        }
+        value = input.slice(valueStart, pos);
+      }
+      if (pos < input.length && input[pos] === ')') {
+        pos++; // skip )
+      }
+    }
+
+    annotations.push(value !== undefined ? { name, value } : { name });
+  }
+
+  return { annotations, remainder: input.slice(pos).trim() };
+}
+
+// =============================================================================
+// Document Parsing
+// =============================================================================
+
+/** Version header regex: #!lse <version> */
+const VERSION_HEADER_RE = /^#!lse\s+(\d+\.\d+(?:\.\d+)?)\s*$/;
+
+/**
+ * Parse a multi-line LSE document into an LSEEnvelope.
+ *
+ * ABNF: document = [ version-header LF ] *( line LF ) [ line ]
+ *
+ * Handles version headers (#!lse 1.2), comments (// or #), blank lines,
+ * and statement lines (one compound statement per line).
+ *
+ * @example
+ * ```typescript
+ * const envelope = parseDocument(`
+ *   #!lse 1.2
+ *   // Toggle active state
+ *   [toggle patient:.active]
+ *   [add patient:.highlight]
+ * `);
+ * // envelope.lseVersion === '1.2'
+ * // envelope.nodes.length === 2
+ * ```
+ */
+export function parseDocument(input: string, options?: ParseExplicitOptions): LSEEnvelope {
+  const lines = input.split('\n');
+  let lseVersion = '1.0';
+  const nodes: SemanticNode[] = [];
+  let startLine = 0;
+
+  // Check for version header on first non-blank line
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!trimmed) continue; // skip leading blank lines
+    const versionMatch = trimmed.match(VERSION_HEADER_RE);
+    if (versionMatch) {
+      lseVersion = versionMatch[1];
+      startLine = i + 1;
+    }
+    break;
+  }
+
+  // Parse remaining lines
+  for (let i = startLine; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+
+    // Skip blank lines
+    if (!trimmed) continue;
+
+    // Skip comments (// or #, but NOT #! which is version header)
+    if (trimmed.startsWith('//') || (trimmed.startsWith('#') && !trimmed.startsWith('#!'))) {
+      continue;
+    }
+
+    // Parse statement line
+    nodes.push(parseCompound(trimmed, options));
+  }
+
+  return { lseVersion, nodes };
+}
+
+// =============================================================================
+// Detection Helpers
+// =============================================================================
+
+/**
+ * Check if input contains compound chaining (multiple bracket commands
+ * with chain operators at bracket-depth 0).
+ */
+export function isCompoundSyntax(input: string): boolean {
+  const { segments } = splitCompoundSegments(input.trim());
+  return segments.length > 1;
+}
+
+/**
+ * Check if input is a multi-line LSE document (contains newlines,
+ * version header, or comment lines).
+ */
+export function isDocumentSyntax(input: string): boolean {
+  const trimmed = input.trim();
+  if (trimmed.includes('\n')) return true;
+  if (VERSION_HEADER_RE.test(trimmed)) return true;
+  if (trimmed.startsWith('//') || (trimmed.startsWith('#') && !trimmed.startsWith('#!'))) {
+    return true;
+  }
+  return false;
+}
+
 // =============================================================================
 // Internal Helpers
 // =============================================================================

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

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { renderExplicit } from './explicit-renderer';
-import { parseExplicit } from './explicit-parser';
+import { renderExplicit, renderDocument } from './explicit-renderer';
+import { parseExplicit, parseCompound } from './explicit-parser';
 import {
   createCommandNode,
   createSelector,
@@ -10,6 +10,7 @@ import {
   createEventHandlerNode,
   createCompoundNode,
 } from '../core/types';
+import type { SemanticNode, LSEEnvelope } from '../core/types';
 
 describe('renderExplicit', () => {
   it('renders a basic command', () => {
@@ -142,3 +143,87 @@ describe('round-trip: parse → render', () => {
     });
   }
 });
+
+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');
+  });
+});