@blumintinc/eslint-plugin-blumint 1.20.199 → 1.20.200

package/lib/index.js

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

package/lib/rules/enforce-firestore-doc-ref-generic.js

@@ -204,7 +204,7 @@ function typeDeclarationNamed(statement, name) {
  * dropped the nested-`any` check rather than reporting anything.
  */
 function declarationOfType(from, name) {
-    return (0, lexicalScope_1.resolveInEnclosingScopes)(from, (statements) => {
+    return (0, lexicalScope_1.resolveNameInEnclosingScopes)(from, name, 'type', (statements) => {
         for (const statement of statements) {
             const declaration = typeDeclarationNamed(statement, name);
             if (declaration) {

package/lib/rules/enforce-firestore-set-merge.js

@@ -408,7 +408,10 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
          * the shadow.
          */
         function resolveClassBody(name, reference) {
-            return ((0, lexicalScope_1.resolveInEnclosingScopes)(reference, (statements, container) => containerClasses(container, statements).get(name)) ?? null);
+            return ((0, lexicalScope_1.resolveNameInEnclosingScopes)(reference, name, 
+            // `extends X` names X as a value, so a value binder — the parameter
+            // of a mixin factory — is what shadows a same-named outer class.
+            'value', (statements, container) => containerClasses(container, statements).get(name)) ?? null);
         }
         function enclosingClassBody(node) {
             let current = node.parent;

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

@@ -40,7 +40,7 @@ function typeAliasNamed(statement, name) {
  * hoisting of type declarations.
  */
 function resolveTypeAlias(from, name) {
-    return (0, lexicalScope_1.resolveInEnclosingScopes)(from, (statements) => {
+    return (0, lexicalScope_1.resolveNameInEnclosingScopes)(from, name, 'type', (statements) => {
         for (const statement of statements) {
             const alias = typeAliasNamed(statement, name);
             if (alias) {

package/lib/rules/no-explicit-return-type.js

@@ -493,7 +493,7 @@ function createReturnCycleResolver(visitorKeys) {
         bindings.set(container, computed);
         return computed;
     };
-    const resolveFunctionInScope = (from, name) => (0, lexicalScope_1.resolveInEnclosingScopes)(from, (statements, container) => {
+    const resolveFunctionInScope = (from, name) => (0, lexicalScope_1.resolveNameInEnclosingScopes)(from, name, 'value', (statements, container) => {
         const scope = bindingsOf(container, statements);
         if (!scope.has(name))
             return undefined;

package/lib/rules/no-firestore-object-arrays.js

@@ -366,7 +366,7 @@ exports.noFirestoreObjectArrays = (0, createRule_1.createRule)({
          * declaration written below its own reference still resolves, matching
          * TypeScript's hoisting of type declarations.
          */
-        const resolveTypeName = (from, name) => (0, lexicalScope_1.resolveInEnclosingScopes)(from, (statements) => typeDeclarationIn(statements, name), () => {
+        const resolveTypeName = (from, name) => (0, lexicalScope_1.resolveNameInEnclosingScopes)(from, name, 'type', (statements) => typeDeclarationIn(statements, name), () => {
             if (interfaceNames.has(name))
                 return { kind: 'interface' };
             if (enumNames.has(name))
@@ -376,7 +376,7 @@ exports.noFirestoreObjectArrays = (0, createRule_1.createRule)({
                 ? { kind: 'alias', typeAnnotation: aliased }
                 : undefined;
         });
-        const resolveConstArray = (from, name) => (0, lexicalScope_1.resolveInEnclosingScopes)(from, (statements) => constArrayIn(statements, name), () => constArrayNameToLiteral.get(name));
+        const resolveConstArray = (from, name) => (0, lexicalScope_1.resolveNameInEnclosingScopes)(from, name, 'value', (statements) => constArrayIn(statements, name), () => constArrayNameToLiteral.get(name));
         // Keyed by resolved declaration rather than by name: one name can denote
         // different declarations in different scopes, so a name-keyed memo would
         // answer for whichever scope asked first.

package/lib/rules/prefer-batch-operations.js

@@ -272,7 +272,7 @@ function isMapInstance(node) {
  * searched instead, and the first match wins, which is what shadowing requires.
  */
 function findVariableDeclaration(node, varName) {
-    return (0, lexicalScope_1.resolveInEnclosingScopes)(node, (statements) => {
+    return (0, lexicalScope_1.resolveNameInEnclosingScopes)(node, varName, 'value', (statements) => {
         for (const statement of statements) {
             const declaration = (0, lexicalScope_1.declarationOf)(statement);
             if (declaration.type !== utils_1.AST_NODE_TYPES.VariableDeclaration)

package/lib/rules/prefer-spread-over-reassembly.js

@@ -266,7 +266,7 @@ function typeDeclarationIn(statements, name) {
  * find what the walk would have.
  */
 function findLocalTypeDeclaration(program, from, name) {
-    return ((0, lexicalScope_1.resolveInEnclosingScopes)(from, (statements) => typeDeclarationIn(statements, name) ?? undefined, () => typeDeclarationIn(program.body, name) ?? undefined) ?? null);
+    return ((0, lexicalScope_1.resolveNameInEnclosingScopes)(from, name, 'type', (statements) => typeDeclarationIn(statements, name) ?? undefined, () => typeDeclarationIn(program.body, name) ?? undefined) ?? null);
 }
 /**
  * Finds a type alias or interface a module exports by writing `export` in front

package/lib/rules/prevent-children-clobber.js

@@ -154,36 +154,57 @@ function constArrayMembersNamed(statement, name) {
  * type aliases hoist: a component declared above its own props alias must still
  * resolve it.
  */
-function aliasResolverFrom(lists, startIndex = 0) {
+function aliasResolverFrom(frames, startIndex = 0, barrierFrom = 0) {
+    /**
+     * Walks the frames outward, stopping at the first binder that takes the name.
+     *
+     * A frame's `barriers` gate entry into it from the frame inside it, so a
+     * resumed resolver skips the barriers of the frame it resumes at: the alias
+     * body it is reading already sits there and never crosses them.
+     */
+    const search = (name, namespace, found) => {
+        for (let index = startIndex; index < frames.length; index += 1) {
+            const frame = frames[index];
+            if (index >= barrierFrom &&
+                frame.barriers.some((barrier) => (0, lexicalScope_1.bindsNameOutsideStatements)(barrier, name, namespace))) {
+                return undefined;
+            }
+            const match = found(frame, index);
+            if (match !== undefined) {
+                return match;
+            }
+        }
+        return undefined;
+    };
     return {
         typeAlias(name) {
-            for (let index = startIndex; index < lists.length; index += 1) {
-                for (const statement of lists[index]) {
+            return search(name, 'type', (frame, index) => {
+                for (const statement of frame.statements) {
                     const declaration = aliasDeclarationNamed(statement, name);
                     if (declaration) {
                         return {
                             typeNode: declaration.typeAnnotation,
-                            resolve: aliasResolverFrom(lists, index),
+                            resolve: aliasResolverFrom(frames, index, index + 1),
                         };
                     }
                 }
-            }
-            return undefined;
+                return undefined;
+            });
         },
         constArrayKeys(name) {
-            for (let index = startIndex; index < lists.length; index += 1) {
-                for (const statement of lists[index]) {
+            return search(name, 'value', (frame) => {
+                for (const statement of frame.statements) {
                     const members = constArrayMembersNamed(statement, name);
                     if (members)
                         return members;
                 }
-            }
-            return undefined;
+                return undefined;
+            });
         },
     };
 }
 function aliasResolverAt(from) {
-    return aliasResolverFrom((0, lexicalScope_1.enclosingStatementLists)(from));
+    return aliasResolverFrom((0, lexicalScope_1.enclosingScopeFrames)(from));
 }
 /**
  * The property names a `Pick<T, K>` keep-list names, or `null` when the list is

package/lib/rules/require-hooks-default-params.js

@@ -303,7 +303,7 @@ exports.requireHooksDefaultParams = (0, createRule_1.createRule)({
          * resolved fine (#1781).
          */
         function resolveTypeDeclaration(from, name) {
-            return (0, lexicalScope_1.resolveInEnclosingScopes)(from, (statements) => {
+            return (0, lexicalScope_1.resolveNameInEnclosingScopes)(from, name, 'type', (statements) => {
                 for (const statement of statements) {
                     const found = typeDeclarationNamed(statement, name);
                     if (found) {

package/lib/rules/require-props-composition.js

@@ -1842,7 +1842,7 @@ exports.requirePropsComposition = (0, createRule_1.createRule)({
  * would instead hand one scope's verdict to another.
  */
 function findPropsTypeAliasByName(scope, typeName) {
-    return ((0, lexicalScope_1.resolveInEnclosingScopes)(scope, (statements) => {
+    return ((0, lexicalScope_1.resolveNameInEnclosingScopes)(scope, typeName, 'type', (statements) => {
         for (const stmt of statements) {
             const declaration = (0, lexicalScope_1.declarationOf)(stmt);
             if (declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration &&

package/lib/utils/lexicalScope.d.ts

@@ -82,3 +82,64 @@ export declare function resolveInEnclosingScopes<T>(from: TSESTree.Node, matchIn
  * the scope that referenced the alias.
  */
 export declare function enclosingStatementLists(from: TSESTree.Node): (readonly TSESTree.Node[])[];
+/**
+ * One statement container on the chain, with the binders guarding entry to it.
+ *
+ * {@link enclosingStatementLists} loses the nodes BETWEEN two containers, and
+ * those are exactly the ones that bind a name without holding a statement — a
+ * function's parameters and type parameters sit on the function, not on the
+ * block that is its body. A caller that materialises the chain rather than
+ * walking it once therefore cannot ask the question {@link
+ * resolveNameInEnclosingScopes} asks, unless the frames carry them.
+ *
+ * `barriers` holds the nodes crossed to reach this frame from the one inside
+ * it, so a binder among them shadows the name for this frame and every frame
+ * outside it.
+ */
+export type ScopeFrame = {
+    statements: readonly TSESTree.Node[];
+    barriers: readonly TSESTree.Node[];
+};
+/**
+ * The statement containers enclosing a node, innermost outward, each carrying
+ * the binders crossed to reach it.
+ */
+export declare function enclosingScopeFrames(from: TSESTree.Node): ScopeFrame[];
+/**
+ * Which of TypeScript's two declaration spaces a name is being resolved in.
+ *
+ * The distinction is load-bearing rather than pedantic: `function f<Props>()`
+ * shadows a `type Props` for every type position inside `f` while leaving a
+ * `const Props` untouched, and a parameter `(batch) => …` does the reverse.
+ * Testing both spaces at once would decline on a collision that TypeScript does
+ * not consider one, turning a resolution hole into an over-decline.
+ */
+export type BindingNamespace = 'type' | 'value';
+/**
+ * Whether a container binds `name` somewhere OTHER than its statement list.
+ *
+ * {@link statementsOf} recognises five containers, so every binder that is not a
+ * statement — a type parameter, a function parameter, a `catch` parameter, a
+ * `for` head, a function or class expression's own name — introduces a scope the
+ * walk cannot see. That makes the walk step straight past a shadow and let an
+ * outer declaration answer for a name the reference does not denote, which is
+ * precisely the failure move 3 of this module's contract forbids: an unrelated
+ * `type ToClose = () => void` answered for the type parameter of
+ * `function useThing<ToClose>(…)`, and `no-direct-function-state` reported —
+ * and rewrote — code whose state type it had never seen (#2257).
+ *
+ * A shadow is deliberately not a resolution. The binder proves only that the
+ * name is taken here, never what it denotes, so a caller must treat it exactly
+ * as {@link BOUND_UNPROVABLE} — stop, and answer nothing.
+ */
+export declare function bindsNameOutsideStatements(container: TSESTree.Node, name: string, namespace: BindingNamespace): boolean;
+/**
+ * {@link resolveInEnclosingScopes}, stopped by the binders it cannot see.
+ *
+ * The name and the space it is resolved in have to be stated by the caller
+ * because the shadow test needs them and `matchIn` only closes over them. That
+ * is the point of the separate entry rather than an optional argument: a caller
+ * resolving a name gets the shadow test by writing the name down, instead of by
+ * remembering that a hazard exists.
+ */
+export declare function resolveNameInEnclosingScopes<T>(from: TSESTree.Node, name: string, namespace: BindingNamespace, matchIn: (statements: readonly TSESTree.Node[], container: TSESTree.Node) => ScopeMatch<T>, fallback?: () => T | undefined): T | undefined;

package/lib/utils/lexicalScope.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.enclosingStatementLists = exports.resolveInEnclosingScopes = exports.BOUND_UNPROVABLE = exports.declarationOf = exports.statementsOf = void 0;
+exports.resolveNameInEnclosingScopes = exports.bindsNameOutsideStatements = exports.enclosingScopeFrames = exports.enclosingStatementLists = exports.resolveInEnclosingScopes = exports.BOUND_UNPROVABLE = exports.declarationOf = exports.statementsOf = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 /**
  * Same-file lexical resolution: what a name denotes at the point it is written.
@@ -128,4 +128,154 @@ function enclosingStatementLists(from) {
     return lists;
 }
 exports.enclosingStatementLists = enclosingStatementLists;
+/**
+ * The statement containers enclosing a node, innermost outward, each carrying
+ * the binders crossed to reach it.
+ */
+function enclosingScopeFrames(from) {
+    const frames = [];
+    let barriers = [];
+    let current = from;
+    while (current) {
+        const statements = statementsOf(current);
+        if (statements) {
+            frames.push({ statements, barriers });
+            barriers = [];
+        }
+        else {
+            barriers.push(current);
+        }
+        current = current.parent;
+    }
+    return frames;
+}
+exports.enclosingScopeFrames = enclosingScopeFrames;
+/**
+ * Whether a pattern binds `name`, looking through destructuring and defaults.
+ */
+function patternBindsName(node, name) {
+    if (!node) {
+        return false;
+    }
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.Identifier:
+            return node.name === name;
+        case utils_1.AST_NODE_TYPES.ArrayPattern:
+            return node.elements.some((element) => patternBindsName(element, name));
+        case utils_1.AST_NODE_TYPES.ObjectPattern:
+            return node.properties.some((property) => patternBindsName(property.type === utils_1.AST_NODE_TYPES.RestElement
+                ? property.argument
+                : property.value, name));
+        case utils_1.AST_NODE_TYPES.AssignmentPattern:
+            return patternBindsName(node.left, name);
+        case utils_1.AST_NODE_TYPES.RestElement:
+            return patternBindsName(node.argument, name);
+        default:
+            return false;
+    }
+}
+/**
+ * Whether a `for` head declares `name`, for any of the three loop spellings.
+ */
+function forHeadBindsName(node, name) {
+    const head = node.type === utils_1.AST_NODE_TYPES.ForStatement
+        ? node.init
+        : node.type === utils_1.AST_NODE_TYPES.ForOfStatement ||
+            node.type === utils_1.AST_NODE_TYPES.ForInStatement
+            ? node.left
+            : undefined;
+    return head?.type === utils_1.AST_NODE_TYPES.VariableDeclaration
+        ? head.declarations.some((declarator) => patternBindsName(declarator.id, name))
+        : false;
+}
+/**
+ * Whether a container binds `name` somewhere OTHER than its statement list.
+ *
+ * {@link statementsOf} recognises five containers, so every binder that is not a
+ * statement — a type parameter, a function parameter, a `catch` parameter, a
+ * `for` head, a function or class expression's own name — introduces a scope the
+ * walk cannot see. That makes the walk step straight past a shadow and let an
+ * outer declaration answer for a name the reference does not denote, which is
+ * precisely the failure move 3 of this module's contract forbids: an unrelated
+ * `type ToClose = () => void` answered for the type parameter of
+ * `function useThing<ToClose>(…)`, and `no-direct-function-state` reported —
+ * and rewrote — code whose state type it had never seen (#2257).
+ *
+ * A shadow is deliberately not a resolution. The binder proves only that the
+ * name is taken here, never what it denotes, so a caller must treat it exactly
+ * as {@link BOUND_UNPROVABLE} — stop, and answer nothing.
+ */
+function bindsNameOutsideStatements(container, name, namespace) {
+    const node = container;
+    if (namespace === 'type') {
+        // `typeParameters` names two unrelated things: the DECLARATION that binds
+        // `<T>` on a function or class, and the INSTANTIATION that supplies `<Foo>`
+        // at a call, `new`, or type reference. Only the first binds anything, and
+        // the second holds type nodes carrying no `name` at all, so reading one as
+        // the other throws on any ancestor that passes type arguments.
+        const declared = node.typeParameters?.type === utils_1.AST_NODE_TYPES.TSTypeParameterDeclaration
+            ? node.typeParameters.params
+            : undefined;
+        return (declared?.some((parameter) => parameter.name.name === name) === true ||
+            (container.type === utils_1.AST_NODE_TYPES.ClassExpression &&
+                node.id?.name === name));
+    }
+    if ((container.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        container.type === utils_1.AST_NODE_TYPES.ClassExpression) &&
+        node.id?.name === name) {
+        return true;
+    }
+    if (container.type === utils_1.AST_NODE_TYPES.CatchClause &&
+        patternBindsName(container.param, name)) {
+        return true;
+    }
+    if (forHeadBindsName(container, name)) {
+        return true;
+    }
+    // `TSTypeParameterDeclaration` also carries `params`, of a node kind no
+    // pattern arm matches, so a type parameter cannot leak into this space.
+    return (isFunctionLike(container) &&
+        node.params?.some((parameter) => patternBindsName(parameter, name)) === true);
+}
+exports.bindsNameOutsideStatements = bindsNameOutsideStatements;
+function isFunctionLike(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.TSDeclareFunction ||
+        node.type === utils_1.AST_NODE_TYPES.TSEmptyBodyFunctionExpression);
+}
+/**
+ * {@link resolveInEnclosingScopes}, stopped by the binders it cannot see.
+ *
+ * The name and the space it is resolved in have to be stated by the caller
+ * because the shadow test needs them and `matchIn` only closes over them. That
+ * is the point of the separate entry rather than an optional argument: a caller
+ * resolving a name gets the shadow test by writing the name down, instead of by
+ * remembering that a hazard exists.
+ */
+function resolveNameInEnclosingScopes(from, name, namespace, matchIn, fallback) {
+    let current = from;
+    while (current) {
+        const statements = statementsOf(current);
+        if (statements) {
+            const match = matchIn(statements, current);
+            if (match === exports.BOUND_UNPROVABLE) {
+                return undefined;
+            }
+            if (match !== undefined) {
+                return match;
+            }
+        }
+        // Tested after the statement list, so a container that both declares the
+        // name and binds it — `function f<T>() { type T = …; }` — resolves to the
+        // declaration the reference actually denotes.
+        if (bindsNameOutsideStatements(current, name, namespace)) {
+            return undefined;
+        }
+        current = current.parent;
+    }
+    return fallback?.();
+}
+exports.resolveNameInEnclosingScopes = resolveNameInEnclosingScopes;
 //# sourceMappingURL=lexicalScope.js.map

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,90 @@
 [
+  {
+    "version": "1.20.200",
+    "date": "2026-09-01T14:50:44.328Z",
+    "rules": [
+      {
+        "name": "enforce-firestore-doc-ref-generic",
+        "changeType": "fix",
+        "issues": [
+          2258
+        ],
+        "summary": "stop type resolution at a shadowing type parameter (closes #2258)"
+      },
+      {
+        "name": "enforce-firestore-set-merge",
+        "changeType": "fix",
+        "issues": [
+          2266
+        ],
+        "summary": "stop class resolution at a shadowing parameter (closes #2266)"
+      },
+      {
+        "name": "no-direct-function-state",
+        "changeType": "fix",
+        "issues": [
+          2257
+        ],
+        "summary": "stop alias resolution at a shadowing type parameter (closes #2257)"
+      },
+      {
+        "name": "no-explicit-return-type",
+        "changeType": "fix",
+        "issues": [
+          2265
+        ],
+        "summary": "stop function resolution at a shadowing parameter (closes #2265)"
+      },
+      {
+        "name": "no-firestore-object-arrays",
+        "changeType": "fix",
+        "issues": [
+          2261
+        ],
+        "summary": "stop resolution at a shadowing type parameter (closes #2261)"
+      },
+      {
+        "name": "prefer-batch-operations",
+        "changeType": "fix",
+        "issues": [
+          2264
+        ],
+        "summary": "stop setter resolution at a shadowing parameter (closes #2264)"
+      },
+      {
+        "name": "prefer-spread-over-reassembly",
+        "changeType": "fix",
+        "issues": [
+          2259
+        ],
+        "summary": "stop resolution at a shadowing type parameter (closes #2259)"
+      },
+      {
+        "name": "prevent-children-clobber",
+        "changeType": "fix",
+        "issues": [
+          2263
+        ],
+        "summary": "stop alias resolution at a shadowing parameter (closes #2263)"
+      },
+      {
+        "name": "require-hooks-default-params",
+        "changeType": "fix",
+        "issues": [
+          2262
+        ],
+        "summary": "stop type resolution at a shadowing type parameter (closes #2262)"
+      },
+      {
+        "name": "require-props-composition",
+        "changeType": "fix",
+        "issues": [
+          2260
+        ],
+        "summary": "stop props resolution at a shadowing type parameter (closes #2260)"
+      }
+    ]
+  },
   {
     "version": "1.20.199",
     "date": "2026-09-01T09:29:27.682Z",