@lokascript/framework 2.1.0 → 2.2.0

package/src/ir/explicit-renderer.ts

@@ -3,6 +3,8 @@
  *
  * 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 {
@@ -13,24 +15,78 @@ import type {
   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));
-    return renderedStatements.join(` ${compoundNode.chainType} `);
+    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
@@ -109,10 +165,6 @@ export function renderExplicit(node: SemanticNode): string {
   return `[${parts.join(' ')}]`;
 }
 
-// =============================================================================
-// Internal Helpers
-// =============================================================================
-
 /**
  * Convert a semantic value to its explicit syntax string form.
  */

package/src/ir/index.ts

@@ -32,10 +32,17 @@ export type {
 export { DEFAULT_REFERENCES, isValidReference } from './references';
 
 // Explicit syntax parser
-export { parseExplicit, isExplicitSyntax } from './explicit-parser';
+export {
+  parseExplicit,
+  parseCompound,
+  parseDocument,
+  isExplicitSyntax,
+  isCompoundSyntax,
+  isDocumentSyntax,
+} from './explicit-parser';
 
 // Explicit syntax renderer
-export { renderExplicit } from './explicit-renderer';
+export { renderExplicit, renderDocument } from './explicit-renderer';
 
 // JSON schema conversion (deprecated — use fromProtocolJSON/validateProtocolJSON/toProtocolJSON)
 export { jsonToSemanticNode, validateSemanticJSON, semanticNodeToJSON } from './json-schema';
@@ -64,3 +71,7 @@ export {
 
 // Interchange AST → SemanticNode converter
 export { fromInterchangeNode, convertValue, renderExpr } from './from-interchange';
+
+// SemanticNode → Runtime AST converter (for core runtime execution)
+export { semanticNodeToRuntimeAST, semanticValueToAST } from './to-runtime-ast';
+export type { RuntimeASTNode, RuntimeCommandNode, RuntimeEventNode } from './to-runtime-ast';

package/src/ir/protocol-json.test.ts

@@ -995,10 +995,10 @@ describe('v1.2: diagnostics', () => {
       ...createCommandNode('toggle', { patient: createSelector('#button', 'id') }),
       diagnostics: [
         {
-          level: 'error',
-          role: 'patient',
+          severity: 'error',
           message: "toggle.patient expects selector kind [class, attribute], got 'id'",
           code: 'SCHEMA_SELECTOR_KIND_MISMATCH',
+          source: 'schema',
         },
       ],
     };
@@ -1006,6 +1006,7 @@ describe('v1.2: diagnostics', () => {
     expect(json.diagnostics).toHaveLength(1);
     expect(json.diagnostics![0].level).toBe('error');
     expect(json.diagnostics![0].code).toBe('SCHEMA_SELECTOR_KIND_MISMATCH');
+    expect(json.diagnostics![0].source).toBe('schema');
   });
 
   it('deserializes diagnostics from protocol JSON', () => {
@@ -1025,6 +1026,7 @@ describe('v1.2: diagnostics', () => {
     const node = fromProtocolJSON(json);
     expect(node.diagnostics).toHaveLength(1);
     expect(node.diagnostics![0].code).toBe('SCHEMA_VALUE_TYPE_MISMATCH');
+    expect(node.diagnostics![0].severity).toBe('error');
   });
 
   describe('fixture conformance: type-constraints.json', () => {

package/src/ir/protocol-json.ts

@@ -54,6 +54,7 @@ import {
 import type {
   ProtocolNodeJSON,
   ProtocolValueJSON,
+  ProtocolDiagnosticJSON,
   ProtocolChainType,
   IRDiagnostic,
   LSEEnvelopeJSON,
@@ -164,14 +165,18 @@ export function toProtocolJSON(node: SemanticNode): ProtocolNodeJSON {
     );
   }
 
-  // v1.2: diagnostics (all node kinds)
+  // v1.2/v1.2.1: diagnostics (all node kinds)
   if (node.diagnostics && node.diagnostics.length > 0) {
-    result.diagnostics = node.diagnostics.map(d => ({
-      level: d.level,
-      role: d.role,
-      message: d.message,
-      code: d.code,
-    }));
+    result.diagnostics = node.diagnostics.map(d => {
+      const json: ProtocolDiagnosticJSON = {
+        level: d.severity,
+        message: d.message,
+      };
+      if (d.code) json.code = d.code;
+      if (d.source) json.source = d.source;
+      if (d.suggestions && d.suggestions.length > 0) json.suggestions = [...d.suggestions];
+      return json;
+    });
   }
 
   return result;
@@ -252,10 +257,11 @@ export function fromProtocolJSON(json: ProtocolNodeJSON): SemanticNode {
     a.value !== undefined ? { name: a.name, value: a.value } : { name: a.name }
   );
   const diagnostics = json.diagnostics?.map(d => ({
-    level: d.level as 'error' | 'warning',
-    role: d.role,
+    severity: d.level as 'error' | 'warning' | 'info',
     message: d.message,
-    code: d.code,
+    ...(d.code ? { code: d.code } : {}),
+    ...(d.source ? { source: d.source } : {}),
+    ...(d.suggestions && d.suggestions.length > 0 ? { suggestions: d.suggestions } : {}),
   }));
 
   // trigger sugar: wrap command in event handler (check before kind dispatch)
@@ -361,7 +367,13 @@ function applyV12Metadata(
   node: SemanticNode,
   annotations: Array<{ name: string; value?: string }> | undefined,
   diagnostics:
-    | Array<{ level: 'error' | 'warning'; role: string; message: string; code: string }>
+    | Array<{
+        severity: 'error' | 'warning' | 'info';
+        message: string;
+        code?: string;
+        source?: string;
+        suggestions?: string[];
+      }>
     | undefined
 ): SemanticNode {
   if ((!annotations || annotations.length === 0) && (!diagnostics || diagnostics.length === 0)) {
@@ -460,7 +472,7 @@ const VALID_VALUE_TYPES = new Set([
 ]);
 const VALID_CHAIN_TYPES = new Set(['then', 'and', 'async', 'sequential', 'pipe']);
 const VALID_ASYNC_VARIANTS = new Set(['all', 'race']);
-const VALID_DIAGNOSTIC_LEVELS = new Set(['error', 'warning']);
+const VALID_DIAGNOSTIC_LEVELS = new Set(['error', 'warning', 'info']);
 
 /**
  * Validate that an unknown value conforms to the protocol JSON format.
@@ -637,14 +649,7 @@ export function validateProtocolJSON(json: unknown): IRDiagnostic[] {
           diagnostics.push({
             severity: 'error',
             code: 'INVALID_DIAGNOSTIC_LEVEL',
-            message: `diagnostics[${i}].level must be "error" or "warning"`,
-          });
-        }
-        if (typeof d.role !== 'string') {
-          diagnostics.push({
-            severity: 'error',
-            code: 'MISSING_DIAGNOSTIC_ROLE',
-            message: `diagnostics[${i}] missing required field: role`,
+            message: `diagnostics[${i}].level must be "error", "warning", or "info"`,
           });
         }
         if (typeof d.message !== 'string') {
@@ -654,11 +659,12 @@ export function validateProtocolJSON(json: unknown): IRDiagnostic[] {
             message: `diagnostics[${i}] missing required field: message`,
           });
         }
-        if (typeof d.code !== 'string') {
+        // v1.2.1: role and code are now optional
+        if ('code' in d && typeof d.code !== 'string') {
           diagnostics.push({
-            severity: 'error',
-            code: 'MISSING_DIAGNOSTIC_CODE',
-            message: `diagnostics[${i}] missing required field: code`,
+            severity: 'warning',
+            code: 'INVALID_DIAGNOSTIC_CODE',
+            message: `diagnostics[${i}].code must be a string if present`,
           });
         }
       }

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

@@ -0,0 +1,203 @@
+/**
+ * SemanticNode → Runtime AST Converter
+ *
+ * Converts framework SemanticNode (LSE IR) to a structural AST format
+ * that the core runtime can execute directly. Uses structural typing
+ * to avoid a dependency on the core package.
+ *
+ * This is the canonical converter — AOT compiler delegates to it.
+ *
+ * The output matches the core runtime's expected node shapes:
+ * - `{ type: 'command', name, args, roles }` → processCommand()
+ * - `{ type: 'event', event, modifiers, body }` → adapted to executeEventHandler()
+ */
+
+import type {
+  SemanticNode,
+  SemanticValue,
+  EventHandlerSemanticNode,
+  ConditionalSemanticNode,
+  LoopSemanticNode,
+} from '../core/types';
+
+// =============================================================================
+// Structural output types (no core package dependency)
+// =============================================================================
+
+/** Minimal AST node that the core runtime can execute. */
+export interface RuntimeASTNode {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+/** Command node shape expected by runtime's processCommand(). */
+export interface RuntimeCommandNode extends RuntimeASTNode {
+  readonly type: 'command';
+  readonly name: string;
+  readonly args: RuntimeASTNode[];
+  readonly roles?: Readonly<Record<string, RuntimeASTNode>>;
+  readonly modifiers?: Record<string, unknown>;
+}
+
+/** Event node shape expected by runtime's event adapter. */
+export interface RuntimeEventNode extends RuntimeASTNode {
+  readonly type: 'event';
+  readonly event: string;
+  readonly modifiers: Record<string, unknown>;
+  readonly body: RuntimeASTNode[];
+}
+
+// =============================================================================
+// Converter
+// =============================================================================
+
+/**
+ * Convert a SemanticNode to a RuntimeASTNode that the core runtime can execute.
+ *
+ * @example
+ * ```typescript
+ * import { parseExplicit } from '@lokascript/framework/ir';
+ * import { semanticNodeToRuntimeAST } from '@lokascript/framework/ir';
+ *
+ * const node = parseExplicit('[toggle patient:.active]');
+ * const ast = semanticNodeToRuntimeAST(node);
+ * // { type: 'command', name: 'toggle', args: [{ type: 'selector', value: '.active' }], roles: { patient: ... } }
+ * ```
+ */
+export function semanticNodeToRuntimeAST(node: SemanticNode): RuntimeASTNode {
+  switch (node.kind) {
+    case 'event-handler':
+      return convertEventHandler(node as EventHandlerSemanticNode);
+
+    case 'conditional':
+      return convertConditional(node as ConditionalSemanticNode);
+
+    case 'loop':
+      return convertLoop(node as LoopSemanticNode);
+
+    case 'compound': {
+      const compound = node as SemanticNode & { statements?: SemanticNode[]; chainType?: string };
+      const commands = (compound.statements ?? []).map(semanticNodeToRuntimeAST);
+      return {
+        type: 'CommandSequence',
+        commands,
+      };
+    }
+
+    case 'command':
+    default:
+      return convertCommand(node);
+  }
+}
+
+function convertEventHandler(eh: EventHandlerSemanticNode): RuntimeEventNode {
+  const eventValue = eh.roles.get('event');
+  const eventName = eventValue && 'value' in eventValue ? String(eventValue.value) : 'click';
+
+  const modifiers: Record<string, unknown> = {};
+  if (eh.eventModifiers) {
+    if (eh.eventModifiers.once) modifiers.once = true;
+    if (eh.eventModifiers.debounce) modifiers.debounce = eh.eventModifiers.debounce;
+    if (eh.eventModifiers.throttle) modifiers.throttle = eh.eventModifiers.throttle;
+    if (eh.eventModifiers.queue) modifiers.queue = eh.eventModifiers.queue;
+  }
+
+  return {
+    type: 'event',
+    event: eventName,
+    modifiers,
+    body: (eh.body ?? []).map(semanticNodeToRuntimeAST),
+  };
+}
+
+function convertCommand(node: SemanticNode): RuntimeCommandNode {
+  const roles: Record<string, RuntimeASTNode> = {};
+  const args: RuntimeASTNode[] = [];
+
+  for (const [roleName, value] of node.roles) {
+    const astValue = semanticValueToAST(value);
+    roles[roleName] = astValue;
+    args.push(astValue);
+  }
+
+  return {
+    type: 'command',
+    name: node.action,
+    args,
+    roles,
+  };
+}
+
+function convertConditional(node: ConditionalSemanticNode): RuntimeASTNode {
+  const conditionValue = node.roles.get('condition');
+  return {
+    type: 'command',
+    name: 'if',
+    args: conditionValue ? [semanticValueToAST(conditionValue)] : [],
+    condition: conditionValue ? semanticValueToAST(conditionValue) : undefined,
+    thenBranch: (node.thenBranch ?? []).map(semanticNodeToRuntimeAST),
+    elseBranch: (node.elseBranch ?? []).map(semanticNodeToRuntimeAST),
+  };
+}
+
+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,
+  };
+}
+
+/**
+ * Convert a SemanticValue to a RuntimeASTNode.
+ */
+export function semanticValueToAST(value: SemanticValue): RuntimeASTNode {
+  switch (value.type) {
+    case 'selector':
+      return { type: 'selector', value: value.value as string };
+
+    case 'reference':
+      return { type: 'identifier', value: value.value as string };
+
+    case 'literal': {
+      const lit = value as { value: unknown; dataType?: string };
+      if (lit.dataType === 'duration') {
+        const str = String(lit.value);
+        const match = /^(\d+(?:\.\d+)?)(ms|s)$/.exec(str);
+        if (match) {
+          const ms = match[2] === 's' ? parseFloat(match[1]) * 1000 : parseFloat(match[1]);
+          return { type: 'literal', value: ms };
+        }
+      }
+      return { type: 'literal', value: lit.value as string | number | boolean | null };
+    }
+
+    case 'property-path': {
+      const pp = value as import('../core/types').PropertyPathValue;
+      const objectAST = semanticValueToAST(pp.object);
+      return {
+        type: 'member',
+        object: objectAST,
+        property: pp.property,
+      };
+    }
+
+    case 'expression': {
+      const expr = value as { raw: string };
+      return { type: 'expression', value: expr.raw };
+    }
+
+    case 'flag': {
+      const flag = value as { name: string; enabled: boolean };
+      return { type: 'literal', value: flag.enabled };
+    }
+
+    default:
+      return { type: 'literal', value: String((value as { value?: unknown }).value ?? '') };
+  }
+}

package/src/ir/types.ts

@@ -67,6 +67,12 @@ export interface ParseExplicitOptions {
   schemaLookup?: SchemaLookup;
   /** Custom set of valid reference names (defaults to DEFAULT_REFERENCES) */
   referenceSet?: ReadonlySet<string>;
+  /**
+   * When true, validation errors are collected as diagnostics on the
+   * returned node instead of throwing. Fatal parse errors (missing brackets,
+   * empty input) still throw. Default: false.
+   */
+  collectDiagnostics?: boolean;
 }
 
 // =============================================================================
@@ -153,12 +159,16 @@ export interface ProtocolNodeJSON {
 // v1.2 Sub-types
 // =============================================================================
 
-/** A type constraint diagnostic in protocol wire format (v1.2). */
+/** A diagnostic in protocol wire format (v1.2, extended v1.2.1). */
 export interface ProtocolDiagnosticJSON {
-  level: 'error' | 'warning';
-  role: string;
+  level: 'error' | 'warning' | 'info';
+  role?: string;
   message: string;
-  code: string;
+  code?: string;
+  /** v1.2.1: source parser/stage that produced this diagnostic. */
+  source?: string;
+  /** v1.2.1: actionable fix suggestions. */
+  suggestions?: string[];
 }
 
 /** A metadata annotation in protocol wire format (v1.2). */