@lokascript/framework 2.1.0 → 2.2.0

package/dist/api/index.js

@@ -1696,6 +1696,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 ...]");
   }
@@ -1718,10 +1720,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}`
         );
@@ -1731,14 +1753,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);
@@ -1754,37 +1795,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": {
@@ -1810,14 +1881,18 @@ 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) {
@@ -1925,11 +2000,23 @@ 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 renderBracketCommand(node) {
   const parts = [node.action];
   for (const [role, value] of node.roles) {
     if (value.type === "flag") {