@blumintinc/eslint-plugin-blumint 1.20.106 → 1.20.108

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.106',
+        version: '1.20.108',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/parallelize-async-operations.js

@@ -474,6 +474,142 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
             }
             return names;
         }
+        /**
+         * Records the binding a single assignment target writes to.
+         *
+         * A member write records its ROOT object (`obj.a.b = 1` yields `obj`),
+         * because the state it mutates is reachable through that binding, and a
+         * later await naming the object observes the mutation. Optional chains and
+         * TS wrappers (`obj!.x = 1`) are unwrapped so the root is still found.
+         * Destructuring targets recurse to their leaf identifiers, since
+         * `({ a } = source)` and `[a] = source` write `a` just as `a = source.a`
+         * does.
+         */
+        function collectAssignmentTarget(target, targets) {
+            switch (target.type) {
+                case utils_1.AST_NODE_TYPES.Identifier:
+                    targets.push(target);
+                    break;
+                case utils_1.AST_NODE_TYPES.MemberExpression: {
+                    let root = target;
+                    for (;;) {
+                        if (root.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+                            root = root.object;
+                        }
+                        else if (root.type === utils_1.AST_NODE_TYPES.ChainExpression ||
+                            root.type === utils_1.AST_NODE_TYPES.TSNonNullExpression ||
+                            root.type === utils_1.AST_NODE_TYPES.TSAsExpression) {
+                            root = root.expression;
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                    if (root.type === utils_1.AST_NODE_TYPES.Identifier) {
+                        targets.push(root);
+                    }
+                    break;
+                }
+                case utils_1.AST_NODE_TYPES.ObjectPattern:
+                    for (const property of target.properties) {
+                        if (property.type === utils_1.AST_NODE_TYPES.Property) {
+                            collectAssignmentTarget(property.value, targets);
+                        }
+                        else {
+                            collectAssignmentTarget(property.argument, targets);
+                        }
+                    }
+                    break;
+                case utils_1.AST_NODE_TYPES.ArrayPattern:
+                    for (const element of target.elements) {
+                        if (element) {
+                            collectAssignmentTarget(element, targets);
+                        }
+                    }
+                    break;
+                case utils_1.AST_NODE_TYPES.RestElement:
+                    collectAssignmentTarget(target.argument, targets);
+                    break;
+                case utils_1.AST_NODE_TYPES.AssignmentPattern:
+                    collectAssignmentTarget(target.left, targets);
+                    break;
+            }
+        }
+        /**
+         * Reports whether an assignment target resolves to a binding DECLARED
+         * inside the given expression.
+         *
+         * Such a binding is a fresh local: `async () => { let tmp; tmp = 1; }`
+         * publishes nothing to the enclosing scope, so a later await mentioning
+         * `tmp` is reading some other binding entirely. An unresolved name (an
+         * implicit global) counts as external, which keeps the barrier in place for
+         * the case the analysis cannot see.
+         */
+        function isDeclaredWithin(identifier, root) {
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, identifier), identifier.name);
+            if (!variable || variable.defs.length === 0) {
+                return false;
+            }
+            return variable.defs.every((definition) => definition.name.range[0] >= root.range[0] &&
+                definition.name.range[1] <= root.range[1]);
+        }
+        /**
+         * Collects the identifier names an awaited expression WRITES.
+         *
+         * The traversal deliberately crosses function boundaries, which is the
+         * opposite of what containsSuspendingAwait needs: the write that matters
+         * lives inside the callback handed to the awaited call. `await
+         * db.runTransaction(async (tx) => { mutator = new Mutator(tx); })` publishes
+         * `mutator` to the enclosing scope by the time it settles, so the callback
+         * body is part of what that statement does, not a separate deferred unit.
+         *
+         * A `VariableDeclarator` id is deliberately NOT a write: `const x = ...`
+         * inside a callback creates a fresh local binding rather than publishing a
+         * value to an outer one, so it cannot be what a later await reads.
+         */
+        function getAssignedNames(node) {
+            const targets = [];
+            const visit = (current) => {
+                if (current.type === utils_1.AST_NODE_TYPES.AssignmentExpression) {
+                    collectAssignmentTarget(current.left, targets);
+                }
+                else if (current.type === utils_1.AST_NODE_TYPES.UpdateExpression) {
+                    collectAssignmentTarget(current.argument, targets);
+                }
+                else if ((current.type === utils_1.AST_NODE_TYPES.ForOfStatement ||
+                    current.type === utils_1.AST_NODE_TYPES.ForInStatement) &&
+                    current.left.type !== utils_1.AST_NODE_TYPES.VariableDeclaration) {
+                    // `for (captured of items)` assigns an existing binding on every
+                    // iteration; only the declaration form introduces a fresh local.
+                    collectAssignmentTarget(current.left, targets);
+                }
+                for (const key in current) {
+                    if (key === 'parent' || key === 'range' || key === 'loc')
+                        continue;
+                    const child = current[key];
+                    if (!child || typeof child !== 'object')
+                        continue;
+                    if (Array.isArray(child)) {
+                        for (const item of child) {
+                            if (item && typeof item === 'object' && 'type' in item) {
+                                visit(item);
+                            }
+                        }
+                    }
+                    else if ('type' in child) {
+                        visit(child);
+                    }
+                }
+            };
+            visit(node);
+            const names = new Set();
+            for (const target of targets) {
+                if (!isDeclaredWithin(target, node)) {
+                    names.add(target.name);
+                }
+            }
+            return names;
+        }
         /**
          * Checks if there are dependencies between await expressions
          */
@@ -671,6 +807,37 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                     return true;
                 }
             }
+            // 10. Closure-write barrier: read after write. An awaited call whose
+            // callback ASSIGNS an outer binding carries a data dependency that no
+            // value flowing out of the await expresses, so `variableNames` -- which
+            // holds only the names the run's own statements DECLARE -- cannot see it.
+            // `let mutator; await db.runTransaction(async (tx) => { mutator = new
+            // Mutator(tx); }); await mutator?.deleteIfEmptied();` is the shape. The
+            // rewrite is silently wrong rather than merely eager: array elements
+            // evaluate left to right at construction time, so the second element runs
+            // while `mutator` is still undefined -- the optional chain short-circuits
+            // and the operation NEVER happens, with no error to reveal it. Dropping
+            // the `?.` turns the same rewrite into a TypeError instead. Keyed on a
+            // write that a LATER await actually reads, so a callback whose effects
+            // nothing downstream observes still parallelizes. (#1723)
+            const assignedNames = awaitNodes.map((node) => {
+                const awaitExpr = getAwaitExpression(node);
+                return awaitExpr
+                    ? getAssignedNames(awaitExpr.argument)
+                    : new Set();
+            });
+            for (let i = 1; i < awaitNodes.length; i++) {
+                const currentIds = allIdentifiers[i];
+                if (currentIds.size === 0)
+                    continue;
+                for (let j = 0; j < i; j++) {
+                    for (const written of assignedNames[j]) {
+                        if (currentIds.has(written)) {
+                            return true;
+                        }
+                    }
+                }
+            }
             return false;
         }
         /**

package/lib/rules/parallelize-loop-awaits.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parallelizeLoopAwaits = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 // Anchored at the end of the path so multi-part suffixes such as
 // `EventRegistry.integration.test.ts` are recognized while production modules
 // that merely contain the word (`testHelpers.ts`, `latest.ts`, `contest/Thing.ts`)
@@ -291,85 +292,162 @@ exports.parallelizeLoopAwaits = (0, createRule_1.createRule)({
             return false;
         }
         /**
-         * Collects all variables declared INSIDE the loop body (at the direct
-         * body scope, not crossing nested function boundaries). These are
-         * iteration-local variables.
+         * Collects the IDENTIFIERS an assignment target writes through, returning
+         * false when the target's root is not a plain binding at all.
+         *
+         * A member write reaches the object its ROOT names: `box.value = 1` writes
+         * through `box`, and `value` is a field label that binds nothing — the same
+         * distinction drawn for a non-computed property key (#1688). Counting the
+         * label as a written name makes every member write look like a write to an
+         * outer binding, which is what hides a callback writing through its own
+         * parameter (`async (page) => { page.total = 1 }`).
+         *
+         * A root the analysis cannot name — `this.count += 1` reaches instance
+         * state every iteration shares — returns false, and the caller reads that
+         * as an outer write. The plugin prefers a missed report to a spurious one.
+         *
+         * The identifier NODE is carried rather than its name, because locality is
+         * a question about scope: two bindings can share a spelling, and only the
+         * node knows which one a given write reaches. (#1725)
          */
-        function collectLoopLocalVars(body) {
-            const localVars = new Set();
-            function visit(node, isRoot) {
-                if (!isRoot &&
-                    (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
-                        node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
-                        node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression)) {
-                    return;
-                }
-                if (node.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
-                    for (const declarator of node.declarations) {
-                        collectBindingNames(declarator.id, localVars);
+        function collectAssignmentTargetIdentifiers(target, identifiers) {
+            switch (target.type) {
+                case utils_1.AST_NODE_TYPES.Identifier:
+                    identifiers.push(target);
+                    return true;
+                case utils_1.AST_NODE_TYPES.MemberExpression:
+                    return collectAssignmentTargetIdentifiers(target.object, identifiers);
+                case utils_1.AST_NODE_TYPES.ChainExpression:
+                case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+                case utils_1.AST_NODE_TYPES.TSAsExpression:
+                    return collectAssignmentTargetIdentifiers(target.expression, identifiers);
+                case utils_1.AST_NODE_TYPES.ObjectPattern: {
+                    let resolved = true;
+                    for (const property of target.properties) {
+                        const inner = property.type === utils_1.AST_NODE_TYPES.RestElement
+                            ? property.argument
+                            : property.value;
+                        if (!collectAssignmentTargetIdentifiers(inner, identifiers)) {
+                            resolved = false;
+                        }
                     }
+                    return resolved;
                 }
-                for (const key in node) {
-                    if (key === 'parent' ||
-                        key === 'range' ||
-                        key === 'loc' ||
-                        key === 'type')
-                        continue;
-                    const child = node[key];
-                    if (child && typeof child === 'object') {
-                        if (Array.isArray(child)) {
-                            for (const item of child) {
-                                if (item && typeof item === 'object' && 'type' in item) {
-                                    visit(item, false);
-                                }
-                            }
-                        }
-                        else if ('type' in child) {
-                            visit(child, false);
+                case utils_1.AST_NODE_TYPES.ArrayPattern: {
+                    let resolved = true;
+                    for (const element of target.elements) {
+                        if (element &&
+                            !collectAssignmentTargetIdentifiers(element, identifiers)) {
+                            resolved = false;
                         }
                     }
+                    return resolved;
                 }
+                case utils_1.AST_NODE_TYPES.RestElement:
+                    return collectAssignmentTargetIdentifiers(target.argument, identifiers);
+                case utils_1.AST_NODE_TYPES.AssignmentPattern:
+                    return collectAssignmentTargetIdentifiers(target.left, identifiers);
+                default:
+                    return false;
+            }
+        }
+        /**
+         * Reports whether an identifier resolves to a binding DECLARED inside the
+         * given root node.
+         *
+         * Such a binding is iteration-local: nothing it holds outlives the
+         * iteration that created it, so writing it couples no two iterations.
+         * `async () => { let tmp; tmp = 1; }` publishes nothing to the enclosing
+         * scope, and a callback's parameters bind afresh on every invocation.
+         *
+         * The question is settled by SCOPE rather than by spelling. A flat set of
+         * declared NAMES cannot tell an outer binding from a nested one that merely
+         * reuses the identifier, so a genuine cross-iteration write to `cursor`
+         * would read as local the moment any callback in the loop happened to name
+         * a parameter `cursor`. (#1725)
+         *
+         * An UNRESOLVED name — an implicit global — counts as external, which keeps
+         * the barrier in place for the case the analysis cannot see.
+         */
+        function isDeclaredWithin(identifier, root) {
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(ASTHelpers_1.ASTHelpers.getScope(context, identifier), identifier.name);
+            if (!variable || variable.defs.length === 0) {
+                return false;
             }
-            visit(body, true);
-            return localVars;
+            return variable.defs.every((definition) => definition.name.range[0] >= root.range[0] &&
+                definition.name.range[1] <= root.range[1]);
         }
         /**
          * Detects cross-iteration state patterns that require sequential
          * execution:
          *
-         * 1. Accumulator: a variable declared OUTSIDE the loop body (i.e., not
-         *    in localVars) is ASSIGNED inside the loop body. Examples: `total +=
-         *    value`, `cursor = page.nextCursor`, `previousResult = result`. This
-         *    catches running totals, pagination cursors, and chained results.
+         * 1. Accumulator: a variable declared OUTSIDE the loop body is ASSIGNED
+         *    inside it, whether directly or from inside a callback the body hands
+         *    to the awaited call. Examples: `total += value`, `cursor =
+         *    page.nextCursor`, `previousResult = result`. This catches running
+         *    totals, pagination cursors, and chained results.
          *
          * 2. Direct cross-await dependency: a variable declared by an await
          *    inside the loop is then read as an argument to another await in the
          *    same loop body. Example: `const a = await f(); const b = await g(a);`.
          */
-        function hasSequentialDependency(body, loopLocalVars) {
+        function hasSequentialDependency(body) {
             // Pattern 1: outer variable is written inside the loop body.
-            // Collect all assignment targets (left-hand sides of assignments and
-            // compound assignments) in the loop body.
+            // Collect every assignment target — the left-hand side of an assignment
+            // or compound assignment, and the operand of an increment in a callback.
             let foundOuterWrite = false;
-            function findOuterWrites(node, isRoot) {
+            /**
+             * Reports whether an assignment target reaches a binding the iterations
+             * share rather than one the iteration creates.
+             *
+             * The body is the locality root, so a binding introduced by the loop's
+             * own HEAD reads as shared. That is the conservative reading and the
+             * correct one for a C-style counter: `for (let i = 0; i < n; i += 1)`
+             * carries `i` forward between iterations, so a body write to it really
+             * does couple them.
+             */
+            function writesOuterBinding(target) {
+                const identifiers = [];
+                if (!collectAssignmentTargetIdentifiers(target, identifiers)) {
+                    return true;
+                }
+                for (const identifier of identifiers) {
+                    if (!isDeclaredWithin(identifier, body))
+                        return true;
+                }
+                return false;
+            }
+            function findOuterWrites(node, isRoot, inNestedFunction) {
                 if (foundOuterWrite)
                     return;
-                if (!isRoot &&
-                    (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
-                        node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
-                        node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression)) {
+                // The walk deliberately enters callbacks. A write handed to the awaited
+                // call is the same data dependency as one written beside it:
+                // `await run(item, async (page) => { cursor = page.nextCursor })` has
+                // settled — and published `cursor` — by the time the iteration ends, so
+                // parallel iterations would race exactly as they would over
+                // `cursor = await run(item, cursor)`. (#1724)
+                const isNested = inNestedFunction ||
+                    (!isRoot &&
+                        (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+                            node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                            node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression));
+                if (node.type === utils_1.AST_NODE_TYPES.AssignmentExpression &&
+                    writesOuterBinding(node.left)) {
+                    foundOuterWrite = true;
                     return;
                 }
-                if (node.type === utils_1.AST_NODE_TYPES.AssignmentExpression) {
-                    // Collect identifiers on the left-hand side
-                    const lhsIds = new Set();
-                    collectIdentifiers(node.left, lhsIds, false);
-                    for (const id of lhsIds) {
-                        if (!loopLocalVars.has(id)) {
-                            foundOuterWrite = true;
-                            return;
-                        }
-                    }
+                // An increment counts only inside a callback. At the loop-body level it
+                // is the loop's own step counter — `while (i < n) { await f(items[i]);
+                // i++; }` walks the iteration space, and the `Promise.all(items.map(
+                // ...))` rewrite subsumes it — whereas a callback steps no iteration:
+                // `count++` there folds what the awaited work produced into a binding
+                // the whole loop shares, carrying the same dependency as the compound
+                // assignment it stands in for. (#1724)
+                if (isNested &&
+                    node.type === utils_1.AST_NODE_TYPES.UpdateExpression &&
+                    writesOuterBinding(node.argument)) {
+                    foundOuterWrite = true;
+                    return;
                 }
                 for (const key in node) {
                     if (key === 'parent' ||
@@ -382,17 +460,17 @@ exports.parallelizeLoopAwaits = (0, createRule_1.createRule)({
                         if (Array.isArray(child)) {
                             for (const item of child) {
                                 if (item && typeof item === 'object' && 'type' in item) {
-                                    findOuterWrites(item, false);
+                                    findOuterWrites(item, false, isNested);
                                 }
                             }
                         }
                         else if ('type' in child) {
-                            findOuterWrites(child, false);
+                            findOuterWrites(child, false, isNested);
                         }
                     }
                 }
             }
-            findOuterWrites(body, true);
+            findOuterWrites(body, true, false);
             if (foundOuterWrite)
                 return true;
             // Pattern 2: a variable declared by an await is used as arg to another await.
@@ -736,8 +814,7 @@ exports.parallelizeLoopAwaits = (0, createRule_1.createRule)({
                 return null;
             // Exclusion: accumulator / pagination patterns — sequential dependency
             // detected between iterations
-            const loopLocalVars = collectLoopLocalVars(body);
-            if (hasSequentialDependency(body, loopLocalVars))
+            if (hasSequentialDependency(body))
                 return null;
             // Exclusion: the specific await being reported is a rate-limiting call
             const callNames = getCallNames(awaitExpr);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.106",
+  "version": "1.20.108",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "1.20.108",
+    "date": "2026-08-05T05:55:32.346Z",
+    "rules": [
+      {
+        "name": "parallelize-loop-awaits",
+        "changeType": "fix",
+        "issues": [
+          1725
+        ],
+        "summary": "resolve write locality by scope, not by name (closes #1725)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.107",
+    "date": "2026-08-05T05:11:58.347Z",
+    "rules": [
+      {
+        "name": "parallelize-async-operations",
+        "changeType": "fix",
+        "issues": [
+          1723
+        ],
+        "summary": "treat a callback's write to an outer binding as a dependency (closes #1723)"
+      },
+      {
+        "name": "parallelize-loop-awaits",
+        "changeType": "fix",
+        "issues": [
+          1724
+        ],
+        "summary": "see a callback's write to an outer binding (closes #1724)"
+      }
+    ]
+  },
   {
     "version": "1.20.106",
     "date": "2026-08-05T01:12:16.076Z",