mimo-lang 1.1.0 → 2.0.6

package/bun.lock

@@ -0,0 +1,74 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "name": "mimo-next",
+      "devDependencies": {
+        "@types/bun": "latest",
+        "esbuild": "^0.25.5",
+      },
+    },
+  },
+  "packages": {
+    "@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.25.5", "", { "os": "aix", "cpu": "ppc64" }, "sha512-9o3TMmpmftaCMepOdA5k/yDw8SfInyzWWTjYTFCX3kPSDJMROQTb8jg+h9Cnwnmm1vOzvxN7gIfB5V2ewpjtGA=="],
+
+    "@esbuild/android-arm": ["@esbuild/android-arm@0.25.5", "", { "os": "android", "cpu": "arm" }, "sha512-AdJKSPeEHgi7/ZhuIPtcQKr5RQdo6OO2IL87JkianiMYMPbCtot9fxPbrMiBADOWWm3T2si9stAiVsGbTQFkbA=="],
+
+    "@esbuild/android-arm64": ["@esbuild/android-arm64@0.25.5", "", { "os": "android", "cpu": "arm64" }, "sha512-VGzGhj4lJO+TVGV1v8ntCZWJktV7SGCs3Pn1GRWI1SBFtRALoomm8k5E9Pmwg3HOAal2VDc2F9+PM/rEY6oIDg=="],
+
+    "@esbuild/android-x64": ["@esbuild/android-x64@0.25.5", "", { "os": "android", "cpu": "x64" }, "sha512-D2GyJT1kjvO//drbRT3Hib9XPwQeWd9vZoBJn+bu/lVsOZ13cqNdDeqIF/xQ5/VmWvMduP6AmXvylO/PIc2isw=="],
+
+    "@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.25.5", "", { "os": "darwin", "cpu": "arm64" }, "sha512-GtaBgammVvdF7aPIgH2jxMDdivezgFu6iKpmT+48+F8Hhg5J/sfnDieg0aeG/jfSvkYQU2/pceFPDKlqZzwnfQ=="],
+
+    "@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.25.5", "", { "os": "darwin", "cpu": "x64" }, "sha512-1iT4FVL0dJ76/q1wd7XDsXrSW+oLoquptvh4CLR4kITDtqi2e/xwXwdCVH8hVHU43wgJdsq7Gxuzcs6Iq/7bxQ=="],
+
+    "@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.25.5", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-nk4tGP3JThz4La38Uy/gzyXtpkPW8zSAmoUhK9xKKXdBCzKODMc2adkB2+8om9BDYugz+uGV7sLmpTYzvmz6Sw=="],
+
+    "@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.25.5", "", { "os": "freebsd", "cpu": "x64" }, "sha512-PrikaNjiXdR2laW6OIjlbeuCPrPaAl0IwPIaRv+SMV8CiM8i2LqVUHFC1+8eORgWyY7yhQY+2U2fA55mBzReaw=="],
+
+    "@esbuild/linux-arm": ["@esbuild/linux-arm@0.25.5", "", { "os": "linux", "cpu": "arm" }, "sha512-cPzojwW2okgh7ZlRpcBEtsX7WBuqbLrNXqLU89GxWbNt6uIg78ET82qifUy3W6OVww6ZWobWub5oqZOVtwolfw=="],
+
+    "@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.25.5", "", { "os": "linux", "cpu": "arm64" }, "sha512-Z9kfb1v6ZlGbWj8EJk9T6czVEjjq2ntSYLY2cw6pAZl4oKtfgQuS4HOq41M/BcoLPzrUbNd+R4BXFyH//nHxVg=="],
+
+    "@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.25.5", "", { "os": "linux", "cpu": "ia32" }, "sha512-sQ7l00M8bSv36GLV95BVAdhJ2QsIbCuCjh/uYrWiMQSUuV+LpXwIqhgJDcvMTj+VsQmqAHL2yYaasENvJ7CDKA=="],
+
+    "@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.25.5", "", { "os": "linux", "cpu": "none" }, "sha512-0ur7ae16hDUC4OL5iEnDb0tZHDxYmuQyhKhsPBV8f99f6Z9KQM02g33f93rNH5A30agMS46u2HP6qTdEt6Q1kg=="],
+
+    "@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.25.5", "", { "os": "linux", "cpu": "none" }, "sha512-kB/66P1OsHO5zLz0i6X0RxlQ+3cu0mkxS3TKFvkb5lin6uwZ/ttOkP3Z8lfR9mJOBk14ZwZ9182SIIWFGNmqmg=="],
+
+    "@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.25.5", "", { "os": "linux", "cpu": "ppc64" }, "sha512-UZCmJ7r9X2fe2D6jBmkLBMQetXPXIsZjQJCjgwpVDz+YMcS6oFR27alkgGv3Oqkv07bxdvw7fyB71/olceJhkQ=="],
+
+    "@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.25.5", "", { "os": "linux", "cpu": "none" }, "sha512-kTxwu4mLyeOlsVIFPfQo+fQJAV9mh24xL+y+Bm6ej067sYANjyEw1dNHmvoqxJUCMnkBdKpvOn0Ahql6+4VyeA=="],
+
+    "@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.25.5", "", { "os": "linux", "cpu": "s390x" }, "sha512-K2dSKTKfmdh78uJ3NcWFiqyRrimfdinS5ErLSn3vluHNeHVnBAFWC8a4X5N+7FgVE1EjXS1QDZbpqZBjfrqMTQ=="],
+
+    "@esbuild/linux-x64": ["@esbuild/linux-x64@0.25.5", "", { "os": "linux", "cpu": "x64" }, ""],
+
+    "@esbuild/netbsd-arm64": ["@esbuild/netbsd-arm64@0.25.5", "", { "os": "none", "cpu": "arm64" }, "sha512-pwHtMP9viAy1oHPvgxtOv+OkduK5ugofNTVDilIzBLpoWAM16r7b/mxBvfpuQDpRQFMfuVr5aLcn4yveGvBZvw=="],
+
+    "@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.25.5", "", { "os": "none", "cpu": "x64" }, "sha512-WOb5fKrvVTRMfWFNCroYWWklbnXH0Q5rZppjq0vQIdlsQKuw6mdSihwSo4RV/YdQ5UCKKvBy7/0ZZYLBZKIbwQ=="],
+
+    "@esbuild/openbsd-arm64": ["@esbuild/openbsd-arm64@0.25.5", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-7A208+uQKgTxHd0G0uqZO8UjK2R0DDb4fDmERtARjSHWxqMTye4Erz4zZafx7Di9Cv+lNHYuncAkiGFySoD+Mw=="],
+
+    "@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.25.5", "", { "os": "openbsd", "cpu": "x64" }, "sha512-G4hE405ErTWraiZ8UiSoesH8DaCsMm0Cay4fsFWOOUcz8b8rC6uCvnagr+gnioEjWn0wC+o1/TAHt+It+MpIMg=="],
+
+    "@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.25.5", "", { "os": "sunos", "cpu": "x64" }, "sha512-l+azKShMy7FxzY0Rj4RCt5VD/q8mG/e+mDivgspo+yL8zW7qEwctQ6YqKX34DTEleFAvCIUviCFX1SDZRSyMQA=="],
+
+    "@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.25.5", "", { "os": "win32", "cpu": "arm64" }, "sha512-O2S7SNZzdcFG7eFKgvwUEZ2VG9D/sn/eIiz8XRZ1Q/DO5a3s76Xv0mdBzVM5j5R639lXQmPmSo0iRpHqUUrsxw=="],
+
+    "@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.25.5", "", { "os": "win32", "cpu": "ia32" }, "sha512-onOJ02pqs9h1iMJ1PQphR+VZv8qBMQ77Klcsqv9CNW2w6yLqoURLcgERAIurY6QE63bbLuqgP9ATqajFLK5AMQ=="],
+
+    "@esbuild/win32-x64": ["@esbuild/win32-x64@0.25.5", "", { "os": "win32", "cpu": "x64" }, "sha512-TXv6YnJ8ZMVdX+SXWVBo/0p8LTcrUYngpWjvm91TMjjBQii7Oz11Lw5lbDV5Y0TzuhSJHwiH4hEtC1I42mMS0g=="],
+
+    "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],
+
+    "@types/node": ["@types/node@25.3.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-4K3bqJpXpqfg2XKGK9bpDTc6xO/xoUP/RBWS7AtRMug6zZFaRekiLzjVtAoZMquxoAbzBvy5nxQ7veS5eYzf8A=="],
+
+    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
+
+    "esbuild": ["esbuild@0.25.5", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.25.5", "@esbuild/android-arm": "0.25.5", "@esbuild/android-arm64": "0.25.5", "@esbuild/android-x64": "0.25.5", "@esbuild/darwin-arm64": "0.25.5", "@esbuild/darwin-x64": "0.25.5", "@esbuild/freebsd-arm64": "0.25.5", "@esbuild/freebsd-x64": "0.25.5", "@esbuild/linux-arm": "0.25.5", "@esbuild/linux-arm64": "0.25.5", "@esbuild/linux-ia32": "0.25.5", "@esbuild/linux-loong64": "0.25.5", "@esbuild/linux-mips64el": "0.25.5", "@esbuild/linux-ppc64": "0.25.5", "@esbuild/linux-riscv64": "0.25.5", "@esbuild/linux-s390x": "0.25.5", "@esbuild/linux-x64": "0.25.5", "@esbuild/netbsd-arm64": "0.25.5", "@esbuild/netbsd-x64": "0.25.5", "@esbuild/openbsd-arm64": "0.25.5", "@esbuild/openbsd-x64": "0.25.5", "@esbuild/sunos-x64": "0.25.5", "@esbuild/win32-arm64": "0.25.5", "@esbuild/win32-ia32": "0.25.5", "@esbuild/win32-x64": "0.25.5" }, "bin": "bin/esbuild" }, "sha512-P8OtKZRv/5J5hhz0cUAdu/cLuPIKXpQl1R9pZtvmHWQvrAUVd0UNIPT4IB4W3rNOqVO0rlqHmCIbSwxh/c9yUQ=="],
+
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
+  }
+}

package/index.js

@@ -1,41 +1,51 @@
-import { generateTokens } from "./compiler/lexer/tokenizer.js";
-import { parseTokens } from "./compiler/parser/parser.js";
-import { interpret } from "./compiler/execute/interpreter.js";
-import { generateCodeJsFromAstArray } from "./converter/js/convert.js";
-
-// The main class for the Mimo language
-export default class Mimo {
-  constructor() {
-    // Initialize the environment for variables
-    this.env = {};
-  }
-
-  // Tokenize the given code into a list of tokens
-  async tokenize(code) {
-    return generateTokens(code);
-  }
-
-  // Parse the list of tokens into an abstract syntax tree (AST)
-  async parse(tokens) {
-    return parseTokens(tokens);
-  }
-
-  // Interpret the AST and execute the code
-  async interpret(program) {
-    return interpret(program, this.env);
-  }
-
-  // Run the given code by tokenizing, parsing, and interpreting it
-  async run(code) {
-    const tokens = await this.tokenize(code);
-    const program = await this.parse(tokens);
-    const env = await this.interpret(program);
-    return { program, env };
-  }
-
-  // Convert the AST to JavaScript code
-  toJS(ast) {
-    return generateCodeJsFromAstArray(ast);
-  }
+/**
+ * @file The Mimo library entry point for NODE.JS environments.
+ * Exports the Mimo class and Node.js-specific helpers.
+ */
+
+import { Interpreter } from './interpreter/index.js';
+import { Lexer } from './lexer/Lexer.js';
+import { Parser } from './parser/Parser.js';
+import { MimoError } from './interpreter/MimoError.js';
+import { nodeAdapter } from './adapters/nodeAdapter.js';
+
+export class Mimo {
+    constructor(adapter = nodeAdapter) {
+        this.interpreter = new Interpreter(adapter);
+    }
+
+    run(source, filePath) {
+        if (!filePath) {
+            throw new Error("Mimo.run() requires a filePath argument in a Node.js environment for module resolution.");
+        }
+
+        try {
+            const lexer = new Lexer(source, filePath);
+            const tokens = [];
+            let token;
+            while ((token = lexer.nextToken()) !== null) {
+                tokens.push(token);
+            }
+
+            const parser = new Parser(tokens, filePath);
+            this.interpreter.errorHandler.addSourceFile(filePath, source);
+            parser.setErrorHandler(this.interpreter.errorHandler);
+            const ast = parser.parse();
+
+            const result = this.interpreter.interpret(ast, filePath);
+
+            return result;
+
+        } catch (error) {
+            if (error instanceof MimoError) {
+                throw error.format(this.interpreter.errorHandler.getLine(error.location.file, error.location.line));
+            } else {
+                throw error;
+            }
+        }
+    }
 }
 
+
+// Export Node.js specific helpers and other components
+export { Interpreter, Lexer, Parser, MimoError, nodeAdapter };

package/index.web.js

@@ -0,0 +1,364 @@
+/**
+ * @file The Mimo library entry point for BROWSER environments.
+ * It exports the Mimo class but avoids importing any Node.js-specific modules.
+ */
+
+import { Interpreter } from './interpreter/index.js';
+import { Lexer } from './lexer/Lexer.js';
+import { Parser } from './parser/Parser.js';
+import { MimoError } from './interpreter/MimoError.js';
+import { Linter } from './tools/lint/Linter.js';
+import { PrettyPrinter } from './tools/PrettyPrinter.js';
+import { extractComments } from './tools/format/CommentLexer.js';
+import { attachComments } from './tools/format/CommentAttacher.js';
+
+/**
+ * Tokenizer module - handles lexical analysis
+ */
+export class MimoTokenizer {
+    constructor(source, filePath = '/playground.mimo') {
+        this.source = source;
+        this.filePath = filePath;
+        this.lexer = new Lexer(source, filePath);
+    }
+
+    tokenize() {
+        const tokens = [];
+        let token;
+        while ((token = this.lexer.nextToken()) !== null) {
+            tokens.push(token);
+        }
+        return tokens;
+    }
+}
+
+/**
+ * Parser module - handles syntax analysis
+ */
+export class MimoParser {
+    constructor(tokens, filePath = '/playground.mimo', errorHandler = null) {
+        this.tokens = tokens;
+        this.filePath = filePath;
+        this.parser = new Parser(tokens, filePath);
+        if (errorHandler) {
+            this.parser.setErrorHandler(errorHandler);
+        }
+    }
+
+    parse() {
+        return this.parser.parse();
+    }
+}
+
+/**
+ * AST Hook Manager - manages AST interception callbacks
+ */
+export class ASTHookManager {
+    constructor() {
+        this.hooks = [];
+    }
+
+    /**
+     * Register a callback to receive the AST
+     * @param {Function} callback - Function that receives (ast, filePath) as parameters
+     * @param {string} [name] - Optional name for the hook
+     */
+    registerHook(callback, name = null) {
+        if (typeof callback !== 'function') {
+            throw new Error('AST hook must be a function');
+        }
+        
+        const hook = {
+            callback,
+            name: name || `hook_${this.hooks.length}`,
+            id: Date.now() + Math.random()
+        };
+        
+        this.hooks.push(hook);
+        return hook.id;
+    }
+
+    /**
+     * Unregister a hook by ID
+     * @param {string|number} hookId - The ID returned by registerHook
+     */
+    unregisterHook(hookId) {
+        this.hooks = this.hooks.filter(hook => hook.id !== hookId);
+    }
+
+    /**
+     * Unregister all hooks with a specific name
+     * @param {string} name - The name of hooks to remove
+     */
+    unregisterHooksByName(name) {
+        this.hooks = this.hooks.filter(hook => hook.name !== name);
+    }
+
+    /**
+     * Clear all registered hooks
+     */
+    clearHooks() {
+        this.hooks = [];
+    }
+
+    /**
+     * Execute all registered hooks with the AST
+     * @param {Object} ast - The parsed AST
+     * @param {string} filePath - The file path
+     */
+    executeHooks(ast, filePath) {
+        for (const hook of this.hooks) {
+            try {
+                hook.callback(ast, filePath);
+            } catch (error) {
+                console.error(`Error in AST hook '${hook.name}':`, error);
+            }
+        }
+    }
+
+    /**
+     * Get list of registered hooks
+     */
+    getHooks() {
+        return this.hooks.map(hook => ({
+            id: hook.id,
+            name: hook.name
+        }));
+    }
+}
+
+/**
+ * Main Mimo class with modular design and AST interception
+ */
+export class Mimo {
+    constructor(adapter, options = {}) {
+        if (!adapter) {
+            throw new Error("Mimo constructor requires an adapter object.");
+        }
+        
+        this.interpreter = new Interpreter(adapter);
+        this.astHookManager = new ASTHookManager();
+        
+        // Configuration options
+        this.options = {
+            enableASTHooks: options.enableASTHooks !== false, 
+            throwOnHookError: options.throwOnHookError || false,
+            ...options
+        };
+    }
+
+    /**
+     * Register an AST hook
+     * @param {Function} callback - Function that receives (ast, filePath)
+     * @param {string} [name] - Optional name for the hook
+     * @returns {string|number} Hook ID for later removal
+     */
+    onAST(callback, name) {
+        return this.astHookManager.registerHook(callback, name);
+    }
+
+    /**
+     * Remove an AST hook by ID
+     * @param {string|number} hookId - The hook ID
+     */
+    offAST(hookId) {
+        this.astHookManager.unregisterHook(hookId);
+    }
+
+    /**
+     * Get the AST hook manager for advanced hook management
+     */
+    getASTHookManager() {
+        return this.astHookManager;
+    }
+
+    /**
+     * Tokenize source code
+     * @param {string} source - The source code
+     * @param {string} [filePath] - Optional file path
+     * @returns {Array} Array of tokens
+     */
+    tokenize(source, filePath = '/playground.mimo') {
+        const tokenizer = new MimoTokenizer(source, filePath);
+        return tokenizer.tokenize();
+    }
+
+    /**
+     * Parse tokens into an AST
+     * @param {Array} tokens - Array of tokens
+     * @param {string} [filePath] - Optional file path
+     * @returns {Object} The parsed AST
+     */
+    parse(tokens, filePath = '/playground.mimo') {
+        const parser = new MimoParser(tokens, filePath, this.interpreter.errorHandler);
+        this.interpreter.errorHandler.addSourceFile(filePath, ''); // Add empty source for now
+        return parser.parse();
+    }
+
+    /**
+     * Parse source code directly into an AST
+     * @param {string} source - The source code
+     * @param {string} [filePath] - Optional file path
+     * @returns {Object} The parsed AST
+     */
+    parseSource(source, filePath = '/playground.mimo') {
+        const tokens = this.tokenize(source, filePath);
+        this.interpreter.errorHandler.addSourceFile(filePath, source);
+        const parser = new MimoParser(tokens, filePath, this.interpreter.errorHandler);
+        const ast = parser.parse();
+        
+        // Execute AST hooks if enabled
+        if (this.options.enableASTHooks) {
+            this.astHookManager.executeHooks(ast, filePath);
+        }
+        
+        return ast;
+    }
+
+    /**
+     * Run source code with full pipeline
+     * @param {string} source - The source code
+     * @param {string} [filePath] - Optional file path
+     * @returns {*} The execution result
+     */
+    run(source, filePath = '/playground.mimo') {
+        const effectivePath = filePath;
+
+        try {
+            // Tokenize
+            const tokens = this.tokenize(source, effectivePath);
+            
+            // Parse and get AST
+            const ast = this.parseSource(source, effectivePath);
+
+            // Interpret
+            const result = this.interpreter.interpret(ast, effectivePath);
+
+            return result;
+
+        } catch (error) {
+            if (error instanceof MimoError) {
+                throw error.format(this.interpreter.errorHandler.getLine(error.location.file, error.location.line));
+            } else {
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * Run pre-parsed AST
+     * @param {Object} ast - The parsed AST
+     * @param {string} [filePath] - Optional file path
+     * @returns {*} The execution result
+     */
+    runAST(ast, filePath = '/playground.mimo') {
+        try {
+            return this.interpreter.interpret(ast, filePath);
+        } catch (error) {
+            if (error instanceof MimoError) {
+                throw error.format(this.interpreter.errorHandler.getLine(error.location.file, error.location.line));
+            } else {
+                throw error;
+            }
+        }
+    }
+}
+
+// Export all classes and modules
+export { Interpreter } from './interpreter/index.js';
+export { Lexer } from './lexer/Lexer.js';
+export { Parser } from './parser/Parser.js';
+export { MimoError } from './interpreter/MimoError.js';
+export { Linter } from './tools/lint/Linter.js';
+export { PrettyPrinter } from './tools/PrettyPrinter.js';
+
+const DEFAULT_LINT_RULES = {
+    'no-unused-vars': true,
+    'prefer-const': true,
+    'no-magic-numbers': false
+};
+
+export function lintSource(source, filePath = '/playground.mimo', rules = {}) {
+    const enabledRules = { ...DEFAULT_LINT_RULES, ...rules };
+    
+    try {
+        const lexer = new Lexer(source, filePath);
+        const tokens = [];
+        let token;
+        while ((token = lexer.nextToken()) !== null) {
+            tokens.push(token);
+        }
+        
+        const parser = new Parser(tokens, filePath);
+        const ast = parser.parse();
+        
+        const linter = new Linter({ rules: enabledRules });
+        const messages = linter.verify(ast, source, filePath);
+        
+        return { 
+            ok: true, 
+            file: filePath,
+            messages: messages.map(msg => ({
+                line: msg.line,
+                column: msg.column,
+                endColumn: msg.endColumn,
+                message: msg.message,
+                ruleId: msg.ruleId,
+                severity: 'warning'
+            }))
+        };
+    } catch (err) {
+        // Convert syntax/parse errors into lint diagnostics
+        return { 
+            ok: false, 
+            file: filePath,
+            error: {
+                message: err.message,
+                line: err.location?.line || 1,
+                column: err.location?.column || 1
+            },
+            messages: [{
+                line: err.location?.line || 1,
+                column: err.location?.column || 1,
+                endColumn: (err.location?.column || 1) + 1,
+                message: err.message,
+                ruleId: 'syntax-error',
+                severity: 'error'
+            }]
+        };
+    }
+}
+
+export function formatSource(source) {
+    try {
+        // Extract comments from raw source (formatter-only path)
+        const { comments } = extractComments(source);
+
+        const lexer = new Lexer(source, '/format.mimo');
+        const tokens = [];
+        let token;
+        while ((token = lexer.nextToken()) !== null) {
+            tokens.push(token);
+        }
+
+        const parser = new Parser(tokens, '/format.mimo');
+        const ast = parser.parse();
+
+        // Attach extracted comments to AST nodes
+        attachComments(ast, comments);
+
+        const printer = new PrettyPrinter();
+        // A8: format() already normalises the trailing newline
+        const formatted = printer.format(ast);
+
+        return {
+            ok: true,
+            formatted,
+        };
+    } catch (err) {
+        return {
+            ok: false,
+            error: err.message,
+        };
+    }
+}

package/interpreter/BuiltinFunction.js

@@ -0,0 +1,32 @@
+export class BuiltinFunction {
+  constructor(name, implementation, arity) {
+    this.name = name;
+    this.implementation = implementation;
+    this.arity = arity;
+  }
+
+  call(interpreter, args, callNode) { // Add callNode parameter
+    // Handle variable arity functions (arity can be an array [min, max])
+    if (Array.isArray(this.arity)) {
+      const [min, max] = this.arity;
+      if (args.length < min || args.length > max) {
+        throw interpreter.errorHandler.createRuntimeError(
+          `Built-in function '${this.name}' expects ${min}-${max} arguments but received ${args.length}.`,
+          callNode,
+          'BUILTIN001',
+          `Check the arguments provided to built-in function '${this.name}'.`
+        );
+      }
+    } else {
+      if (args.length !== this.arity) {
+        throw interpreter.errorHandler.createRuntimeError(
+          `Built-in function '${this.name}' expects ${this.arity} arguments but received ${args.length}.`,
+          callNode,
+          'BUILTIN001',
+          `Check the arguments provided to built-in function '${this.name}'.`
+        );
+      }
+    }
+    return this.implementation(args, interpreter, callNode); // Pass callNode to implementation
+  }
+}