@blumintinc/eslint-plugin-blumint 1.21.16 → 1.21.17

package/lib/index.js

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

package/lib/rules/enforce-memoize-async.js

@@ -636,6 +636,108 @@ function namesRelease(call) {
     const name = calleeName(call);
     return (name !== undefined && wordsOf(name).some((word) => RELEASE_WORDS.has(word)));
 }
+/**
+ * Words that name REPORTING on the work rather than acting on what the work
+ * held. A call spelled from one of them observes the attempt: it reads the
+ * handle to say something about it, which leaves the handle exactly as
+ * outstanding as it was.
+ *
+ * Words for a lifetime ending stay out of this set for the reason they stay
+ * out of `RELEASE_WORDS`: `end` and `close` name the moment, and reading them
+ * here would strip the carve-out from a genuine hand-back spelled that way.
+ */
+const REPORT_WORDS = new Set([
+    'count',
+    'debug',
+    'emit',
+    'error',
+    'increment',
+    'info',
+    'log',
+    'measure',
+    'observe',
+    'record',
+    'report',
+    'span',
+    'time',
+    'track',
+    'trace',
+    'warn',
+]);
+/**
+ * Receivers that are somewhere to SEND an observation, not something a method
+ * holds. A call routed through one of them reports whatever its own verb is
+ * called, which is what reaches `span.setAttribute(…)` and `this.stats.bump(…)`
+ * — spellings whose verb carries no report word at all.
+ */
+const SINK_NAMES = new Set([
+    'analytics',
+    'console',
+    'log',
+    'logger',
+    'metrics',
+    'span',
+    'stats',
+    'telemetry',
+    'tracer',
+]);
+/**
+ * The nearest static name of a call's receiver: `logger` for
+ * `this.logger.info(…)` and for `this.deps.logger.info(…)` alike, `console`
+ * for `console.log(…)`. The nearest name rather than the root is what a sink
+ * is spelled as — the root of an injected logger is `this`, which says nothing.
+ */
+function receiverName(call) {
+    const callee = withoutChain(call.callee);
+    if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression) {
+        return undefined;
+    }
+    const receiver = withoutValueWrappers(callee.object);
+    if (receiver.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return receiver.name;
+    }
+    return receiver.type === utils_1.AST_NODE_TYPES.MemberExpression &&
+        !receiver.computed &&
+        receiver.property.type === utils_1.AST_NODE_TYPES.Identifier
+        ? receiver.property.name
+        : undefined;
+}
+/**
+ * The binding a call's receiver is rooted at: `log` for `log.flush()`,
+ * undefined for `this.logger.info(…)`, whose root is `this`.
+ */
+function receiverRootBinding(call) {
+    const callee = withoutChain(call.callee);
+    if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression) {
+        return undefined;
+    }
+    let receiver = withoutValueWrappers(callee.object);
+    while (receiver.type === utils_1.AST_NODE_TYPES.MemberExpression) {
+        receiver = withoutValueWrappers(receiver.object);
+    }
+    return receiver.type === utils_1.AST_NODE_TYPES.Identifier
+        ? receiver.name
+        : undefined;
+}
+/**
+ * Whether the call reads as an observation of the attempt: its verb names a
+ * report, or it is routed through a sink. Either way what it does with a handle
+ * it names is describe it.
+ *
+ * A hand-back word in the verb is decided ahead of this, so
+ * `this.logger.release(lease)` stays a release: a sink is inferred from a name
+ * a caller chose freely, while a release verb states the intent outright.
+ */
+function readsAsReport(call) {
+    const name = calleeName(call);
+    if (name !== undefined &&
+        wordsOf(name).some((word) => REPORT_WORDS.has(word))) {
+        return true;
+    }
+    const receiver = receiverName(call);
+    return (receiver !== undefined &&
+        wordsOf(receiver).some((word) => SINK_NAMES.has(word)));
+}
 /**
  * Whether the `finally` gives back something the method took, rather than
  * reporting on the work that took it.
@@ -650,6 +752,14 @@ function namesRelease(call) {
  * bookkeeping the work never touched — `clearTimeout(t)` beside a `fetch` that
  * ignores `t`, or a span that observes the attempt from outside it.
  *
+ * Naming the handle is evidence the finalizer USED it, though, and a log line
+ * uses it exactly as loudly as a hand-back does: `this.logger.info('used
+ * lease', lease.id)` closes the triangle while the lease leaks. So a call that
+ * reads as an observation — a reporting verb, or a route through a sink — does
+ * not close it. The exception is a call ON the handle whose own acquisition is
+ * being paired: `log.flush()` acts on the thing it is spelled after, and only a
+ * receiver NAME suggested otherwise.
+ *
  * The second shape is the name, and it covers the release a method does not
  * acquire: the caller takes the lock and passes it in, leaving `finally {
  * lock.release() }` with nothing in the body to pair against. Structurally that
@@ -671,10 +781,16 @@ function releasesResource(guarded, finalizer, acquisitions) {
         if (namesRelease(node)) {
             return true;
         }
+        const reporting = readsAsReport(node);
+        const receiver = reporting ? receiverRootBinding(node) : undefined;
         for (const bindings of acquisitions) {
-            if (mentionsAny(node, bindings) && mentionsAny(guarded, bindings)) {
-                return true;
+            if (!mentionsAny(node, bindings) || !mentionsAny(guarded, bindings)) {
+                continue;
             }
+            if (reporting && (receiver === undefined || !bindings.has(receiver))) {
+                continue;
+            }
+            return true;
         }
     }
     return false;
@@ -691,7 +807,8 @@ function releasesResource(guarded, finalizer, acquisitions) {
  * (`finally { done = true; }`) records that the attempt finished instead of
  * undoing it, and one that logs, emits a metric, ends a span or clears a timer
  * the work never touched reports on the attempt instead of giving anything
- * back, so none of them costs the method its report.
+ * back, so none of them costs the method its report. A log line naming the
+ * handle is such a report however much of the handle it names.
  */
 function releasesInOwnFinalizer(fn) {
     const acquisitions = acquisitionsOf(fn);

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

@@ -486,7 +486,7 @@ const accessPathRootOf = (node) => {
     }
 };
 /**
- * Every name a binding PATTERN introduces — `x`, `{ n }`, `{ n: value }`,
+ * Every identifier a binding PATTERN introduces — `x`, `{ n }`, `{ n: value }`,
  * `[head]`, `{ n, ...rest }` and every nesting of them.
  *
  * Destructuring and member access are two spellings of ONE extraction, so a
@@ -505,16 +505,16 @@ const accessPathRootOf = (node) => {
  * Reading the default would trade an over-decline, which costs one report, for
  * a `--fix` that stops the file compiling.
  */
-const patternBoundNames = (pattern, names = new Set()) => {
+const patternBoundIdentifiers = (pattern, bindings = new Set()) => {
     switch (pattern.type) {
         case utils_1.AST_NODE_TYPES.Identifier:
-            names.add(pattern.name);
+            bindings.add(pattern);
             break;
         case utils_1.AST_NODE_TYPES.ObjectPattern:
             for (const property of pattern.properties) {
-                patternBoundNames(property.type === utils_1.AST_NODE_TYPES.Property
+                patternBoundIdentifiers(property.type === utils_1.AST_NODE_TYPES.Property
                     ? property.value
-                    : property.argument, names);
+                    : property.argument, bindings);
             }
             break;
         case utils_1.AST_NODE_TYPES.ArrayPattern:
@@ -522,21 +522,28 @@ const patternBoundNames = (pattern, names = new Set()) => {
                 // An array pattern holds a HOLE for each skipped position
                 // (`([, second]) => second`), which binds no name.
                 if (element) {
-                    patternBoundNames(element, names);
+                    patternBoundIdentifiers(element, bindings);
                 }
             }
             break;
         case utils_1.AST_NODE_TYPES.AssignmentPattern:
-            patternBoundNames(pattern.left, names);
+            patternBoundIdentifiers(pattern.left, bindings);
             break;
         case utils_1.AST_NODE_TYPES.RestElement:
-            patternBoundNames(pattern.argument, names);
+            patternBoundIdentifiers(pattern.argument, bindings);
             break;
         default:
             break;
     }
-    return names;
+    return bindings;
 };
+/**
+ * The NAMES those bindings introduce, which is what the value descent matches
+ * the element by — see `returnsHandedElement` for why that descent works in
+ * spellings rather than in bindings. Derived from the identifiers rather than
+ * collected alongside them so the two answers cannot drift apart.
+ */
+const patternBoundNames = (pattern) => new Set([...patternBoundIdentifiers(pattern)].map((binding) => binding.name));
 /**
  * Every value a function hands back: its expression body, the argument of each
  * `return` in its block, and the argument of each `yield` — a generator hands
@@ -706,6 +713,205 @@ const functionCarriesElementType = (fn, elementNames) => {
     return (carriesDefault ||
         returnedValuesOf(fn).some((handed) => carriesElementType(handed, reachable)));
 };
+/**
+ * Every VALUE binding a single statement introduces into the scope holding it.
+ *
+ * Type declarations are skipped because `typeof x` reads the value namespace,
+ * so an alias or an interface spelled like the element shadows it nowhere.
+ *
+ * A `var` is collected against the block it is written in rather than the
+ * function it hoists to, so it is seen from inside that block alone. That
+ * under-reads shadowing, and a missed shadow reads a `typeof` as the element,
+ * which withholds a report — the cheap error of the two, since claiming a shadow
+ * that is not there licenses a freeze.
+ */
+const statementBoundIdentifiers = (statement, bindings) => {
+    switch (statement.type) {
+        case utils_1.AST_NODE_TYPES.VariableDeclaration:
+            for (const declarator of statement.declarations) {
+                patternBoundIdentifiers(declarator.id, bindings);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.FunctionDeclaration:
+        case utils_1.AST_NODE_TYPES.ClassDeclaration:
+        case utils_1.AST_NODE_TYPES.TSEnumDeclaration:
+            if (statement.id) {
+                bindings.add(statement.id);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.ImportDeclaration:
+            for (const specifier of statement.specifiers) {
+                bindings.add(specifier.local);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.ExportNamedDeclaration:
+        case utils_1.AST_NODE_TYPES.ExportDefaultDeclaration:
+            if (statement.declaration) {
+                statementBoundIdentifiers(statement.declaration, bindings);
+            }
+            break;
+        default:
+            break;
+    }
+};
+/**
+ * The binding a node introduces for `name` in its OWN scope, or null when it
+ * introduces none.
+ *
+ * Carries just enough of the scope grammar to answer whether anything between a
+ * `typeof` and the element parameter rebinds the name, which is the only
+ * question `resolvesToElementBinding` asks of it. A scope form left out can fail
+ * to find a shadow and never invent one, so the error it admits is a withheld
+ * report rather than a freeze.
+ */
+const scopeBindingOf = (node, name) => {
+    const bindings = new Set();
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.ArrowFunctionExpression:
+        case utils_1.AST_NODE_TYPES.FunctionExpression:
+        case utils_1.AST_NODE_TYPES.FunctionDeclaration:
+        case utils_1.AST_NODE_TYPES.TSDeclareFunction:
+            for (const parameter of node.params) {
+                patternBoundIdentifiers(parameter, bindings);
+            }
+            // A function EXPRESSION binds its own name inside itself; an arrow has no
+            // name to bind.
+            if (node.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression && node.id) {
+                bindings.add(node.id);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.CatchClause:
+            if (node.param) {
+                patternBoundIdentifiers(node.param, bindings);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.ClassDeclaration:
+        case utils_1.AST_NODE_TYPES.ClassExpression:
+            if (node.id) {
+                bindings.add(node.id);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.ForStatement:
+            if (node.init) {
+                statementBoundIdentifiers(node.init, bindings);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.ForInStatement:
+        case utils_1.AST_NODE_TYPES.ForOfStatement:
+            statementBoundIdentifiers(node.left, bindings);
+            break;
+        case utils_1.AST_NODE_TYPES.Program:
+        case utils_1.AST_NODE_TYPES.BlockStatement:
+        case utils_1.AST_NODE_TYPES.TSModuleBlock:
+        case utils_1.AST_NODE_TYPES.StaticBlock:
+            for (const statement of node.body) {
+                statementBoundIdentifiers(statement, bindings);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.SwitchCase:
+            for (const statement of node.consequent) {
+                statementBoundIdentifiers(statement, bindings);
+            }
+            break;
+        default:
+            break;
+    }
+    for (const binding of bindings) {
+        if (binding.name === name) {
+            return binding;
+        }
+    }
+    return null;
+};
+/**
+ * Whether an identifier written in a TYPE position resolves to one of the
+ * bindings the element parameter introduces.
+ *
+ * Resolution is lexical — the nearest enclosing binder wins — rather than a
+ * match on the name, because a `typeof` deep inside a callback can spell the
+ * element's name while naming something else entirely: `(item) => () => { const
+ * item = { n: 9 }; return (x: typeof item) => x; }` is typed from that local
+ * binding, which the constant reaches never, and freezing under it is measured
+ * safe.
+ */
+const resolvesToElementBinding = (identifier, elementBindings) => {
+    for (let node = identifier.parent; node; node = node.parent) {
+        const binding = scopeBindingOf(node, identifier.name);
+        if (binding) {
+            return elementBindings.has(binding);
+        }
+    }
+    return false;
+};
+/**
+ * The identifier a `typeof` query is rooted at — `item` for `typeof item` and
+ * for `typeof item.n` alike — or null when the query names an import instead.
+ */
+const typeQueryRootOf = (query) => {
+    let entity = query.exprName;
+    while (entity.type === utils_1.AST_NODE_TYPES.TSQualifiedName) {
+        entity = entity.left;
+    }
+    return entity.type === utils_1.AST_NODE_TYPES.Identifier ? entity : null;
+};
+/**
+ * Whether a `typeof` anywhere inside `node` names the element.
+ *
+ * The element's type reaches a mapper's result through TYPE positions as
+ * readily as through value ones: a handed-back closure annotated `(x: typeof
+ * item) => x` is typed from the element without ever returning it, so freezing
+ * the receiver makes `makers.push((v: { n: number }) => v)` TS2345 for an input
+ * that compiled (Issue #2357).
+ *
+ * The query is looked for by STRUCTURE rather than by enumerating the type
+ * syntax it can sit under, because every wrapper measured breaks the build the
+ * same way — `typeof item.n`, `Wrapper<typeof item>`, `(typeof item)[]`,
+ * `[typeof item]`, `(typeof item)['n']`, a union, a conditional type, a
+ * function type, and a RETURN annotation rather than a parameter — and
+ * enumerating forms is what leaves the next spelling out.
+ *
+ * The sweep covers the whole CALLBACK rather than the values it returns,
+ * because the type an annotation names can be introduced beside them: `type
+ * Held = typeof item;` or an `interface` declared in the callback's body, a
+ * `satisfies` written in an expression, a class expression's field. Each of
+ * those is measured to break under `--fix` too, and each is invisible to a
+ * sweep of the returned value alone. A `typeof` of the element that composes
+ * the result nowhere then withholds one report, which is the cheap error of
+ * the two.
+ */
+const typeQueryNamesElement = (node, elementBindings) => {
+    // A query spelling some other name resolves to some other binding whatever
+    // the scopes hold, so screening on the spelling first keeps the lexical walk
+    // for the queries that can possibly be the element.
+    const spellings = new Set([...elementBindings].map((binding) => binding.name));
+    let found = false;
+    const visit = (current) => {
+        if (found) {
+            return;
+        }
+        if (current.type === utils_1.AST_NODE_TYPES.TSTypeQuery) {
+            const root = typeQueryRootOf(current);
+            if (root &&
+                spellings.has(root.name) &&
+                resolvesToElementBinding(root, elementBindings)) {
+                found = true;
+                return;
+            }
+        }
+        for (const [key, value] of Object.entries(current)) {
+            if (key === 'parent') {
+                continue;
+            }
+            for (const child of Array.isArray(value) ? value : [value]) {
+                if (ASTHelpers_1.ASTHelpers.isNode(child)) {
+                    visit(child);
+                }
+            }
+        }
+    };
+    visit(node);
+    return found;
+};
 /**
  * Whether a callback hands back the value it is given at `elementIndex`, or a
  * value the element's type reaches — see `carriesElementType`.
@@ -732,6 +938,9 @@ const functionCarriesElementType = (fn, elementNames) => {
  * different things widen their union, so the assertion may then reach nothing
  * and the withhold costs a report; demanding EVERY branch would instead ship a
  * `--fix` that stops the file compiling.
+ *
+ * A TYPE position carries the element too, and is asked as a separate question
+ * because it is resolved rather than name-matched — see `typeQueryNamesElement`.
  */
 const returnsHandedElement = (callback, elementIndex) => {
     if (!callback || !isFunctionValue(callback)) {
@@ -741,10 +950,14 @@ const returnsHandedElement = (callback, elementIndex) => {
     if (!parameter) {
         return false;
     }
-    const elementNames = patternBoundNames(parameter);
-    if (elementNames.size === 0) {
+    const elementBindings = patternBoundIdentifiers(parameter);
+    if (elementBindings.size === 0) {
         return false;
     }
+    if (typeQueryNamesElement(callback, elementBindings)) {
+        return true;
+    }
+    const elementNames = patternBoundNames(parameter);
     return returnedValuesOf(callback).some((value) => carriesElementType(value, elementNames));
 };
 /**
@@ -874,6 +1087,165 @@ const copyExpressionOf = (node) => {
     }
     return null;
 };
+/**
+ * The argument position `Array.from`'s MAPPER arrives in.
+ *
+ * Named beside `ARRAY_FROM_MAPPER_ELEMENT_INDEX` because the mapper is the
+ * SECOND argument while the element it is handed is its FIRST parameter, so
+ * two different indices for one call sit beside each other here.
+ */
+const ARRAY_FROM_MAPPER_ARGUMENT_INDEX = 1;
+/**
+ * The call whose RESULT is typed from what this function literal hands back:
+ * the `map`/`flatMap` call it is the callback of, or the `Array.from` call it
+ * is the mapper of.
+ *
+ * The RECEIVER is not consulted, because the question is what composes the
+ * result rather than where the elements came from — a mapper handing back a
+ * value of its own retypes the result whatever it is mapping over.
+ *
+ * A callback passed by NAME is a LIMITATION rather than a decision: the climb
+ * ends at the function's own declaration, and reaching the call sites from
+ * there is a hop through the binding that this resolver does not take, so
+ * `const pick = () => OTHER; items.map(pick)` keeps its report and its fix.
+ */
+const mapperCallOf = (fn) => {
+    const value = outermostValueOf(fn);
+    const call = value.parent;
+    if (!call || call.type !== utils_1.AST_NODE_TYPES.CallExpression) {
+        return null;
+    }
+    if (call.arguments[ARRAY_FROM_MAPPER_ARGUMENT_INDEX] === value &&
+        isNamespacedCallee(call.callee, 'Array', 'from')) {
+        return call;
+    }
+    if (call.arguments[0] !== value) {
+        return null;
+    }
+    const callee = unwrapValueWrappers(call.callee);
+    if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression) {
+        return null;
+    }
+    const method = accessedPropertyName(callee);
+    return method !== null && CALLBACK_TYPED_COPY_METHODS.has(method)
+        ? call
+        : null;
+};
+/** The function whose body encloses this node, or null at the top level. */
+const enclosingFunctionOf = (node) => {
+    let current = node.parent;
+    while (current) {
+        if (FUNCTION_TYPES.has(current.type)) {
+            return current;
+        }
+        current = current.parent;
+    }
+    return null;
+};
+/**
+ * The expression whose type this value COMPOSES, or null where it composes
+ * nothing that leaves the position it sits in.
+ *
+ * These are the positions `carriesElementType` descends through, read in the
+ * opposite direction: that resolver starts from a returned value and asks
+ * whether the element reaches it, while this one starts from a reference and
+ * climbs to what is returned. The two must agree, since one file's
+ * `ITEMS.map((x) => [x])` and `ITEMS.map(() => [OTHER])` are the same
+ * composition of a frozen value into a fresh array.
+ *
+ * A `return` and a `yield` climb to the function they leave, whose result type
+ * they compose — the pair `returnedValuesOf` collects going the other way.
+ *
+ * Everything else stops the climb, which withholds nothing that matters: an
+ * arithmetic operand, a template literal and a call argument all WIDEN, so the
+ * assertion no longer reaches the value the position produces.
+ */
+const composedValueOf = (value) => {
+    const parent = value.parent;
+    if (!parent) {
+        return null;
+    }
+    switch (parent.type) {
+        case utils_1.AST_NODE_TYPES.ConditionalExpression:
+            // The TEST decides which branch runs rather than what the expression is
+            // typed as, so only the branches compose the result's union.
+            return parent.consequent === value || parent.alternate === value
+                ? parent
+                : null;
+        case utils_1.AST_NODE_TYPES.LogicalExpression:
+            return parent;
+        case utils_1.AST_NODE_TYPES.SequenceExpression:
+            return parent.expressions[parent.expressions.length - 1] === value
+                ? parent
+                : null;
+        case utils_1.AST_NODE_TYPES.ArrayExpression:
+            return parent;
+        case utils_1.AST_NODE_TYPES.Property:
+            // A COMPUTED key types the property NAME rather than the value, and the
+            // pattern screen reads names, not keys.
+            return parent.value === value &&
+                parent.parent?.type === utils_1.AST_NODE_TYPES.ObjectExpression
+                ? parent.parent
+                : null;
+        case utils_1.AST_NODE_TYPES.SpreadElement:
+            return parent.parent &&
+                (parent.parent.type === utils_1.AST_NODE_TYPES.ArrayExpression ||
+                    parent.parent.type === utils_1.AST_NODE_TYPES.ObjectExpression)
+                ? parent.parent
+                : null;
+        case utils_1.AST_NODE_TYPES.AwaitExpression:
+            return parent;
+        case utils_1.AST_NODE_TYPES.ArrowFunctionExpression:
+            return parent.body === value ? parent : null;
+        case utils_1.AST_NODE_TYPES.CallExpression:
+            // A function literal INVOKED on the spot hands its returns to the call,
+            // which is the one call whose result the assertion still reaches — the
+            // exception `carriesElementType` makes for the same shape.
+            return isFunctionValue(value) && parent.callee === value ? parent : null;
+        case utils_1.AST_NODE_TYPES.ReturnStatement:
+        case utils_1.AST_NODE_TYPES.YieldExpression:
+            return parent.argument === value ? enclosingFunctionOf(parent) : null;
+        default:
+            return null;
+    }
+};
+/**
+ * The `map`/`flatMap`/`Array.from` call whose result is typed from THIS value,
+ * or null when no mapper hands it back.
+ *
+ * A mapper's result is typed from what it returns, so a constant reached
+ * through that return types the copy exactly as the receiver's own element type
+ * does — and freezing the constant narrows the copy's elements, making
+ * `const xs = ITEMS.map(() => OTHER); xs.push({ n: 9 })` TS2322 for an input
+ * that compiled (Issue #2356). `carriesElementType` cannot answer this: it is
+ * keyed on the names the ELEMENT parameter binds, and the value here comes from
+ * a different binding entirely.
+ *
+ * The constant is identified by the reference walk that calls this, which reads
+ * the scope manager's reference lists rather than matching names — so a
+ * callback-local binding that shadows the constant's name is a different
+ * variable and reaches this resolver never, and a LOCAL constant, which this
+ * rule does not freeze, is walked never.
+ *
+ * Returns an ANCESTOR of the node it is given, as every derivation resolver
+ * must, so the walk that follows them strictly ascends.
+ */
+const mapperResultOf = (node) => {
+    let value = outermostValueOf(node);
+    for (;;) {
+        if (isFunctionValue(value)) {
+            const call = mapperCallOf(value);
+            if (call) {
+                return call;
+            }
+        }
+        const composed = composedValueOf(value);
+        if (!composed) {
+            return null;
+        }
+        value = outermostValueOf(composed);
+    }
+};
 /**
  * Array methods whose result is an ELEMENT of the receiver rather than a fresh
  * array over it.
@@ -1045,19 +1417,23 @@ const ELEMENT_PARAMETER_INDEX_BY_METHOD = new Map([
  * handed-node spelling escapes it (Issue #2339).
  *
  * The position is carried apart from the element's because the two are enrolled
- * on different terms rather than because they differ by one: an element keeps
- * the constant's type through every derivation the iteration walk follows,
- * while the receiver is the constant only when the iteration reads the
- * constant's own value or member path — see `iterationBindingsOf`.
+ * on different TERMS rather than because they differ by one: an element keeps
+ * the constant's readonly-ness through every derivation the iteration walk
+ * follows, while the receiver parameter carries it only when the iteration
+ * reads the constant's own value or member path. Over a DERIVED receiver
+ * (`[...ITEMS].forEach(…)`) the parameter names the fresh array the derivation
+ * built, which is mutable, and only the narrower assignability question remains
+ * — see `MUTABLE_ARRAY_PARAMETER_METHODS` and `iterationBindingsOf`.
  * `reduce`/`reduceRight` push it to fourth, having spent the first position on
  * the accumulator.
  *
  * `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).
+ * parameter `T[]` where every sibling on `ReadonlyArray` 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],
@@ -1074,7 +1450,14 @@ const ARRAY_PARAMETER_INDEX_BY_METHOD = new Map([
     ['reduceRight', 3],
 ]);
 /**
- * The methods above whose receiver-array parameter is declared MUTABLE `T[]`.
+ * The methods above whose receiver-array parameter is declared MUTABLE `T[]`
+ * even when the receiver itself is frozen.
+ *
+ * The set is keyed on the METHOD because that is the only thing that varies
+ * once the receiver is the constant's own value. A DERIVED receiver settles the
+ * same question by a shorter route and does not consult this set at all: the
+ * derivation builds a fresh `Array<T>`, so every one of its methods declares
+ * the parameter `T[]` and the whole family is mutable (Issue #2355).
  *
  * 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
@@ -1420,13 +1803,15 @@ const frozenAccessPathsRootedAt = (identifier, frozenValue) => {
 };
 /**
  * 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.
+ * a copy of it, the mapper result it is handed back into, 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,
+    mapperResultOf,
     elementProjectionCallOf,
     iteratorProjectionCallOf,
     elementCollectionOf,
@@ -1446,12 +1831,18 @@ const DERIVATION_RESOLVERS = [
  * absent from the resolver itself, its result being `string[]` whatever the
  * argument holds.
  *
+ * A mapper RESULT is followed for that same TYPE half: the copy it builds is
+ * typed from what the callback hands back, so a constant reached through that
+ * return narrows the copy's elements and `const xs = ITEMS.map(() => OTHER);
+ * xs.push({ n: 9 });` is TS2322 for an input that compiled (Issue #2356).
+ *
  * The remaining iteration resolvers stay absent: an ITERATOR is not a value a
  * binding is written through, and `new Set(ITEMS)` reshapes the constant into a
  * collection whose own question the iteration walk asks.
  */
 const ALIAS_DERIVATION_RESOLVERS = [
     copyExpressionOf,
+    mapperResultOf,
     elementExpressionOf,
     elementProjectionCallOf,
 ];
@@ -1541,11 +1932,12 @@ const parameterBindingsOf = (callback, positions, declaredVariablesOf) => {
  * passed by name is declared elsewhere, where its parameter carries whatever
  * type that declaration gives it rather than one read off the constant.
  *
- * `iteratesConstantValue` says whether `iterable` is the constant's own value
- * or member path rather than something derived from it. It gates the receiver
- * ARRAY parameter alone: the element parameter is typed from the constant
- * either way, while the array parameter names the constant only in the first
- * case — see `iterationBindingsOf`.
+ * `iteratesConstantValue` says whether `iterable` is the constant's own value or
+ * member path rather than something derived from it. It decides the TERMS the
+ * receiver ARRAY parameter is enrolled on rather than whether to enrol it: the
+ * element parameter is typed from the constant either way, while the array
+ * parameter is the constant itself only in the first case and a fresh mutable
+ * array in the second — see `iterationBindingsOf`.
  */
 const bindingsOfIterationOver = (iterable, declaredVariablesOf, iteratesConstantValue) => {
     // The member path is resolved first because the iterated expression is
@@ -1596,9 +1988,7 @@ const bindingsOfIterationOver = (iterable, declaredVariablesOf, iteratesConstant
     if (!callback || !isFunctionValue(callback)) {
         return [];
     }
-    const arrayIndex = iteratesConstantValue
-        ? ARRAY_PARAMETER_INDEX_BY_METHOD.get(method)
-        : undefined;
+    const arrayIndex = ARRAY_PARAMETER_INDEX_BY_METHOD.get(method);
     return parameterBindingsOf(callback, [
         { index: elementIndex, breaksOnAnyMutatingMethod: true },
         ...(arrayIndex === undefined
@@ -1606,7 +1996,8 @@ const bindingsOfIterationOver = (iterable, declaredVariablesOf, iteratesConstant
             : [
                 {
                     index: arrayIndex,
-                    breaksOnAnyMutatingMethod: !MUTABLE_ARRAY_PARAMETER_METHODS.has(method),
+                    breaksOnAnyMutatingMethod: iteratesConstantValue &&
+                        !MUTABLE_ARRAY_PARAMETER_METHODS.has(method),
                 },
             ]),
     ], declaredVariablesOf);
@@ -1642,15 +2033,19 @@ const bindingsOfIterationOver = (iterable, declaredVariablesOf, iteratesConstant
  * 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, 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
- * assignable — which belongs to the literal-narrowing family filed as #2330 and
- * needs the type checker. Enrolling it here would withhold the assertion for a
- * reason this arm cannot justify, so it is an over-decline (Issue #2339).
+ * The receiver ARRAY parameter is enrolled for a derived iterable as well as for
+ * the constant's own value, but on different terms, because the two break on
+ * different things. The constant's own value hands the callback the frozen
+ * array, so any mutating call through the parameter is a TS2339. A derivation
+ * hands it the fresh MUTABLE array the derivation built, where there is no
+ * TS2339 to have — and the fresh array's ELEMENTS are still the constant's, so
+ * the assertion narrows what it accepts and a call that INSERTS a value from
+ * outside the constant is rejected:
+ * `[...ITEMS].forEach((item, index, arr) => { arr.push({ n: 3 }); })` compiles
+ * and is TS2322 under the assertion (Issue #2355). That is the same narrow
+ * question `MUTABLE_ARRAY_PARAMETER_METHODS` poses for `flatMap`, so the derived
+ * enrolment reuses it, keeping `arr.sort()` and `arr.push(item)` fixable while
+ * declining the insertion.
  */
 const iterationBindingsOf = (identifier, declaredVariablesOf) => {
     const value = outermostValueOf(identifier);

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "1.21.17",
+    "date": "2026-09-07T12:35:50.668Z",
+    "rules": [
+      {
+        "name": "enforce-memoize-async",
+        "changeType": "fix",
+        "issues": [
+          2359
+        ],
+        "summary": "tell a finalizer's log from a hand-back (closes #2359)"
+      },
+      {
+        "name": "global-const-style",
+        "changeType": "fix",
+        "issues": [
+          2355,
+          2356,
+          2357
+        ],
+        "summary": "read the element's type through type positions, not only value ones (closes #2357); track a copy against every constant whose type reaches it (closes #2356); withhold when a callback inserts through the receiver parameter (closes #2355)"
+      }
+    ]
+  },
   {
     "version": "1.21.16",
     "date": "2026-09-07T07:42:18.078Z",