stone-lang 0.1.0

package/frontend/parsing/stoneAstTypes.js

@@ -0,0 +1,703 @@
+/**
+ * Stone Language AST Node Type Definitions
+ *
+ * These represent the structure of Stone programs as abstract syntax trees.
+ * Each node type corresponds to a Stone language construct.
+ */
+
+/**
+ * Base class for all AST nodes
+ */
+export class ASTNode {
+  constructor(type, location) {
+    this.type = type;
+    this.location = location; // { line, column, file }
+  }
+}
+
+// ============================================================================
+// LITERALS & IDENTIFIERS
+// ============================================================================
+
+/**
+ * Literal values: numbers, strings, booleans, complex numbers
+ * @example 42, 3.14, "hello", true, false, none, 2+3i
+ */
+export class Literal extends ASTNode {
+  constructor(value, literalType, location) {
+    super("Literal", location);
+    this.value = value;
+    this.literalType = literalType; // 'number' | 'complex' | 'string' | 'bool' | 'none'
+  }
+}
+
+/**
+ * Variable/identifier reference
+ * @example x, user_name, count
+ */
+export class Identifier extends ASTNode {
+  constructor(name, location) {
+    super("Identifier", location);
+    this.name = name;
+  }
+}
+
+// ============================================================================
+// EXPRESSIONS
+// ============================================================================
+
+/**
+ * Binary operations: +, -, *, /, <, >, ==, &&, ||, etc.
+ * @example a + b, x < 5, count == 0, a && b
+ */
+export class BinaryOp extends ASTNode {
+  constructor(operator, left, right, location) {
+    super("BinaryOp", location);
+    this.operator = operator;
+    this.left = left;
+    this.right = right;
+  }
+}
+
+/**
+ * Unary operations: -, !, not
+ * @example -x, !flag
+ */
+export class UnaryOp extends ASTNode {
+  constructor(operator, operand, location) {
+    super("UnaryOp", location);
+    this.operator = operator;
+    this.operand = operand;
+  }
+}
+
+/**
+ * Function call expression
+ * @example add(5, 3), process(user, options), Math.sqrt(4)
+ */
+export class FunctionCall extends ASTNode {
+  constructor(funcName, args, location, callee = null) {
+    super("FunctionCall", location);
+    this.funcName = funcName; // null for method calls
+    this.args = args;
+    this.callee = callee; // MemberAccess for method calls like obj.method(args)
+  }
+}
+
+/**
+ * Array literal
+ * @example [1, 2, 3], ["a", "b", "c"]
+ */
+export class ArrayLiteral extends ASTNode {
+  constructor(elements, location) {
+    super("ArrayLiteral", location);
+    this.elements = elements;
+  }
+}
+
+/**
+ * Object literal (record)
+ * @example {name: "Alice", age: 30}
+ */
+export class ObjectLiteral extends ASTNode {
+  constructor(properties, location) {
+    super("ObjectLiteral", location);
+    this.properties = properties; // Array<{key: string, value: ASTNode}>
+  }
+}
+
+/**
+ * Block expression - a block of statements that evaluates to the returned value
+ * @example { x = 5; y = x * 2; return y }
+ * @deprecated Use BindingStructure instead for unified braces model
+ */
+export class BlockExpression extends ASTNode {
+  constructor(body, location) {
+    super("BlockExpression", location);
+    this.body = body; // Array<ASTNode> - statements in the block
+  }
+}
+
+/**
+ * Binding structure - unified representation for all {} constructs
+ *
+ * In Stone, {} is always a structure of bindings:
+ * - Ends with bindings → evaluates to object of those bindings
+ * - Ends with bare expression → evaluates to that value (sugar for return)
+ * - Used for: objects, blocks, loop state, loop body
+ *
+ * @example { x = 10, y = 20 }              // object
+ * @example { x = 10, x + 1 }               // block returning x + 1
+ * @example { sum = 0 } for (x in xs) {...} // loop state
+ */
+export class BindingStructure extends ASTNode {
+  constructor(bindings, trailingExpr, location) {
+    super("BindingStructure", location);
+    this.bindings = bindings; // Array<{name: string, typeAnnotation: TypeAnnotation|null, value: ASTNode}>
+    this.trailingExpr = trailingExpr; // ASTNode|null - bare expression at end (sugar for return)
+  }
+}
+
+/**
+ * Single binding within a BindingStructure
+ * @example sum = 0
+ * @example sum: num = 0
+ * @example sum' = sum + x  (prime binding for loop state transitions)
+ * @example name: string  (type descriptor - no value, required field in schema)
+ * @example name: string = 'default'  (type descriptor with default value)
+ */
+export class Binding {
+  constructor(name, value, typeAnnotation = null, isTypeDescriptor = false) {
+    this.name = name; // string - may end with ' for state transitions
+    this.value = value; // ASTNode - null for type descriptors without defaults
+    this.typeAnnotation = typeAnnotation; // TypeAnnotation|null
+    this.isTypeDescriptor = isTypeDescriptor; // true if this is a type descriptor (name: type) binding
+  }
+
+  get isPrime() {
+    return this.name.endsWith("'");
+  }
+
+  get baseName() {
+    return this.isPrime ? this.name.slice(0, -1) : this.name;
+  }
+}
+
+/**
+ * Member access: object.field or array[index]
+ * @example user.name, items[0]
+ */
+export class MemberAccess extends ASTNode {
+  constructor(object, property, computed, location) {
+    super("MemberAccess", location);
+    this.object = object;
+    this.property = property;
+    this.computed = computed; // true for [], false for .
+  }
+}
+
+/**
+ * String interpolation
+ * @example f"Hello {name}, you are {age} years old"
+ */
+export class StringInterpolation extends ASTNode {
+  constructor(parts, expressions, location) {
+    super("StringInterpolation", location);
+    this.parts = parts;
+    this.expressions = expressions;
+  }
+}
+
+// ============================================================================
+// STATEMENTS
+// ============================================================================
+
+/**
+ * Variable binding/assignment
+ * @example x = 5, name = "Alice"
+ */
+export class Assignment extends ASTNode {
+  constructor(target, value, typeAnnotation, location) {
+    super("Assignment", location);
+    this.target = target; // string (variable name)
+    this.value = value;
+    this.typeAnnotation = typeAnnotation;
+  }
+}
+
+/**
+ * Destructuring assignment - extracts properties from an object into variables
+ * @example x, y := point
+ * @example name, age as years := person
+ */
+export class DestructuringAssignment extends ASTNode {
+  constructor(targets, value, location) {
+    super("DestructuringAssignment", location);
+    this.targets = targets; // Array<{name: string, alias: string|null}> - properties to extract
+    this.value = value; // ASTNode - expression that evaluates to an object
+  }
+}
+
+/**
+ * Type alias declaration
+ * @example type Person = {name: string, age: num}
+ * @example type ScoreMap = {[string]: num}
+ */
+export class TypeAlias extends ASTNode {
+  constructor(name, typeAnnotation, location) {
+    super("TypeAlias", location);
+    this.name = name; // string (alias name)
+    this.typeAnnotation = typeAnnotation; // TypeAnnotation AST node
+  }
+}
+
+/**
+ * Indexed mapping assignment (parallel transformation)
+ * @example doubled[i] = xs[i] * 2
+ * @example matrix[i][j] = a[i][j] + b[i][j]
+ */
+export class IndexedAssignment extends ASTNode {
+  constructor(target, indices, value, location) {
+    super("IndexedAssignment", location);
+    this.target = target; // string (result array name)
+    this.indices = indices; // Array<string> (index variable names like ['i'] or ['i', 'j'])
+    this.value = value; // ASTNode (expression to compute each element)
+  }
+}
+
+/**
+ * Return statement
+ * @example return x + y
+ */
+export class ReturnStatement extends ASTNode {
+  constructor(value, location) {
+    super("ReturnStatement", location);
+    this.value = value;
+  }
+}
+
+/**
+ * Break statement
+ * @example break
+ */
+export class BreakStatement extends ASTNode {
+  constructor(location) {
+    super("BreakStatement", location);
+  }
+}
+
+/**
+ * Continue statement
+ * @example continue
+ */
+export class ContinueStatement extends ASTNode {
+  constructor(location) {
+    super("ContinueStatement", location);
+  }
+}
+
+// ============================================================================
+// CONTROL FLOW
+// ============================================================================
+
+/**
+ * Branch/conditional expression (if/elif/else)
+ * @example if (condition) { value1 } else { value2 }
+ */
+export class BranchExpression extends ASTNode {
+  constructor(paths, location) {
+    super("BranchExpression", location);
+    this.paths = paths;
+  }
+}
+
+/**
+ * Single path in a branch (if, elif, or else)
+ */
+export class BranchPath {
+  constructor(type, condition, body) {
+    this.type = type; // 'if' | 'elif' | 'else'
+    this.condition = condition; // ASTNode | null (null for else)
+    this.body = body; // Array<ASTNode>
+  }
+}
+
+
+// ============================================================================
+// LOOPS
+// ============================================================================
+
+/**
+ * Loop expression - state machine with drivers
+ *
+ * New syntax: { state } driver { body }
+ * @example { sum = 0 } for (x in xs) { sum' = sum + x }
+ * @example { x = 1 } while (x < 100) { x' = x * 2 }
+ *
+ * The state block defines initial bindings. The driver iterates.
+ * The body contains prime bindings (state transitions) like sum' = sum + x.
+ */
+export class LoopExpression extends ASTNode {
+  constructor(variables, drivers, body, destructuring, location) {
+    super("LoopExpression", location);
+    this.variables = variables; // Array<LoopVariable> - state variables from state block
+    this.drivers = drivers; // Array<LoopDriver> - for/while drivers
+    this.body = body; // Array<ASTNode> - body statements (includes prime bindings)
+    this.destructuring = destructuring; // Array<{name: string, alias: string|null}>
+    this.isDestructured = false; // true if using := operator
+  }
+}
+
+/**
+ * Loop variable (state variable)
+ * @param {string} name - Variable name
+ * @param {ASTNode|null} initialValue - Initial value expression
+ * @param {TypeAnnotation|null} typeAnnotation - Optional type annotation
+ */
+export class LoopVariable {
+  constructor(name, initialValue, typeAnnotation) {
+    this.name = name;
+    this.initialValue = initialValue;
+    this.typeAnnotation = typeAnnotation;
+  }
+}
+
+/**
+ * Loop variable update within loop body
+ * @example sum = sum + i, count += 1, counter++
+ */
+export class VariableUpdate extends ASTNode {
+  constructor(variableName, operator, value, location) {
+    super("VariableUpdate", location);
+    this.variableName = variableName;
+    this.operator = operator; // '=' | '+=' | '-=' | '*=' | '/=' | '++' | '--'
+    this.value = value; // ASTNode | null (null for ++ and --)
+  }
+}
+
+// ============================================================================
+// LOOP DRIVERS
+// ============================================================================
+
+/**
+ * Base class for loop drivers
+ */
+export class LoopDriver {
+  constructor(type, location) {
+    this.type = type;
+    this.location = location;
+  }
+}
+
+/**
+ * For driver: ~for(pattern in iterable)
+ * @example ~for(i in 1..=10), ~for(item in items)
+ */
+export class ForDriver extends LoopDriver {
+  constructor(pattern, iterable, step, location) {
+    super("for", location);
+    this.pattern = pattern;
+    this.iterable = iterable;
+    this.step = step;
+  }
+}
+
+/**
+ * While driver: ~while(condition)
+ * @example ~while(sum < 100), ~while(count > 0)
+ */
+export class WhileDriver extends LoopDriver {
+  constructor(condition, location) {
+    super("while", location);
+    this.condition = condition;
+  }
+}
+
+// ============================================================================
+// FUNCTIONS
+// ============================================================================
+
+/**
+ * Function definition
+ * @example fn add(x, y) = x + y
+ * @example fn abs(x) { if (x >= 0) { return x } else { return -x } }
+ * @example extend fn T(self: array) = transpose(self)
+ */
+export class FunctionDefinition extends ASTNode {
+  constructor(name, parameters, returnType, body, isExpression, location) {
+    super("FunctionDefinition", location);
+    this.name = name;
+    this.parameters = parameters; // Array<Parameter>
+    this.returnType = returnType; // TypeAnnotation | null
+    this.body = body; // ASTNode (expression) or Array<ASTNode> (block)
+    this.isExpression = isExpression; // true for `= expr`, false for `{ ... }`
+    this.isExtension = false; // true for `extend fn` - enables method call syntax
+    this.selfType = null; // TypeAnnotation for extension's self parameter
+  }
+}
+
+/**
+ * Function parameter
+ */
+export class Parameter {
+  constructor(name, typeAnnotation, defaultValue) {
+    this.name = name;
+    this.typeAnnotation = typeAnnotation;
+    this.defaultValue = defaultValue;
+  }
+}
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+/**
+ * Type annotation - represents parsed type syntax
+ *
+ * Kinds:
+ * - 'simple': Int, Float, Bool, String, Unit
+ * - 'generic': Array<Float, 2>, List<Int>
+ * - 'function': (Int, Int) -> Float
+ * - 'record': { x: Int, y: Float }
+ * - 'union': Int | String
+ *
+ * @example Int, String?, Array<Float, 2>, List<Int>, (Int) -> Bool
+ */
+export class TypeAnnotation {
+  constructor(kind, details, location = null) {
+    this.kind = kind; // 'simple' | 'generic' | 'function' | 'record' | 'union'
+    this.details = details; // type-specific details
+    this.location = location;
+    this.isOptional = false; // set separately when ? is present
+  }
+
+  // Convenience getters for backward compatibility
+  get baseType() {
+    if (this.kind === "simple") {
+      return this.details.name;
+    }
+    if (this.kind === "generic") {
+      return this.details.name;
+    }
+    return null;
+  }
+
+  get genericParams() {
+    if (this.kind === "generic") {
+      return this.details.params;
+    }
+    return null;
+  }
+
+  toString() {
+    let str;
+    switch (this.kind) {
+      case "simple":
+        str = this.details.name;
+        break;
+      case "generic":
+        const params = this.details.params
+          .map((p) => (p instanceof TypeAnnotation ? p.toString() : String(p)))
+          .join(", ");
+        str = `${this.details.name}<${params}>`;
+        break;
+      case "function":
+        const paramTypes = this.details.paramTypes
+          .map((t) => t.toString())
+          .join(", ");
+        str = `(${paramTypes}) -> ${this.details.returnType.toString()}`;
+        break;
+      case "record":
+        const fields = this.details.fields
+          .map((f) => `${f.name}: ${f.type.toString()}`)
+          .join(", ");
+        const suffix = this.details.open ? ", .." : "";
+        str = `{ ${fields}${suffix} }`;
+        break;
+      case "union":
+        str = this.details.types.map((t) => t.toString()).join(" | ");
+        break;
+      case "promoted":
+        str = `${this.details.targetType.toString()} | ${this.details.converterFunc}(${this.details.paramRef})`;
+        break;
+      default:
+        str = "unknown";
+    }
+    return this.isOptional ? `${str}?` : str;
+  }
+}
+
+/**
+ * Helper to create a simple type annotation
+ */
+export function simpleType(name, location = null) {
+  return new TypeAnnotation("simple", { name }, location);
+}
+
+/**
+ * Helper to create a generic type annotation
+ */
+export function genericType(name, params, location = null) {
+  return new TypeAnnotation("generic", { name, params }, location);
+}
+
+/**
+ * Helper to create a function type annotation
+ */
+export function functionType(paramTypes, returnType, location = null) {
+  return new TypeAnnotation("function", { paramTypes, returnType }, location);
+}
+
+/**
+ * Helper to create a record type annotation
+ */
+export function recordType(fields, open = false, location = null) {
+  return new TypeAnnotation("record", { fields, open }, location);
+}
+
+// ============================================================================
+// RANGES
+// ============================================================================
+
+/**
+ * Range expression
+ * @example 1..10, 1..<10, 0..100 by 2
+ */
+export class Range extends ASTNode {
+  constructor(start, end, inclusive, step, location) {
+    super("Range", location);
+    this.start = start;
+    this.end = end;
+    this.inclusive = inclusive; // true for ..=, false for ..<
+    this.step = step;
+  }
+}
+
+// ============================================================================
+// MODULES (IMPORTS & EXPORTS)
+// ============================================================================
+
+/**
+ * Import statement - selective import
+ * @example import calcVelocity, calcAcceleration from physics/mechanics/SpeedCalcUtility
+ * @example import calcVelocity as vel from physics/mechanics/SpeedCalcUtility
+ * @example import stats from "core logic/math" (quoted path with inferred filename)
+ */
+export class ImportStatement extends ASTNode {
+  constructor(specifiers, modulePath, location, isQuotedPath = false, inferredFilename = null) {
+    super("ImportStatement", location);
+    this.specifiers = specifiers; // Array<ImportSpecifier>
+    this.modulePath = modulePath; // string - module path like "physics/mechanics/SpeedCalcUtility"
+    this.isNamespaceImport = false;
+    this.isQuotedPath = isQuotedPath; // boolean - true if path was a string literal
+    this.inferredFilename = inferredFilename; // string | null - filename to append for directory imports
+  }
+}
+
+/**
+ * Namespace import statement
+ * @example import physics/mechanics/SpeedCalcUtility as Speed
+ * @example import physics/mechanics/SpeedCalcUtility (auto-binds as SpeedCalcUtility)
+ * @example import "core logic/math/stats" as stats (quoted path)
+ */
+export class NamespaceImportStatement extends ASTNode {
+  constructor(modulePath, alias, location, isQuotedPath = false) {
+    super("NamespaceImportStatement", location);
+    this.modulePath = modulePath; // string - module path
+    this.alias = alias; // string | null - if null, use last segment of path
+    this.isNamespaceImport = true;
+    this.isQuotedPath = isQuotedPath; // boolean - true if path was a string literal
+  }
+}
+
+/**
+ * Import specifier (for selective imports)
+ * @example name1 as local1
+ */
+export class ImportSpecifier {
+  constructor(importedName, localName, location = null) {
+    this.importedName = importedName; // Original exported name
+    this.localName = localName || importedName; // Local binding name (alias)
+    this.location = location; // Source location for error reporting
+  }
+}
+
+/**
+ * Export statement - marks a binding as exported
+ * @example export fn calcVelocity(d, t) = d / t
+ * @example export constant = 42
+ */
+export class ExportStatement extends ASTNode {
+  constructor(declaration, location) {
+    super("ExportStatement", location);
+    this.declaration = declaration; // The exported declaration (FunctionDefinition, Assignment, etc.)
+  }
+}
+
+/**
+ * Selective re-export - re-exports specific names from another module
+ * @example export add, sub from ./math
+ * @example export add as plus, sub as minus from ./math
+ */
+export class SelectiveReExportStatement extends ASTNode {
+  constructor(specifiers, modulePath, location) {
+    super("SelectiveReExportStatement", location);
+    this.specifiers = specifiers; // Array of { name, alias } objects
+    this.modulePath = modulePath; // The module to re-export from
+  }
+}
+
+/**
+ * Namespace re-export - re-exports an entire module as a namespace
+ * @example export ./math as math
+ * @example export ./physics/mechanics/SpeedCalcUtility
+ */
+export class NamespaceReExportStatement extends ASTNode {
+  constructor(modulePath, alias, location) {
+    super("NamespaceReExportStatement", location);
+    this.modulePath = modulePath; // The module path to re-export
+    this.alias = alias; // Optional alias name (if null, uses last path segment)
+  }
+}
+
+// ============================================================================
+// PROGRAM ROOT
+// ============================================================================
+
+/**
+ * Top-level program/module
+ */
+export class Program extends ASTNode {
+  constructor(statements, location) {
+    super("Program", location);
+    this.statements = statements;
+    this.imports = []; // Will be populated by parser
+    this.exports = []; // Will be populated by parser
+  }
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+export function createLocation(line, column, file = null) {
+  return { line, column, file };
+}
+
+export function isExpression(node) {
+  return (
+    node instanceof Literal ||
+    node instanceof Identifier ||
+    node instanceof BinaryOp ||
+    node instanceof UnaryOp ||
+    node instanceof FunctionCall ||
+    node instanceof ArrayLiteral ||
+    node instanceof ObjectLiteral ||
+    node instanceof BlockExpression ||
+    node instanceof BindingStructure ||
+    node instanceof MemberAccess ||
+    node instanceof StringInterpolation ||
+    node instanceof BranchExpression ||
+    node instanceof LoopExpression ||
+    node instanceof Range
+  );
+}
+
+export function isStatement(node) {
+  return (
+    node instanceof Assignment ||
+    node instanceof IndexedAssignment ||
+    node instanceof ReturnStatement ||
+    node instanceof BreakStatement ||
+    node instanceof ContinueStatement ||
+    node instanceof VariableUpdate ||
+    node instanceof FunctionDefinition ||
+    node instanceof ImportStatement ||
+    node instanceof NamespaceImportStatement ||
+    node instanceof ExportStatement
+  );
+}
+
+export function hasDrivers(loopExpr) {
+  return loopExpr.drivers && loopExpr.drivers.length > 0;
+}