littlewing 0.5.3 → 0.6.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 declare namespace exports_ast {
-	export { unaryOp, subtract, number, nullishAssign, notEquals, negate, multiply, modulo, logicalOr, logicalAnd, lessThan, lessEqual, identifier, greaterThan, greaterEqual, functionCall, exponentiate, equals, divide, conditional, binaryOp, assign, add };
+	export { unaryOp, subtract, program, number, notEquals, negate, multiply, modulo, logicalOr, logicalAnd, lessThan, lessEqual, identifier, greaterThan, greaterEqual, functionCall, exponentiate, equals, divide, conditional, binaryOp, assign, add };
 }
 /**
 * Runtime value type - only numbers
@@ -44,7 +44,6 @@ declare enum TokenType {
 	COMMA = "COMMA",
 	QUESTION = "QUESTION",
 	COLON = "COLON",
-	NULLISH_ASSIGN = "NULLISH_ASSIGN",
 	EOF = "EOF"
 }
 /**
@@ -58,7 +57,7 @@ interface Token {
 /**
 * AST Node - base type
 */
-type ASTNode = Program | NumberLiteral | Identifier | BinaryOp | UnaryOp | FunctionCall | Assignment | ConditionalExpression | NullishAssignment;
+type ASTNode = Program | NumberLiteral | Identifier | BinaryOp | UnaryOp | FunctionCall | Assignment | ConditionalExpression;
 /**
 * Program node (multiple statements)
 */
@@ -124,16 +123,6 @@ interface ConditionalExpression {
 	alternate: ASTNode;
 }
 /**
-* Nullish assignment (x ??= 5)
-* Assigns value only if variable is undefined (not provided in context)
-* Used for providing defaults for external variables
-*/
-interface NullishAssignment {
-	type: "NullishAssignment";
-	name: string;
-	value: ASTNode;
-}
-/**
 * Type guard functions for discriminated union narrowing
 */
 declare function isNumberLiteral(node: ASTNode): node is NumberLiteral;
@@ -144,11 +133,14 @@ declare function isFunctionCall(node: ASTNode): node is FunctionCall;
 declare function isAssignment(node: ASTNode): node is Assignment;
 declare function isProgram(node: ASTNode): node is Program;
 declare function isConditionalExpression(node: ASTNode): node is ConditionalExpression;
-declare function isNullishAssignment(node: ASTNode): node is NullishAssignment;
 /**
 * Builder functions for creating AST nodes manually
 */
 /**
+* Create a program node
+*/
+declare function program(statements: ASTNode[]): Program;
+/**
 * Create a number literal node
 */
 declare function number(value: number): NumberLiteral;
@@ -173,11 +165,6 @@ declare function functionCall(name: string, args?: ASTNode[]): FunctionCall;
 */
 declare function assign(name: string, value: ASTNode): Assignment;
 /**
-* Create a nullish assignment node (x ??= 5)
-* Assigns only if variable is undefined
-*/
-declare function nullishAssign(name: string, value: ASTNode): NullishAssignment;
-/**
 * Create a conditional expression node (ternary operator)
 */
 declare function conditional(condition: ASTNode, consequent: ASTNode, alternate: ASTNode): ConditionalExpression;
@@ -287,10 +274,6 @@ declare class CodeGenerator {
 	*/
 	private generateAssignment;
 	/**
-	* Generate code for a nullish assignment
-	*/
-	private generateNullishAssignment;
-	/**
 	* Generate code for a conditional expression (ternary operator)
 	*/
 	private generateConditionalExpression;
@@ -337,10 +320,12 @@ declare function generate(node: ASTNode): string;
 declare const defaultContext: ExecutionContext;
 /**
 * Executor - evaluates an AST with given context
+* Uses a tree-walk interpreter with O(n) execution time where n is the number of AST nodes
 */
 declare class Executor {
 	private context;
 	private variables;
+	private externalVariables;
 	constructor(context?: ExecutionContext);
 	/**
 	* Execute an AST node and return the result
@@ -372,15 +357,11 @@ declare class Executor {
 	private executeFunctionCall;
 	/**
 	* Execute a variable assignment
+	* External variables (from context) take precedence over script assignments
+	* This allows scripts to define defaults that can be overridden at runtime
 	*/
 	private executeAssignment;
 	/**
-	* Execute a nullish assignment (??=)
-	* Only assigns if the variable is undefined (not in variables map)
-	* Returns the existing value if defined, otherwise evaluates and assigns the value
-	*/
-	private executeNullishAssignment;
-	/**
 	* Execute a conditional expression (ternary operator)
 	* Returns consequent if condition !== 0, otherwise returns alternate
 	*/
@@ -392,10 +373,12 @@ declare class Executor {
 declare function execute(source: string, context?: ExecutionContext): RuntimeValue;
 /**
 * Lexer - converts source code into tokens
+* Implements a single-pass O(n) tokenization algorithm
 */
 declare class Lexer {
 	private source;
 	private position;
+	private length;
 	constructor(source: string);
 	/**
 	* Tokenize the entire source and return all tokens
@@ -419,23 +402,11 @@ declare class Lexer {
 	*/
 	private readIdentifier;
 	/**
-	* Get character at position
-	*/
-	private getCharAt;
-	/**
-	* Peek at the next character without consuming it
-	*/
-	private peek;
-	/**
-	* Peek ahead n positions without consuming
-	*/
-	private peekAhead;
-	/**
-	* Check if character is a digit
+	* Check if character is a digit (0-9)
 	*/
 	private isDigit;
 	/**
-	* Check if character is a letter
+	* Check if character is a letter (a-z, A-Z)
 	*/
 	private isLetter;
 	/**
@@ -444,25 +415,25 @@ declare class Lexer {
 	private isWhitespace;
 }
 /**
-* Optimize an AST using a theoretically optimal O(n) algorithm.
+* Optimize an AST using constant folding and expression simplification.
 *
-* This optimizer implements a single-pass data-flow analysis algorithm that:
-* 1. Builds a dependency graph of all variables and expressions
-* 2. Performs constant propagation via forward data-flow analysis
-* 3. Eliminates dead code via backward reachability analysis
-* 4. Evaluates expressions in a single topological pass
+* This optimizer performs LOCAL, SAFE optimizations that preserve program semantics:
+* - Constant folding: Evaluates arithmetic with literal operands at compile-time
+* - Function argument pre-evaluation: Simplifies expressions passed to functions
+* - Conditional folding: Evaluates ternary with constant condition
+*
+* Optimizations that are NOT performed (because they're unsafe with context variables):
+* - Variable propagation: Variables can be overridden by ExecutionContext
+* - Dead code elimination: Cannot determine if variables are "dead" without knowing context
+* - Cross-statement analysis: Each statement may affect external state
 *
 * Time complexity: O(n) where n is the number of AST nodes
-* Space complexity: O(n) for the dependency graph
+* Space complexity: O(d) where d is the max depth (recursion stack)
 *
 * Algorithm properties:
 * - Sound: Preserves program semantics exactly
-* - Complete: Finds all optimization opportunities
-* - Optimal: No redundant traversals or recomputation
-*
-* Based on classical compiler optimization theory:
-* - Cytron et al. "Efficiently Computing Static Single Assignment Form" (1991)
-* - Wegman & Zadeck "Constant Propagation with Conditional Branches" (1991)
+* - Safe: No assumptions about variable values or liveness
+* - Local: Only optimizes within individual expressions
 *
 * @param node - The AST node to optimize
 * @returns Optimized AST node
@@ -470,6 +441,7 @@ declare class Lexer {
 declare function optimize(node: ASTNode): ASTNode;
 /**
 * Parser using Pratt parsing (top-down operator precedence)
+* Implements an efficient O(n) parsing algorithm
 */
 declare class Parser {
 	private tokens;
@@ -477,11 +449,12 @@ declare class Parser {
 	constructor(tokens: Token[]);
 	/**
 	* Parse tokens into an AST
-	* Supports multiple statements separated by semicolons
+	* Supports multiple statements separated by semicolons or newlines
 	*/
 	parse(): ASTNode;
 	/**
 	* Parse an expression with Pratt parsing (precedence climbing)
+	* This is the core of the parser - handles infix operators with proper precedence
 	*/
 	private parseExpression;
 	/**
@@ -496,15 +469,15 @@ declare class Parser {
 	* Get unary operator precedence
 	* Returns 6 which is higher than add/sub (6) but lower than exponentiation (8)
 	* This means: -2^2 parses as -(2^2) = -4, not (-2)^2 = 4
-	* This matches the behavior of Python, Ruby, and most languages
+	* Matches the behavior of Python, Ruby, and most languages
 	*/
 	private getUnaryPrecedence;
 	/**
-	* Check if token is a binary operator
+	* Check if token is a binary operator (O(1) Set lookup)
 	*/
 	private isBinaryOperator;
 	/**
-	* Get current token
+	* Get current token without advancing
 	*/
 	private peek;
 	/**
@@ -514,9 +487,10 @@ declare class Parser {
 }
 /**
 * Parse source code string into AST
+* Convenience function that creates lexer and parser
 *
 * @param source - The source code to parse
 * @returns Parsed AST
 */
 declare function parseSource(source: string): ASTNode;
-export { parseSource, optimize, isUnaryOp, isProgram, isNumberLiteral, isNullishAssignment, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, generate, execute, defaultContext, exports_ast as ast, TokenType, Token, RuntimeValue, Parser, Lexer, Executor, ExecutionContext, CodeGenerator, ASTNode };
+export { parseSource, optimize, isUnaryOp, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, generate, execute, defaultContext, exports_ast as ast, TokenType, Token, RuntimeValue, Parser, Lexer, Executor, ExecutionContext, CodeGenerator, ASTNode };