@blumintinc/eslint-plugin-blumint 1.16.1 → 1.17.0

package/lib/rules/logical-top-to-bottom-grouping.js

@@ -368,6 +368,18 @@ function statementReferencesAny(statement, names) {
     }
     return false;
 }
+/**
+ * Find the index of the first statement that references any of the given names,
+ * searching forward from afterIndex.
+ */
+function findFirstUsageIndex(body, names, afterIndex) {
+    for (let cursor = afterIndex; cursor < body.length; cursor += 1) {
+        if (statementReferencesAny(body[cursor], names)) {
+            return cursor;
+        }
+    }
+    return -1;
+}
 function collectAssignedNamesFromPattern(target, names) {
     if (TYPE_EXPRESSION_WRAPPERS.has(target.type) &&
         'expression' in target) {
@@ -671,10 +683,13 @@ function findEarliestSafeIndex(body, startIndex, dependencies, { allowHooks }) {
 }
 function getStartWithComments(statement, sourceCode) {
     const comments = sourceCode.getCommentsBefore(statement);
-    if (comments.length === 0) {
-        return statement.range[0];
+    const start = comments.length === 0 ? statement.range[0] : comments[0].range[0];
+    const text = sourceCode.getText();
+    let cursor = start - 1;
+    while (cursor >= 0 && (text[cursor] === ' ' || text[cursor] === '\t')) {
+        cursor -= 1;
     }
-    return comments[0].range[0];
+    return cursor + 1;
 }
 function getNextStart(body, index, parent, sourceCode) {
     const nextStatement = body[index + 1];
@@ -907,42 +922,95 @@ function isSiblingSourceDerivation(statement, sourceNodes, sourceDeclarators) {
         return !sourceDeclarators.has(name);
     });
 }
+/**
+ * Restrict late-declaration candidates to simple variables with at most an Identifier or
+ * Literal initializer. This ensures they are pure values that do not have side effects or
+ * change execution order when moved closer to their usage. More complex initializers are
+ * excluded to maintain temporal safety.
+ */
+function isLateDeclarationCandidate(statement) {
+    if (statement.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
+        statement.declarations.length !== 1) {
+        return false;
+    }
+    const [declarator] = statement.declarations;
+    return (declarator.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+        (!declarator.init ||
+            declarator.init.type === utils_1.AST_NODE_TYPES.Identifier ||
+            declarator.init.type === utils_1.AST_NODE_TYPES.Literal));
+}
+const LOOP_TYPES = new Set([
+    utils_1.AST_NODE_TYPES.ForStatement,
+    utils_1.AST_NODE_TYPES.ForInStatement,
+    utils_1.AST_NODE_TYPES.ForOfStatement,
+    utils_1.AST_NODE_TYPES.WhileStatement,
+    utils_1.AST_NODE_TYPES.DoWhileStatement,
+]);
+/**
+ * Treat a loop as an ordering barrier for late-declaration moves when it mutates any
+ * tracked variable inside the loop body.
+ *
+ * Variables that are declared before a loop and mutated inside it (accumulators,
+ * counters, collectors) must remain before the loop so their declaration is visible
+ * across all iterations. Moving them inside would reset them on every iteration,
+ * changing program semantics. This guard applies regardless of whether the variable
+ * is also read after the loop.
+ *
+ * Assumptions:
+ * - nameSet contains the name(s) being tracked for late declaration.
+ * - body is the array of statements in the current block.
+ * - usageIndex is the index of the first statement that references the variable(s).
+ */
+function isMutatedInLoop(body, usageIndex, nameSet) {
+    const firstUsage = body[usageIndex];
+    if (!firstUsage) {
+        return false;
+    }
+    if (!LOOP_TYPES.has(firstUsage.type)) {
+        return false;
+    }
+    return statementMutatesAny(firstUsage, nameSet);
+}
 function handleLateDeclarations(ruleContext, body, parent) {
     const { sourceCode } = ruleContext;
     body.forEach((statement, index) => {
-        if (statement.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
-            statement.declarations.length !== 1) {
+        if (!isLateDeclarationCandidate(statement)) {
             return;
         }
         const [declarator] = statement.declarations;
-        if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
-            (declarator.init &&
-                declarator.init.type !== utils_1.AST_NODE_TYPES.Identifier &&
-                declarator.init.type !== utils_1.AST_NODE_TYPES.Literal)) {
-            return;
-        }
         const name = declarator.id.name;
         const dependencies = new Set();
         if (declarator.init && declarator.init.type === utils_1.AST_NODE_TYPES.Identifier) {
             dependencies.add(declarator.init.name);
         }
         const nameSet = new Set([name]);
-        let usageIndex = -1;
-        for (let cursor = index + 1; cursor < body.length; cursor += 1) {
-            if (statementReferencesAny(body[cursor], nameSet)) {
-                usageIndex = cursor;
-                break;
-            }
-        }
+        const usageIndex = findFirstUsageIndex(body, nameSet, index + 1);
         if (usageIndex === -1 || usageIndex <= index + 1) {
             return;
         }
+        // Loop mutations create a dependency barrier: declarations that precede loops and are
+        // mutated inside them cannot be safely moved, as the declaration must be visible across
+        // all iterations. Prevent false positives for this pattern.
+        if (isMutatedInLoop(body, usageIndex, nameSet)) {
+            return;
+        }
         const intervening = body.slice(index + 1, usageIndex);
         // Only move across pure declarations that do not mention the placeholder or its initializer dependencies to avoid changing closure timing or TDZ behavior.
-        const crossesImpureOrTracked = intervening.some((stmt) => {
+        const crossesImpureOrTracked = intervening.some((stmt, i) => {
             if (!isPureDeclaration(stmt, { allowHooks: false })) {
                 return true;
             }
+            // Do not hop over another declaration that is used at the same index or earlier
+            // if it is also a candidate for being moved.
+            // This prevents circular swapping of related declarations (like resolve/reject pairs).
+            if (isLateDeclarationCandidate(stmt)) {
+                const declaredNames = getDeclaredNames(stmt);
+                const firstUsageOfIntervening = findFirstUsageIndex(body, declaredNames, index + 1 + i + 1);
+                if (firstUsageOfIntervening !== -1 &&
+                    firstUsageOfIntervening <= usageIndex) {
+                    return true;
+                }
+            }
             if (statementDeclaresAny(stmt, nameSet) ||
                 statementMutatesAny(stmt, nameSet)) {
                 return true;

package/lib/rules/no-direct-function-state.d.ts

@@ -0,0 +1,8 @@
+import { TSESLint } from '@typescript-eslint/utils';
+type Options = [
+    {
+        functionPatterns?: string[];
+    }
+];
+export declare const noDirectFunctionState: TSESLint.RuleModule<"noDirectFunctionState", Options, TSESLint.RuleListener>;
+export {};

package/lib/rules/no-direct-function-state.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noDirectFunctionState = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_FUNCTION_PATTERNS = [
+    'callback',
+    'handler',
+    'fn',
+    'func',
+    'on[A-Z].*',
+];
+/**
+ * Returns true if the TSTypeAnnotation node (from useState's type parameter)
+ * represents a function type — either directly or as part of a union with
+ * null/undefined. We check purely syntactically; no type-checker required.
+ */
+function isFunctionTypeAnnotation(typeNode) {
+    switch (typeNode.type) {
+        case utils_1.AST_NODE_TYPES.TSFunctionType:
+        case utils_1.AST_NODE_TYPES.TSConstructorType:
+            return true;
+        case utils_1.AST_NODE_TYPES.TSUnionType:
+            // Union like `(() => void) | null` — any member being a function type suffices
+            return typeNode.types.some(isFunctionTypeAnnotation);
+        default:
+            return false;
+    }
+}
+/**
+ * Checks whether a useState call expression has a type parameter that
+ * includes a function type, e.g. useState<(() => void) | null>(null).
+ */
+function useStateHasFunctionTypeParam(callNode) {
+    const typeParams = callNode.typeParameters;
+    if (!typeParams || typeParams.params.length === 0) {
+        return false;
+    }
+    return isFunctionTypeAnnotation(typeParams.params[0]);
+}
+/**
+ * Returns true when the AST node is a safe value to pass to a setter — i.e.,
+ * NOT a bare identifier or member expression that could be a function reference.
+ * Arrow/function expressions are always safe (they are intentional).
+ * Literals, null, undefined, call expressions, arrays, objects are all safe.
+ */
+function isDefinitelySafeArg(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.ArrowFunctionExpression:
+        case utils_1.AST_NODE_TYPES.FunctionExpression:
+            // Inline function/arrow — always intentional (updater or thunk)
+            return true;
+        case utils_1.AST_NODE_TYPES.Literal:
+            // Literal values (numbers, strings, booleans, null, regex)
+            return true;
+        case utils_1.AST_NODE_TYPES.TemplateLiteral:
+            return true;
+        case utils_1.AST_NODE_TYPES.Identifier:
+            // `undefined` is safe; generic identifiers may be function refs
+            return node.name === 'undefined';
+        case utils_1.AST_NODE_TYPES.UnaryExpression:
+            // `void 0`, `!flag`, `typeof x` etc. — all non-function values
+            return true;
+        case utils_1.AST_NODE_TYPES.BinaryExpression:
+            // `a + b`, `a * b`, etc. — never callable
+            return true;
+        case utils_1.AST_NODE_TYPES.CallExpression:
+        case utils_1.AST_NODE_TYPES.NewExpression:
+            // Call/new expressions — return value unknown without types; skip (no FP)
+            return true;
+        case utils_1.AST_NODE_TYPES.ArrayExpression:
+        case utils_1.AST_NODE_TYPES.ObjectExpression:
+            return true;
+        case utils_1.AST_NODE_TYPES.TSAsExpression:
+        case utils_1.AST_NODE_TYPES.TSTypeAssertion:
+        case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+            // Unwrap type assertions and recurse
+            return isDefinitelySafeArg(node.expression);
+        default:
+            // MemberExpression, Identifier (non-undefined), etc. are NOT definitely safe
+            return false;
+    }
+}
+/**
+ * Checks whether an identifier name matches any of the function-naming patterns
+ * (e.g. onClose, handler, fn, callback).
+ */
+function matchesFunctionPattern(name, patterns) {
+    for (const pattern of patterns) {
+        try {
+            const regex = new RegExp(`^${pattern}$`);
+            if (regex.test(name)) {
+                return true;
+            }
+        }
+        catch {
+            // Ignore invalid regex patterns
+        }
+    }
+    return false;
+}
+/**
+ * Extracts the identifier name from an argument node for pattern matching.
+ * For MemberExpression like `obj.handler`, returns `handler`.
+ * For Identifier like `myCallback`, returns `myCallback`.
+ */
+function getArgName(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return node.name;
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        const prop = node.property;
+        if (prop.type === utils_1.AST_NODE_TYPES.Identifier && !node.computed) {
+            return prop.name;
+        }
+    }
+    return null;
+}
+/**
+ * Walks up the scope to find if an identifier is bound (in scope) to a
+ * function — an arrow function expression or function expression/declaration.
+ * This covers: `const x = () => ...` and `function x() {...}`.
+ */
+function isIdentifierBoundToFunction(name, scope) {
+    let currentScope = scope;
+    while (currentScope) {
+        for (const variable of currentScope.variables) {
+            if (variable.name !== name)
+                continue;
+            for (const def of variable.defs) {
+                if (def.type === 'Variable' &&
+                    def.node.init &&
+                    (def.node.init.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+                        def.node.init.type === utils_1.AST_NODE_TYPES.FunctionExpression)) {
+                    return true;
+                }
+                if (def.type === 'FunctionName' ||
+                    def.type === 'ImplicitGlobalVariable') {
+                    return true;
+                }
+            }
+        }
+        currentScope = currentScope.upper;
+    }
+    return false;
+}
+exports.noDirectFunctionState = (0, createRule_1.createRule)({
+    name: 'no-direct-function-state',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Prevent passing a function directly to a useState setter — React will invoke it as a functional updater instead of storing it. Wrap in a thunk: setState(() => fn).',
+            recommended: 'error',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    functionPatterns: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: DEFAULT_FUNCTION_PATTERNS,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            noDirectFunctionState: 'What\'s wrong: "{{argText}}" is passed directly to "{{setterName}}", but React invokes a function argument as a functional updater (prev => next) instead of storing it. ' +
+                'Why it matters: The function will be called with the previous state value and its return value stored — a silent bug with no error. ' +
+                'How to fix: Wrap it in a thunk so React stores the function as a value: {{setterName}}(() => {{argText}})',
+        },
+    },
+    defaultOptions: [{ functionPatterns: DEFAULT_FUNCTION_PATTERNS }],
+    create(context) {
+        const options = context.options[0] ?? {};
+        const functionPatterns = options.functionPatterns ?? DEFAULT_FUNCTION_PATTERNS;
+        /**
+         * Maps setter-variable names to whether the corresponding useState has
+         * an explicit function type parameter. This is populated as we encounter
+         * useState array-destructuring declarations.
+         */
+        const setterFunctionTyped = new Map();
+        return {
+            VariableDeclarator(node) {
+                // Look for `const [state, setter] = useState<T>(...)` or
+                // `const [state, setter] = React.useState<T>(...)`.
+                if (node.id.type !== utils_1.AST_NODE_TYPES.ArrayPattern ||
+                    !node.init ||
+                    node.init.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+                    return;
+                }
+                const callNode = node.init;
+                const callee = callNode.callee;
+                const isUseStateCall = (callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    callee.name === 'useState') ||
+                    (callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+                        callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+                        callee.property.name === 'useState');
+                if (!isUseStateCall)
+                    return;
+                // The setter is the second element of the destructured array
+                const elements = node.id.elements;
+                if (elements.length < 2)
+                    return;
+                const setterElement = elements[1];
+                if (!setterElement ||
+                    setterElement.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                    return;
+                }
+                const setterName = setterElement.name;
+                const hasFunctionType = useStateHasFunctionTypeParam(callNode);
+                setterFunctionTyped.set(setterName, hasFunctionType);
+            },
+            CallExpression(node) {
+                // We are looking for calls like `setter(arg)` where:
+                // 1. setter is known (tracked from useState destructuring), AND
+                //    - the useState type is function-typed, OR
+                //    - the arg name matches a function pattern, OR
+                //    - the arg is bound to a function in scope
+                // 2. The arg is NOT already a safe value (arrow/function expr, literal, etc.)
+                const callee = node.callee;
+                if (callee.type !== utils_1.AST_NODE_TYPES.Identifier)
+                    return;
+                const setterName = callee.name;
+                // Only flag calls to tracked setters
+                if (!setterFunctionTyped.has(setterName))
+                    return;
+                // Only consider single-argument calls (setters take exactly one value arg)
+                if (node.arguments.length !== 1)
+                    return;
+                const arg = node.arguments[0];
+                // SpreadElement is not a plain expression; skip
+                if (arg.type === utils_1.AST_NODE_TYPES.SpreadElement)
+                    return;
+                // If arg is a definitely-safe type (inline arrow, literal, undefined, etc.),
+                // skip without further checks
+                if (isDefinitelySafeArg(arg))
+                    return;
+                // At this point arg is an Identifier (non-undefined) or MemberExpression.
+                // Decide whether it is a function reference.
+                const isFunctionTypedState = setterFunctionTyped.get(setterName) === true;
+                if (isFunctionTypedState) {
+                    // Type annotation says the state holds a function — any bare
+                    // identifier or member expression is suspect.
+                    reportAndFix(node, arg, setterName, context);
+                    return;
+                }
+                // No explicit function type. Fall back to heuristic: name pattern match
+                // or scope-level binding to a function.
+                const argName = getArgName(arg);
+                if (argName && matchesFunctionPattern(argName, functionPatterns)) {
+                    reportAndFix(node, arg, setterName, context);
+                    return;
+                }
+                // Check if the identifier is bound to a function in scope
+                if (arg.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    arg.name !== 'undefined') {
+                    const scope = context.getScope();
+                    if (isIdentifierBoundToFunction(arg.name, scope)) {
+                        reportAndFix(node, arg, setterName, context);
+                        return;
+                    }
+                }
+            },
+        };
+    },
+});
+function reportAndFix(callNode, arg, setterName, context) {
+    const sourceCode = context.getSourceCode();
+    const argText = sourceCode.getText(arg);
+    context.report({
+        node: callNode,
+        messageId: 'noDirectFunctionState',
+        data: {
+            argText,
+            setterName,
+        },
+        fix(fixer) {
+            return fixer.replaceText(arg, `() => ${argText}`);
+        },
+    });
+}
+//# sourceMappingURL=no-direct-function-state.js.map

package/lib/rules/no-fill-template-mutation.d.ts

@@ -0,0 +1 @@
+export declare const noFillTemplateMutation: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"noFillTemplateMutation", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;