@lokascript/framework 2.0.0 → 2.2.0

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

@@ -0,0 +1,191 @@
+/**
+ * IR (Intermediate Representation) Types
+ *
+ * Types for the explicit bracket syntax, LLM JSON format, and
+ * schema-based validation. These are domain-agnostic — they work
+ * for any DSL built on the framework.
+ */
+
+import type { CommandSchema } from '../schema/command-schema';
+
+// =============================================================================
+// LLM JSON Format
+// =============================================================================
+
+/**
+ * Structured input format for LLMs.
+ * No parsing ambiguity — action and roles are explicitly typed.
+ *
+ * @example
+ * ```json
+ * {
+ *   "action": "toggle",
+ *   "roles": { "patient": { "type": "selector", "value": ".active" } },
+ *   "trigger": { "event": "click" }
+ * }
+ * ```
+ */
+export interface SemanticJSON {
+  /** The command/action name */
+  action: string;
+  /** Named semantic roles with typed values */
+  roles: Record<string, SemanticJSONValue>;
+  /** Optional event trigger (wraps command in event handler) */
+  trigger?: {
+    event: string;
+    modifiers?: Record<string, unknown>;
+  };
+}
+
+/**
+ * A typed value in the LLM JSON format.
+ */
+export interface SemanticJSONValue {
+  type: 'selector' | 'literal' | 'reference' | 'expression' | 'property-path' | 'flag';
+  value: string | number | boolean;
+}
+
+// =============================================================================
+// Schema Lookup
+// =============================================================================
+
+/**
+ * Interface for optional schema-based role validation in the explicit parser.
+ * Consumers provide this to validate roles against command definitions.
+ *
+ * When not provided, the parser accepts any role names.
+ */
+export interface SchemaLookup {
+  getSchema(action: string): CommandSchema | undefined;
+}
+
+/**
+ * Options for parseExplicit().
+ */
+export interface ParseExplicitOptions {
+  /** Optional schema lookup for role validation */
+  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;
+}
+
+// =============================================================================
+// Diagnostics
+// =============================================================================
+
+/**
+ * A diagnostic message from IR validation.
+ *
+ * Uses required `code` field (compatible with both framework Diagnostic
+ * and compilation-service Diagnostic types via structural typing).
+ */
+export interface IRDiagnostic {
+  severity: 'error' | 'warning' | 'info';
+  code: string;
+  message: string;
+  suggestion?: string;
+}
+
+// =============================================================================
+// Protocol Full-Fidelity JSON Format
+// =============================================================================
+// These types match the wire format spec (protocol/spec/wire-format.md).
+// Wire format has 3 node kinds; TS-only kinds (conditional, loop) are losslessly
+// encoded as command nodes with v1.1 extension fields.
+// property-path is flattened to expression.
+
+export type ProtocolNodeKind = 'command' | 'event-handler' | 'compound';
+export type ProtocolChainType = 'then' | 'and' | 'async' | 'sequential' | 'pipe';
+
+/**
+ * A typed semantic value in the protocol full-fidelity JSON format.
+ * Matches protocol/spec/wire-format.md "Value Shapes" table.
+ */
+export interface ProtocolValueJSON {
+  type: 'selector' | 'literal' | 'reference' | 'expression' | 'property-path' | 'flag';
+  value?: string | number | boolean;
+  dataType?: 'string' | 'number' | 'boolean' | 'duration';
+  raw?: string; // expression only
+  name?: string; // flag only
+  enabled?: boolean; // flag only
+  selectorKind?: 'id' | 'class' | 'attribute' | 'element' | 'complex'; // selector only, optional
+}
+
+/**
+ * Protocol JSON node — matches protocol/spec/wire-format.md.
+ * Produced by toProtocolJSON() and consumed by fromProtocolJSON().
+ *
+ * `kind` defaults to `"command"` when omitted.
+ * `trigger` is convenience sugar that wraps a command in an event handler.
+ */
+export interface ProtocolNodeJSON {
+  kind?: ProtocolNodeKind; // defaults to "command" when absent
+  action: string;
+  roles: Record<string, ProtocolValueJSON>;
+  trigger?: { event: string; modifiers?: Record<string, unknown> }; // convenience sugar
+  body?: ProtocolNodeJSON[]; // event-handler body OR try body (v1.2)
+  statements?: ProtocolNodeJSON[]; // compound only
+  chainType?: ProtocolChainType; // compound only
+  // Conditional fields (v1.1)
+  thenBranch?: ProtocolNodeJSON[];
+  elseBranch?: ProtocolNodeJSON[];
+  // Loop fields (v1.1)
+  loopVariant?: 'forever' | 'times' | 'for' | 'while' | 'until';
+  loopBody?: ProtocolNodeJSON[];
+  loopVariable?: string;
+  indexVariable?: string;
+  // Type constraint diagnostics (v1.2)
+  diagnostics?: ProtocolDiagnosticJSON[];
+  // Metadata annotations (v1.2)
+  annotations?: AnnotationJSON[];
+  // Error handling: try/catch/finally (v1.2)
+  catchBranch?: ProtocolNodeJSON[];
+  finallyBranch?: ProtocolNodeJSON[];
+  // Async coordination: all/race (v1.2)
+  asyncVariant?: 'all' | 'race';
+  asyncBody?: ProtocolNodeJSON[];
+  // Pattern matching: match/arms (v1.2)
+  arms?: MatchArmJSON[];
+  defaultArm?: ProtocolNodeJSON[];
+}
+
+// =============================================================================
+// v1.2 Sub-types
+// =============================================================================
+
+/** A diagnostic in protocol wire format (v1.2, extended v1.2.1). */
+export interface ProtocolDiagnosticJSON {
+  level: 'error' | 'warning' | 'info';
+  role?: string;
+  message: 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). */
+export interface AnnotationJSON {
+  name: string;
+  value?: string;
+}
+
+/** A match arm in protocol wire format (v1.2). */
+export interface MatchArmJSON {
+  pattern: ProtocolValueJSON;
+  body: ProtocolNodeJSON[];
+}
+
+/** Versioned envelope for multi-node LSE documents (v1.2). */
+export interface LSEEnvelopeJSON {
+  lseVersion: string;
+  features?: string[];
+  nodes: ProtocolNodeJSON[];
+}

package/src/prompts/index.ts

@@ -0,0 +1,15 @@
+/**
+ * LLM Prompt Generation
+ *
+ * Auto-generates system prompts from CommandSchema[] for teaching LLMs
+ * to output valid LokaScript Explicit Syntax.
+ */
+
+export type {
+  PromptGeneratorConfig,
+  GeneratedPrompt,
+  PromptSection,
+  PromptMetadata,
+} from './types';
+
+export { generatePrompt, generateExamples, generateProtocolReference } from './prompt-generator';