mimo-lang 1.1.0 → 2.0.6

package/interpreter/ErrorHandler.js

@@ -0,0 +1,120 @@
+import { MimoError } from './MimoError.js';
+
+/**
+ * Handles and formats errors within the Mimo interpreter.
+ */
+export class ErrorHandler {
+    constructor(sourceCodeMap = {}, options = {}) {
+        this.sourceCodeMap = sourceCodeMap; // Map of filePath -> sourceCodeString
+        this.stackFramesProvider = options.stackFramesProvider || null;
+    }
+
+    /**
+     * Adds or updates source code for a given file path in the handler's map.
+     * Useful for REPL or module loading where source becomes available dynamically.
+     * @param {string} filePath
+     * @param {string} sourceCode
+     */
+    addSourceFile(filePath, sourceCode) {
+        this.sourceCodeMap[filePath] = sourceCode;
+    }
+
+    /**
+     * Clears source code for a given file path from the handler's map.
+     * Useful for cleaning up memory after a module is processed or a REPL line is done.
+     * @param {string} filePath
+     */
+    clearSourceFile(filePath) {
+        delete this.sourceCodeMap[filePath];
+    }
+
+    /**
+     * Gets a specific line from the source code map for error reporting.
+     * @param {string} filePath - The path to the source file.
+     * @param {number} lineNumber - The 1-based line number.
+     * @returns {string} The requested line of code, or an empty string if not found.
+     */
+    getLine(filePath, lineNumber) {
+        const source = this.sourceCodeMap[filePath];
+        if (!source) return '';
+        const lines = source.split('\n');
+        // line numbers are 1-based
+        if (lineNumber > 0 && lineNumber <= lines.length) {
+            return lines[lineNumber - 1];
+        }
+        return '';
+    }
+
+    /**
+     * Creates and formats a LexerError.
+     * @param {string} message - Error message.
+     * @param {Object} token - The token that caused the error.
+     * @param {string} [code='LEX000'] - Unique error code.
+     * @param {string} [suggestion=''] - Actionable suggestion.
+     * @returns {MimoError}
+     */
+    createLexerError(message, token, code = 'LEX000', suggestion = '') {
+        const error = MimoError.lexerError(code, message, token, suggestion);
+        error.location.file = token.file || 'unknown'; // Ensure file is set from token
+        error.location.snippet = this.getLine(error.location.file, error.location.line);
+        return error;
+    }
+
+    /**
+     * Creates and formats a SyntaxError.
+     * @param {string} message - Error message.
+     * @param {Object} astNodeOrToken - The AST node or token that caused the error.
+     * @param {string} [code='SYN000'] - Unique error code.
+     * @param {string} [suggestion=''] - Actionable suggestion.
+     * @returns {MimoError}
+     */
+    createSyntaxError(message, astNodeOrToken, code = 'SYN000', suggestion = '') {
+        const error = MimoError.syntaxError(code, message, astNodeOrToken, suggestion);
+        error.location.file = astNodeOrToken.file || 'unknown'; // Ensure file is set
+        error.location.snippet = this.getLine(error.location.file, error.location.line);
+        return error;
+    }
+
+    /**
+     * Creates and formats a RuntimeError.
+     * @param {string} message - Error message.
+     * @param {Object} astNode - The AST node being evaluated when the error occurred.
+     * @param {string} [code='RUN000'] - Unique error code.
+     * @param {string} [suggestion=''] - Actionable suggestion.
+     * @param {Array<Object>} [stackFrames=[]] - The Mimo call stack (from interpreter).
+     * @returns {MimoError}
+     */
+    createRuntimeError(message, astNode, code = 'RUN000', suggestion = '', stackFrames = null) {
+        const framesFromProvider = (stackFrames === null && typeof this.stackFramesProvider === 'function')
+            ? this.stackFramesProvider()
+            : (stackFrames || []);
+
+        const enrichedFrames = Array.isArray(framesFromProvider)
+            ? framesFromProvider.map((frame) => ({
+                ...frame,
+                snippet: this.getLine(frame.file || 'unknown', frame.line),
+            }))
+            : [];
+
+        const error = MimoError.runtimeError(code, message, astNode, suggestion, enrichedFrames);
+        // Ensure file is set for runtime errors too, even if astNode has it.
+        // It's crucial for context.
+        error.location.file = astNode?.file || 'unknown';
+        error.location.snippet = this.getLine(error.location.file, error.location.line);
+        return error;
+    }
+
+    /**
+     * Prints an error to the console.
+     * @param {Error|MimoError} error - The error object.
+     */
+    printError(error) {
+        if (error instanceof MimoError) {
+            console.error(error.format(error.location.snippet));
+        } else {
+            // Fallback for unexpected non-Mimo errors
+            console.error(`An unexpected error occurred: ${error.message}`);
+            console.error(error.stack);
+        }
+    }
+}

package/interpreter/ExpressionEvaluator.js

@@ -0,0 +1,106 @@
+import {
+    evaluateBinaryExpression,
+    evaluateUnaryExpression,
+} from "./evaluators/binaryExpressionEvaluator.js";
+import {
+    evaluateIdentifier,
+    evaluateLiteral,
+} from "./evaluators/literalEvaluator.js";
+import {
+    evaluateArrayLiteral,
+    evaluateArrayAccess,
+    evaluateObjectLiteral,
+    evaluatePropertyAccess,
+    evaluateSafePropertyAccess,
+    evaluateSafeArrayAccess,
+} from "./evaluators/collectionEvaluator.js";
+import {
+    evaluateAnonymousFunction,
+    evaluateCallExpression,
+    evaluateSafeCallExpression,
+} from "./evaluators/functionCallEvaluator.js";
+import { evaluateTemplateLiteral } from "./evaluators/templateLiteralEvaluator.js";
+import { evaluateModuleAccess } from "./evaluators/moduleAccessEvaluator.js";
+
+export class ExpressionEvaluator {
+    constructor(interpreter) {
+        this.interpreter = interpreter;
+    }
+
+    evaluateExpression(node) {
+        switch (node.type) {
+            case "BinaryExpression":
+                return evaluateBinaryExpression(this.interpreter, node);
+            case "UnaryExpression":
+                return evaluateUnaryExpression(this.interpreter, node);
+            case "Identifier":
+                return evaluateIdentifier(this.interpreter, node);
+            case "Literal":
+                return evaluateLiteral(this.interpreter, node);
+            case "ArrayLiteral":
+                return evaluateArrayLiteral(this.interpreter, node);
+            case "ObjectLiteral":
+                return evaluateObjectLiteral(this.interpreter, node);
+            case "PropertyAccess":
+                return evaluatePropertyAccess(this.interpreter, node);
+            case "SafePropertyAccess":
+                return evaluateSafePropertyAccess(this.interpreter, node);
+            case "SafeArrayAccess":
+                return evaluateSafeArrayAccess(this.interpreter, node);
+            case "ArrayAccess":
+                return evaluateArrayAccess(this.interpreter, node);
+            case "ModuleAccess":
+                return evaluateModuleAccess(this.interpreter, node);
+            case "AnonymousFunction":
+                return evaluateAnonymousFunction(this.interpreter, node);
+            case "TemplateLiteral":
+                return evaluateTemplateLiteral(this.interpreter, node);
+            case "CallExpression":
+                return evaluateCallExpression(this.interpreter, node);
+            case "SafeCallExpression":
+                return evaluateSafeCallExpression(this.interpreter, node);
+            case "InlineIfExpression":
+                return this.isTruthy(this.interpreter.visitNode(node.condition))
+                    ? this.interpreter.visitNode(node.consequent)
+                    : this.interpreter.visitNode(node.alternate);
+            case "PipeExpression": {
+                // Evaluate the piped value (left side)
+                const pipedValue = this.interpreter.visitNode(node.left);
+
+                // Evaluate the callee — if it's an inline-if, we get the function from it
+                let func;
+                if (node.callee.type === "InlineIfExpression") {
+                    func = this.isTruthy(this.interpreter.visitNode(node.callee.condition))
+                        ? this.interpreter.visitNode(node.callee.consequent)
+                        : this.interpreter.visitNode(node.callee.alternate);
+                } else {
+                    func = this.interpreter.visitNode(node.callee);
+                }
+
+                // Evaluate any extra args, then prepend the piped value
+                const extraArgs = node.args.map(arg => this.interpreter.visitNode(arg));
+                const allArgs = [pipedValue, ...extraArgs];
+
+                // Call the function
+                return func.call(this.interpreter, allArgs, node);
+            }
+            default:
+                throw new Error(`Unknown expression type: ${node.type}`);
+        }
+    }
+
+    // Keep isTruthy as a utility method in case it's used elsewhere
+    isTruthy(value) {
+        // JavaScript-like truthiness: false, 0, "", null, undefined are falsy
+        if (
+            value === false ||
+            value === 0 ||
+            value === "" ||
+            value === null ||
+            value === undefined
+        ) {
+            return false;
+        }
+        return true;
+    }
+}

package/interpreter/Interpreter.js

@@ -0,0 +1,172 @@
+/**
+ * @file The main Mimo Interpreter class.
+ * This file contains the core Interpreter class that orchestrates the entire
+ * execution process, managing environments, call stacks, and dispatching
+ * to specialized executors and evaluators.
+ */
+
+import { initializeBuiltins } from "./coreBuiltins.js";
+import { initializeArrayModule } from "./stdlib/array.js";
+
+import { ErrorHandler } from "./ErrorHandler.js";
+import { MimoError } from "./MimoError.js";
+import { ExpressionEvaluator } from "./ExpressionEvaluator.js";
+import { ModuleLoader } from "./ModuleLoader.js";
+import { StatementExecutor } from "./StatementExecutor.js";
+import { FunctionValue, ReturnValue } from "./Values.js";
+import { Environment } from "./environment.js";
+
+/**
+ * The core Mimo interpreter. It walks the AST produced by the parser and
+ * executes the program's logic.
+ */
+export class Interpreter {
+  /**
+   * Creates a new Interpreter instance.
+   * @param {object} adapter - The host adapter for interacting with the underlying system (e.g., file system, console).
+   */
+  constructor(adapter) {
+    this.adapter = adapter;
+    this.callStack = [];
+    this.globalEnv = new Environment(null, true);
+    this.currentEnv = this.globalEnv;
+    this.expressionEvaluator = new ExpressionEvaluator(this);
+    this.statementExecutor = new StatementExecutor(this);
+    this.errorHandler = new ErrorHandler({}, {
+      stackFramesProvider: () => [...this.callStack],
+    });
+    this.moduleLoader = new ModuleLoader(this);
+    this.currentFile = "/repl";
+
+    initializeBuiltins(this.globalEnv);
+    initializeArrayModule(this.globalEnv);
+
+  }
+
+  /**
+   * Interprets an AST and executes the Mimo program. This is the main entry point.
+   * @param {object} ast - The Abstract Syntax Tree (Program node) to interpret.
+   * @param {string} [filePath="main.mimo"] - The path of the file being executed, for error reporting.
+   * @returns {any} The result of the last executed statement.
+   * @throws {MimoError} If any lexing, parsing, or runtime errors occur.
+   */
+  interpret(ast, filePath = "main.mimo") {
+    const previousCurrentFile = this.currentFile;
+    this.currentFile = filePath;
+
+    try {
+      this.pushCallStack('<root>', ast);
+      const result = this.visitNode(ast);
+      return result;
+    } catch (error) {
+      if (error instanceof MimoError) {
+        throw error;
+      } else {
+        const lastFrameNode = this.callStack.length > 0 ? this.callStack[this.callStack.length - 1].node : ast;
+        const mimoError = this.errorHandler.createRuntimeError(
+          `Internal JavaScript error: ${error.message}`,
+          lastFrameNode,
+          'INT001',
+          'An unexpected internal error occurred. This might be a bug in the Mimo interpreter.',
+          this.callStack
+        );
+        throw mimoError;
+      }
+    } finally {
+      this.popCallStack();
+      this.currentFile = previousCurrentFile;
+    }
+  }
+
+  /**
+   * Pushes a new frame onto the Mimo call stack for better error reporting.
+   * @param {string} functionName - The name of the function being called.
+   * @param {object} node - The AST node of the call site (for location info).
+   */
+  pushCallStack(functionName, node) {
+    if (node && node.line !== undefined && node.column !== undefined && node.file !== undefined) {
+      this.callStack.push({
+        functionName: functionName || '<anonymous>',
+        file: node.file,
+        line: node.line,
+        column: node.column,
+        node: node
+      });
+    }
+  }
+
+  /**
+   * Pops the top frame from the Mimo call stack.
+   */
+  popCallStack() {
+    this.callStack.pop();
+  }
+
+  /**
+   * The main visitor dispatch method. It determines whether a node is an
+   * expression or a statement and delegates to the appropriate handler.
+   * @param {object} node - The AST node to visit.
+   * @returns {any} The result of the node's evaluation or execution.
+   */
+  visitNode(node) {
+    if (this.isExpression(node)) {
+      return this.expressionEvaluator.evaluateExpression(node);
+    }
+    return this.statementExecutor.executeStatement(node);
+  }
+
+  /**
+   * Checks if a given AST node is an expression type.
+   * @param {object} node - The AST node to check.
+   * @returns {boolean} True if the node is an expression.
+   */
+  isExpression(node) {
+    const expressionTypes = [
+      "BinaryExpression", "UnaryExpression", "Identifier", "Literal",
+      "ArrayLiteral", "ArrayAccess", "ObjectLiteral", "PropertyAccess",
+      "SafePropertyAccess", "SafeArrayAccess", "SafeCallExpression",
+      "ModuleAccess", "AnonymousFunction", "TemplateLiteral",
+      "CallExpression", "InlineIfExpression", "PipeExpression"
+    ];
+    return expressionTypes.includes(node.type);
+  }
+
+  /**
+   * Executes a block of statements within a new or existing environment.
+   * @param {object[]} statements - An array of statement AST nodes.
+   * @param {Environment} [env=null] - The environment to execute the block in. If null, uses the current environment.
+   * @returns {any} The result of the last statement in the block, or a ReturnValue.
+   */
+  executeBlock(statements, env = null) {
+    const previousEnv = this.currentEnv;
+    if (env) {
+      this.currentEnv = env;
+    }
+
+    try {
+      this.hoistFunctionDeclarations(statements);
+      let result = null;
+      for (const statement of statements) {
+        result = this.visitNode(statement);
+        if (result instanceof ReturnValue) {
+          return result;
+        }
+      }
+      return result;
+    } finally {
+      if (env) {
+        this.currentEnv = previousEnv;
+      }
+    }
+  }
+
+  hoistFunctionDeclarations(statements) {
+    for (const statement of statements) {
+      if (statement?.type === "FunctionDeclaration") {
+        if (!this.currentEnv.hasInCurrentScope(statement.name)) {
+          this.currentEnv.define(statement.name, new FunctionValue(statement, this.currentEnv));
+        }
+      }
+    }
+  }
+}

package/interpreter/MimoError.js

@@ -0,0 +1,112 @@
+/**
+ * Represents a Mimo language error.
+ * Includes detailed information for better debugging and user experience.
+ */
+export class MimoError extends Error {
+    /**
+     * @param {string} type - 'LexerError', 'SyntaxError', 'RuntimeError'
+     * @param {string} code - A unique error code (e.g., 'PARSE001', 'RUNTIME001', 'TYPE001')
+     * @param {string} message - A concise description of the error.
+     * @param {string} [suggestion=''] - An actionable suggestion for how to fix the error.
+     * @param {Object} [location={}] - Object containing line, column, file, and a code snippet.
+     * @param {Array<Object>} [stackFrames=[]] - An array of stack frames for runtime errors.
+     */
+    constructor(type, code, message, suggestion = '', location = {}, stackFrames = []) {
+        super(message);
+        this.name = type;
+        this.type = type;
+        this.code = code;
+        this.suggestion = suggestion;
+
+        // Ensure all location properties are explicitly defined, defaulting if not provided.
+        this.location = {
+            file: location.file || 'unknown',
+            line: location.line,
+            column: location.column,
+            start: location.start, // <--- Add start
+            length: location.length, // <--- Add length
+            snippet: location.snippet, // <--- Add snippet
+        };
+        this.stackFrames = stackFrames;
+
+        // Standard JavaScript error properties
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        } else {
+            this.stack = new Error().stack;
+        }
+    }
+
+    static lexerError(code, message, token, suggestion) {
+        const location = token ? {
+            line: token.line,
+            column: token.column,
+            start: token.start,   // <--- Add start
+            length: token.length, // <--- Add length
+            file: token.file
+        } : {};
+        return new MimoError('LexerError', code, message, suggestion, location);
+    }
+
+    static syntaxError(code, message, astNodeOrToken, suggestion) {
+        const location = astNodeOrToken ? {
+            line: astNodeOrToken.line,
+            column: astNodeOrToken.column,
+            start: astNodeOrToken.start,   // <--- Add start
+            length: astNodeOrToken.length, // <--- Add length
+            file: astNodeOrToken.file
+        } : {};
+        return new MimoError('SyntaxError', code, message, suggestion, location);
+    }
+
+    static runtimeError(code, message, astNode, suggestion, stackFrames) {
+        const location = astNode ? {
+            line: astNode.line,
+            column: astNode.column,
+            start: astNode.start,   // <--- Add start
+            length: astNode.length, // <--- Add length
+            file: astNode.file,
+        } : {};
+        return new MimoError('RuntimeError', code, message, suggestion, location, stackFrames);
+    }
+
+    format(sourceCodeLine = '') {
+        let output = `[${this.type} ${this.code}]: ${this.message}\n`;
+        
+        if (this.location.file) {
+            output += `    at ${this.location.file}:${this.location.line}:${this.location.column}\n`;
+        } else if (this.location.line !== undefined && this.location.column !== undefined) {
+            output += `    at Line ${this.location.line}, Col ${this.location.column}\n`;
+        }
+
+        if (sourceCodeLine) {
+            output += `> ${sourceCodeLine.trim()}\n`;
+            if (this.location.column !== undefined && sourceCodeLine.trim().length > 0) {
+                const trimmedOffset = sourceCodeLine.length - sourceCodeLine.trimStart().length;
+                const pointerCol = Math.max(0, this.location.column - 1 - trimmedOffset);
+                output += `  ${' '.repeat(pointerCol)}^\n`;
+            }
+        }
+
+        if (this.suggestion) {
+            output += `Suggestion: ${this.suggestion}\n`;
+        }
+
+        if (this.stackFrames && this.stackFrames.length > 0) {
+            output += "Mimo Stack:\n";
+            this.stackFrames.forEach(frame => {
+                output += `    at ${frame.functionName} (${frame.file || 'unknown'}:${frame.line}:${frame.column})\n`;
+                if (frame.snippet) {
+                    const snippet = String(frame.snippet);
+                    output += `      > ${snippet.trim()}\n`;
+                    if (frame.column !== undefined && snippet.trim().length > 0) {
+                        const trimmedOffset = snippet.length - snippet.trimStart().length;
+                        const pointerCol = Math.max(0, frame.column - 1 - trimmedOffset);
+                        output += `        ${' '.repeat(pointerCol)}^\n`;
+                    }
+                }
+            });
+        }
+        return output;
+    }
+}