@blumintinc/eslint-plugin-blumint 1.21.13 → 1.21.14

package/lib/index.js

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

package/lib/rules/global-const-style.js

@@ -270,6 +270,68 @@ const isMutatingMethodCall = (path) => {
     return (callee.parent?.type === utils_1.AST_NODE_TYPES.CallExpression &&
         callee.parent.callee === callee);
 };
+/**
+ * The mutating methods that INSERT a value into the receiver, mapped to the
+ * argument positions that value can occupy.
+ *
+ * The positions are carried per method rather than taken as "every argument",
+ * because two of these spend leading or trailing arguments on INDICES:
+ * `splice(start, deleteCount, ...items)` inserts from the third argument on,
+ * and `fill(value, start, end)` inserts at the first alone.
+ *
+ * `sort`, `reverse`, `pop`, `shift` and `copyWithin` are absent because they
+ * insert nothing — they reorder, remove or copy elements the receiver already
+ * holds, so no element type can reject what they write. (`sort`'s argument is a
+ * comparator function, `copyWithin`'s three are indices.)
+ */
+const INSERTED_VALUE_POSITIONS_BY_METHOD = new Map([
+    ['push', { first: 0 }],
+    ['unshift', { first: 0 }],
+    ['splice', { first: 2 }],
+    ['fill', { first: 0, last: 0 }],
+]);
+/**
+ * Whether a mutating call INTRODUCES a value the receiver's element type would
+ * have to accept from outside the constant.
+ *
+ * This is the question that decides a mutating call through a receiver-array
+ * parameter the lib declares MUTABLE, where no readonly violation is possible
+ * and the only way the assertion can break the call is by narrowing what the
+ * array accepts — see `MUTABLE_ARRAY_PARAMETER_METHODS`. Three answers, and the
+ * boundary sits between the second and the third:
+ *
+ * - a method that inserts nothing (`arr.sort()`) cannot narrow-break, because
+ *   it writes back only elements the receiver already holds;
+ * - an inserted value that is a REFERENCE to a binding already enrolled for
+ *   this constant (`arr.push(item)`, where `item` is the element the callback
+ *   was handed) is typed from the constant itself, so the assertion narrows the
+ *   argument and the parameter together and the call keeps compiling;
+ * - an inserted value from anywhere else (`arr.push({ n: 3 })`) is typed
+ *   independently of the constant, so narrowing the element type can reject it:
+ *   TS2322 for an input that compiled (Issue #2340).
+ *
+ * A SPREAD argument is treated as introducing a foreign value even when it
+ * spreads the constant. Its elements do satisfy the narrowed type, so this
+ * withholds the assertion from a call that would have compiled — the cheap
+ * error of the two, and the one this predicate exists to prefer.
+ */
+const introducesForeignElement = (path, isEnrolledReference) => {
+    const method = accessedPropertyName(path);
+    const positions = method === null
+        ? undefined
+        : INSERTED_VALUE_POSITIONS_BY_METHOD.get(method);
+    if (!positions) {
+        return false;
+    }
+    const call = outermostValueOf(path).parent;
+    if (call?.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+        return false;
+    }
+    const last = positions.last ?? call.arguments.length - 1;
+    return call.arguments
+        .slice(positions.first, last + 1)
+        .some((argument) => !isEnrolledReference(argument));
+};
 /**
  * Whether `node` sits in a position that writes to it: the left of an
  * assignment (plain or compound), the operand of `++`/`--` or `delete`, the
@@ -625,12 +687,12 @@ const ELEMENT_PARAMETER_INDEX_BY_METHOD = new Map([
  * `reduce`/`reduceRight` push it to fourth, having spent the first position on
  * the accumulator.
  *
- * `flatMap` is listed even though its lib signature declares the parameter
- * `T[]` where every sibling declares it `readonly T[]` — measured against
- * `lib.es2020`, so a mutating METHOD through it survives the assertion. Its
- * ELEMENTS are frozen regardless, so `arr[0].n = 2` inside a `flatMap` callback
- * is TS2540 for an input that compiled, and the walk's write check reaches it
- * only once the parameter is enrolled.
+ * `flatMap` is listed for its ELEMENTS alone. Its lib signature declares the
+ * parameter `T[]` where every sibling declares it `readonly T[]` — measured
+ * against `lib.es2020` — so `arr[0].n = 2` inside a `flatMap` callback is
+ * TS2540 for an input that compiled, while a mutating method called through the
+ * parameter compiles unchanged. `MUTABLE_ARRAY_PARAMETER_METHODS` carries that
+ * second half, which enrolment alone cannot express (Issue #2340).
  */
 const ARRAY_PARAMETER_INDEX_BY_METHOD = new Map([
     ['forEach', 2],
@@ -646,6 +708,26 @@ const ARRAY_PARAMETER_INDEX_BY_METHOD = new Map([
     ['reduce', 3],
     ['reduceRight', 3],
 ]);
+/**
+ * The methods above whose receiver-array parameter is declared MUTABLE `T[]`.
+ *
+ * Enrolling that parameter answers two questions at once, and each needs its own
+ * answer. Its ELEMENTS are frozen with the constant, so an element write through
+ * it is TS2540 and the assertion is withheld. A mutating METHOD through it is no
+ * readonly violation at all — the declared type is mutable, so there is no
+ * TS2339 to have — and withholding the assertion for one costs a report for a
+ * break that does not happen: `ITEMS.flatMap((x, i, arr) => { arr.sort(); return
+ * [x]; })` and the `arr.push(x)` spelling both compile under the assertion,
+ * measured by appending it by hand and reading the checker.
+ *
+ * What such a call CAN break is assignability, and only by introducing a value
+ * from outside the constant: `arr.push({ n: 3 })` is TS2322 once the assertion
+ * narrows the element type. That is decided per CALL by
+ * `introducesForeignElement`, not per method — an exemption keyed on the method
+ * alone would trade two over-declines for a `--fix` that stops the file
+ * compiling, which is the defect this walk exists to prevent (Issue #2340).
+ */
+const MUTABLE_ARRAY_PARAMETER_METHODS = new Set(['flatMap']);
 /**
  * The `Object.values(X)` / `Object.entries(X)` call this value feeds — a fresh
  * array whose ELEMENTS are the constant's own property values, so freezing the
@@ -670,6 +752,146 @@ const elementProjectionCallOf = (node) => {
         ? parent
         : null;
 };
+/**
+ * Array methods whose result ITERATES the receiver's own elements.
+ *
+ * The result is an iterator rather than an array, which is why it belongs to
+ * neither of the maps the walk already reads: nothing is copied, so
+ * `TYPE_PRESERVING_COPY_METHODS` refuses it, and nothing is handed to a
+ * callback, so `ELEMENT_PARAMETER_INDEX_BY_METHOD` refuses it too. Every
+ * binding taken from it still carries the constant's element type, so
+ * `for (const item of ITEMS.values()) { item.n = 2; }` is TS2540 once `ITEMS`
+ * is frozen, for an input that compiled (Issue #2340). `entries` yields
+ * `[index, element]` pairs, which carry the element exactly as `values` does.
+ *
+ * `keys` is absent for the reason `Object.keys` is: its result is a number
+ * whatever the receiver holds, so the assertion cannot reach a binding taken
+ * from it.
+ */
+const ELEMENT_ITERATOR_METHODS = new Set(['values', 'entries']);
+const iteratorProjectionCallOf = (node) => {
+    const parent = node.parent;
+    if (parent?.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+        parent.object !== node) {
+        return null;
+    }
+    const method = accessedPropertyName(parent);
+    if (method === null || !ELEMENT_ITERATOR_METHODS.has(method)) {
+        return null;
+    }
+    // A method REFERENCE (`const walk = ITEMS.values;`) iterates nothing, so the
+    // iterator exists only once the method is called — the same terms
+    // `copyExpressionOf` reads a copy on.
+    const callee = outermostValueOf(parent);
+    return callee.parent?.type === utils_1.AST_NODE_TYPES.CallExpression &&
+        callee.parent.callee === callee
+        ? callee.parent
+        : null;
+};
+/**
+ * Constructors that build a collection out of the argument's ELEMENTS.
+ *
+ * `new Set(ITEMS)` holds the constant's own contents, so iterating it hands out
+ * the frozen elements and `for (const item of new Set(ITEMS)) { item.n = 2; }`
+ * is TS2540 for an input that compiled (Issue #2340).
+ *
+ * The construction is not a copy in `copyExpressionOf`'s sense — the result has
+ * a different shape from the argument, so a write to the collection says
+ * nothing about the constant — which is why it is resolved here, where only the
+ * ITERATION question is asked. `WeakSet`/`WeakMap` are absent because they are
+ * not iterable, so no binding can be taken from one.
+ */
+const ELEMENT_PRESERVING_COLLECTION_NAMES = new Set(['Set', 'Map']);
+const elementCollectionOf = (node) => {
+    const parent = node.parent;
+    if (parent?.type !== utils_1.AST_NODE_TYPES.NewExpression ||
+        parent.arguments[0] !== node) {
+        return null;
+    }
+    const callee = unwrapValueWrappers(parent.callee);
+    return callee.type === utils_1.AST_NODE_TYPES.Identifier &&
+        ELEMENT_PRESERVING_COLLECTION_NAMES.has(callee.name)
+        ? parent
+        : null;
+};
+/**
+ * The expressions a reference denotes a FROZEN value through: the reference
+ * itself and every property access rooted at it — `CONFIG`, `CONFIG.list`,
+ * `CONFIG.list.rows` for `CONFIG.list.rows`.
+ *
+ * `as const` freezes the value in depth, so a property of the constant carries
+ * the assertion exactly as the constant does, and an iteration is routinely
+ * reached through one (`CONFIG.list.values()`, `Array.from(CONFIG.list, fn)`).
+ * A derivation resolver reads a node's immediate parent, so it sees only the
+ * innermost access unless each step of the path is offered to it in turn
+ * (Issue #2340).
+ */
+const accessPathsRootedAt = (identifier) => {
+    const paths = [];
+    let current = outermostValueOf(identifier);
+    for (;;) {
+        paths.push(current);
+        const parent = current.parent;
+        if (!parent ||
+            parent.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+            parent.object !== current) {
+            return paths;
+        }
+        current = outermostValueOf(parent);
+    }
+};
+/**
+ * Every way a value derived from this one keeps the constant's ELEMENT types:
+ * a copy of it, the `Object.values`/`Object.entries` array over it, the
+ * iterator its own `values`/`entries` hands back, and the collection built out
+ * of it. Each resolver returns an ANCESTOR of the node it is given, which is
+ * what lets the iteration walk follow them transitively without looping.
+ */
+const DERIVATION_RESOLVERS = [
+    copyExpressionOf,
+    elementProjectionCallOf,
+    iteratorProjectionCallOf,
+    elementCollectionOf,
+];
+const enrolFully = (variables) => variables.map((variable) => ({
+    variable,
+    breaksOnAnyMutatingMethod: true,
+}));
+/**
+ * The bindings a callback's parameters at `positions` introduce, each carrying
+ * the question its position can break on.
+ *
+ * A callback routinely declares fewer parameters than the caller passes, so a
+ * position is taken only where the signature actually spells it.
+ *
+ * The scope manager answers for the WHOLE function — every parameter, and a
+ * function expression's own name — so the enrolled parameters' bindings are
+ * picked out by the spans they are declared in. Taking the function's list
+ * whole would enrol the accumulator of a `reduce`, typed from the seed value
+ * rather than from the constant, and the index, which the assertion cannot
+ * reach.
+ */
+const parameterBindingsOf = (callback, positions, declaredVariablesOf) => {
+    const enrolled = positions.flatMap(({ index, breaksOnAnyMutatingMethod }) => {
+        const param = callback.params[index];
+        return param ? [{ param, breaksOnAnyMutatingMethod }] : [];
+    });
+    if (enrolled.length === 0) {
+        return [];
+    }
+    return declaredVariablesOf(callback).flatMap((variable) => {
+        const position = enrolled.find(({ param }) => variable.defs.some((def) => def.name.range[0] >= param.range[0] &&
+            def.name.range[1] <= param.range[1]));
+        return position
+            ? [
+                {
+                    variable,
+                    breaksOnAnyMutatingMethod: position.breaksOnAnyMutatingMethod,
+                },
+            ]
+            : [];
+    });
+};
 /**
  * The bindings a construct that ITERATES `iterable` introduces: the head of a
  * `for…of` over it, the parameter an array method hands each element to, and —
@@ -708,7 +930,23 @@ const bindingsOfIterationOver = (iterable, declaredVariablesOf, iteratesConstant
     if (parent.type === utils_1.AST_NODE_TYPES.ForOfStatement &&
         parent.right === value &&
         parent.left.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
-        return declaredVariablesOf(parent.left);
+        return enrolFully(declaredVariablesOf(parent.left));
+    }
+    // `Array.from(X, mapfn)` hands each element of `X` to `mapfn` exactly as
+    // `X.map` hands it to a callback, so the mapper's first parameter is typed
+    // from the constant and `Array.from(ITEMS, (item) => { item.n = 2; … })` is
+    // TS2540 once `ITEMS` is frozen. The two-argument form reaches the walk
+    // nowhere else: `isCopyingCall` admits `Array.from` at one argument alone,
+    // because a mapper retypes the RESULT — which says nothing about the element
+    // it is handed (Issue #2340). The mapper takes the element first and the
+    // index second, and is handed no receiver array at all.
+    if (parent.type === utils_1.AST_NODE_TYPES.CallExpression &&
+        parent.arguments[0] === value &&
+        isNamespacedCallee(parent.callee, 'Array', 'from')) {
+        const mapper = parent.arguments[1];
+        return mapper && isFunctionValue(mapper)
+            ? parameterBindingsOf(mapper, [{ index: 0, breaksOnAnyMutatingMethod: true }], declaredVariablesOf)
+            : [];
     }
     if (path === null) {
         return [];
@@ -730,23 +968,17 @@ const bindingsOfIterationOver = (iterable, declaredVariablesOf, iteratesConstant
     const arrayIndex = iteratesConstantValue
         ? ARRAY_PARAMETER_INDEX_BY_METHOD.get(method)
         : undefined;
-    // A callback routinely declares fewer parameters than the method passes, so
-    // each position is taken only where the signature actually spells it.
-    const enrolled = [
-        callback.params[elementIndex],
-        arrayIndex === undefined ? undefined : callback.params[arrayIndex],
-    ].filter((param) => param !== undefined);
-    if (enrolled.length === 0) {
-        return [];
-    }
-    // The scope manager answers for the WHOLE function — every parameter, and a
-    // function expression's own name — so the enrolled parameters' bindings are
-    // picked out by the spans they are declared in. Taking the function's list
-    // whole would enrol the accumulator of a `reduce`, typed from the seed value
-    // rather than from the constant, and the index, which the assertion cannot
-    // reach.
-    return declaredVariablesOf(callback).filter((variable) => variable.defs.some((def) => enrolled.some((param) => def.name.range[0] >= param.range[0] &&
-        def.name.range[1] <= param.range[1])));
+    return parameterBindingsOf(callback, [
+        { index: elementIndex, breaksOnAnyMutatingMethod: true },
+        ...(arrayIndex === undefined
+            ? []
+            : [
+                {
+                    index: arrayIndex,
+                    breaksOnAnyMutatingMethod: !MUTABLE_ARRAY_PARAMETER_METHODS.has(method),
+                },
+            ]),
+    ], declaredVariablesOf);
 };
 /**
  * The bindings ITERATING this reference introduces, directly or through a value
@@ -763,15 +995,25 @@ const bindingsOfIterationOver = (iterable, declaredVariablesOf, iteratesConstant
  * only READS its element fixable.
  *
  * The derivations are followed because the receiver of the iteration is
- * routinely one step removed from the constant (`[...ITEMS].forEach(…)`,
- * `ITEMS.filter(Boolean).forEach(…)`, `Object.values(CONFIG).forEach(…)`): each
- * builds a fresh OUTER value whose elements are still the frozen ones, so the
- * element binding breaks identically. One derivation step is followed, matching
- * the depth the alias walk already follows a copy to.
+ * routinely removed from the constant (`[...ITEMS].forEach(…)`,
+ * `ITEMS.filter(Boolean).forEach(…)`, `Object.values(CONFIG).forEach(…)`,
+ * `ITEMS.values()`, `new Set(ITEMS)`): each builds a fresh OUTER value whose
+ * elements are still the frozen ones, so the element binding breaks
+ * identically.
+ *
+ * Following them is TRANSITIVE, on the same reasoning as the alias walk — every
+ * hop keeps the element type, so a chain of them keeps it too, and
+ * `ITEMS.filter(Boolean).slice().forEach((item) => { item.n = 2; })` is the
+ * same TS2540 as the one-hop spelling that already declines. A single step
+ * gave two spellings of one construct opposite verdicts (Issue #2340).
+ *
+ * The derivations are resolved from each step of the reference's own access
+ * path as well as from the reference, since the value a derivation is taken
+ * from is routinely a PROPERTY of the constant — see `accessPathsRootedAt`.
  *
  * The receiver ARRAY parameter is enrolled for the constant's own value or
- * member path ALONE, which is the one iterable of the three that hands the
- * callback the constant itself. A derivation hands it the fresh outer value it
+ * member path ALONE, the one iterable that hands the callback the constant
+ * itself. A derivation hands it the fresh outer value it
  * built, and mutating that is no readonly violation:
  * `[...ITEMS].forEach((item, index, arr) => { arr.push(3); })` does break after
  * the fix, but as TS2345 — the spread narrows the element type, so `3` is not
@@ -781,13 +1023,28 @@ const bindingsOfIterationOver = (iterable, declaredVariablesOf, iteratesConstant
  */
 const iterationBindingsOf = (identifier, declaredVariablesOf) => {
     const value = outermostValueOf(identifier);
-    const derivations = [copyExpressionOf(value), elementProjectionCallOf(value)];
-    return [
+    const bindings = [
         ...bindingsOfIterationOver(value, declaredVariablesOf, true),
-        ...derivations.flatMap((iterable) => iterable
-            ? bindingsOfIterationOver(iterable, declaredVariablesOf, false)
-            : []),
     ];
+    // Grown in place and walked by index, so a derivation OF a derivation is
+    // reached by the same loop without recursion of its own. Every resolver
+    // returns an ancestor of the node it is given, so the walk strictly ascends
+    // and terminates; `visited` keeps a node two resolvers agree on from being
+    // expanded twice.
+    const pending = accessPathsRootedAt(value);
+    const visited = new Set(pending);
+    for (let index = 0; index < pending.length; index += 1) {
+        for (const resolveDerivation of DERIVATION_RESOLVERS) {
+            const derived = resolveDerivation(pending[index]);
+            if (!derived || visited.has(derived)) {
+                continue;
+            }
+            visited.add(derived);
+            pending.push(derived);
+            bindings.push(...bindingsOfIterationOver(derived, declaredVariablesOf, false));
+        }
+    }
+    return bindings;
 };
 /**
  * Whether anything in the file stops this binding taking `as const`, under its
@@ -842,10 +1099,37 @@ const iterationBindingsOf = (identifier, declaredVariablesOf) => {
 const blocksAsConstAssertion = (variable, declaredVariablesOf) => {
     // Grown in place and walked by index: an alias found mid-walk is appended and
     // reached by the same loop, so the traversal needs no recursion of its own.
-    const pending = [variable];
-    const visited = new Set(pending);
+    const pending = [
+        { variable, breaksOnAnyMutatingMethod: true },
+    ];
+    const visited = new Set([variable]);
+    /**
+     * Whether a node is a REFERENCE to a binding already enrolled for this
+     * constant, and so holds a value typed from the constant itself.
+     *
+     * Answered from the scope manager's reference lists rather than by name, on
+     * the same terms as the rest of the walk: a same-named binding from another
+     * scope names another value and must not exempt anything.
+     *
+     * A binding enrolled LATER in the walk than the one being examined answers
+     * false here. That can only withhold an exemption, never grant one wrongly,
+     * so the walk order costs a report at worst.
+     */
+    const isEnrolledReference = (node) => {
+        const value = unwrapValueWrappers(node);
+        if (value.type !== utils_1.AST_NODE_TYPES.Identifier) {
+            return false;
+        }
+        for (const enrolledVariable of visited) {
+            if (enrolledVariable.references.some((enrolledReference) => enrolledReference.identifier === value)) {
+                return true;
+            }
+        }
+        return false;
+    };
     for (let index = 0; index < pending.length; index += 1) {
-        for (const reference of pending[index].references) {
+        const { variable: enrolled, breaksOnAnyMutatingMethod } = pending[index];
+        for (const reference of enrolled.references) {
             // Reassigning an alias is as disqualifying as writing through one. A
             // binding that takes its type from the constant narrows to the frozen
             // literal, so `let stage = DEFAULT; stage = 'live';` becomes TS2322 for
@@ -858,8 +1142,20 @@ const blocksAsConstAssertion = (variable, declaredVariablesOf) => {
                 return true;
             }
             const path = accessPathOf(reference.identifier);
+            // The ELEMENT question is asked of every binding alike: the elements are
+            // frozen whatever the container's own declaration says.
+            if (path !== null && isWriteTarget(path)) {
+                return true;
+            }
+            // The mutating-method question is asked in full of every binding the
+            // assertion types `readonly`, where any such call is a TS2339. A
+            // parameter the lib declares MUTABLE has no such break to have, so it is
+            // asked the narrower question that remains: does this call introduce a
+            // value the narrowed element type would have to accept (Issue #2340).
             if (path !== null &&
-                (isMutatingMethodCall(path) || isWriteTarget(path))) {
+                isMutatingMethodCall(path) &&
+                (breaksOnAnyMutatingMethod ||
+                    introducesForeignElement(path, isEnrolledReference))) {
                 return true;
             }
             // A copy carries the constant's frozen type into a second binding, so it
@@ -874,14 +1170,16 @@ const blocksAsConstAssertion = (variable, declaredVariablesOf) => {
                     : null;
             // A binding introduced by ITERATING the constant is enrolled beside the
             // aliases: it names the constant's CONTENTS, which the assertion freezes
-            // with the constant itself — see `iterationBindingsOf`.
+            // with the constant itself — see `iterationBindingsOf`. An alias is
+            // enrolled on the constant's own terms, because it denotes the constant's
+            // value and so carries its readonly-ness whole.
             const derived = [
-                ...(declarator ? declaredVariablesOf(declarator) : []),
+                ...enrolFully(declarator ? declaredVariablesOf(declarator) : []),
                 ...iterationBindingsOf(reference.identifier, declaredVariablesOf),
             ];
             for (const alias of derived) {
-                if (!visited.has(alias)) {
-                    visited.add(alias);
+                if (!visited.has(alias.variable)) {
+                    visited.add(alias.variable);
                     pending.push(alias);
                 }
             }

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "1.21.14",
+    "date": "2026-09-06T01:53:58.858Z",
+    "rules": [
+      {
+        "name": "global-const-style",
+        "changeType": "fix",
+        "issues": [
+          2340
+        ],
+        "summary": "enrol the element bindings of derived iterables (closes #2340)"
+      }
+    ]
+  },
   {
     "version": "1.21.13",
     "date": "2026-09-05T22:39:56.997Z",