mimo-lang 1.1.1 → 2.0.6

package/tools/lint/config.js

@@ -0,0 +1,114 @@
+/**
+ * tools/lint/config.js
+ *
+ * Loads per-project lint configuration from a `.mimorc` file.
+ *
+ * File format (JSON):
+ * {
+ *   "rules": {
+ *     "no-unused-vars": true,
+ *     "prefer-const": false,
+ *     "no-magic-numbers": { "severity": "error", "allow": [0, 1, 2] },
+ *     "max-depth": { "max": 4 }
+ *   }
+ * }
+ *
+ * The resolved config is merged in this priority order (highest wins):
+ *   CLI --rule flags  >  .mimorc  >  DEFAULT_RULES in linter.js
+ *
+ * loadConfig() is designed to be safe in non-Node environments (bundlers,
+ * playground): it accepts an optional `readFileFn` so callers can inject
+ * a filesystem reader.  When no reader is provided it returns an empty
+ * config object (no file system access attempted).
+ */
+
+/**
+ * Attempt to load and parse a `.mimorc` file located at `configPath`.
+ *
+ * @param {string} configPath - Absolute path to the `.mimorc` file.
+ * @param {Function|null} readFileFn - A sync `(path) => string` reader,
+ *   e.g. `(p) => fs.readFileSync(p, 'utf-8')`.  Pass `null` or omit to
+ *   skip file I/O (safe for bundled/browser environments).
+ * @returns {{ rules: Object }} Parsed config, or `{ rules: {} }` on any
+ *   failure (missing file, bad JSON, wrong environment).
+ */
+export function loadConfig(configPath, readFileFn = null) {
+    if (typeof readFileFn !== 'function') {
+        return { rules: {} };
+    }
+
+    let raw;
+    try {
+        raw = readFileFn(configPath);
+    } catch {
+        // File does not exist or is unreadable — silently return empty config
+        return { rules: {} };
+    }
+
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (e) {
+        throw new Error(`.mimorc: invalid JSON — ${e.message}`);
+    }
+
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('.mimorc: root must be a JSON object');
+    }
+
+    const rules = parsed.rules;
+    if (rules !== undefined && (typeof rules !== 'object' || Array.isArray(rules))) {
+        throw new Error('.mimorc: "rules" must be an object');
+    }
+
+    return { rules: rules || {} };
+}
+
+/**
+ * Merge rule configs in priority order.
+ * Later arguments take precedence over earlier ones.
+ *
+ * Each argument is a `{ ruleId: true | false | {...options} }` map.
+ *
+ * @param {...Object} layers
+ * @returns {Object}
+ */
+export function mergeRuleConfigs(...layers) {
+    const result = {};
+    for (const layer of layers) {
+        if (!layer || typeof layer !== 'object') continue;
+        for (const [ruleId, value] of Object.entries(layer)) {
+            result[ruleId] = value;
+        }
+    }
+    return result;
+}
+
+/**
+ * Find the `.mimorc` file by walking up from `startDir` to `rootDir`.
+ * Returns the path of the first `.mimorc` found, or `null`.
+ *
+ * @param {string} startDir
+ * @param {string} rootDir
+ * @param {Function} readFileFn - Same sync reader as in loadConfig().
+ * @param {Function} pathJoinFn - `(a, b) => string` path joiner.
+ * @returns {string|null}
+ */
+export function findConfigFile(startDir, rootDir, readFileFn, pathJoinFn) {
+    if (typeof readFileFn !== 'function' || typeof pathJoinFn !== 'function') return null;
+
+    let dir = startDir;
+    while (true) {
+        const candidate = pathJoinFn(dir, '.mimorc');
+        try {
+            readFileFn(candidate);
+            return candidate; // readable → found
+        } catch {
+            // not here
+        }
+        const parent = pathJoinFn(dir, '..');
+        if (parent === dir || dir === rootDir) break;
+        dir = parent;
+    }
+    return null;
+}

package/tools/lint/rules/consistent-return.js

@@ -0,0 +1,62 @@
+/**
+ * consistent-return
+ *
+ * Requires that functions either always return a value, or never return a
+ * value.  Mixing `return` (bare) and `return <expr>` in the same function
+ * is confusing and often a bug.
+ *
+ * Uses entry/exit listeners to track per-function state on a stack.
+ */
+
+export const consistentReturn = {
+    meta: {
+        type: 'problem',
+        description: 'Require consistent use of `return` in functions',
+        defaultSeverity: 'warning',
+    },
+    create: (context) => {
+        /**
+         * Stack of per-function frames.
+         * Each frame: { node, hasValueReturn: bool, hasVoidReturn: bool }
+         */
+        const stack = [];
+
+        function enterFunction(node) {
+            stack.push({ node, hasValueReturn: false, hasVoidReturn: false });
+        }
+
+        function exitFunction() {
+            const frame = stack.pop();
+            if (!frame) return;
+
+            if (frame.hasValueReturn && frame.hasVoidReturn) {
+                const label = frame.node.name
+                    ? `Function '${frame.node.name}'`
+                    : 'Anonymous function';
+                context.report({
+                    node: frame.node,
+                    message: `${label} inconsistently returns a value — some paths return a value and others do not.`,
+                });
+            }
+        }
+
+        return {
+            FunctionDeclaration:          enterFunction,
+            'FunctionDeclaration:exit':   exitFunction,
+
+            AnonymousFunction:            enterFunction,
+            'AnonymousFunction:exit':     exitFunction,
+
+            ReturnStatement: (node) => {
+                const frame = stack[stack.length - 1];
+                if (!frame) return;
+
+                if (node.argument !== null && node.argument !== undefined) {
+                    frame.hasValueReturn = true;
+                } else {
+                    frame.hasVoidReturn = true;
+                }
+            },
+        };
+    },
+};

package/tools/lint/rules/max-depth.js

@@ -0,0 +1,56 @@
+/**
+ * max-depth
+ *
+ * Enforces a maximum depth for nested block-creating constructs (if, while,
+ * for, loop, match/case, try).  Helps prevent deeply-nested, hard-to-read code.
+ *
+ * Options:
+ *   max {number}  — maximum allowed nesting depth (default: 4)
+ *
+ * Example config:
+ *   "max-depth": { "max": 3 }
+ */
+
+/** Node types that increase the nesting depth tracked by LinterScopeTracker. */
+const BLOCK_TYPES = new Set([
+    'IfStatement',
+    'WhileStatement',
+    'ForStatement',
+    'LoopStatement',
+    'MatchStatement',
+    'CaseClause',
+    'TryStatement',
+]);
+
+export const maxDepth = {
+    meta: {
+        type: 'suggestion',
+        description: 'Enforce a maximum depth for nested blocks',
+        defaultSeverity: 'warning',
+    },
+    create: (context) => {
+        const maxAllowed = typeof context.options?.max === 'number'
+            ? context.options.max
+            : 4;
+
+        return {
+            // Use a generic visitor that fires for all block-creating node types.
+            // We check the depth *after* enterNode has already incremented it,
+            // so the current depth equals the depth of this node.
+            ...Object.fromEntries(
+                [...BLOCK_TYPES].map(nodeType => [
+                    nodeType,
+                    (node) => {
+                        const depth = context.getScope().getCurrentDepth();
+                        if (depth > maxAllowed) {
+                            context.report({
+                                node,
+                                message: `Block nesting depth (${depth}) exceeds the maximum allowed (${maxAllowed}).`,
+                            });
+                        }
+                    },
+                ])
+            ),
+        };
+    },
+};

package/tools/lint/rules/no-empty-function.js

@@ -0,0 +1,45 @@
+/**
+ * no-empty-function
+ *
+ * Disallows function declarations and anonymous functions whose body contains
+ * no executable statements.
+ *
+ * An empty body is defined as `body` being an empty array, or an array that
+ * contains only comment-like nodes (nodes without a `type` property, e.g.
+ * null/undefined elements).  A body with any typed AST node is not empty.
+ */
+
+function isEmptyBody(body) {
+    if (!Array.isArray(body) || body.length === 0) return true;
+    // Consider the body non-empty if at least one element is a real AST node.
+    return !body.some(item => item && typeof item === 'object' && item.type);
+}
+
+export const noEmptyFunction = {
+    meta: {
+        type: 'suggestion',
+        description: 'Disallow empty function bodies',
+        defaultSeverity: 'warning',
+    },
+    create: (context) => {
+        return {
+            FunctionDeclaration: (node) => {
+                if (isEmptyBody(node.body)) {
+                    context.report({
+                        node,
+                        message: `Function '${node.name}' has an empty body.`,
+                    });
+                }
+            },
+
+            AnonymousFunction: (node) => {
+                if (isEmptyBody(node.body)) {
+                    context.report({
+                        node,
+                        message: 'Anonymous function has an empty body.',
+                    });
+                }
+            },
+        };
+    },
+};

package/tools/lint/rules/no-magic-numbers.js

@@ -0,0 +1,46 @@
+// Default set of numbers that are commonly allowed (and not "magic").
+// This can be extended via rule options: { allow: [0, 1, 2, ...] }
+const DEFAULT_ALLOWED = [0, 1, -1, 10, 100, 1000];
+
+export const noMagicNumbers = {
+    meta: {
+        type: 'suggestion',
+        description: 'Disallow magic numbers - prefer named constants',
+        defaultSeverity: 'warning',
+    },
+    create: (context) => {
+        // Merge default allowed list with any user-supplied values.
+        const allowList = Array.isArray(context.options?.allow)
+            ? new Set([...DEFAULT_ALLOWED, ...context.options.allow])
+            : new Set(DEFAULT_ALLOWED);
+
+        return {
+            // This listener will run for every Literal node the linter encounters.
+            Literal: (node) => {
+                // We only care about numeric literals.
+                if (typeof node.value !== 'number') {
+                    return;
+                }
+                
+                // Ignore numbers that are commonly used and not considered "magic".
+                if (allowList.has(node.value)) {
+                    return;
+                }
+                
+                // Get the parent node to check the context.
+                const parent = context.getParent(node);
+
+                // Allow numbers if they are the direct value of a `const` declaration.
+                if (parent?.type === 'VariableDeclaration' && parent.kind === 'const') {
+                    return;
+                }
+                
+                // If it's a "magic number", report it.
+                context.report({
+                    node: node,
+                    message: `Magic number '${node.value}' detected. Consider declaring it as a named constant.`,
+                });
+            }
+        };
+    }
+};

package/tools/lint/rules/no-shadow.js

@@ -0,0 +1,113 @@
+/**
+ * no-shadow
+ *
+ * Disallows variable or function declarations that shadow a binding from an
+ * outer scope.  Shadowing makes code harder to reason about and can hide bugs.
+ *
+ * Checks:
+ *   - `let` / `const` / `global` VariableDeclarations
+ *   - FunctionDeclarations (the function name itself)
+ *   - Function parameters (declared inside FunctionDeclaration / AnonymousFunction)
+ */
+
+export const noShadow = {
+    meta: {
+        type: 'problem',
+        description: 'Disallow variable declarations that shadow variables in outer scopes',
+        defaultSeverity: 'warning',
+    },
+    create: (context) => {
+        /**
+         * Check whether `name` already exists in any *ancestor* scope (not the
+         * current scope, since the declaration hasn't been committed yet when the
+         * node-entry listener fires for VariableDeclaration, but the scope tracker
+         * has already called enterNode which calls declare() — so we look for
+         * an owning scope that is an ancestor of the current scope).
+         */
+        function isShadowing(name) {
+            const tracker = context.getScope();
+            const current = tracker.getCurrentScope();
+
+            // Walk up the parent chain looking for the binding.
+            let ancestor = current.parent;
+            while (ancestor) {
+                if (ancestor.variables.has(name)) return true;
+                ancestor = ancestor.parent;
+            }
+            return false;
+        }
+
+        return {
+            VariableDeclaration: (node) => {
+                if (typeof node.identifier !== 'string') return; // destructuring — skip
+                if (node.kind === 'set') return; // re-assignment, not a new binding
+
+                if (isShadowing(node.identifier)) {
+                    context.report({
+                        node,
+                        message: `'${node.identifier}' shadows a variable from an outer scope.`,
+                    });
+                }
+            },
+
+            FunctionDeclaration: (node) => {
+                // The function name is declared in the parent scope, so we check
+                // whether any *grandparent-or-higher* scope owns the same name.
+                const tracker = context.getScope();
+                const current = tracker.getCurrentScope(); // already the new fn scope
+
+                // Function name lives in current.parent (the scope that surrounds the fn).
+                // We want to know if current.parent.parent or higher has the same name.
+                let ancestor = current.parent?.parent;
+                while (ancestor) {
+                    if (ancestor.variables.has(node.name)) {
+                        context.report({
+                            node,
+                            message: `Function '${node.name}' shadows a variable from an outer scope.`,
+                        });
+                        break;
+                    }
+                    ancestor = ancestor.parent;
+                }
+
+                // Also check parameters — they are declared in the function's own scope
+                // (current), so check current.parent and above.
+                const paramScope = current.parent;
+                (node.params || []).forEach(param => {
+                    let a = paramScope;
+                    while (a) {
+                        if (a.variables.has(param.name)) {
+                            context.report({
+                                node: param,
+                                message: `Parameter '${param.name}' shadows a variable from an outer scope.`,
+                            });
+                            break;
+                        }
+                        a = a.parent;
+                    }
+                });
+            },
+
+            AnonymousFunction: (node) => {
+                // Parameters in the function's scope — check parent and above.
+                const tracker = context.getScope();
+                const current = tracker.getCurrentScope(); // the anonymous fn scope
+                const paramScope = current.parent;
+
+                (node.params || []).forEach(param => {
+                    let a = paramScope;
+                    while (a) {
+                        if (a.variables.has(param.name)) {
+                            context.report({
+                                node: param,
+                                message: `Parameter '${param.name}' shadows a variable from an outer scope.`,
+                            });
+                            break;
+                        }
+                        a = a.parent;
+                    }
+                });
+            },
+        };
+    },
+};

package/tools/lint/rules/no-unused-vars.js

@@ -0,0 +1,26 @@
+export const noUnusedVars = {
+    meta: {
+        type: 'suggestion',
+        description: 'Disallow unused variables and function parameters',
+    },
+    create: (context) => {
+        return {
+            // This runs once after the entire file has been traversed.
+            Program_exit: (programNode) => {
+                const unused = context.getScope().getUnusedVariables();
+                unused.forEach(variable => {
+                    let message;
+                    if (variable.kind === 'parameter') {
+                        message = `Parameter '${variable.name}' is defined but never used.`;
+                    } else {
+                        message = `Variable '${variable.name}' is defined but never used.`;
+                    }
+                    context.report({
+                        node: variable.node,
+                        message: message,
+                    });
+                });
+            }
+        };
+    }
+};

package/tools/lint/rules/prefer-const.js

@@ -0,0 +1,19 @@
+export const preferConst = {
+    meta: {
+        type: 'suggestion',
+        description: 'Suggest using `const` for variables that are never reassigned.',
+    },
+    create: (context) => {
+        return {
+            Program_exit: (programNode) => {
+                const unmutatedLets = context.getScope().getUnmutatedLets();
+                unmutatedLets.forEach(variable => {
+                    context.report({
+                        node: variable.node,
+                        message: `Variable '${variable.name}' is never reassigned. Use 'const' instead.`,
+                    });
+                });
+            }
+        };
+    }
+};