@lokascript/framework 2.0.0 → 2.2.0

package/dist/ir/to-runtime-ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-runtime-ast.d.ts","sourceRoot":"","sources":["../../src/ir/to-runtime-ast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EAId,MAAM,eAAe,CAAC;AAMvB,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9C;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,CAAC;CACjC;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,CAwB3E;AAiED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CA4CvE"}

package/dist/ir/types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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';
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+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;
+    name?: string;
+    enabled?: boolean;
+    selectorKind?: 'id' | 'class' | 'attribute' | 'element' | 'complex';
+}
+/**
+ * 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;
+    action: string;
+    roles: Record<string, ProtocolValueJSON>;
+    trigger?: {
+        event: string;
+        modifiers?: Record<string, unknown>;
+    };
+    body?: ProtocolNodeJSON[];
+    statements?: ProtocolNodeJSON[];
+    chainType?: ProtocolChainType;
+    thenBranch?: ProtocolNodeJSON[];
+    elseBranch?: ProtocolNodeJSON[];
+    loopVariant?: 'forever' | 'times' | 'for' | 'while' | 'until';
+    loopBody?: ProtocolNodeJSON[];
+    loopVariable?: string;
+    indexVariable?: string;
+    diagnostics?: ProtocolDiagnosticJSON[];
+    annotations?: AnnotationJSON[];
+    catchBranch?: ProtocolNodeJSON[];
+    finallyBranch?: ProtocolNodeJSON[];
+    asyncVariant?: 'all' | 'race';
+    asyncBody?: ProtocolNodeJSON[];
+    arms?: MatchArmJSON[];
+    defaultArm?: ProtocolNodeJSON[];
+}
+/** 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[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/ir/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ir/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAM9D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzC,8DAA8D;IAC9D,OAAO,CAAC,EAAE;QACR,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,eAAe,GAAG,MAAM,CAAC;IACrF,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAClC;AAMD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAMD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAUD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,eAAe,GAAG,UAAU,CAAC;AACxE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,YAAY,GAAG,MAAM,CAAC;AAEjF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,eAAe,GAAG,MAAM,CAAC;IACrF,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAClC,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;CACrE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IACjE,IAAI,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC1B,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAE9B,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEhC,WAAW,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC;IAC9D,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,WAAW,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAEvC,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAE/B,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC,aAAa,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEnC,YAAY,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAE/B,IAAI,CAAC,EAAE,YAAY,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;CACjC;AAMD,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,gBAAgB,EAAE,CAAC;CAC1B;AAED,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B"}

package/dist/parsing/index.js

@@ -224,7 +224,7 @@ var _PatternMatcher = class _PatternMatcher {
    * a token and the immediately following pattern token fails, the matcher
    * resets to before the optional role and retries the failed token.
    */
-  matchTokenSequence(tokens, patternTokens, captured) {
+  matchTokenSequence(tokens, patternTokens, captured, parentStopMarkers) {
     const firstPatternToken = patternTokens[0];
     const patternExpectsConjunction = firstPatternToken?.type === "literal" && (firstPatternToken.value === "and" || firstPatternToken.value === "then" || firstPatternToken.alternatives?.includes("and") || firstPatternToken.alternatives?.includes("then"));
     if (this.currentProfile?.code === "ar" && !patternExpectsConjunction) {
@@ -248,6 +248,9 @@ var _PatternMatcher = class _PatternMatcher {
       );
       if (patternToken.type === "role" && patternToken.greedy) {
         const stopMarkers = this.collectStopMarkers(patternTokens, i + 1);
+        if (parentStopMarkers) {
+          for (const m of parentStopMarkers) stopMarkers.add(m);
+        }
         const values = [];
         while (!tokens.isAtEnd()) {
           const nextToken = tokens.peek();
@@ -267,8 +270,58 @@ var _PatternMatcher = class _PatternMatcher {
           return false;
         }
       }
+      if (patternToken.type === "group") {
+        const siblingStopMarkers = this.collectStopMarkers(patternTokens, i + 1);
+        if (parentStopMarkers) {
+          for (const m of parentStopMarkers) siblingStopMarkers.add(m);
+        }
+        const groupMatched = this.matchGroupToken(
+          tokens,
+          patternToken,
+          captured,
+          siblingStopMarkers
+        );
+        if (groupMatched) {
+          prevOptionalMark = null;
+          prevOptionalRole = null;
+          continue;
+        }
+        if (this.isOptional(patternToken)) {
+          continue;
+        }
+        return false;
+      }
       const isOptionalRole = patternToken.type === "role" && patternToken.optional === true;
       const markBefore = isOptionalRole ? tokens.mark() : null;
+      const isRoleToken = patternToken.type === "role";
+      if (isRoleToken && !isOptionalRole) {
+        const nextPT = i + 1 < patternTokens.length ? patternTokens[i + 1] : null;
+        if (nextPT?.type === "literal") {
+          const currentToken = tokens.peek();
+          if (currentToken && this.getMatchType(currentToken, nextPT.value) !== "none") {
+            this.logger.debug(
+              "  >> MARKER-STEAL GUARD: current token matches next literal, skipping role"
+            );
+            this.logger.debug("  >> Token match FAILED");
+            if (this.isOptional(patternToken)) {
+              continue;
+            }
+            if (prevOptionalMark && prevOptionalRole) {
+              this.logger.debug("  >> BACKTRACKING: undoing optional role", prevOptionalRole);
+              tokens.reset(prevOptionalMark);
+              captured.delete(prevOptionalRole);
+              prevOptionalMark = null;
+              prevOptionalRole = null;
+              const retryMatched = this.matchPatternToken(tokens, patternToken, captured);
+              this.logger.debug("  >> Backtrack retry result:", retryMatched);
+              if (retryMatched) {
+                continue;
+              }
+            }
+            return false;
+          }
+        }
+      }
       const matched = this.matchPatternToken(tokens, patternToken, captured);
       this.logger.debug("  >> Match result:", matched);
       if (matched) {
@@ -389,7 +442,7 @@ var _PatternMatcher = class _PatternMatcher {
     const possessiveValue = this.tryMatchPossessiveExpression(tokens);
     if (possessiveValue) {
       if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
-        if (!patternToken.expectedTypes.includes(possessiveValue.type) && !patternToken.expectedTypes.includes("expression")) {
+        if (!isTypeCompatible(possessiveValue.type, patternToken.expectedTypes)) {
           return patternToken.optional || false;
         }
       }
@@ -399,7 +452,7 @@ var _PatternMatcher = class _PatternMatcher {
     const methodCallValue = this.tryMatchMethodCallExpression(tokens);
     if (methodCallValue) {
       if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
-        if (!patternToken.expectedTypes.includes(methodCallValue.type) && !patternToken.expectedTypes.includes("expression")) {
+        if (!isTypeCompatible(methodCallValue.type, patternToken.expectedTypes)) {
           return patternToken.optional || false;
         }
       }
@@ -419,7 +472,7 @@ var _PatternMatcher = class _PatternMatcher {
     const propertyAccessValue = this.tryMatchPropertyAccessExpression(tokens);
     if (propertyAccessValue) {
       if (patternToken.expectedTypes && patternToken.expectedTypes.length > 0) {
-        if (!patternToken.expectedTypes.includes(propertyAccessValue.type) && !patternToken.expectedTypes.includes("expression")) {
+        if (!isTypeCompatible(propertyAccessValue.type, patternToken.expectedTypes)) {
           return patternToken.optional || false;
         }
       }
@@ -739,10 +792,15 @@ var _PatternMatcher = class _PatternMatcher {
    * (e.g., a value like 'hello') to sit between groups without blocking later
    * marker matches.
    */
-  matchGroupToken(tokens, patternToken, captured) {
+  matchGroupToken(tokens, patternToken, captured, parentStopMarkers) {
     const mark = tokens.mark();
     const capturedBefore = new Set(captured.keys());
-    const success = this.matchTokenSequence(tokens, patternToken.tokens, captured);
+    const success = this.matchTokenSequence(
+      tokens,
+      patternToken.tokens,
+      captured,
+      parentStopMarkers
+    );
     if (success) return true;
     tokens.reset(mark);
     for (const role of captured.keys()) {
@@ -764,7 +822,12 @@ var _PatternMatcher = class _PatternMatcher {
             "- skipping intervening tokens"
           );
           for (let s = 0; s < offset; s++) tokens.advance();
-          const retrySuccess = this.matchTokenSequence(tokens, patternToken.tokens, captured);
+          const retrySuccess = this.matchTokenSequence(
+            tokens,
+            patternToken.tokens,
+            captured,
+            parentStopMarkers
+          );
           if (retrySuccess) return true;
           tokens.reset(mark);
           for (const role of captured.keys()) {
@@ -831,7 +894,7 @@ var _PatternMatcher = class _PatternMatcher {
             break;
           }
         }
-        break;
+        if (!pt.optional) break;
       }
     }
     return markers;
@@ -841,8 +904,9 @@ var _PatternMatcher = class _PatternMatcher {
    */
   isStopMarker(token, stopMarkers) {
     if (stopMarkers.size === 0) return false;
-    const value = (token.normalized || token.value).toLowerCase();
-    return stopMarkers.has(value);
+    if (stopMarkers.has(token.value.toLowerCase())) return true;
+    if (token.normalized && stopMarkers.has(token.normalized.toLowerCase())) return true;
+    return false;
   }
   /**
    * Convert a language token to a semantic value.