@lokascript/framework 2.0.0 → 2.2.0

package/dist/ir/explicit-parser.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Explicit Syntax Parser
+ *
+ * Parses the universal [command role:value ...] bracket syntax.
+ * Domain-agnostic — schema validation is injectable via ParseExplicitOptions.
+ *
+ * Three parsing levels matching the ABNF grammar:
+ *   parseDocument()  → parseCompound()  → parseExplicit()
+ *   (multi-line)       (chain ops)         (single bracket)
+ *
+ * Syntax:
+ *   [command role1:value1 role2:value2 ...]
+ *   [cmd1 ...] then [cmd2 ...]
+ *   @annotation(value) [command ...]
+ *   #!lse 1.2\n[cmd1 ...]\n[cmd2 ...]
+ */
+import type { SemanticNode, LSEEnvelope } from '../core/types';
+import type { ParseExplicitOptions } from './types';
+/** Structural role names whose bracket-enclosed values may be nested commands. */
+export declare const STRUCTURAL_ROLES: Set<string>;
+/**
+ * Parse explicit bracket syntax into a semantic node.
+ *
+ * When `options.schemaLookup` is provided, validates roles against the
+ * command's schema. When omitted, accepts any role names.
+ */
+export declare function parseExplicit(input: string, options?: ParseExplicitOptions): SemanticNode;
+/**
+ * Check if input is explicit bracket syntax.
+ */
+export declare function isExplicitSyntax(input: string): boolean;
+/**
+ * Parse a compound statement (one or more bracket commands chained with operators).
+ *
+ * ABNF: compound-stmt = bracket-cmd *( chain-op bracket-cmd )
+ *
+ * Single commands pass through to parseExplicit(). Multiple commands produce
+ * a CompoundSemanticNode.
+ *
+ * Also handles annotations (@name or @name(value)) before the first bracket.
+ *
+ * @example
+ * ```typescript
+ * // Single command — passthrough
+ * parseCompound('[toggle patient:.active]')
+ *
+ * // Compound statement
+ * parseCompound('[add patient:.loading] then [fetch source:/api/data]')
+ *
+ * // With annotation
+ * parseCompound('@timeout(5s) [fetch source:/api/users]')
+ * ```
+ */
+export declare function parseCompound(input: string, options?: ParseExplicitOptions): SemanticNode;
+/**
+ * Parse a multi-line LSE document into an LSEEnvelope.
+ *
+ * ABNF: document = [ version-header LF ] *( line LF ) [ line ]
+ *
+ * Handles version headers (#!lse 1.2), comments (// or #), blank lines,
+ * and statement lines (one compound statement per line).
+ *
+ * @example
+ * ```typescript
+ * const envelope = parseDocument(`
+ *   #!lse 1.2
+ *   // Toggle active state
+ *   [toggle patient:.active]
+ *   [add patient:.highlight]
+ * `);
+ * // envelope.lseVersion === '1.2'
+ * // envelope.nodes.length === 2
+ * ```
+ */
+export declare function parseDocument(input: string, options?: ParseExplicitOptions): LSEEnvelope;
+/**
+ * Check if input contains compound chaining (multiple bracket commands
+ * with chain operators at bracket-depth 0).
+ */
+export declare function isCompoundSyntax(input: string): boolean;
+/**
+ * Check if input is a multi-line LSE document (contains newlines,
+ * version header, or comment lines).
+ */
+export declare function isDocumentSyntax(input: string): boolean;
+//# sourceMappingURL=explicit-parser.d.ts.map

package/dist/ir/explicit-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explicit-parser.d.ts","sourceRoot":"","sources":["../../src/ir/explicit-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,YAAY,EAMZ,WAAW,EAEZ,MAAM,eAAe,CAAC;AAavB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAGpD,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,aAS3B,CAAC;AAsBH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,YAAY,CAkQ7F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGvD;AAuFD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,YAAY,CAuBzF;AA0ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,WAAW,CAmCxF;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQvD"}

package/dist/ir/explicit-renderer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Explicit Syntax Renderer
+ *
+ * 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 { SemanticNode, 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 declare function renderExplicit(node: SemanticNode): string;
+/**
+ * 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 declare function renderDocument(envelope: LSEEnvelope): string;
+//# sourceMappingURL=explicit-renderer.d.ts.map

package/dist/ir/explicit-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explicit-renderer.d.ts","sourceRoot":"","sources":["../../src/ir/explicit-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EAOZ,WAAW,EACZ,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAqBzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAc5D"}

package/dist/ir/from-interchange.d.ts

@@ -0,0 +1,51 @@
+/**
+ * InterchangeNode → SemanticNode Converter
+ *
+ * Converts the expression-level InterchangeNode AST (from core/semantic parsers)
+ * into the command-level SemanticNode IR used by LSE, MCP tools, and domain DSLs.
+ *
+ * This bridges the two IR pipelines in the monorepo:
+ * - Pipeline A (InterchangeNode): full expression trees, 16 node types
+ * - Pipeline B (SemanticNode): command-level semantics, opaque expression values
+ *
+ * Expression subtrees are intentionally collapsed to ExpressionValue { raw: string }
+ * — LSE deliberately abstracts away expression-level detail.
+ *
+ * Uses structural typing for the input to avoid a dependency on the core package.
+ */
+import type { SemanticNode, SemanticValue } from '../core/types';
+/**
+ * Minimal interface matching InterchangeNode's structural shape.
+ * Uses the `type` discriminant for dispatch. Additional fields are
+ * accessed dynamically — this keeps the framework free of core imports.
+ */
+interface INode {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Convert an InterchangeNode (expression-level AST) to a SemanticNode (command-level IR).
+ *
+ * Handles all 16 InterchangeNode types:
+ * - Command/event nodes map to corresponding SemanticNode kinds
+ * - Control flow nodes (if, repeat, foreach, while) map to conditional/loop kinds
+ * - Expression nodes are wrapped as `get` commands with the value as patient role
+ *
+ * @param node - An InterchangeNode (or structurally compatible object)
+ * @returns A SemanticNode suitable for LSE rendering, protocol JSON, or MCP tools
+ */
+export declare function fromInterchangeNode(node: INode): SemanticNode;
+/**
+ * Convert an InterchangeNode to a SemanticValue.
+ *
+ * Simple nodes map directly to typed SemanticValue variants.
+ * Complex expression nodes are collapsed to ExpressionValue { raw: string }.
+ */
+export declare function convertValue(node: INode): SemanticValue;
+/**
+ * Recursively render an InterchangeNode expression tree to a string.
+ * Used to collapse complex expressions into ExpressionValue.raw.
+ */
+export declare function renderExpr(node: INode): string;
+export {};
+//# sourceMappingURL=from-interchange.d.ts.map

package/dist/ir/from-interchange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-interchange.d.ts","sourceRoot":"","sources":["../../src/ir/from-interchange.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EAId,MAAM,eAAe,CAAC;AAkBvB;;;;GAIG;AACH,UAAU,KAAK;IACb,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,KAAK,GAAG,YAAY,CA4B7D;AAsKD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,aAAa,CAmCvD;AA0CD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CA8E9C"}

package/dist/ir/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * IR (Intermediate Representation)
+ *
+ * Universal explicit bracket syntax for semantic DSL interchange.
+ * Domain-agnostic — works for any DSL built on the framework.
+ *
+ * Three input formats converge on SemanticNode:
+ *   1. Bracket syntax:  [toggle patient:.active destination:#button]
+ *   2. LLM JSON:        { action: "toggle", roles: { patient: { type: "selector", value: ".active" } } }
+ *   3. Natural language: (handled by language-specific parsers, not this module)
+ *
+ * @example
+ * ```typescript
+ * import { parseExplicit, renderExplicit, jsonToSemanticNode } from '@lokascript/framework/ir';
+ *
+ * const node = parseExplicit('[toggle patient:.active]');
+ * const bracket = renderExplicit(node);   // "[toggle patient:.active]"
+ * const json = semanticNodeToJSON(node);  // { action: "toggle", roles: { ... } }
+ * ```
+ */
+export type { SemanticJSON, SemanticJSONValue, SchemaLookup, ParseExplicitOptions, IRDiagnostic, } from './types';
+export { DEFAULT_REFERENCES, isValidReference } from './references';
+export { parseExplicit, parseCompound, parseDocument, isExplicitSyntax, isCompoundSyntax, isDocumentSyntax, } from './explicit-parser';
+export { renderExplicit, renderDocument } from './explicit-renderer';
+export { jsonToSemanticNode, validateSemanticJSON, semanticNodeToJSON } from './json-schema';
+export type { ProtocolNodeJSON, ProtocolValueJSON, ProtocolNodeKind, ProtocolChainType, ProtocolDiagnosticJSON, AnnotationJSON, MatchArmJSON, LSEEnvelopeJSON, } from './types';
+export { toProtocolJSON, fromProtocolJSON, validateProtocolJSON, toEnvelopeJSON, fromEnvelopeJSON, isEnvelope, } from './protocol-json';
+export { fromInterchangeNode, convertValue, renderExpr } from './from-interchange';
+export { semanticNodeToRuntimeAST, semanticValueToAST } from './to-runtime-ast';
+export type { RuntimeASTNode, RuntimeCommandNode, RuntimeEventNode } from './to-runtime-ast';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ir/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGpE,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrE,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAG7F,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EAEjB,sBAAsB,EACtB,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EAEpB,cAAc,EACd,gBAAgB,EAChB,UAAU,GACX,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGnF,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAChF,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}