mimo-lang 1.1.1 → 2.0.6

package/tools/format/config.js

@@ -0,0 +1,107 @@
+/**
+ * tools/format/config.js
+ *
+ * Loads and merges formatter options from .mimorc or a caller-supplied object.
+ * Uses an injected readFileFn so this module is safe in bundled/browser environments.
+ *
+ * .mimorc format (JSON):
+ *   {
+ *     "format": {
+ *       "indentSize": 4,
+ *       "useTabs": false,
+ *       "quoteStyle": "double",
+ *       "maxInlineArrayLength": 100,
+ *       "maxInlineObjectLength": 80
+ *     }
+ *   }
+ */
+
+export const DEFAULT_FORMAT_OPTIONS = {
+    indentSize: 4,
+    useTabs: false,
+    quoteStyle: 'double',       // 'double' | 'single'
+    maxInlineArrayLength: 100,
+    maxInlineObjectLength: 80,
+};
+
+/**
+ * Find the nearest .mimorc file by walking up from startDir.
+ * @param {string} startDir   Absolute directory path to start searching from.
+ * @param {Function} existsFn (path: string) => boolean
+ * @param {Function} joinFn   path.join equivalent
+ * @param {Function} dirnameFn path.dirname equivalent
+ * @returns {string|null} Absolute path to .mimorc, or null if not found.
+ */
+export function findConfigFile(startDir, existsFn, joinFn, dirnameFn) {
+    let dir = startDir;
+    while (true) {
+        const candidate = joinFn(dir, '.mimorc');
+        if (existsFn(candidate)) return candidate;
+        const parent = dirnameFn(dir);
+        if (parent === dir) return null; // filesystem root
+        dir = parent;
+    }
+}
+
+/**
+ * Load and parse a .mimorc file, returning only the `format` section.
+ * @param {string} configPath  Absolute path to .mimorc.
+ * @param {Function} readFileFn (path: string) => string — injected so this works in bundlers.
+ * @returns {object} Raw format options from the config file (may be partial).
+ */
+export function loadConfig(configPath, readFileFn) {
+    try {
+        const raw = readFileFn(configPath);
+        const parsed = JSON.parse(raw);
+        return parsed.format ?? {};
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Merge format options: defaults < config file < caller-supplied overrides.
+ * All values are validated; unknown keys and invalid values are silently ignored.
+ * @param {object} fromConfig   Options from .mimorc (may be partial or empty).
+ * @param {object} fromCaller   Options passed directly by the caller (highest priority).
+ * @returns {object} Fully-resolved format options object.
+ */
+export function mergeOptions(fromConfig = {}, fromCaller = {}) {
+    const merged = { ...DEFAULT_FORMAT_OPTIONS };
+
+    // Apply config-file values
+    if (typeof fromConfig.indentSize === 'number' && fromConfig.indentSize > 0) {
+        merged.indentSize = fromConfig.indentSize;
+    }
+    if (typeof fromConfig.useTabs === 'boolean') {
+        merged.useTabs = fromConfig.useTabs;
+    }
+    if (fromConfig.quoteStyle === 'single' || fromConfig.quoteStyle === 'double') {
+        merged.quoteStyle = fromConfig.quoteStyle;
+    }
+    if (typeof fromConfig.maxInlineArrayLength === 'number' && fromConfig.maxInlineArrayLength > 0) {
+        merged.maxInlineArrayLength = fromConfig.maxInlineArrayLength;
+    }
+    if (typeof fromConfig.maxInlineObjectLength === 'number' && fromConfig.maxInlineObjectLength > 0) {
+        merged.maxInlineObjectLength = fromConfig.maxInlineObjectLength;
+    }
+
+    // Apply caller-supplied overrides (same validation)
+    if (typeof fromCaller.indentSize === 'number' && fromCaller.indentSize > 0) {
+        merged.indentSize = fromCaller.indentSize;
+    }
+    if (typeof fromCaller.useTabs === 'boolean') {
+        merged.useTabs = fromCaller.useTabs;
+    }
+    if (fromCaller.quoteStyle === 'single' || fromCaller.quoteStyle === 'double') {
+        merged.quoteStyle = fromCaller.quoteStyle;
+    }
+    if (typeof fromCaller.maxInlineArrayLength === 'number' && fromCaller.maxInlineArrayLength > 0) {
+        merged.maxInlineArrayLength = fromCaller.maxInlineArrayLength;
+    }
+    if (typeof fromCaller.maxInlineObjectLength === 'number' && fromCaller.maxInlineObjectLength > 0) {
+        merged.maxInlineObjectLength = fromCaller.maxInlineObjectLength;
+    }
+
+    return merged;
+}

package/tools/formatter.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'url';
+import { Parser } from '../parser/Parser.js';
+import { Lexer } from '../lexer/Lexer.js';
+import { PrettyPrinter } from './format/Printer.js';
+import { findConfigFile, loadConfig, mergeOptions } from './format/config.js';
+import { extractComments } from './format/CommentLexer.js';
+import { attachComments } from './format/CommentAttacher.js';
+
+// ── Config resolution helpers (Node-only, safe to tree-shake in browser builds) ──
+
+function _resolveOptions(filePath, callerOptions = {}) {
+    try {
+        const startDir = path.dirname(path.resolve(filePath));
+        const configPath = findConfigFile(
+            startDir,
+            fs.existsSync,
+            path.join,
+            path.dirname,
+        );
+        const fromConfig = configPath
+            ? loadConfig(configPath, (p) => fs.readFileSync(p, 'utf-8'))
+            : {};
+        return mergeOptions(fromConfig, callerOptions);
+    } catch {
+        return mergeOptions({}, callerOptions);
+    }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Formats Mimo source code from a string.
+ * Comments in the source are preserved in the output.
+ *
+ * @param {string} source     The Mimo source code to format.
+ * @param {string} [filePath] Optional file path used for error reporting and config lookup.
+ * @param {object} [options]  Optional format options (override .mimorc).
+ * @returns {string} The formatted source code.
+ */
+export function formatSource(source, filePath = 'snippet.mimo', options = {}) {
+    // 1. Extract comments from raw source (formatter-only path, main Lexer untouched)
+    const { comments } = extractComments(source);
+
+    // 2. Lex + parse (comments are silently dropped by the main Lexer, as always)
+    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();
+
+    // 3. Re-attach extracted comments to AST nodes
+    attachComments(ast, comments);
+
+    // 4. Pretty-print with resolved options
+    const resolved = _resolveOptions(filePath, options);
+    const printer = new PrettyPrinter(resolved);
+    return printer.format(ast);
+}
+
+/**
+ * Formats a Mimo file on disk.
+ * @param {string} filePath   Path to the file.
+ * @param {object} [options]  Options: { write, check, quiet, ...formatOptions }
+ * @returns {{ ok: boolean, changed: boolean, error?: Error }}
+ */
+export function formatFile(filePath, options = {}) {
+    const { write = false, check = false, quiet = false, ...formatOptions } = options;
+    if (!quiet) console.log(`Formatting ${filePath}...`);
+
+    try {
+        const source = fs.readFileSync(filePath, 'utf-8');
+        const formattedSource = formatSource(source, filePath, formatOptions);
+        const changed = formattedSource !== source;
+
+        if (write) {
+            if (changed) {
+                fs.writeFileSync(filePath, formattedSource, 'utf-8');
+                if (!quiet) console.log('✅ File formatted successfully.');
+            } else if (!quiet) {
+                console.log('✅ Already formatted.');
+            }
+            return { ok: true, changed };
+        }
+
+        if (check) {
+            if (changed) {
+                console.log(`❌ ${filePath} is not formatted.`);
+            } else if (!quiet) {
+                console.log(`✅ ${filePath} is formatted.`);
+            }
+            return { ok: true, changed };
+        }
+
+        // Preview mode (no flag)
+        console.log('\n--- Formatted Output ---');
+        console.log(formattedSource);
+        console.log('--- End Output ---');
+        console.log('\nUse --write flag to apply changes to the file.');
+        return { ok: true, changed };
+    } catch (err) {
+        console.error(`❌ Error formatting file ${filePath}:`);
+        if (err.format) {
+            const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : '';
+            const lines = content.split('\n');
+            const snippet = lines[(err.location?.line ?? 1) - 1] || '';
+            console.error(err.format(snippet));
+        } else {
+            console.error(err.message);
+        }
+        return { ok: false, changed: false, error: err };
+    }
+}
+
+// ── Stdin helper ──────────────────────────────────────────────────────────────
+
+async function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf-8');
+        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('end', () => { resolve(data); });
+    });
+}
+
+// ── CLI entry point ───────────────────────────────────────────────────────────
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const args = process.argv.slice(2);
+    const shouldWrite = args.includes('--write');
+    const shouldCheck = args.includes('--check');
+    const quiet = args.includes('--quiet');
+    const filePaths = args.filter(arg => !arg.startsWith('--'));
+
+    if (filePaths.length === 0 || filePaths.includes('-')) {
+        if (!process.stdin.isTTY || filePaths.includes('-')) {
+            readStdin().then(source => {
+                try {
+                    const formatted = formatSource(source, 'stdin');
+                    process.stdout.write(formatted);
+                } catch (err) {
+                    console.error(err.message);
+                    process.exit(1);
+                }
+            });
+        } else {
+            console.error('Error: No file path provided and STDIN is a TTY.');
+            console.log('Usage: node tools/formatter.js [--write|--check] [--quiet] <file1.mimo> ...');
+            console.log('Or pipe source to stdin: echo "..." | node tools/formatter.js');
+            process.exit(1);
+        }
+    } else {
+        let hadErrors = false;
+        let hadUnformatted = false;
+
+        filePaths.forEach(p => {
+            const result = formatFile(p, { write: shouldWrite, check: shouldCheck, quiet });
+            if (!result.ok) hadErrors = true;
+            if (shouldCheck && result.changed) hadUnformatted = true;
+        });
+
+        if (hadErrors || hadUnformatted) process.exit(1);
+    }
+}

package/tools/lint/Linter.js

@@ -0,0 +1,391 @@
+// tools/lint/Linter.js
+
+// Import all rules from the rules directory.
+// New rules must be added here manually (keeps bundler compatibility).
+import { noUnusedVars }    from './rules/no-unused-vars.js';
+import { preferConst }     from './rules/prefer-const.js';
+import { noMagicNumbers }  from './rules/no-magic-numbers.js';
+import { noEmptyFunction } from './rules/no-empty-function.js';
+import { maxDepth }        from './rules/max-depth.js';
+import { noShadow }        from './rules/no-shadow.js';
+import { consistentReturn } from './rules/consistent-return.js';
+
+/**
+ * Central registry of all available lint rules.
+ *
+ * Keys are rule IDs (used in config and CLI flags).
+ * Values are rule modules that implement { meta, create(context) }.
+ *
+ * To add a new rule:
+ *   1. Create tools/lint/rules/<rule-id>.js
+ *   2. Add an import above
+ *   3. Add an entry here
+ */
+export const RULES = {
+    'no-unused-vars':    noUnusedVars,
+    'prefer-const':      preferConst,
+    'no-magic-numbers':  noMagicNumbers,
+    'no-empty-function': noEmptyFunction,
+    'max-depth':         maxDepth,
+    'no-shadow':         noShadow,
+    'consistent-return': consistentReturn,
+};
+
+// ---------------------------------------------------------------------------
+// Scope model
+// ---------------------------------------------------------------------------
+
+class LinterScope {
+    constructor(parent) {
+        this.parent = parent;
+        this.children = [];
+        /** @type {Map<string, { name, kind, node, used, reassigned, isExported }>} */
+        this.variables = new Map();
+        if (parent) parent.children.push(this);
+    }
+
+    declare(name, info) {
+        this.variables.set(name, { name, ...info, used: false, reassigned: false });
+    }
+
+    markAsUsed(name) {
+        if (this.variables.has(name)) {
+            this.variables.get(name).used = true;
+        } else if (this.parent) {
+            this.parent.markAsUsed(name);
+        }
+    }
+
+    markAsReassigned(name) {
+        if (this.variables.has(name)) {
+            this.variables.get(name).reassigned = true;
+        } else if (this.parent) {
+            this.parent.markAsReassigned(name);
+        }
+    }
+
+    resolveVariable(name) {
+        if (this.variables.has(name)) return this.variables.get(name);
+        return this.parent ? this.parent.resolveVariable(name) : null;
+    }
+
+    /** Find which scope actually owns the binding for `name` (not inherited). */
+    owningScope(name) {
+        if (this.variables.has(name)) return this;
+        return this.parent ? this.parent.owningScope(name) : null;
+    }
+
+    getUnusedVariables() {
+        let unused = [];
+        for (const info of this.variables.values()) {
+            if (!info.used && !info.isExported) unused.push(info);
+        }
+        for (const child of this.children) {
+            unused = unused.concat(child.getUnusedVariables());
+        }
+        return unused;
+    }
+
+    getUnmutatedLets() {
+        let unmutated = Array.from(this.variables.values())
+            .filter(info => info.kind === 'let' && !info.reassigned);
+        for (const child of this.children) {
+            unmutated = unmutated.concat(child.getUnmutatedLets());
+        }
+        return unmutated;
+    }
+}
+
+class LinterScopeTracker {
+    constructor() {
+        this.globalScope = new LinterScope(null);
+        this.currentScope = this.globalScope;
+        /** Nesting depth of block-creating nodes (for max-depth rule). */
+        this.currentDepth = 0;
+    }
+
+    enterNode(node, parent) {
+        // ------------------------------------------------------------------
+        // Scope creation
+        // ------------------------------------------------------------------
+        const createsScope =
+            node.type === 'FunctionDeclaration' ||
+            node.type === 'AnonymousFunction';
+
+        const createsBlockScope =
+            node.type === 'ForStatement' ||
+            node.type === 'WhileStatement' ||
+            node.type === 'LoopStatement' ||
+            node.type === 'IfStatement' ||
+            node.type === 'MatchStatement' ||
+            node.type === 'CaseClause' ||
+            node.type === 'TryStatement';
+
+        if (createsScope || createsBlockScope) {
+            this.currentScope = new LinterScope(this.currentScope);
+        }
+
+        if (createsScope) {
+            // Declare parameters in the new function scope
+            (node.params || []).forEach(p =>
+                this.currentScope.declare(p.name, { kind: 'parameter', node: p })
+            );
+            if (node.restParam) {
+                this.currentScope.declare(node.restParam.name, { kind: 'parameter', node: node.restParam });
+            }
+        }
+
+        if (createsBlockScope) {
+            this.currentDepth++;
+        }
+
+        // ------------------------------------------------------------------
+        // Declaration registration
+        // ------------------------------------------------------------------
+        if (node.type === 'VariableDeclaration' && typeof node.identifier === 'string') {
+            if (node.kind === 'set') {
+                const existing = this.currentScope.resolveVariable(node.identifier);
+                if (existing) {
+                    this.currentScope.markAsReassigned(node.identifier);
+                } else {
+                    this.currentScope.declare(node.identifier, {
+                        kind: node.kind,
+                        node,
+                        isExported: node.isExported,
+                    });
+                }
+            } else {
+                this.currentScope.declare(node.identifier, {
+                    kind: node.kind,
+                    node,
+                    isExported: node.isExported,
+                });
+            }
+        }
+
+        if (node.type === 'FunctionDeclaration') {
+            // Function name is declared in the *parent* scope
+            this.currentScope.parent.declare(node.name, {
+                kind: 'function',
+                node,
+                isExported: node.isExported,
+            });
+        }
+
+        if (node.type === 'DestructuringAssignment') {
+            if (node.pattern.type === 'ArrayPattern') {
+                node.pattern.elements.forEach(id =>
+                    this.currentScope.declare(id.name, { kind: 'let', node: id })
+                );
+            } else if (node.pattern.type === 'ObjectPattern') {
+                node.pattern.properties.forEach(id =>
+                    this.currentScope.declare(id.name, { kind: 'let', node: id })
+                );
+            }
+        }
+
+        // ------------------------------------------------------------------
+        // Usage tracking
+        // ------------------------------------------------------------------
+        if (node.type === 'Identifier') {
+            const isDeclarationSite =
+                (parent?.type === 'VariableDeclaration' && parent.identifier === node.name) ||
+                (parent?.type === 'FunctionDeclaration' && parent.name === node.name) ||
+                (parent?.type === 'FunctionDeclaration' && parent.params?.includes(node)) ||
+                (parent?.type === 'AnonymousFunction' && parent.params?.includes(node)) ||
+                (parent?.type === 'FunctionDeclaration' && parent.restParam === node) ||
+                (parent?.type === 'AnonymousFunction' && parent.restParam === node) ||
+                (parent?.type === 'CallStatement' && parent.destination === node);
+
+            if (!isDeclarationSite) {
+                this.currentScope.markAsUsed(node.name);
+            }
+        }
+
+        // A `set` that targets an existing variable is also a reassignment
+        if (node.type === 'VariableDeclaration' && node.kind === 'set' && typeof node.identifier === 'string') {
+            const local = this.currentScope.variables.get(node.identifier);
+            if (!local || local.node !== node) {
+                this.currentScope.markAsReassigned(node.identifier);
+            }
+        }
+    }
+
+    exitNode(node) {
+        const createsScope =
+            node.type === 'FunctionDeclaration' ||
+            node.type === 'AnonymousFunction';
+
+        const createsBlockScope =
+            node.type === 'ForStatement' ||
+            node.type === 'WhileStatement' ||
+            node.type === 'LoopStatement' ||
+            node.type === 'IfStatement' ||
+            node.type === 'MatchStatement' ||
+            node.type === 'CaseClause' ||
+            node.type === 'TryStatement';
+
+        if ((createsScope || createsBlockScope) && this.currentScope.parent) {
+            this.currentScope = this.currentScope.parent;
+        }
+
+        if (createsBlockScope) {
+            this.currentDepth--;
+        }
+    }
+
+    /** Returns the tracker itself so rules can call any public method. */
+    getScope()             { return this; }
+    getUnusedVariables()   { return this.globalScope.getUnusedVariables(); }
+    getUnmutatedLets()     { return this.globalScope.getUnmutatedLets(); }
+    getCurrentScope()      { return this.currentScope; }
+    getCurrentDepth()      { return this.currentDepth; }
+}
+
+// ---------------------------------------------------------------------------
+// Linter
+// ---------------------------------------------------------------------------
+
+export class Linter {
+    /**
+     * @param {Object} options
+     * @param {Object} options.rules  - Map of ruleId → true | false | { severity?, ...options }
+     *   - `true`  : enable with defaults
+     *   - `false` : disable
+     *   - object  : enable with per-rule options; may include `severity: 'error'|'warning'`
+     */
+    constructor(options = {}) {
+        this.messages  = [];
+        this.ancestry  = [];
+        this.ruleConfig = options.rules || {};
+    }
+
+    verify(ast, sourceCode, filePath) {
+        this.messages = [];
+        this.ancestry = [];
+
+        const scopeTracker  = new LinterScopeTracker();
+        const ruleListeners = this.initializeRules(scopeTracker);
+
+        this.traverse(ast, null, ruleListeners, scopeTracker);
+        this.triggerExitListeners(ast, ruleListeners);
+
+        // Sort messages by line then column
+        this.messages.sort((a, b) => a.line - b.line || a.column - b.column);
+
+        return this.messages;
+    }
+
+    // -------------------------------------------------------------------------
+    // Rule initialisation
+    // -------------------------------------------------------------------------
+
+    /**
+     * Resolve the effective config entry for a rule.
+     * Returns `null` if the rule is disabled.
+     * Returns `{ severity, options }` if enabled.
+     */
+    _resolveRuleConfig(ruleId, ruleMeta) {
+        const entry = this.ruleConfig[ruleId];
+
+        // Explicitly disabled
+        if (entry === false) return null;
+
+        // Enabled with defaults
+        if (entry === true || entry === undefined) {
+            const defaultSeverity = (ruleMeta?.defaultSeverity) || 'warning';
+            return { severity: defaultSeverity, options: {} };
+        }
+
+        // Object config: { severity?, ...options }
+        if (typeof entry === 'object') {
+            const { severity, ...options } = entry;
+            const defaultSeverity = (ruleMeta?.defaultSeverity) || 'warning';
+            return { severity: severity || defaultSeverity, options };
+        }
+
+        return null;
+    }
+
+    initializeRules(scopeTracker) {
+        const listeners = {};
+
+        for (const ruleId in RULES) {
+            const ruleModule = RULES[ruleId];
+            const resolved   = this._resolveRuleConfig(ruleId, ruleModule.meta);
+
+            if (!resolved) continue; // disabled
+
+            const context = {
+                getScope:   () => scopeTracker,
+                getParent:  () => this.ancestry[this.ancestry.length - 2] || null,
+                options:    resolved.options,
+                report: (descriptor) => this.report({
+                    ...descriptor,
+                    ruleId,
+                    severity: descriptor.severity || resolved.severity,
+                }),
+            };
+
+            const ruleListeners = ruleModule.create(context);
+
+            for (const event in ruleListeners) {
+                if (!listeners[event]) listeners[event] = [];
+                listeners[event].push(ruleListeners[event]);
+            }
+        }
+
+        return listeners;
+    }
+
+    // -------------------------------------------------------------------------
+    // Reporting
+    // -------------------------------------------------------------------------
+
+    report(descriptor) {
+        const { node, message, ruleId, severity = 'warning' } = descriptor;
+        this.messages.push({
+            ruleId,
+            message,
+            severity,
+            line:      node.line,
+            column:    node.column,
+            endColumn: node.column + (node.length || 1),
+        });
+    }
+
+    // -------------------------------------------------------------------------
+    // Traversal
+    // -------------------------------------------------------------------------
+
+    traverse(node, parent, listeners, scope) {
+        if (!node || typeof node !== 'object' || !node.type) return;
+
+        this.ancestry.push(node);
+        scope.enterNode(node, parent);
+
+        // Fire entry listeners for this node type
+        (listeners[node.type] || []).forEach(fn => fn(node));
+
+        // Recurse into children
+        for (const key in node) {
+            if (key === 'parent') continue;
+            const child = node[key];
+            if (Array.isArray(child)) {
+                child.forEach(item => this.traverse(item, node, listeners, scope));
+            } else if (child && typeof child === 'object' && child.type) {
+                this.traverse(child, node, listeners, scope);
+            }
+        }
+
+        // Fire exit listeners: "NodeType:exit"
+        (listeners[`${node.type}:exit`] || []).forEach(fn => fn(node));
+
+        scope.exitNode(node);
+        this.ancestry.pop();
+    }
+
+    triggerExitListeners(programNode, listeners) {
+        (listeners['Program_exit'] || []).forEach(fn => fn(programNode));
+    }
+}