@lokascript/semantic 1.3.0 → 2.0.0

package/dist/ast-builder/index.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Semantic to AST Builder
+ *
+ * Converts SemanticNodes directly to AST nodes, bypassing the English text
+ * generation and re-parsing step.
+ *
+ * Flow:
+ *   Japanese → Semantic Parser → SemanticNode → AST Builder → AST
+ *
+ * Instead of:
+ *   Japanese → Semantic Parser → SemanticNode → English Text → Parser → AST
+ */
+import type { SemanticNode } from '../types';
+import type { ExpressionNode } from './expression-parser';
+/**
+ * Base AST node interface
+ */
+export interface ASTNode {
+    readonly type: string;
+    readonly start?: number;
+    readonly end?: number;
+    readonly line?: number;
+    readonly column?: number;
+    [key: string]: unknown;
+}
+/**
+ * Command AST node
+ */
+export interface CommandNode extends ASTNode {
+    readonly type: 'command';
+    readonly name: string;
+    readonly args: ExpressionNode[];
+    readonly modifiers?: Record<string, ExpressionNode>;
+    readonly isBlocking?: boolean;
+    readonly implicitTarget?: ExpressionNode;
+}
+/**
+ * Event handler AST node (compatible with @hyperfixi/core)
+ */
+export interface EventHandlerNode extends ASTNode {
+    readonly type: 'eventHandler';
+    /** Primary event name */
+    readonly event: string;
+    /** All event names when using "on event1 or event2" syntax */
+    readonly events?: string[];
+    /** CSS selector for event delegation ("from" keyword) */
+    readonly selector?: string;
+    /** Target for "from" clause (as string or expression) */
+    readonly target?: string;
+    /** Optional event condition ("[condition]" syntax) */
+    readonly condition?: ASTNode;
+    /** Attribute name for mutation events ("of @attribute" syntax) */
+    readonly attributeName?: string;
+    /** Target element to watch for changes ("in <target>" syntax) */
+    readonly watchTarget?: ExpressionNode;
+    /** Event parameter names to destructure (e.g., ['clientX', 'clientY']) */
+    readonly args?: string[];
+    /** Event parameters (alias for args) */
+    readonly params?: string[];
+    /** Handler commands */
+    readonly commands: ASTNode[];
+}
+/**
+ * Conditional AST node (if/else)
+ *
+ * Note: For runtime compatibility, buildConditional() now produces a CommandNode
+ * with condition and branches as args, matching what IfCommand expects.
+ * This interface is retained for reference but not used as output.
+ */
+export interface ConditionalNode extends ASTNode {
+    readonly type: 'if';
+    readonly condition: ExpressionNode;
+    readonly thenBranch: ASTNode[];
+    readonly elseBranch?: ASTNode[];
+}
+/**
+ * Command sequence node (runtime-compatible format for chained commands)
+ */
+export interface CommandSequenceNode extends ASTNode {
+    readonly type: 'CommandSequence';
+    /** Commands in the sequence */
+    readonly commands: ASTNode[];
+}
+/**
+ * Block node (for grouping commands)
+ */
+export interface BlockNode extends ASTNode {
+    readonly type: 'block';
+    readonly commands: ASTNode[];
+}
+export interface ASTBuilderOptions {
+    /**
+     * Fallback function to parse complex expressions that can't be handled
+     * directly by the AST builder. Uses the expression-parser by default.
+     */
+    parseExpression?: (input: string) => ExpressionNode | null;
+}
+/**
+ * Builds AST nodes directly from SemanticNodes.
+ */
+export declare class ASTBuilder {
+    /**
+     * Warnings collected during AST building (e.g., type inference issues).
+     */
+    warnings: string[];
+    constructor(_options?: ASTBuilderOptions);
+    /**
+     * Build an AST from a SemanticNode.
+     *
+     * @param node - The semantic node to convert
+     * @returns The corresponding AST node
+     */
+    build(node: SemanticNode): ASTNode;
+    /**
+     * Build a CommandNode from a CommandSemanticNode.
+     */
+    private buildCommand;
+    /**
+     * Generic command builder when no specific mapper is available.
+     * Maps roles to args in a predictable order.
+     */
+    private buildGenericCommand;
+    /**
+     * Map semantic roles to hyperscript modifier keywords.
+     */
+    private roleToModifierKey;
+    /**
+     * Build an EventHandlerNode from an EventHandlerSemanticNode.
+     */
+    private buildEventHandler;
+    /**
+     * Build a CommandNode from a ConditionalSemanticNode.
+     *
+     * Produces a command node with:
+     * - args[0]: condition expression
+     * - args[1]: then block (wrapped in { type: 'block', commands: [...] })
+     * - args[2]: else block (optional, same format)
+     *
+     * This format matches what IfCommand.parseInput() expects.
+     */
+    private buildConditional;
+    /**
+     * Build AST nodes from a CompoundSemanticNode.
+     *
+     * Converts to CommandSequence for runtime compatibility.
+     * The runtime recognizes 'CommandSequence' type and executes commands in order.
+     */
+    private buildCompound;
+    /**
+     * Build a CommandNode from a LoopSemanticNode.
+     *
+     * Produces a 'repeat' command with:
+     * - args[0]: loop type identifier (forever, times, for, while, until)
+     * - args[1]: count/condition/variable depending on loop type
+     * - args[2]: collection (for 'for' loops)
+     * - args[last]: body block
+     *
+     * This format matches what the repeat command parser produces.
+     */
+    private buildLoop;
+    /**
+     * Build a BlockNode from an array of semantic nodes.
+     * Useful for grouping commands in if/else branches.
+     */
+    buildBlock(nodes: SemanticNode[]): BlockNode;
+}
+/**
+ * Result from building an AST, including any warnings.
+ */
+export interface BuildASTResult {
+    ast: ASTNode;
+    warnings: string[];
+}
+/**
+ * Build an AST from a SemanticNode using default options.
+ *
+ * @param node - The semantic node to convert
+ * @returns The corresponding AST node and any warnings
+ */
+export declare function buildAST(node: SemanticNode): BuildASTResult;
+export { convertValue, convertLiteral, convertSelector, convertReference, convertPropertyPath, convertExpression, } from './value-converters';
+export { getCommandMapper, registerCommandMapper, getRegisteredMappers, type CommandMapper, type CommandMapperResult, } from './command-mappers';
+//# sourceMappingURL=index.d.ts.map

package/dist/ast-builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ast-builder/index.ts"],"names":[],"mappings":"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"}

package/dist/ast-builder/value-converters.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Semantic Value to AST Node Converters
+ *
+ * Converts SemanticValue types to AST expression nodes.
+ * Used by the AST builder to construct expression trees from semantic parsing results.
+ */
+import type { SemanticValue, LiteralValue, SelectorValue, ReferenceValue, PropertyPathValue, ExpressionValue } from '../types';
+import { type ExpressionNode, type LiteralNode, type SelectorNode, type ContextReferenceNode, type PropertyAccessNode } from './expression-parser';
+/**
+ * Convert a SemanticValue to an AST ExpressionNode.
+ *
+ * @param value - The semantic value to convert
+ * @param warnings - Optional array to collect warnings about potentially incorrect type choices
+ * @returns The corresponding AST expression node
+ */
+export declare function convertValue(value: SemanticValue, warnings?: string[]): ExpressionNode;
+/**
+ * Convert a LiteralValue to a LiteralNode.
+ */
+export declare function convertLiteral(value: LiteralValue): LiteralNode;
+/**
+ * Convert a SelectorValue to a SelectorNode.
+ *
+ * @param value - The selector value to convert
+ * @param warnings - Optional array to collect warnings
+ */
+export declare function convertSelector(value: SelectorValue, warnings?: string[]): SelectorNode;
+/**
+ * Convert a ReferenceValue to a ContextReferenceNode.
+ */
+export declare function convertReference(value: ReferenceValue): ContextReferenceNode;
+/**
+ * Convert a PropertyPathValue to a PropertyAccessNode.
+ * Recursively converts the object part.
+ *
+ * @param value - The property path value to convert
+ * @param warnings - Optional array to collect warnings
+ */
+export declare function convertPropertyPath(value: PropertyPathValue, warnings?: string[]): PropertyAccessNode;
+/**
+ * Convert an ExpressionValue (raw string) by parsing it with the expression parser.
+ * This is the fallback for complex expressions that couldn't be fully parsed
+ * at the semantic level.
+ */
+export declare function convertExpression(value: ExpressionValue): ExpressionNode;
+export declare function isLiteralValue(value: SemanticValue): value is LiteralValue;
+export declare function isSelectorValue(value: SemanticValue): value is SelectorValue;
+export declare function isReferenceValue(value: SemanticValue): value is ReferenceValue;
+export declare function isPropertyPathValue(value: SemanticValue): value is PropertyPathValue;
+export declare function isExpressionValue(value: SemanticValue): value is ExpressionValue;
+//# sourceMappingURL=value-converters.d.ts.map

package/dist/ast-builder/value-converters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-converters.d.ts","sourceRoot":"","sources":["../../src/ast-builder/value-converters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,eAAe,EAChB,MAAM,UAAU,CAAC;AAElB,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EAIxB,MAAM,qBAAqB,CAAC;AAM7B;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,CAiBtF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAY/D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,CAiBvF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,oBAAoB,CAM5E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,iBAAiB,EACxB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,kBAAkB,CAMpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,cAAc,CAaxE;AAMD,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,YAAY,CAE1E;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,aAAa,CAE5E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,cAAc,CAE9E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,iBAAiB,CAEpF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,eAAe,CAEhF"}