@lokascript/framework 2.1.0 → 2.2.0

package/dist/ir/index.js

@@ -162,6 +162,8 @@ function isNestedCommand(value) {
 }
 function parseExplicit(input, options = {}) {
   const trimmed = input.trim();
+  const collect = options.collectDiagnostics === true;
+  const diagnostics = [];
   if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
     throw new Error("Explicit syntax must be wrapped in brackets: [command role:value ...]");
   }
@@ -184,10 +186,30 @@ function parseExplicit(input, options = {}) {
       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)) {
         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}`)
+          });
+          roles.set(flagName, createFlag(flagName, enabled));
+          continue;
+        }
         throw new Error(
           `Unknown flag "${flagName}" for command "${command}". Valid roles: ${roleList}`
         );
@@ -197,14 +219,33 @@ function parseExplicit(input, options = {}) {
     }
     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`);
     }
     const roleName = token.slice(0, colonIndex);
     if (validRoleNames && !STRUCTURAL_ROLES.has(roleName) && !validRoleNames.has(roleName)) {
       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]
+        });
+      } else {
+        throw new Error(
+          `Unknown role "${roleName}" for command "${command}". Valid roles: ${roleList}`
+        );
+      }
     }
     const role = roleName;
     const valueStr = token.slice(colonIndex + 1);
@@ -220,37 +261,67 @@ function parseExplicit(input, options = {}) {
   if (schema && command !== "on") {
     for (const roleSpec of schema.roles) {
       if (roleSpec.required && !roles.has(roleSpec.role) && !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}`
+          );
+        }
       }
     }
   }
+  const attachDiagnostics = (node) => {
+    if (diagnostics.length === 0) return node;
+    return { ...node, diagnostics };
+  };
   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 attachDiagnostics(
+            createEventHandlerNode("on", roles, [], {
+              sourceLanguage: "explicit"
+            })
+          );
+        }
         throw new Error("Event handler requires event role: [on event:click ...]");
       }
       const body = extractStructuralBody(roles, "body", options);
       roles.delete("body");
-      return createEventHandlerNode("on", roles, body, {
-        sourceLanguage: "explicit"
-      });
+      return attachDiagnostics(
+        createEventHandlerNode("on", roles, body, {
+          sourceLanguage: "explicit"
+        })
+      );
     }
     case "if": {
       const thenBranch = extractStructuralBody(roles, "then", options);
       const elseBranch = extractStructuralBody(roles, "else", options);
       roles.delete("then");
       roles.delete("else");
-      return createConditionalNode(
-        command,
-        roles,
-        thenBranch,
-        elseBranch.length > 0 ? elseBranch : void 0,
-        {
-          sourceLanguage: "explicit"
-        }
+      return attachDiagnostics(
+        createConditionalNode(
+          command,
+          roles,
+          thenBranch,
+          elseBranch.length > 0 ? elseBranch : void 0,
+          {
+            sourceLanguage: "explicit"
+          }
+        )
       );
     }
     case "repeat": {
@@ -276,20 +347,182 @@ function parseExplicit(input, options = {}) {
       }
       const loopVariable = variableValue?.type === "literal" && typeof variableValue.value === "string" ? variableValue.value : variableValue?.type === "expression" ? variableValue.raw : void 0;
       const indexVariable = indexVariableValue?.type === "literal" && typeof indexVariableValue.value === "string" ? indexVariableValue.value : void 0;
-      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"
+        })
+      );
   }
 }
 function isExplicitSyntax(input) {
   const trimmed = input.trim();
   return trimmed.startsWith("[") && trimmed.endsWith("]");
 }
+var CHAIN_KEYWORDS = /* @__PURE__ */ new Set(["then", "and", "async", "sequential"]);
+function splitCompoundSegments(input) {
+  const segments = [];
+  let chainType = 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;
+      if (bracketDepth === 0) {
+        const rest = input.slice(i + 1);
+        const pipeMatch = rest.match(/^\s*\|>\s*/);
+        if (pipeMatch) {
+          segments.push(current.trim());
+          current = "";
+          chainType ?? (chainType = "pipe");
+          i += pipeMatch[0].length;
+          continue;
+        }
+        const keywordMatch = rest.match(/^\s+(then|and|async|sequential)\s+/);
+        if (keywordMatch && CHAIN_KEYWORDS.has(keywordMatch[1])) {
+          segments.push(current.trim());
+          current = "";
+          chainType ?? (chainType = keywordMatch[1]);
+          i += keywordMatch[0].length;
+          continue;
+        }
+      }
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim()) {
+    segments.push(current.trim());
+  }
+  return { segments, chainType };
+}
+function parseCompound(input, options) {
+  const trimmed = input.trim();
+  const { annotations, remainder } = extractAnnotations(trimmed);
+  const { segments, chainType } = splitCompoundSegments(remainder);
+  let node;
+  if (segments.length <= 1) {
+    node = parseExplicit(segments[0] || remainder, options);
+  } else {
+    const statements = segments.map((seg) => parseExplicit(seg, options));
+    node = createCompoundNode(statements, chainType ?? "sequential");
+  }
+  if (annotations.length > 0) {
+    return { ...node, annotations };
+  }
+  return node;
+}
+function extractAnnotations(input) {
+  const annotations = [];
+  let pos = 0;
+  while (pos < input.length) {
+    while (pos < input.length && (input[pos] === " " || input[pos] === "	")) {
+      pos++;
+    }
+    if (pos >= input.length || input[pos] !== "@") {
+      break;
+    }
+    pos++;
+    const nameStart = pos;
+    while (pos < input.length && /[A-Za-z0-9\-_]/.test(input[pos])) {
+      pos++;
+    }
+    const name = input.slice(nameStart, pos);
+    if (!name) break;
+    let value;
+    if (pos < input.length && input[pos] === "(") {
+      pos++;
+      const valueStart = pos;
+      if (pos < input.length && (input[pos] === '"' || input[pos] === "'")) {
+        const quote = input[pos];
+        pos++;
+        while (pos < input.length && input[pos] !== quote) {
+          if (input[pos] === "\\") pos++;
+          pos++;
+        }
+        pos++;
+        value = input.slice(valueStart + 1, pos - 1);
+      } else {
+        while (pos < input.length && input[pos] !== ")") {
+          pos++;
+        }
+        value = input.slice(valueStart, pos);
+      }
+      if (pos < input.length && input[pos] === ")") {
+        pos++;
+      }
+    }
+    annotations.push(value !== void 0 ? { name, value } : { name });
+  }
+  return { annotations, remainder: input.slice(pos).trim() };
+}
+var VERSION_HEADER_RE = /^#!lse\s+(\d+\.\d+(?:\.\d+)?)\s*$/;
+function parseDocument(input, options) {
+  const lines = input.split("\n");
+  let lseVersion = "1.0";
+  const nodes = [];
+  let startLine = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!trimmed) continue;
+    const versionMatch = trimmed.match(VERSION_HEADER_RE);
+    if (versionMatch) {
+      lseVersion = versionMatch[1];
+      startLine = i + 1;
+    }
+    break;
+  }
+  for (let i = startLine; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith("//") || trimmed.startsWith("#") && !trimmed.startsWith("#!")) {
+      continue;
+    }
+    nodes.push(parseCompound(trimmed, options));
+  }
+  return { lseVersion, nodes };
+}
+function isCompoundSyntax(input) {
+  const { segments } = splitCompoundSegments(input.trim());
+  return segments.length > 1;
+}
+function isDocumentSyntax(input) {
+  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;
+}
 function extractStructuralBody(roles, roleName, options) {
   const value = roles.get(roleName);
   if (!value) return [];
@@ -391,11 +624,33 @@ function findMatchingBracket(str, start) {
 
 // src/ir/explicit-renderer.ts
 function renderExplicit(node) {
+  let result;
   if (node.kind === "compound") {
     const compoundNode = node;
     const renderedStatements = compoundNode.statements.map((stmt) => renderExplicit(stmt));
-    return renderedStatements.join(` ${compoundNode.chainType} `);
+    result = renderedStatements.join(` ${compoundNode.chainType} `);
+  } else {
+    result = renderBracketCommand(node);
+  }
+  if (node.annotations && node.annotations.length > 0) {
+    const annParts = node.annotations.map(
+      (ann) => ann.value !== void 0 ? `@${ann.name}(${ann.value})` : `@${ann.name}`
+    );
+    return annParts.join(" ") + " " + result;
+  }
+  return result;
+}
+function renderDocument(envelope) {
+  const lines = [];
+  if (envelope.lseVersion && envelope.lseVersion !== "1.0") {
+    lines.push(`#!lse ${envelope.lseVersion}`);
   }
+  for (const node of envelope.nodes) {
+    lines.push(renderExplicit(node));
+  }
+  return lines.join("\n");
+}
+function renderBracketCommand(node) {
   const parts = [node.action];
   for (const [role, value] of node.roles) {
     if (value.type === "flag") {
@@ -733,12 +988,16 @@ function toProtocolJSON(node) {
     );
   }
   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 = {
+        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;
 }
@@ -786,10 +1045,11 @@ function fromProtocolJSON(json) {
     (a) => a.value !== void 0 ? { name: a.name, value: a.value } : { name: a.name }
   );
   const diagnostics = json.diagnostics?.map((d) => ({
-    level: d.level,
-    role: d.role,
+    severity: d.level,
     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 } : {}
   }));
   if (json.trigger) {
     const eventName = json.trigger.event;
@@ -930,7 +1190,7 @@ var VALID_VALUE_TYPES2 = /* @__PURE__ */ new Set([
 ]);
 var VALID_CHAIN_TYPES = /* @__PURE__ */ new Set(["then", "and", "async", "sequential", "pipe"]);
 var VALID_ASYNC_VARIANTS = /* @__PURE__ */ new Set(["all", "race"]);
-var VALID_DIAGNOSTIC_LEVELS = /* @__PURE__ */ new Set(["error", "warning"]);
+var VALID_DIAGNOSTIC_LEVELS = /* @__PURE__ */ new Set(["error", "warning", "info"]);
 function validateProtocolJSON(json) {
   const diagnostics = [];
   if (typeof json !== "object" || json === null) {
@@ -1079,14 +1339,7 @@ function validateProtocolJSON(json) {
           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") {
@@ -1096,11 +1349,11 @@ function validateProtocolJSON(json) {
             message: `diagnostics[${i}] missing required field: message`
           });
         }
-        if (typeof d.code !== "string") {
+        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`
           });
         }
       }
@@ -1535,20 +1788,144 @@ function bridgeEventModifiers(mods) {
     ...from !== void 0 ? { from } : {}
   };
 }
+
+// src/ir/to-runtime-ast.ts
+function semanticNodeToRuntimeAST(node) {
+  switch (node.kind) {
+    case "event-handler":
+      return convertEventHandler(node);
+    case "conditional":
+      return convertConditional(node);
+    case "loop":
+      return convertLoop(node);
+    case "compound": {
+      const compound = node;
+      const commands = (compound.statements ?? []).map(semanticNodeToRuntimeAST);
+      return {
+        type: "CommandSequence",
+        commands
+      };
+    }
+    case "command":
+    default:
+      return convertCommand2(node);
+  }
+}
+function convertEventHandler(eh) {
+  const eventValue = eh.roles.get("event");
+  const eventName = eventValue && "value" in eventValue ? String(eventValue.value) : "click";
+  const modifiers = {};
+  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 convertCommand2(node) {
+  const roles = {};
+  const args = [];
+  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) {
+  const conditionValue = node.roles.get("condition");
+  return {
+    type: "command",
+    name: "if",
+    args: conditionValue ? [semanticValueToAST(conditionValue)] : [],
+    condition: conditionValue ? semanticValueToAST(conditionValue) : void 0,
+    thenBranch: (node.thenBranch ?? []).map(semanticNodeToRuntimeAST),
+    elseBranch: (node.elseBranch ?? []).map(semanticNodeToRuntimeAST)
+  };
+}
+function convertLoop(node) {
+  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
+  };
+}
+function semanticValueToAST(value) {
+  switch (value.type) {
+    case "selector":
+      return { type: "selector", value: value.value };
+    case "reference":
+      return { type: "identifier", value: value.value };
+    case "literal": {
+      const lit = value;
+      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]) * 1e3 : parseFloat(match[1]);
+          return { type: "literal", value: ms };
+        }
+      }
+      return { type: "literal", value: lit.value };
+    }
+    case "property-path": {
+      const pp = value;
+      const objectAST = semanticValueToAST(pp.object);
+      return {
+        type: "member",
+        object: objectAST,
+        property: pp.property
+      };
+    }
+    case "expression": {
+      const expr = value;
+      return { type: "expression", value: expr.raw };
+    }
+    case "flag": {
+      const flag = value;
+      return { type: "literal", value: flag.enabled };
+    }
+    default:
+      return { type: "literal", value: String(value.value ?? "") };
+  }
+}
 export {
   DEFAULT_REFERENCES,
   convertValue,
   fromEnvelopeJSON,
   fromInterchangeNode,
   fromProtocolJSON,
+  isCompoundSyntax,
+  isDocumentSyntax,
   isEnvelope,
   isExplicitSyntax,
   isValidReference,
   jsonToSemanticNode,
+  parseCompound,
+  parseDocument,
   parseExplicit,
+  renderDocument,
   renderExplicit,
   renderExpr,
   semanticNodeToJSON,
+  semanticNodeToRuntimeAST,
+  semanticValueToAST,
   toEnvelopeJSON,
   toProtocolJSON,
   validateProtocolJSON,