@robinpath/robinpath 0.30.0

package/bin/robinpath.js

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+
+import { createInterface } from 'readline';
+import { RobinPath } from '../dist/index.js';
+
+// Create interpreter instance with thread control enabled and start a thread for REPL
+const rp = new RobinPath({ threadControl: true });
+rp.createThread('default'); // Creates and sets as currentThread
+
+// Helper function to get the prompt with thread ID and current module
+function getPrompt() {
+    if (!rp.currentThread) return '> ';
+    const threadId = rp.currentThread.id;
+    const currentModule = rp.currentThread.getCurrentModule();
+    if (currentModule) {
+        return `${threadId}@${currentModule}> `;
+    }
+    return `${threadId}> `;
+}
+
+// Create readline interface (prompt will be updated after thread is ready)
+const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: '> '
+});
+
+// Set the initial prompt with current module
+rl.setPrompt(getPrompt());
+
+// State for multi-line blocks
+let accumulatedLines = [];
+
+// Helper function to check if a line ends with backslash (ignoring trailing whitespace)
+function endsWithBackslash(line) {
+    const trimmed = line.trimEnd();
+    return trimmed.endsWith('\\');
+}
+
+// Process a line of input
+async function processLine(line) {
+    const trimmed = line.trim();
+    
+    // Skip empty lines
+    if (!trimmed) {
+        return;
+    }
+    
+    // Handle exit commands
+    if (trimmed === 'exit' || trimmed === 'quit' || trimmed === '.exit' || trimmed === '.quit') {
+        console.log('Goodbye!');
+        rl.close();
+        process.exit(0);
+        return;
+    }
+    
+    // Handle help
+    if (trimmed === 'help' || trimmed === '.help') {
+        console.log(`
+RobinPath REPL Commands:
+  exit, quit, .exit, .quit  - Exit the REPL
+  help, .help                - Show this help message
+  clear, .clear              - Clear the screen
+  ..                         - Show all available commands as JSON
+  
+Multi-line blocks:
+  def <name> ... enddef  - Define a function
+  if <expr> ... endif    - Conditional block
+  for $var in <expr> ... endfor  - Loop block
+  scope ... endscope     - Scope block
+  fn(...)                - Parenthesized function call (multi-line)
+  { ... }                - Object literal (multi-line)
+  [ ... ]                - Array literal (multi-line)
+  <line> \\              - Backslash line continuation
+        `);
+        return;
+    }
+    
+    // Handle clear
+    if (trimmed === 'clear' || trimmed === '.clear') {
+        console.clear();
+        return;
+    }
+    
+    // Handle ".." command - show available commands
+    if (trimmed === '..') {
+        let commands;
+        if (rp.currentThread) {
+            commands = rp.currentThread.getAvailableCommands();
+        } else {
+            commands = rp.getAvailableCommands();
+        }
+        
+        // Just show JSON
+        console.log(JSON.stringify(commands, null, 2));
+        return;
+    }
+    
+    // If we have accumulated lines, add this line and check if block is complete
+    if (accumulatedLines.length > 0) {
+        accumulatedLines.push(line);
+        const script = accumulatedLines.join('\n');
+        
+        // Check if line ends with backslash - if so, continue accumulating
+        if (endsWithBackslash(line)) {
+            // Still in continuation mode, update prompt
+            if (!rp.currentThread) {
+                rl.setPrompt(`... `);
+            } else {
+                const threadId = rp.currentThread.id;
+                const currentModule = rp.currentThread.getCurrentModule();
+                if (currentModule) {
+                    rl.setPrompt(`[${threadId}]@[${currentModule}]... `);
+                } else {
+                    rl.setPrompt(`[${threadId}]... `);
+                }
+            }
+            return;
+        }
+        
+        // Check if the block is now complete using the built-in method
+        let needsMore;
+        if (rp.currentThread) {
+            needsMore = rp.currentThread.needsMoreInput(script);
+        } else {
+            needsMore = rp.needsMoreInput(script);
+        }
+        
+        if (!needsMore.needsMore) {
+            // Block is complete, execute it
+            const finalScript = accumulatedLines.join('\n');
+            accumulatedLines = [];
+            
+            try {
+                let result;
+                if (rp.currentThread) {
+                    // Execute in current thread
+                    result = await rp.currentThread.executeScript(finalScript);
+                } else {
+                    // Execute in global thread (root RobinPath instance)
+                    result = await rp.executeScript(finalScript);
+                }
+                
+                // Check if result is from explain command (structured object)
+                if (result && typeof result === 'object' && !Array.isArray(result) && result.type) {
+                    if (result.type === 'function') {
+                        // Format function documentation
+                        console.log(`\nFunction: ${result.name}`);
+                        console.log(`\nDescription: ${result.description}\n`);
+                        
+                        if (result.parameters && result.parameters.length > 0) {
+                            console.log('Parameters:');
+                            for (const param of result.parameters) {
+                                let paramLine = `  - ${param.name} (${param.dataType})`;
+                                if (param.required) {
+                                    paramLine += ' [required]';
+                                }
+                                console.log(paramLine);
+                                console.log(`    ${param.description}`);
+                                if (param.formInputType) {
+                                    console.log(`    Input type: ${param.formInputType}`);
+                                }
+                                if (param.defaultValue !== undefined) {
+                                    console.log(`    Default: ${JSON.stringify(param.defaultValue)}`);
+                                }
+                            }
+                        } else {
+                            console.log('Parameters: None');
+                        }
+                        
+                        console.log(`\nReturns: ${result.returnType}`);
+                        if (result.returnDescription) {
+                            console.log(`  ${result.returnDescription}`);
+                        }
+                        console.log('');
+                    } else if (result.type === 'module') {
+                        // Format module documentation
+                        console.log(`\nModule: ${result.name}`);
+                        console.log(`\nDescription: ${result.description}\n`);
+                        
+                        if (result.methods && result.methods.length > 0) {
+                            console.log('Available Methods:');
+                            for (const method of result.methods) {
+                                console.log(`  - ${method}`);
+                            }
+                        } else {
+                            console.log('Available Methods: None');
+                        }
+                        console.log('');
+                    } else if (result.error) {
+                        console.log(result.error);
+                    }
+                } else if (result && typeof result === 'object' && result.error) {
+                    // Handle error objects
+                    console.log(result.error);
+                } else if (result !== null && result !== undefined) {
+                    // Only show result if it's meaningful
+                    // (log commands already print, so we don't need to show null)
+                }
+            } catch (error) {
+                console.error(`Error: ${error.message}`);
+            }
+            
+            // Reset prompt after block execution
+            rl.setPrompt(getPrompt());
+        } else {
+            // Still in block mode, update prompt to show continuation
+            if (!rp.currentThread) {
+                rl.setPrompt(`... `);
+            } else {
+                const threadId = rp.currentThread.id;
+                const currentModule = rp.currentThread.getCurrentModule();
+                if (currentModule) {
+                    rl.setPrompt(`[${threadId}]@[${currentModule}]... `);
+                } else {
+                    rl.setPrompt(`[${threadId}]... `);
+                }
+            }
+        }
+        
+        return;
+    }
+    
+    // Check if this line ends with backslash - if so, enter continuation mode
+    if (endsWithBackslash(line)) {
+        accumulatedLines = [line];
+        if (!rp.currentThread) {
+            rl.setPrompt(`... `);
+        } else {
+            const threadId = rp.currentThread.id;
+            const currentModule = rp.currentThread.getCurrentModule();
+            if (currentModule) {
+                rl.setPrompt(`[${threadId}]@[${currentModule}]... `);
+            } else {
+                rl.setPrompt(`[${threadId}]... `);
+            }
+        }
+        return;
+    }
+    
+    // Check if this line starts an incomplete block using the built-in method
+    let needsMore;
+    if (rp.currentThread) {
+        needsMore = rp.currentThread.needsMoreInput(line);
+    } else {
+        needsMore = rp.needsMoreInput(line);
+    }
+    
+    if (needsMore.needsMore) {
+        // This line starts an incomplete block, enter block mode
+        accumulatedLines = [line];
+        if (!rp.currentThread) {
+            rl.setPrompt(`... `);
+        } else {
+            const threadId = rp.currentThread.id;
+            const currentModule = rp.currentThread.getCurrentModule();
+            if (currentModule) {
+                rl.setPrompt(`[${threadId}]@[${currentModule}]... `);
+            } else {
+                rl.setPrompt(`[${threadId}]... `);
+            }
+        }
+        return;
+    }
+    
+    // Regular single-line command - use executeLine for persistent state
+    try {
+        let result;
+        if (rp.currentThread) {
+            // Execute in current thread
+            result = await rp.currentThread.executeLine(line);
+        } else {
+            // Execute in global thread (root RobinPath instance)
+            result = await rp.executeLine(line);
+        }
+        
+        // Check if result is from explain command (structured object)
+        if (result && typeof result === 'object' && !Array.isArray(result) && result.type) {
+            if (result.type === 'function') {
+                // Format function documentation
+                console.log(`\nFunction: ${result.name}`);
+                console.log(`\nDescription: ${result.description}\n`);
+                
+                if (result.parameters && result.parameters.length > 0) {
+                    console.log('Parameters:');
+                    for (const param of result.parameters) {
+                        let paramLine = `  - ${param.name} (${param.dataType})`;
+                        if (param.required) {
+                            paramLine += ' [required]';
+                        }
+                        console.log(paramLine);
+                        console.log(`    ${param.description}`);
+                        if (param.formInputType) {
+                            console.log(`    Input type: ${param.formInputType}`);
+                        }
+                        if (param.defaultValue !== undefined) {
+                            console.log(`    Default: ${JSON.stringify(param.defaultValue)}`);
+                        }
+                    }
+                } else {
+                    console.log('Parameters: None');
+                }
+                
+                console.log(`\nReturns: ${result.returnType}`);
+                if (result.returnDescription) {
+                    console.log(`  ${result.returnDescription}`);
+                }
+                console.log('');
+            } else if (result.type === 'module') {
+                // Format module documentation
+                console.log(`\nModule: ${result.name}`);
+                console.log(`\nDescription: ${result.description}\n`);
+                
+                if (result.methods && result.methods.length > 0) {
+                    console.log('Available Methods:');
+                    for (const method of result.methods) {
+                        console.log(`  - ${method}`);
+                    }
+                } else {
+                    console.log('Available Methods: None');
+                }
+                console.log('');
+            } else if (result.error) {
+                console.log(result.error);
+            }
+        } else if (result && typeof result === 'object' && result.error) {
+            // Handle error objects
+            console.log(result.error);
+        }
+        
+        // Update prompt in case module context changed (e.g., "use" command)
+        rl.setPrompt(getPrompt());
+        // Don't print null/undefined results (log commands handle their own output)
+        if (result !== null && result !== undefined && result !== '' && 
+            (!result || typeof result !== 'object' || (!result.type && !result.error))) {
+            // Only print if it's a meaningful value and not a structured object
+            // Most commands use log for output, so we skip printing here
+        }
+    } catch (error) {
+        console.error(`Error: ${error.message}`);
+    }
+}
+
+// Start the REPL
+console.log('RobinPath REPL');
+console.log('Type "help" for commands, "exit" to quit');
+console.log('');
+
+rl.prompt();
+
+rl.on('line', async (line) => {
+    await processLine(line);
+    rl.prompt();
+});
+
+rl.on('close', () => {
+    console.log('\nGoodbye!');
+    process.exit(0);
+});
+
+// Handle Ctrl+C gracefully
+process.on('SIGINT', () => {
+    if (accumulatedLines.length > 0) {
+        console.log('\nBlock cancelled. Returning to normal mode.');
+        accumulatedLines = [];
+        rl.setPrompt(getPrompt());
+        rl.prompt();
+    } else {
+        console.log('\nGoodbye!');
+        rl.close();
+        process.exit(0);
+    }
+});
+

package/dist/classes/ASTSerializer.d.ts

@@ -0,0 +1,45 @@
+import { Environment } from '../types/Environment.type';
+import { Statement, Arg } from '../types/Ast.type';
+import { Value } from '../utils';
+export declare class ASTSerializer {
+    private environment;
+    constructor(environment: Environment);
+    /**
+     * Find the module name for a given function name
+     * Returns the module name if found, null otherwise
+     */
+    findModuleName(functionName: string, currentModuleContext?: string | null): string | null;
+    /**
+
+     * Get a simplified tree structure of the AST for navigation
+
+     */
+    getStructure(statements: Statement[], nodeKeyPrefix?: string): any[];
+    /**
+
+     * Generate a human-readable label for a statement
+
+     */
+    private getNodeLabel;
+    /**
+
+     * Serialize a statement to a JSON-serializable object
+
+     * @param stmt The statement to serialize
+
+     * @param currentModuleContext Optional module context from "use" command
+
+     * @param lastValue Optional last value (execution state) - can be a Value or a state object with lastValue and beforeValue
+
+     * @param nodeKey Optional key for the node
+
+     */
+    serializeStatement(stmt: Statement, currentModuleContext?: string | null, lastValue?: Value | {
+        lastValue: Value;
+        beforeValue: Value;
+    } | null, nodeKey?: string): any;
+    /**
+     * Serialize an argument to a JSON-serializable object
+     */
+    serializeArg(arg: Arg, currentModuleContext?: string | null, nodeKey?: string): any;
+}

package/dist/classes/ExecutionStateTracker.d.ts

@@ -0,0 +1,30 @@
+import { Value } from '../utils';
+export interface ExecutionStepInfo {
+    nodeKey: string;
+    variables: Record<string, Value>;
+    result: Value;
+    timestamp: number;
+}
+export interface ExecutionLog {
+    message: string;
+    nodeKey?: string;
+    timestamp: number;
+    source?: 'log' | 'say' | string;
+}
+export type LogCallback = (log: ExecutionLog) => void;
+export declare class ExecutionStateTracker {
+    private steps;
+    private logs;
+    private nodeStates;
+    private indexedStates;
+    private onLog;
+    setLogCallback(callback: LogCallback | null): void;
+    addStep(step: ExecutionStepInfo): void;
+    addLog(log: ExecutionLog): void;
+    getSteps(): ExecutionStepInfo[];
+    getLogs(): ExecutionLog[];
+    getNodeState(nodeKey: string): ExecutionStepInfo | undefined;
+    getState(index: number): any;
+    setState(index: number, state: any): void;
+    clear(): void;
+}

package/dist/classes/Executor.d.ts

@@ -0,0 +1,193 @@
+import { Value } from '../utils';
+import { Environment, Frame } from '../index';
+import { Statement, Arg, DefineFunction, OnBlock, DecoratorCall, Expression } from '../types/Ast.type';
+import { RobinPathThread } from './RobinPathThread';
+export declare class Executor {
+    private environment;
+    private callStack;
+    private parentThread;
+    private sourceCode;
+    private recursionDepth;
+    private currentStatement;
+    private static readonly MAX_RECURSION_DEPTH;
+    /**
+     * Debug mode flag - set to true to enable logging
+     * Can be controlled via VITE_DEBUG environment variable or set programmatically
+     */
+    static debug: boolean;
+    constructor(environment: Environment, parentThread?: RobinPathThread | null, sourceCode?: string | null);
+    getCurrentFrame(frameOverride?: Frame): Frame;
+    getCurrentStatement(): Statement | null;
+    getEnvironment(): Environment;
+    getCallStack(): Frame[];
+    /**
+     * Compute Levenshtein distance between two strings
+     */
+    private levenshteinDistance;
+    /**
+     * Find similar function names for "did you mean?" suggestions
+     */
+    private findSimilarFunctions;
+    /**
+     * Format "Unknown function" error with suggestions
+     */
+    private unknownFunctionError;
+    /**
+     * Creates a new Executor instance that shares the same environment and call stack,
+     * but has its own call stack array to allow parallel execution without stack corruption.
+     * The frames themselves (locals Maps) are shared.
+     */
+    spawnChild(): Executor;
+    /**
+     * Execute an event handler with the provided arguments
+     * Arguments are available as $1, $2, $3, etc. in the handler body
+     */
+    executeEventHandler(handler: OnBlock, args: Value[]): Promise<void>;
+    /**
+     * Execute a single statement (public method for state tracking)
+     */
+    executeStatementPublic(stmt: Statement): Promise<void>;
+    /**
+     * Execute a function call and return the result (public method for expression evaluation)
+     */
+    executeFunctionCall(funcName: string, args: Arg[]): Promise<Value>;
+    execute(statements: Statement[]): Promise<Value>;
+    private executeStatement;
+    /**
+     * Get all variables visible in the current frame
+     */
+    private getVariableStateInternal;
+    /**
+     * Reconstructs the original input string from an Arg object.
+     * This is useful for commands that need to preserve the original input
+     * (e.g., variable/function names) rather than evaluating them.
+     *
+     * Examples:
+     * - { type: 'var', name: 'a' } -> '$a'
+     * - { type: 'var', name: 'a', path: [{ type: 'property', name: 'b' }] } -> '$a.b'
+     * - { type: 'var', name: 'a', path: [{ type: 'index', index: 0 }] } -> '$a[0]'
+     * - { type: 'string', value: 'hello' } -> 'hello'
+     *
+     * @param arg The Arg object to reconstruct
+     * @returns The original input string, or null if the arg type cannot be reconstructed
+     */
+    private reconstructOriginalInput;
+    private executeCommand;
+    /**
+     * Execute decorators for a target (function or variable)
+     * @param decorators Array of decorator calls
+     * @param targetName Name of the target (function or variable)
+     * @param func Function object (null for variables)
+     * @param originalArgs Original arguments (for functions, empty array for variables)
+     * @returns Modified arguments (for functions) or original args unchanged
+     */
+    executeDecorators(decorators: DecoratorCall[], targetName: string, func: DefineFunction | null, originalArgs: Value[], frameOverride?: Frame): Promise<Value[]>;
+    private callFunction;
+    private executeAssignment;
+    private executeShorthandAssignment;
+    private executeInlineIf;
+    private executeIfBlock;
+    private executeIfTrue;
+    private executeIfFalse;
+    private executeReturn;
+    private executeBreak;
+    private executeContinue;
+    private registerFunction;
+    private registerEventHandler;
+    private executeScope;
+    private executeTogether;
+    /**
+     * Set a variable at a path in the parent scope (for together blocks)
+     */
+    private setVariableAtPathInParentScope;
+    private executeForLoop;
+    private evaluateArg;
+    /**
+     * Interpolate variables and subexpressions in object literal code
+     * Replaces $var, $(expr), $ (last value), and [$key] with their actual values
+     *
+     * TODO: AST Refactor - This method will be removed once ObjectLiteralExpression
+     * is used. Object literals will be evaluated by walking the properties AST nodes.
+     */
+    private interpolateObjectLiteral;
+    /**
+     * Execute a subexpression from code string with frame override support
+     *
+     * @param code - The subexpression code to execute
+     * @param frameOverride - Optional frame override for variable resolution
+     */
+    private executeSubexpressionWithFrame;
+    /**
+     * Execute a subexpression from code string
+     *
+     * TODO: AST Refactor - This will be replaced with executeSubexpressionStatements()
+     * which takes Statement[] directly, eliminating runtime parsing.
+     */
+    executeSubexpression(code: string): Promise<Value>;
+    /**
+     * Execute subexpression statements directly (for Expression-based AST)
+     *
+     * @param statements - Pre-parsed statements from SubexpressionExpression.body
+     * @param frameOverride - Optional frame override for parallel execution
+     * @returns The lastValue after executing the statements
+     */
+    executeSubexpressionStatements(statements: Statement[], frameOverride?: Frame): Promise<Value>;
+    /**
+     * Evaluate an Expression node
+     *
+     * @param expr - The Expression node to evaluate
+     * @param frameOverride - Optional frame override
+     * @returns The evaluated value
+     */
+    evaluateExpression(expr: Expression, frameOverride?: Frame): Promise<Value>;
+    /**
+     * Evaluate an ObjectLiteralExpression
+     *
+     * @param expr - The ObjectLiteralExpression node
+     * @param frameOverride - Optional frame override
+     * @returns The evaluated object
+     */
+    evaluateObjectLiteral(expr: import('../types/Ast.type').ObjectLiteralExpression, frameOverride?: Frame): Promise<Record<string, Value>>;
+    /**
+     * Evaluate an ArrayLiteralExpression
+     *
+     * @param expr - The ArrayLiteralExpression node
+     * @param frameOverride - Optional frame override
+     * @returns The evaluated array
+     */
+    evaluateArrayLiteral(expr: import('../types/Ast.type').ArrayLiteralExpression, frameOverride?: Frame): Promise<Value[]>;
+    /**
+     * Evaluate a BinaryExpression
+     *
+     * @param expr - The BinaryExpression node
+     * @param frameOverride - Optional frame override
+     * @returns The evaluated value
+     */
+    evaluateBinaryExpression(expr: import('../types/Ast.type').BinaryExpression, frameOverride?: Frame): Promise<Value>;
+    /**
+     * Evaluate a UnaryExpression
+     *
+     * @param expr - The UnaryExpression node
+     * @param frameOverride - Optional frame override
+     * @returns The evaluated value
+     */
+    evaluateUnaryExpression(expr: import('../types/Ast.type').UnaryExpression, frameOverride?: Frame): Promise<Value>;
+    /**
+     * Evaluate a CallExpression
+     *
+     * @param expr - The CallExpression node
+     * @param frameOverride - Optional frame override
+     * @returns The evaluated value
+     */
+    evaluateCallExpression(expr: import('../types/Ast.type').CallExpression, frameOverride?: Frame): Promise<Value>;
+    private resolveVariable;
+    private setVariable;
+    /**
+     * Set a value at an attribute path (e.g., $animal.cat = 5 or $.property = value)
+     */
+    private setVariableAtPath;
+    /**
+     * Resolve a dynamic key segment to its actual key value
+     */
+    private resolveDynamicKey;
+}

package/dist/classes/ExpressionEvaluator.d.ts

@@ -0,0 +1,20 @@
+import { Frame, Environment } from '../index';
+import { Executor } from './Executor';
+export declare class ExpressionEvaluator {
+    private frame;
+    private globals;
+    private executor;
+    constructor(frame: Frame, globals: Environment, executor?: Executor | null);
+    evaluate(expr: string): Promise<boolean>;
+    /**
+     * Replace all subexpressions $(...) in an expression string with their evaluated values
+     */
+    private replaceSubexpressions;
+    /**
+     * Extract a subexpression $(...) from a string, starting at the given position
+     * Returns null if no valid subexpression is found
+     */
+    private extractSubexpressionFromString;
+    private executeFunctionCall;
+    private resolveVariable;
+}