@robinpath/robinpath 0.30.0

package/dist/classes/Lexer.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Lexer class for tokenizing RobinPath code
+ */
+/**
+ * Token kinds for RobinPath language
+ * Using const object instead of enum for better compatibility
+ */
+export declare const TokenKind: {
+    readonly STRING: "STRING";
+    readonly NUMBER: "NUMBER";
+    readonly BOOLEAN: "BOOLEAN";
+    readonly NULL: "NULL";
+    readonly IDENTIFIER: "IDENTIFIER";
+    readonly VARIABLE: "VARIABLE";
+    readonly KEYWORD: "KEYWORD";
+    readonly ASSIGN: "ASSIGN";
+    readonly PLUS: "PLUS";
+    readonly MINUS: "MINUS";
+    readonly MULTIPLY: "MULTIPLY";
+    readonly DIVIDE: "DIVIDE";
+    readonly MODULO: "MODULO";
+    readonly EQ: "EQ";
+    readonly NE: "NE";
+    readonly GT: "GT";
+    readonly LT: "LT";
+    readonly GTE: "GTE";
+    readonly LTE: "LTE";
+    readonly AND: "AND";
+    readonly OR: "OR";
+    readonly NOT: "NOT";
+    readonly LPAREN: "LPAREN";
+    readonly RPAREN: "RPAREN";
+    readonly LBRACKET: "LBRACKET";
+    readonly RBRACKET: "RBRACKET";
+    readonly LBRACE: "LBRACE";
+    readonly RBRACE: "RBRACE";
+    readonly COMMA: "COMMA";
+    readonly COLON: "COLON";
+    readonly DOT: "DOT";
+    readonly DECORATOR: "DECORATOR";
+    readonly COMMENT: "COMMENT";
+    readonly NEWLINE: "NEWLINE";
+    readonly EOF: "EOF";
+    readonly SUBEXPRESSION_OPEN: "SUBEXPRESSION_OPEN";
+};
+export type TokenKind = typeof TokenKind[keyof typeof TokenKind];
+/**
+ * List of RobinPath keywords
+ */
+export declare const KEYWORDS: Set<string>;
+/**
+ * A single token in the source code
+ */
+export interface Token {
+    kind: TokenKind;
+    text: string;
+    line: number;
+    column: number;
+    value?: any;
+    isContinuation?: boolean;
+}
+/**
+ * Position information for error reporting
+ */
+export interface SourcePosition {
+    line: number;
+    column: number;
+}
+export declare class Lexer {
+    /**
+     * Tokenize entire source code into Token objects
+     * This is the new token-stream based approach
+     *
+     * @param source - Full source code (multi-line)
+     * @returns Array of tokens with position information
+     */
+    static tokenizeFull(source: string): Token[];
+    /**
+     * Legacy tokenize method - kept for backward compatibility
+     * Tokenizes a single line into string tokens
+     *
+     * @param line - A single line of code
+     * @returns Array of string tokens
+     */
+    static tokenize(line: string): string[];
+}

package/dist/classes/Parser.d.ts

@@ -0,0 +1,71 @@
+import { Statement, CodePosition, DefineFunction, OnBlock } from '../types/Ast.type';
+import { Environment } from '../index';
+export interface ExtractedVariable {
+    name: string;
+    description?: string;
+    initialValue?: any;
+    codePos: CodePosition;
+}
+export declare class Parser {
+    private tokens;
+    private stream;
+    private source;
+    private extractedFunctions;
+    private extractedEventHandlers;
+    private extractedVariables;
+    private environment;
+    private decoratorBuffer;
+    private pendingComments;
+    /**
+     * Maximum number of iterations allowed before detecting an infinite loop
+     */
+    static readonly MAX_STUCK_ITERATIONS = 100;
+    /**
+     * Debug mode flag - set to true to enable logging
+     * Can be controlled via VITE_DEBUG environment variable or set programmatically
+     */
+    static debug: boolean;
+    /**
+     * Create a new Parser
+     * @param source - Full source code as a single string
+     * @param environment - Optional environment for executing parse decorators
+     */
+    constructor(source: string, environment?: Environment | null);
+    /**
+     * Parse the source code into an AST
+     * @returns Array of statements
+     */
+    parse(): Promise<Statement[]>;
+    /**
+     * Parse a statement from a stream with hierarchical nodeKey support
+     */
+    private parseStatementFromStream;
+    /**
+     * Get extracted function definitions (def/enddef blocks)
+     */
+    getExtractedFunctions(): DefineFunction[];
+    /**
+     * Get extracted event handlers (on/endon blocks)
+     */
+    getExtractedEventHandlers(): OnBlock[];
+    /**
+     * Get extracted variables (from assignments)
+     */
+    getExtractedVariables(): ExtractedVariable[];
+    /**
+     * Track a variable from an assignment statement
+     */
+    private trackVariable;
+    /**
+     * Parse a single statement
+     */
+    private parseStatement;
+    private parseCommentFromStream;
+    private attachInlineComments;
+    private countTrailingBlankLines;
+    /**
+     * Recursively assign nodeKeys to body statements
+     * This ensures all nested statements have hierarchical nodeKeys for execution tracking
+     */
+    private assignBodyNodeKeys;
+}

package/dist/classes/RobinPathThread.d.ts

@@ -0,0 +1,146 @@
+import { Value } from '../utils';
+import { Environment, OnBlock, RobinPath } from '../index';
+export declare class RobinPathThread {
+    private environment;
+    private executor;
+    readonly id: string;
+    private parent;
+    private serializer;
+    constructor(baseEnvironment: Environment, id: string, parent?: RobinPath);
+    /**
+     * Check if a script needs more input (incomplete block)
+     * Returns { needsMore: true, waitingFor: 'endif' | 'enddef' | 'endfor' | 'enddo' | 'subexpr' | 'paren' | 'object' | 'array' } if incomplete,
+     * or { needsMore: false } if complete.
+     */
+    needsMoreInput(script: string): Promise<{
+        needsMore: boolean;
+        waitingFor?: 'endif' | 'enddef' | 'endfor' | 'enddo' | 'subexpr' | 'paren' | 'object' | 'array';
+    }>;
+    /**
+     * Execute a RobinPath script in this thread
+     */
+    executeScript(script: string): Promise<Value>;
+    /**
+     * Execute a single line in this thread (for REPL)
+     */
+    executeLine(line: string): Promise<Value>;
+    /**
+     * Get the last value ($) from this thread
+     */
+    getLastValue(): Value;
+    /**
+     * Get a variable value from this thread
+     */
+    getVariable(name: string): Value;
+    /**
+     * Set a variable value in this thread
+     */
+    setVariable(name: string, value: Value): void;
+    /**
+     * Get all variables in this thread as a plain object
+     */
+    getVariableState(): Record<string, Value>;
+    /**
+     * Get the current module name (set by "use" command)
+     * Returns null if no module is currently in use
+     */
+    getCurrentModule(): string | null;
+    /**
+     * Get the parent RobinPath instance
+     */
+    getParent(): RobinPath | null;
+    /**
+     * Get the environment for this thread (for CLI access to metadata)
+     */
+    getEnvironment(): Environment;
+    /**
+     * Get the AST without execution state
+     * Returns a JSON-serializable AST array
+     *
+     * Note: This method only parses the script, it does not execute it.
+     */
+    getAST(script: string): Promise<any[]>;
+    /**
+     * Get extracted function definitions (def/enddef blocks) from a script
+     * Returns a JSON-serializable array of function definitions
+     *
+     * Note: This method only parses the script, it does not execute it.
+     */
+    getExtractedFunctions(script: string): Promise<any[]>;
+    /**
+     * Get all event handlers as a flat array
+     * @returns Array of all OnBlock handlers
+     */
+    getAllEventHandlers(): OnBlock[];
+    /**
+     * Get event handlers as serialized AST
+     * @returns Array of serialized event handler AST nodes
+     */
+    getEventAST(): any[];
+    /**
+     * Get the AST with execution state for the current thread
+     * Returns a JSON-serializable object with:
+     * - AST nodes with execution state ($ lastValue at each node)
+     * - Available variables (thread-local and global)
+     * - Organized for UI representation
+     *
+     * Note: This method executes the script to capture execution state at each node.
+     */
+    getASTWithState(script: string): Promise<{
+        ast: any[];
+        variables: {
+            thread: Record<string, Value>;
+            global: Record<string, Value>;
+        };
+        lastValue: Value;
+        callStack: Array<{
+            locals: Record<string, Value>;
+            lastValue: Value;
+        }>;
+    }>;
+    /**
+     * Execute statements with state tracking
+     */
+    private executeWithStateTracking;
+    /**
+     * Get all available commands, modules, and functions for this thread
+     * Includes thread-local user-defined functions in addition to shared builtins and modules
+     *
+     * @param context Optional syntax context to filter commands based on what's valid next
+     */
+    getAvailableCommands(context?: {
+        inIfBlock?: boolean;
+        inDefBlock?: boolean;
+        afterIf?: boolean;
+        afterDef?: boolean;
+        afterElseif?: boolean;
+    }): {
+        native: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+        builtin: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+        modules: Array<{
+            name: string;
+            type: string;
+            description: string;
+            author?: string;
+            category?: string;
+        }>;
+        moduleFunctions: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+        userFunctions: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+    };
+}

package/dist/classes/TokenStream.d.ts

@@ -0,0 +1,217 @@
+import { TokenKind, Token } from './Lexer';
+/**
+ * Parsing context types that the TokenStream can track
+ */
+export declare const ParsingContext: {
+    readonly NONE: "none";
+    readonly ARRAY_LITERAL: "array_literal";
+    readonly OBJECT_LITERAL: "object_literal";
+    readonly FUNCTION_CALL: "function_call";
+    readonly SUBEXPRESSION: "subexpression";
+    readonly BLOCK: "block";
+    readonly FUNCTION_DEFINITION: "function_definition";
+    readonly STRING_LITERAL: "string_literal";
+};
+export type ParsingContext = typeof ParsingContext[keyof typeof ParsingContext];
+export declare class TokenStream {
+    private tokens;
+    private position;
+    private contextStack;
+    private lastNextPosition;
+    private consecutiveNextCalls;
+    private positionHistory;
+    private operationsSinceLastAdvance;
+    private lastPositionValue;
+    /**
+     * Maximum number of consecutive next() calls allowed at the same position before throwing
+     */
+    static readonly MAX_CONSECUTIVE_NEXT_AT_SAME_POSITION = 3;
+    /**
+     * Maximum number of operations without position advancement before detecting stuck
+     * Only counts operations that should advance (next, match, expect, etc.)
+     */
+    static readonly MAX_OPERATIONS_WITHOUT_ADVANCE = 100;
+    /**
+     * Debug mode flag - set to true to enable logging
+     * Can be controlled via VITE_DEBUG environment variable or set programmatically
+     * Usage: TokenStream.debug = true;
+     */
+    static debug: boolean;
+    /**
+     * Create a new TokenStream
+     * @param tokens - Array of tokens to stream
+     * @param startIndex - Optional starting index (default 0)
+     */
+    constructor(tokens: Token[], startIndex?: number);
+    /**
+     * Create a new TokenStream starting from the given index
+     * Useful for sub-parsing operations that need to start from a specific position
+     * @param index - Starting index in the token array
+     * @returns New TokenStream instance starting at the given index
+     */
+    cloneFrom(index: number): TokenStream;
+    /**
+     * Reset stuck detection counters (useful when manually advancing position)
+     */
+    resetStuckDetection(): void;
+    /**
+     * Set the current position directly
+     * @param position - New position
+     */
+    setPosition(position: number): void;
+    /**
+     * Get the current token without consuming it
+     * @returns The current token, or null if at end
+     */
+    current(): Token | null;
+    /**
+     * Look ahead at a token without consuming it
+     * @param offset - Number of tokens to look ahead (default 0 = current token)
+     * @returns The token at the given offset, or null if beyond end
+     */
+    peek(offset?: number): Token | null;
+    /**
+     * Consume and return the current token
+     * @returns The current token, or null if at end
+     * @throws Error if called multiple times at the same position (indicates infinite loop)
+     */
+    next(): Token | null;
+    /**
+     * Check if the stream appears to be stuck (no position advancement)
+     * @param operation - Name of the operation being performed
+     * @throws Error if stuck condition detected
+     */
+    private checkStuckCondition;
+    /**
+     * Check if we're at the end of the token stream
+     * @returns True if at EOF or beyond
+     */
+    isAtEnd(): boolean;
+    /**
+     * Check if the current token matches the given kind or text, without consuming it
+     * @param kindOrText - TokenKind enum or string text to match
+     * @returns True if the current token matches
+     */
+    check(kindOrText: TokenKind | string): boolean;
+    /**
+     * If the current token matches, consume it and return true
+     * Otherwise, return false without consuming
+     *
+     * @param kindOrText - TokenKind enum or string text to match
+     * @returns True if matched and consumed, false otherwise
+     */
+    match(kindOrText: TokenKind | string): boolean;
+    /**
+     * Expect the current token to match, consume it, and return it
+     * If it doesn't match, throw an error
+     *
+     * @param kindOrText - TokenKind enum or string text to expect
+     * @param message - Optional custom error message
+     * @returns The consumed token
+     * @throws Error if token doesn't match
+     */
+    expect(kindOrText: TokenKind | string, message?: string): Token;
+    /**
+     * Save the current position for potential backtracking
+     * @returns The current position index
+     */
+    save(): number;
+    /**
+     * Restore a previously saved position (backtrack)
+     * @param pos - The position to restore to
+     */
+    restore(pos: number): void;
+    /**
+     * Skip tokens of a specific kind (useful for skipping newlines, comments, etc.)
+     * @param kind - The TokenKind to skip
+     * @returns Number of tokens skipped
+     */
+    skip(kind: TokenKind): number;
+    /**
+     * Skip all newline tokens
+     * @returns Number of newlines skipped
+     */
+    skipNewlines(): number;
+    /**
+     * Consume tokens until a specific kind or text is found (exclusive)
+     * @param kindOrText - The kind or text to stop at
+     * @returns Array of consumed tokens (not including the stop token)
+     */
+    consumeUntil(kindOrText: TokenKind | string): Token[];
+    /**
+     * Collect all tokens on the current line (until NEWLINE or EOF)
+     * @returns Array of tokens on the current line
+     */
+    collectLine(): Token[];
+    /**
+     * Get the current position in the stream
+     * @returns Current position index
+     */
+    getPosition(): number;
+    /**
+     * Get the total number of tokens in the stream
+     * @returns Total token count
+     */
+    getLength(): number;
+    /**
+     * Get all remaining tokens without consuming them
+     * @returns Array of remaining tokens
+     */
+    remaining(): Token[];
+    /**
+     * Create a sub-stream from a range of tokens
+     * Useful for parsing sub-expressions or blocks
+     *
+     * @param start - Start position (inclusive)
+     * @param end - End position (exclusive), defaults to current position
+     * @returns New TokenStream instance
+     */
+    slice(start: number, end?: number): TokenStream;
+    /**
+     * Format current position for error messages
+     * @returns String like "line 10, column 5"
+     */
+    formatPosition(): string;
+    /**
+     * Push a parsing context onto the context stack
+     * @param context - The parsing context to enter
+     */
+    pushContext(context: ParsingContext): void;
+    /**
+     * Pop the most recent parsing context from the stack
+     * @returns The context that was removed, or NONE if stack was empty
+     */
+    popContext(): ParsingContext;
+    /**
+     * Get the current parsing context (top of the stack)
+     * @returns The current parsing context, or NONE if no context is active
+     */
+    getCurrentContext(): ParsingContext;
+    /**
+     * Check if we're currently in a specific parsing context
+     * @param context - The context to check for
+     * @returns True if we're in the given context (at any level)
+     */
+    isInContext(context: ParsingContext): boolean;
+    /**
+     * Get all active contexts (the entire stack)
+     * @returns Array of contexts from bottom to top
+     */
+    getContextStack(): ParsingContext[];
+    /**
+     * Clear all parsing contexts
+     */
+    clearContexts(): void;
+    /**
+     * Create a new TokenStream with the same tokens and contexts
+     * Useful for sub-parsing that should inherit context
+     * @param startIndex - Optional starting index (defaults to current position)
+     * @returns New TokenStream instance with copied context
+     */
+    cloneWithContext(startIndex?: number): TokenStream;
+    /**
+     * Skip whitespace (newlines) and comments
+     * Advances the stream past any consecutive newline or comment tokens
+     */
+    skipWhitespaceAndComments(): void;
+}

package/dist/classes/code-converter/ASTToCodeConverter.d.ts

@@ -0,0 +1,178 @@
+import { Statement, CommentWithPosition } from '../../types/Ast.type';
+import { Writer } from './Writer';
+import { LineIndex } from './LineIndex';
+import { Patch, CommentLayout, PrintContext } from './types';
+export type { CommentWithPosition, LineIndex, PrintContext };
+export { Writer };
+/**
+ * CommentLayout - Normalize comment ownership
+ *
+ * Decides, per statement:
+ * - leadingComments: Comment[] (non-inline)
+ * - inlineComment: Comment | null
+ * - leadingGapLines: number (blank lines between last leading comment and statement)
+ * - trailingBlankLinesAfterStandaloneComment: number (only for standalone comment nodes)
+ */
+export declare class CommentLayoutNormalizer {
+    /**
+     * Normalize comment layout for a statement
+     */
+    static normalize(node: Statement, lineIndex: LineIndex): CommentLayout;
+}
+/**
+ * PatchApplier - Apply patches to source code
+ *
+ * Sort patches descending (as you do now) and apply.
+ * Optional: validate overlaps and throw in dev mode.
+ */
+export declare class PatchApplier {
+    /**
+     * Apply patches to source code
+     * Patches are sorted descending by startOffset and applied from end to start
+     * to prevent character position shifts from affecting subsequent replacements
+     */
+    static apply(originalScript: string, patches: Patch[]): string;
+    /**
+     * Validate that patches don't overlap
+     * @internal This method is kept for potential future use or manual invocation
+     */
+    static validatePatches(patches: Patch[]): void;
+}
+/**
+ * PatchPlanner - Collect edit operations
+ *
+ * Produces Patch[] = { startOffset, endOffset, replacement }.
+ * Responsible for "range selection" (including blank lines, inline comment removal, etc.)
+ * Must guarantee patches don't overlap (or resolve overlaps deterministically).
+ */
+export declare class PatchPlanner {
+    private lineIndex;
+    private patches;
+    private originalScript;
+    private originalAST;
+    /**
+     * Enable defensive validation of extracted code.
+     * When true, extracted code is validated before use and falls back to regeneration if invalid.
+     * Set via ROBINPATH_DEBUG environment variable or constructor option.
+     */
+    private debugMode;
+    constructor(originalScript: string, options?: {
+        debugMode?: boolean;
+    });
+    /**
+     * Plan patches for all nodes in the AST
+     * This includes patches for:
+     * - Updated nodes (in modified AST)
+     * - New nodes (in modified AST but not in original)
+     * - Deleted nodes (in original AST but not in modified)
+     */
+    planPatches(ast: Statement[]): Promise<Patch[]>;
+    /**
+     * Plan a patch for a deleted node
+     */
+    private planPatchForDeletedNode;
+    /**
+     * Plan a patch for a single node
+     */
+    private planPatchForNode;
+    /**
+     * Plan a patch for a new node (insertion)
+     */
+    private planPatchForNewNode;
+    /**
+     * Plan patch for leading comments (non-overlapping case)
+     */
+    private planPatchForLeadingComments;
+    /**
+     * Generate replacement without leading comments (for non-overlapping case)
+     */
+    private generateReplacementWithoutLeadingComments;
+    /**
+     * Plan patch for a standalone comment node
+     */
+    private planPatchForCommentNode;
+    /**
+     * Find the stop row for comment blank line inclusion
+     */
+    private findStopRowForComment;
+    /**
+     * Plan patch to remove existing comments
+     */
+    private planPatchToRemoveComments;
+    /**
+     * Compute the range for a statement region
+     */
+    private computeStatementRange;
+    /**
+     * Generate replacement text for a node
+     */
+    private generateReplacement;
+    /**
+     * Preserve blank lines that were included in the range after the statement
+     */
+    private preserveBlankLinesInRange;
+    /**
+     * Extract original code from the script if the node hasn't changed
+     * Returns null if the node has changed and needs regeneration
+     *
+     * This preserves all original formatting including:
+     * - Indentation (spaces and tabs)
+     * - Spacing within statements
+     * - Blank lines
+     */
+    private extractOriginalCode;
+    /**
+     * Validate extracted code by checking if it parses correctly and matches expected type.
+     * Used in debug mode to detect extraction corruption.
+     */
+    private validateExtractedCode;
+    /**
+     * Find the original node that corresponds to the modified node
+     */
+    private findOriginalNode;
+    /**
+     * Compare two nodes to see if they're equal (ignoring codePos and metadata)
+     */
+    private nodesAreEqual;
+    /**
+     * Generate code with preserved indentation and spacing from original
+     * This is used when we must regenerate code but want to preserve formatting
+     */
+    private generateCodeWithPreservedIndentation;
+}
+/**
+ * ASTToCodeConverter - Converts AST nodes back to source code
+ *
+ * This class handles the conversion of AST (Abstract Syntax Tree) nodes
+ * back into RobinPath source code strings. It provides methods for:
+ * - Updating source code based on AST changes
+ * - Reconstructing code from individual AST nodes
+ * - Handling comments, indentation, and code positioning
+ */
+export declare class ASTToCodeConverter {
+    /**
+     * Validate that AST node positions are within bounds of the source code.
+     * This helps detect stale AST data from external source modifications.
+     *
+     * @param source The current source code
+     * @param ast The AST to validate
+     * @returns Object with isValid flag and optional error details
+     */
+    private validateASTPositions;
+    /**
+     * Update source code based on AST changes
+     * Uses precise character-level positions (codePos.startRow/startCol/endRow/endCol) to update code
+     * Nested nodes are reconstructed as part of their parent's code
+     * @param originalScript The original source code
+     * @param ast The modified AST array (top-level nodes only)
+     * @returns Updated source code
+     */
+    updateCodeFromAST(originalScript: string, ast: Statement[]): Promise<string>;
+    /**
+     * Reconstruct code string from an AST node
+     * @param node The AST node (serialized)
+     * @param indentLevel Indentation level for nested code
+     * @returns Reconstructed code string, or null if cannot be reconstructed
+     */
+    reconstructCodeFromASTNode(node: Statement, indentLevel?: number): string | null;
+}