@blumintinc/eslint-plugin-blumint 1.20.82 → 1.20.84

package/lib/index.js

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

package/lib/rules/enforce-identifiable-firestore-type.js

@@ -38,15 +38,27 @@ exports.enforceIdentifiableFirestoreType = (0, createRule_1.createRule)({
         }
         // Get the expected type name from the parent folder
         const folderName = path_1.default.basename(path_1.default.dirname(filename));
-        let hasExpectedType = false;
-        let typeHasIdentifiable = false;
+        // The folder-matching alias only satisfies the rule if it is reachable by
+        // consumers. An alias can be exported inline (`export type X = ...`) or
+        // separately (`export { X }` / `export type { X }`), and the separate form
+        // can appear either before or after the declaration, so exportedness can't
+        // be decided inside the TSTypeAliasDeclaration visitor alone — it's
+        // resolved once the whole module has been scanned, in Program:exit.
+        let matchingAliasNode = null;
+        let matchingAliasInlineExported = false;
+        let matchingAliasHasIdentifiable = false;
+        const locallyExportedNames = new Set();
         return {
             Program() {
                 // Reset flags for each file
-                hasExpectedType = false;
-                typeHasIdentifiable = false;
+                matchingAliasNode = null;
+                matchingAliasInlineExported = false;
+                matchingAliasHasIdentifiable = false;
+                locallyExportedNames.clear();
             },
             'Program:exit'(node) {
+                const hasExpectedType = matchingAliasNode !== null &&
+                    (matchingAliasInlineExported || locallyExportedNames.has(folderName));
                 if (!hasExpectedType) {
                     context.report({
                         node,
@@ -57,7 +69,7 @@ exports.enforceIdentifiableFirestoreType = (0, createRule_1.createRule)({
                         },
                     });
                 }
-                else if (!typeHasIdentifiable) {
+                else if (!matchingAliasHasIdentifiable) {
                     context.report({
                         node,
                         messageId: 'notExtendingIdentifiable',
@@ -67,9 +79,22 @@ exports.enforceIdentifiableFirestoreType = (0, createRule_1.createRule)({
                     });
                 }
             },
+            ExportNamedDeclaration(node) {
+                // A re-export (`export { X } from './elsewhere'`) exports a binding
+                // from another module, not the local alias declared in this file, so
+                // it must never satisfy the gate.
+                if (node.source != null) {
+                    return;
+                }
+                for (const specifier of node.specifiers) {
+                    locallyExportedNames.add(specifier.local.name);
+                }
+            },
             TSTypeAliasDeclaration(node) {
                 if (node.id.name === folderName) {
-                    hasExpectedType = true;
+                    matchingAliasNode = node;
+                    matchingAliasInlineExported =
+                        node.parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration;
                     const findTypeAliasAnnotation = (typeName) => {
                         let scope = context.getScope();
                         while (scope) {
@@ -209,7 +234,7 @@ exports.enforceIdentifiableFirestoreType = (0, createRule_1.createRule)({
                         }
                         return false;
                     };
-                    typeHasIdentifiable = checkType(node.typeAnnotation);
+                    matchingAliasHasIdentifiable = checkType(node.typeAnnotation);
                 }
             },
         };

package/lib/rules/no-always-true-false-conditions.js

@@ -95,6 +95,79 @@ exports.noAlwaysTrueFalseConditions = (0, createRule_1.createRule)({
                     return {};
             }
         }
+        const MATH_FOLDABLE_METHODS = new Set(['max', 'min']);
+        /**
+         * Resolves a `Math.max`/`Math.min` call over numeric literals to the number
+         * it always produces. Calls whose value depends on runtime state (spread
+         * arguments, identifiers, computed member access, nested calls) stay
+         * unresolved so callers never treat them as constants.
+         */
+        function evaluateMathMinMaxCall(node) {
+            if (node.type !== utils_1.AST_NODE_TYPES.CallExpression ||
+                node.callee.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+                node.callee.computed ||
+                node.callee.object.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                node.callee.object.name !== 'Math' ||
+                node.callee.property.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                !MATH_FOLDABLE_METHODS.has(node.callee.property.name) ||
+                node.arguments.length < 2) {
+                return undefined;
+            }
+            const numbers = [];
+            for (const argument of node.arguments) {
+                if (argument.type !== utils_1.AST_NODE_TYPES.Literal ||
+                    typeof argument.value !== 'number') {
+                    return undefined;
+                }
+                numbers.push(argument.value);
+            }
+            return node.callee.property.name === 'max'
+                ? Math.max(...numbers)
+                : Math.min(...numbers);
+        }
+        /**
+         * Resolves a comparison operand to the number it always evaluates to.
+         * Returns undefined when the operand depends on runtime values.
+         */
+        function resolveNumericOperand(node) {
+            if (node.type === utils_1.AST_NODE_TYPES.Literal &&
+                typeof node.value === 'number') {
+                return node.value;
+            }
+            return evaluateMathMinMaxCall(node);
+        }
+        function compareNumericValues(leftValue, operator, rightValue) {
+            switch (operator) {
+                case '>':
+                    return leftValue > rightValue
+                        ? { isTruthy: true }
+                        : { isFalsy: true };
+                case '>=':
+                    return leftValue >= rightValue
+                        ? { isTruthy: true }
+                        : { isFalsy: true };
+                case '<':
+                    return leftValue < rightValue
+                        ? { isTruthy: true }
+                        : { isFalsy: true };
+                case '<=':
+                    return leftValue <= rightValue
+                        ? { isTruthy: true }
+                        : { isFalsy: true };
+                case '==':
+                case '===':
+                    return leftValue === rightValue
+                        ? { isTruthy: true }
+                        : { isFalsy: true };
+                case '!=':
+                case '!==':
+                    return leftValue !== rightValue
+                        ? { isTruthy: true }
+                        : { isFalsy: true };
+                default:
+                    return {};
+            }
+        }
         /**
          * Checks if a binary expression with literals is always truthy or falsy
          */
@@ -114,10 +187,17 @@ exports.noAlwaysTrueFalseConditions = (0, createRule_1.createRule)({
                     }
                 }
             }
-            // Only handle cases where both sides are literals
+            // A non-literal operand can still be a compile-time constant, so resolve
+            // it before abandoning the comparison. Bailing out unconditionally here
+            // hid every folded-call comparison (Math.max(1, 2) === 0) from the rule.
             if (node.left.type !== utils_1.AST_NODE_TYPES.Literal ||
                 node.right.type !== utils_1.AST_NODE_TYPES.Literal) {
-                return {};
+                const resolvedLeft = resolveNumericOperand(node.left);
+                const resolvedRight = resolveNumericOperand(node.right);
+                if (resolvedLeft === undefined || resolvedRight === undefined) {
+                    return {};
+                }
+                return compareNumericValues(resolvedLeft, node.operator, resolvedRight);
             }
             const leftValue = node.left.value;
             const rightValue = node.right.value;
@@ -130,33 +210,9 @@ exports.noAlwaysTrueFalseConditions = (0, createRule_1.createRule)({
             }
             // Check numeric comparisons
             if (typeof leftValue === 'number' && typeof rightValue === 'number') {
-                switch (node.operator) {
-                    case '>':
-                        return leftValue > rightValue
-                            ? { isTruthy: true }
-                            : { isFalsy: true };
-                    case '>=':
-                        return leftValue >= rightValue
-                            ? { isTruthy: true }
-                            : { isFalsy: true };
-                    case '<':
-                        return leftValue < rightValue
-                            ? { isTruthy: true }
-                            : { isFalsy: true };
-                    case '<=':
-                        return leftValue <= rightValue
-                            ? { isTruthy: true }
-                            : { isFalsy: true };
-                    case '==':
-                    case '===':
-                        return leftValue === rightValue
-                            ? { isTruthy: true }
-                            : { isFalsy: true };
-                    case '!=':
-                    case '!==':
-                        return leftValue !== rightValue
-                            ? { isTruthy: true }
-                            : { isFalsy: true };
+                const numericResult = compareNumericValues(leftValue, node.operator, rightValue);
+                if (numericResult.isTruthy || numericResult.isFalsy) {
+                    return numericResult;
                 }
             }
             // Check string comparisons
@@ -624,64 +680,12 @@ exports.noAlwaysTrueFalseConditions = (0, createRule_1.createRule)({
                         ? { isTruthy: true }
                         : { isFalsy: true };
                 }
-                // Handle Math.max/min
-                if (node.callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
-                    node.callee.object.name === 'Math' &&
-                    node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
-                    (node.callee.property.name === 'max' ||
-                        node.callee.property.name === 'min') &&
-                    node.arguments.length >= 2 &&
-                    node.arguments.every((arg) => arg.type === utils_1.AST_NODE_TYPES.Literal &&
-                        typeof arg.value === 'number')) {
-                    const numbers = node.arguments.map((arg) => arg.value);
-                    const result = node.callee.property.name === 'max'
-                        ? Math.max(...numbers)
-                        : Math.min(...numbers);
-                    // If this is part of a comparison, evaluate it
-                    if (node.parent &&
-                        node.parent.type === utils_1.AST_NODE_TYPES.BinaryExpression &&
-                        ['===', '!==', '==', '!=', '>', '<', '>=', '<='].includes(node.parent.operator) &&
-                        ((node.parent.left === node &&
-                            node.parent.right.type === utils_1.AST_NODE_TYPES.Literal &&
-                            typeof node.parent.right.value === 'number') ||
-                            (node.parent.right === node &&
-                                node.parent.left.type === utils_1.AST_NODE_TYPES.Literal &&
-                                typeof node.parent.left.value === 'number'))) {
-                        const comparison = node.parent;
-                        const literalNode = comparison.left === node
-                            ? comparison.right
-                            : comparison.left;
-                        const compareValue = literalNode.value;
-                        switch (comparison.operator) {
-                            case '===':
-                            case '==':
-                                return result === compareValue
-                                    ? { isTruthy: true }
-                                    : { isFalsy: true };
-                            case '!==':
-                            case '!=':
-                                return result !== compareValue
-                                    ? { isTruthy: true }
-                                    : { isFalsy: true };
-                            case '>':
-                                return result > compareValue
-                                    ? { isTruthy: true }
-                                    : { isFalsy: true };
-                            case '<':
-                                return result < compareValue
-                                    ? { isTruthy: true }
-                                    : { isFalsy: true };
-                            case '>=':
-                                return result >= compareValue
-                                    ? { isTruthy: true }
-                                    : { isFalsy: true };
-                            case '<=':
-                                return result <= compareValue
-                                    ? { isTruthy: true }
-                                    : { isFalsy: true };
-                        }
-                    }
-                    return result !== 0 ? { isTruthy: true } : { isFalsy: true };
+                // Handle Math.max/min used directly as the condition. Comparisons that
+                // contain such a call are folded by checkBinaryExpression instead,
+                // since evaluation of a comparison starts at the BinaryExpression.
+                const mathValue = evaluateMathMinMaxCall(node);
+                if (mathValue !== undefined) {
+                    return mathValue !== 0 ? { isTruthy: true } : { isFalsy: true };
                 }
                 // Handle Object.keys().length
                 if (node.callee.property.name === 'length' &&
@@ -1038,67 +1042,6 @@ exports.noAlwaysTrueFalseConditions = (0, createRule_1.createRule)({
                     return result ? { isTruthy: true } : { isFalsy: true };
                 }
             }
-            // Handle Math.max/min
-            if (node.type === utils_1.AST_NODE_TYPES.CallExpression &&
-                node.callee.type === utils_1.AST_NODE_TYPES.MemberExpression &&
-                node.callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
-                node.callee.object.name === 'Math' &&
-                node.callee.property.type === utils_1.AST_NODE_TYPES.Identifier &&
-                (node.callee.property.name === 'max' ||
-                    node.callee.property.name === 'min') &&
-                node.arguments.length >= 2 &&
-                node.arguments.every((arg) => arg.type === utils_1.AST_NODE_TYPES.Literal &&
-                    typeof arg.value === 'number')) {
-                const numbers = node.arguments.map((arg) => arg.value);
-                const result = node.callee.property.name === 'max'
-                    ? Math.max(...numbers)
-                    : Math.min(...numbers);
-                // If this is part of a comparison, evaluate it
-                if (node.parent &&
-                    node.parent.type === utils_1.AST_NODE_TYPES.BinaryExpression &&
-                    ['===', '!==', '==', '!=', '>', '<', '>=', '<='].includes(node.parent.operator) &&
-                    ((node.parent.left === node &&
-                        node.parent.right.type === utils_1.AST_NODE_TYPES.Literal &&
-                        typeof node.parent.right.value === 'number') ||
-                        (node.parent.right === node &&
-                            node.parent.left.type === utils_1.AST_NODE_TYPES.Literal &&
-                            typeof node.parent.left.value === 'number'))) {
-                    const comparison = node.parent;
-                    const literalNode = comparison.left === node
-                        ? comparison.right
-                        : comparison.left;
-                    const compareValue = literalNode.value;
-                    switch (comparison.operator) {
-                        case '===':
-                        case '==':
-                            return result === compareValue
-                                ? { isTruthy: true }
-                                : { isFalsy: true };
-                        case '!==':
-                        case '!=':
-                            return result !== compareValue
-                                ? { isTruthy: true }
-                                : { isFalsy: true };
-                        case '>':
-                            return result > compareValue
-                                ? { isTruthy: true }
-                                : { isFalsy: true };
-                        case '<':
-                            return result < compareValue
-                                ? { isTruthy: true }
-                                : { isFalsy: true };
-                        case '>=':
-                            return result >= compareValue
-                                ? { isTruthy: true }
-                                : { isFalsy: true };
-                        case '<=':
-                            return result <= compareValue
-                                ? { isTruthy: true }
-                                : { isFalsy: true };
-                    }
-                }
-                return result !== 0 ? { isTruthy: true } : { isFalsy: true };
-            }
             // Handle nullish coalescing
             if (node.type === utils_1.AST_NODE_TYPES.LogicalExpression) {
                 const logicalNode = node;

package/lib/rules/no-conditional-literals-in-jsx.js

@@ -39,11 +39,22 @@ exports.noConditionalLiteralsInJsx = (0, createRule_1.createRule)({
                 });
                 // If we were evaluating
                 //   <div>{property} {conditional && 'string'}</div>
-                // Then {property} would be one of the siblingExpressionNodes
-                const siblingExpressionNodes = parentChildren.filter((n) => n.type === 'JSXExpressionContainer' &&
-                    'expression' in n &&
-                    (n.expression.type === 'Identifier' ||
-                        n.expression.type === 'MemberExpression'));
+                // Then {property} would be one of the siblingExpressionNodes.
+                //
+                // Any expression container beside the conditional can render text, and
+                // it fragments the text node exactly as adjacent JSX text does, so the
+                // shape of the sibling's expression is not a useful discriminator.
+                // Whether an arbitrary expression renders text rather than an element
+                // (or nothing at all) is not decidable syntactically, so the broad
+                // reading of "other text or expressions" wins. The one container that
+                // provably renders nothing is a comment ({/* ... */}), whose expression
+                // is a JSXEmptyExpression.
+                const siblingExpressionNodes = parentChildren.filter((n) => 
+                // The container under evaluation is not its own sibling: a sole
+                // conditional literal fragments nothing.
+                n !== node &&
+                    n.type === utils_1.TSESTree.AST_NODE_TYPES.JSXExpressionContainer &&
+                    n.expression.type !== utils_1.TSESTree.AST_NODE_TYPES.JSXEmptyExpression);
                 const hasSiblingContent = siblingTextNodes.concat(siblingExpressionNodes).length > 0;
                 if (!hasSiblingContent) {
                     return;

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

@@ -10,19 +10,63 @@ const DEFAULT_FUNCTION_PATTERNS = [
     'func',
     'on[A-Z].*',
 ];
+/**
+ * Walks the top-level statements of a Program to build a name -> type-node
+ * map of every `type X = ...` alias declared in the file (including ones
+ * behind `export`). Populated up front from `Program.body` rather than from
+ * a `TSTypeAliasDeclaration` visitor, because ESLint visits in document
+ * order: an alias declared AFTER the `useState` call it types would not yet
+ * be known if we relied on visitor order alone.
+ */
+function collectTypeAliases(programNode) {
+    const aliases = new Map();
+    for (const statement of programNode.body) {
+        const declaration = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+            statement.declaration
+            ? statement.declaration
+            : statement;
+        if (declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
+            aliases.set(declaration.id.name, declaration.typeAnnotation);
+        }
+    }
+    return aliases;
+}
 /**
  * Returns true if the TSTypeAnnotation node (from useState's type parameter)
  * represents a function type — either directly or as part of a union with
  * null/undefined. We check purely syntactically; no type-checker required.
+ *
+ * A `TSTypeReference` (e.g. `ToClose` in `useState<ToClose>`) is resolved
+ * against same-file type aliases and recursed into. Cross-file aliases
+ * (imported types) are syntactically unreachable and are left unreported by
+ * this signal — the name-pattern and scope-binding signals still apply.
+ * `visitedAliases` guards against infinite recursion on a self-referential
+ * or mutually-recursive alias chain (`type A = B; type B = A;`).
  */
-function isFunctionTypeAnnotation(typeNode) {
+function isFunctionTypeAnnotation(typeNode, aliases, visitedAliases = new Set()) {
     switch (typeNode.type) {
         case utils_1.AST_NODE_TYPES.TSFunctionType:
         case utils_1.AST_NODE_TYPES.TSConstructorType:
             return true;
         case utils_1.AST_NODE_TYPES.TSUnionType:
             // Union like `(() => void) | null` — any member being a function type suffices
-            return typeNode.types.some(isFunctionTypeAnnotation);
+            return typeNode.types.some((member) => isFunctionTypeAnnotation(member, aliases, visitedAliases));
+        case utils_1.AST_NODE_TYPES.TSTypeReference: {
+            const { typeName } = typeNode;
+            // Qualified names (`Foo.Bar`) aren't resolvable without a type checker
+            if (typeName.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return false;
+            }
+            if (visitedAliases.has(typeName.name)) {
+                return false;
+            }
+            const aliasTarget = aliases.get(typeName.name);
+            if (!aliasTarget) {
+                return false;
+            }
+            visitedAliases.add(typeName.name);
+            return isFunctionTypeAnnotation(aliasTarget, aliases, visitedAliases);
+        }
         default:
             return false;
     }
@@ -31,12 +75,12 @@ function isFunctionTypeAnnotation(typeNode) {
  * Checks whether a useState call expression has a type parameter that
  * includes a function type, e.g. useState<(() => void) | null>(null).
  */
-function useStateHasFunctionTypeParam(callNode) {
+function useStateHasFunctionTypeParam(callNode, aliases) {
     const typeParams = callNode.typeParameters;
     if (!typeParams || typeParams.params.length === 0) {
         return false;
     }
-    return isFunctionTypeAnnotation(typeParams.params[0]);
+    return isFunctionTypeAnnotation(typeParams.params[0], aliases);
 }
 /**
  * Returns true when the AST node is a safe value to pass to a setter — i.e.,
@@ -182,7 +226,14 @@ exports.noDirectFunctionState = (0, createRule_1.createRule)({
          * useState array-destructuring declarations.
          */
         const setterFunctionTyped = new Map();
+        // Populated by the Program visitor, which runs before any descendant
+        // visitor, so declaration order of `type` aliases relative to the
+        // `useState` call that references them never matters.
+        let typeAliases = new Map();
         return {
+            Program(node) {
+                typeAliases = collectTypeAliases(node);
+            },
             VariableDeclarator(node) {
                 // Look for `const [state, setter] = useState<T>(...)` or
                 // `const [state, setter] = React.useState<T>(...)`.
@@ -210,7 +261,7 @@ exports.noDirectFunctionState = (0, createRule_1.createRule)({
                     return;
                 }
                 const setterName = setterElement.name;
-                const hasFunctionType = useStateHasFunctionTypeParam(callNode);
+                const hasFunctionType = useStateHasFunctionTypeParam(callNode, typeAliases);
                 setterFunctionTyped.set(setterName, hasFunctionType);
             },
             CallExpression(node) {

package/lib/rules/no-useless-fragment.js

@@ -22,48 +22,54 @@ const describeChild = (child) => {
             return 'child node';
     }
 };
+/**
+ * A `JSXText` child that is pure whitespace AND spans a line break is
+ * formatting padding — the newline + indentation prettier inserts around a
+ * single-line child in the multi-line fragment form — and renders no output.
+ * A whitespace-only child WITHOUT a newline (e.g. `<> <Foo /> </>`) renders
+ * an actual space between siblings, so it still counts as meaningful.
+ */
+const isFormattingWhitespace = (child) => child.type === 'JSXText' &&
+    /^\s*$/.test(child.value) &&
+    child.value.includes('\n');
 exports.noUselessFragment = (0, createRule_1.createRule)({
     name: 'no-useless-fragment',
     create(context) {
         return {
             JSXFragment(node) {
-                if (node.children.length === 1) {
-                    const [child] = node.children;
-                    /**
-                     * A fragment whose only child is an expression container — e.g.
-                     * `<>{portal}</>` — is NOT useless. Unwrapping it to a bare
-                     * `{portal}` is invalid in statement/return position, and wrapping a
-                     * single ReactNode expression in a fragment is the idiomatic way to
-                     * render it. (Mirrors the upstream rule's `allowExpressions`.)
-                     */
-                    if (child.type === 'JSXExpressionContainer') {
-                        return;
-                    }
-                    context.report({
-                        node,
-                        messageId: 'noUselessFragment',
-                        data: {
-                            childKind: describeChild(child),
-                        },
-                        fix(fixer) {
-                            const sourceCode = context.sourceCode;
-                            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                            const openingFragment = sourceCode.getFirstToken(node);
-                            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                            const closingFragment = sourceCode.getLastToken(node);
-                            return [
-                                fixer.removeRange([
-                                    openingFragment.range[0],
-                                    openingFragment.range[0] + 2,
-                                ]),
-                                fixer.removeRange([
-                                    closingFragment.range[0] - 3,
-                                    closingFragment.range[0],
-                                ]),
-                            ];
-                        },
-                    });
+                const meaningfulChildren = node.children.filter((child) => !isFormattingWhitespace(child));
+                if (meaningfulChildren.length !== 1) {
+                    return;
+                }
+                const [child] = meaningfulChildren;
+                /**
+                 * A fragment whose only child is an expression container — e.g.
+                 * `<>{portal}</>` — is NOT useless. Unwrapping it to a bare
+                 * `{portal}` is invalid in statement/return position, and wrapping a
+                 * single ReactNode expression in a fragment is the idiomatic way to
+                 * render it. (Mirrors the upstream rule's `allowExpressions`.)
+                 */
+                if (child.type === 'JSXExpressionContainer') {
+                    return;
                 }
+                /**
+                 * Unwrapping is only sound when the child is itself standalone JSX.
+                 * A text child (`<>hello</>`) would become a bare identifier
+                 * reference, and a spread child (`<>{...items}</>`) is not a valid
+                 * expression on its own — both are report-only so the developer
+                 * chooses how to restructure the surrounding code.
+                 */
+                const isFixable = child.type === 'JSXElement' || child.type === 'JSXFragment';
+                context.report({
+                    node,
+                    messageId: 'noUselessFragment',
+                    data: {
+                        childKind: describeChild(child),
+                    },
+                    fix: isFixable
+                        ? (fixer) => fixer.replaceText(node, context.sourceCode.getText(child))
+                        : null,
+                });
             },
         };
     },

package/lib/rules/prefer-map-over-conditional-dispatch.js

@@ -50,6 +50,23 @@ const FUNCTION_TYPES = new Set([
     utils_1.AST_NODE_TYPES.FunctionExpression,
     utils_1.AST_NODE_TYPES.FunctionDeclaration,
 ]);
+/**
+ * Sentinel standing in for the receiver of a `this`-rooted member chain, which
+ * has no identifier to key on. `this` is a reserved word, so no binding can
+ * carry this name and shadow the sentinel.
+ */
+const THIS_ROOT = 'this';
+/**
+ * Node types that bind their own `this`, so a `this` inside one is a different
+ * receiver than the enclosing scope's. Arrow functions are deliberately absent:
+ * they close over the lexical `this`, exactly as a closure closes over an
+ * identifier binding.
+ */
+const THIS_REBINDING_TYPES = new Set([
+    utils_1.AST_NODE_TYPES.FunctionExpression,
+    utils_1.AST_NODE_TYPES.FunctionDeclaration,
+    utils_1.AST_NODE_TYPES.ClassBody,
+]);
 /**
  * Function/constructor/conditional type notation must be parenthesized to
  * appear as a `|` union member, or the emitted annotation does not parse
@@ -362,12 +379,22 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
             }
             return cur.type === utils_1.AST_NODE_TYPES.Identifier;
         }
-        /** Root identifier of a member chain (`a.b.c` -> `a`). */
-        function rootIdentifierName(node) {
+        /**
+         * Root of a member chain (`a.b.c` -> `a`, `this.a.b` -> `THIS_ROOT`).
+         *
+         * A `this`-rooted chain names its receiver with a keyword rather than a
+         * binding, so it needs a sentinel to participate in root-keyed analysis at
+         * all. `'this'` cannot collide with a real root: `this` is a reserved word,
+         * so no identifier can ever carry that name.
+         */
+        function chainRootName(node) {
             let cur = node;
             while (cur.type === utils_1.AST_NODE_TYPES.MemberExpression) {
                 cur = cur.object;
             }
+            if (cur.type === utils_1.AST_NODE_TYPES.ThisExpression) {
+                return THIS_ROOT;
+            }
             return cur.type === utils_1.AST_NODE_TYPES.Identifier ? cur.name : null;
         }
         function isInlineLiteralKey(node) {
@@ -485,6 +512,48 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
             visit(node);
             return found;
         }
+        /**
+         * Whether the subtree reads the receiver of the enclosing scope — the `this`
+         * counterpart of `referencesIdentifier`. Nested `function`/class bodies are
+         * skipped because their `this` is a different receiver, so a `this` inside
+         * one is no more a read of the narrowed object than an identifier of the
+         * same name declared in an inner scope would be.
+         */
+        function referencesThis(node) {
+            let found = false;
+            const visit = (n) => {
+                if (found || !n || typeof n !== 'object') {
+                    return;
+                }
+                const anyNode = n;
+                if (typeof anyNode.type !== 'string') {
+                    return;
+                }
+                if (anyNode.type === utils_1.AST_NODE_TYPES.ThisExpression) {
+                    found = true;
+                    return;
+                }
+                if (THIS_REBINDING_TYPES.has(anyNode.type)) {
+                    return;
+                }
+                for (const key of Object.keys(anyNode)) {
+                    if (key === 'parent') {
+                        continue;
+                    }
+                    const val = anyNode[key];
+                    if (Array.isArray(val)) {
+                        for (const child of val) {
+                            visit(child);
+                        }
+                    }
+                    else {
+                        visit(val);
+                    }
+                }
+            };
+            visit(node);
+            return found;
+        }
         // ---- Name derivation ----------------------------------------------------
         function toUpperSnake(name) {
             return name
@@ -799,16 +868,25 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
          * Narrowing exemption (Edge Case 1): when the discriminant is `obj.tag`, a
          * flat Record cannot express variant narrowing. If any KEPT branch value
          * references the base object beyond the tag access itself, do not fire.
+         *
+         * `this.obj.tag` narrows identically — the receiver is reached through a
+         * keyword instead of a binding, which changes nothing about what the Record
+         * would lose (hoisting `this.obj.data` out of the switch drops the narrowing
+         * and the emitted code no longer typechecks), so a `this`-rooted chain is
+         * matched against `this` reads in the kept branches.
          */
         function isNarrowingExempt(discriminant, keptValues) {
             if (discriminant.type !== utils_1.AST_NODE_TYPES.MemberExpression) {
                 return false;
             }
-            const root = rootIdentifierName(discriminant);
+            const root = chainRootName(discriminant);
             if (!root) {
                 return false;
             }
-            return keptValues.some((value) => referencesIdentifier(value, root));
+            const readsRoot = root === THIS_ROOT
+                ? referencesThis
+                : (value) => referencesIdentifier(value, root);
+            return keptValues.some(readsRoot);
         }
         // ---- Switch form --------------------------------------------------------
         function handleSwitch(node) {

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferSpreadOverReassembly = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
 const DEFAULT_MIN_FIELDS = 2;
 /**
  * Collects all identifier references (not declarations) used anywhere in a
@@ -70,6 +71,139 @@ function getSimpleDestructuredNames(pattern) {
     }
     return names;
 }
+/**
+ * Array methods that hand each element of the receiver to their callback. They
+ * are the contextual route by which an unannotated destructured parameter still
+ * has a knowable type: the element type of the array being iterated.
+ */
+const ELEMENT_CALLBACK_METHODS = new Set([
+    'map',
+    'forEach',
+    'filter',
+    'flatMap',
+]);
+const ARRAY_TYPE_NAMES = new Set(['Array', 'ReadonlyArray']);
+/**
+ * Resolves `Promise<T>` to `T`, leaving anything else as it stands, which is
+ * what `await` does to the type of the expression it operates on.
+ */
+function unwrapPromise(typeNode) {
+    if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+        typeNode.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+        typeNode.typeName.name === 'Promise' &&
+        typeNode.typeParameters?.params.length === 1) {
+        return typeNode.typeParameters.params[0];
+    }
+    return typeNode;
+}
+/** The element type of an array type, or null when the type is not an array. */
+function arrayElementTypeOf(typeNode) {
+    if (typeNode.type === utils_1.AST_NODE_TYPES.TSArrayType) {
+        return typeNode.elementType;
+    }
+    // `readonly Unit[]` wraps the array type in a type operator.
+    if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeOperator &&
+        typeNode.operator === 'readonly' &&
+        typeNode.typeAnnotation) {
+        return arrayElementTypeOf(typeNode.typeAnnotation);
+    }
+    if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+        typeNode.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+        ARRAY_TYPE_NAMES.has(typeNode.typeName.name) &&
+        typeNode.typeParameters?.params.length === 1) {
+        return typeNode.typeParameters.params[0];
+    }
+    return null;
+}
+/**
+ * The property names a member list declares, or null when the list cannot be
+ * enumerated exactly. An index signature, a call/construct signature or a
+ * computed key all describe members whose names are not written down, and a
+ * member set that may be larger than what is read would let a narrowing pick
+ * pass for an exhaustive one.
+ */
+function namesOfMembers(members) {
+    const names = new Set();
+    for (const member of members) {
+        if (member.type !== utils_1.AST_NODE_TYPES.TSPropertySignature &&
+            member.type !== utils_1.AST_NODE_TYPES.TSMethodSignature) {
+            return null;
+        }
+        if (member.computed) {
+            return null;
+        }
+        const key = member.key;
+        if (key.type === utils_1.AST_NODE_TYPES.Identifier) {
+            names.add(key.name);
+        }
+        else if (key.type === utils_1.AST_NODE_TYPES.Literal &&
+            typeof key.value === 'string') {
+            names.add(key.value);
+        }
+        else {
+            return null;
+        }
+    }
+    return names;
+}
+/**
+ * Finds a type alias or interface declared at the top level of the file being
+ * linted, including one that is exported.
+ *
+ * Resolution stops at the file boundary on purpose: an imported name's members
+ * live in a module this rule cannot read, and guessing at them would be the
+ * opposite of a proof.
+ */
+function findLocalTypeDeclaration(program, name) {
+    for (const statement of program.body) {
+        const declaration = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+            statement.declaration
+            ? statement.declaration
+            : statement;
+        if ((declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
+            declaration.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration) &&
+            declaration.id.name === name) {
+            return declaration;
+        }
+    }
+    return null;
+}
+/**
+ * Enumerates every property name a type node declares, or null when the member
+ * list cannot be established with certainty.
+ *
+ * Only an unambiguous, fully written-out member list qualifies. A union, an
+ * intersection, a mapped or conditional type, a generic instantiation and an
+ * interface with an `extends` clause all describe a member set assembled
+ * elsewhere, so none of them can prove anything here.
+ */
+function memberNamesOf(typeNode, program, seen = new Set()) {
+    if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
+        return namesOfMembers(typeNode.members);
+    }
+    if (typeNode.type !== utils_1.AST_NODE_TYPES.TSTypeReference ||
+        typeNode.typeName.type !== utils_1.AST_NODE_TYPES.Identifier ||
+        typeNode.typeParameters) {
+        return null;
+    }
+    const name = typeNode.typeName.name;
+    // A self-referential alias (`type T = T`) would otherwise recur forever.
+    if (seen.has(name)) {
+        return null;
+    }
+    seen.add(name);
+    const declaration = findLocalTypeDeclaration(program, name);
+    if (!declaration || declaration.typeParameters) {
+        return null;
+    }
+    if (declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
+        return memberNamesOf(declaration.typeAnnotation, program, seen);
+    }
+    if (declaration.extends && declaration.extends.length > 0) {
+        return null;
+    }
+    return namesOfMembers(declaration.body.body);
+}
 /**
  * For a JSX element, returns the set of destructured names that are forwarded
  * with identical key names (e.g. `hits={hits}`, `isLoading={isLoading}`).
@@ -492,6 +626,158 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
     create(context, [options]) {
         const minFields = options?.minFields ?? DEFAULT_MIN_FIELDS;
         const sourceCode = context.getSourceCode();
+        const program = sourceCode.ast;
+        /**
+         * Walks an expression toward its syntactic root and returns the type node
+         * that root declares, mirroring the receiver trace in
+         * `enforce-firestore-doc-ref-generic`.
+         *
+         * The trace is syntax only. `parserOptions.project` is absent from the
+         * shared testers and from many consumer configs, so a type-checker branch
+         * would be dead exactly where the destructured pick it must protect lives —
+         * inside an `Array.prototype.map` callback, whose signature comes from
+         * `lib.d.ts`.
+         */
+        function typeNodeOfExpression(node, visited) {
+            // Guards against a self-referential declaration such as `const a = a.b;`.
+            if (!node || visited.has(node)) {
+                return null;
+            }
+            visited.add(node);
+            switch (node.type) {
+                case utils_1.AST_NODE_TYPES.AwaitExpression: {
+                    const awaited = typeNodeOfExpression(node.argument, visited);
+                    return awaited ? unwrapPromise(awaited) : null;
+                }
+                case utils_1.AST_NODE_TYPES.ChainExpression:
+                case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+                    return typeNodeOfExpression(node.expression, visited);
+                // An assertion states the type outright, which is stronger evidence
+                // than anything the operand could supply.
+                case utils_1.AST_NODE_TYPES.TSAsExpression:
+                case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+                    return node.typeAnnotation;
+                case utils_1.AST_NODE_TYPES.Identifier:
+                    return typeNodeOfIdentifier(node, visited);
+                case utils_1.AST_NODE_TYPES.CallExpression:
+                    return typeNodeOfCallResult(node);
+                default:
+                    // A member expression is deliberately absent: a property's type lives
+                    // in the type of its object, which syntax alone does not supply.
+                    return null;
+            }
+        }
+        function typeNodeOfIdentifier(node, visited) {
+            const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, node.name);
+            if (!variable || variable.defs.length !== 1) {
+                return null;
+            }
+            const def = variable.defs[0];
+            if (def.type === 'Parameter') {
+                return def.name.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    def.name.typeAnnotation
+                    ? def.name.typeAnnotation.typeAnnotation
+                    : null;
+            }
+            if (def.type !== 'Variable' ||
+                def.node.type !== utils_1.AST_NODE_TYPES.VariableDeclarator) {
+                return null;
+            }
+            const declarator = def.node;
+            // An annotation constrains every assignment rather than just the
+            // initializer, so it describes the binding even when it is a `let`.
+            if (declarator.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+                declarator.id.typeAnnotation) {
+                return declarator.id.typeAnnotation.typeAnnotation;
+            }
+            // Without an annotation only an immutable binding still holds its
+            // initializer's type by the time the callback runs.
+            if (def.parent?.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
+                def.parent.kind !== 'const') {
+                return null;
+            }
+            return typeNodeOfExpression(declarator.init, visited);
+        }
+        /**
+         * A receiver that is a call result takes its type from what the callee
+         * declares it returns; an inferred return type is not written down and so
+         * proves nothing.
+         */
+        function typeNodeOfCallResult(node) {
+            if (node.callee.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return null;
+            }
+            const scope = ASTHelpers_1.ASTHelpers.getScope(context, node.callee);
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, node.callee.name);
+            if (!variable || variable.defs.length !== 1) {
+                return null;
+            }
+            const def = variable.defs[0];
+            // A hoisted declaration binds the helper the same way a `const` arrow
+            // does, so both spellings are read.
+            if (def.type === 'FunctionName') {
+                return def.node.returnType?.typeAnnotation ?? null;
+            }
+            if (def.type !== 'Variable' ||
+                def.node.type !== utils_1.AST_NODE_TYPES.VariableDeclarator ||
+                def.parent?.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
+                def.parent.kind !== 'const') {
+                return null;
+            }
+            const init = def.node.init;
+            if (init?.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression &&
+                init?.type !== utils_1.AST_NODE_TYPES.FunctionExpression) {
+                return null;
+            }
+            return init.returnType?.typeAnnotation ?? null;
+        }
+        /**
+         * The member names of the element type of the array whose method call this
+         * function is the callback of, e.g. `Unit` for `units.map(fn)` where
+         * `units` is annotated `Unit[]`.
+         */
+        function contextualElementMemberNames(fn) {
+            const call = fn.parent;
+            if (!call ||
+                call.type !== utils_1.AST_NODE_TYPES.CallExpression ||
+                call.arguments[0] !== fn ||
+                call.callee.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+                call.callee.computed ||
+                call.callee.property.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                !ELEMENT_CALLBACK_METHODS.has(call.callee.property.name)) {
+                return null;
+            }
+            const receiverType = typeNodeOfExpression(call.callee.object, new Set());
+            if (!receiverType) {
+                return null;
+            }
+            const elementType = arrayElementTypeOf(receiverType);
+            return elementType ? memberNamesOf(elementType, program) : null;
+        }
+        /**
+         * Reports whether the destructured pick is provably a PROPER subset of the
+         * source object's own type, in which case spreading the parameter would add
+         * the members the author left out and change what the function produces
+         * (#1642: a GitHub review payload gained unknown keys).
+         *
+         * The proof runs in the safe direction only. A member set that matches the
+         * pick exactly is exhaustive, so the rewrite is behavior-preserving and the
+         * rule still reports; a type it cannot resolve — imported, generic, a union,
+         * an index signature — yields no proof and the rule likewise still reports.
+         * Silence is reserved for the case where the widening is demonstrated.
+         */
+        function isProvablyNarrowingPick(fn, param, destructuredNames) {
+            // An explicit annotation overrides whatever the call site would imply,
+            // so the contextual route is consulted only in its absence.
+            const memberNames = param.typeAnnotation
+                ? memberNamesOf(param.typeAnnotation.typeAnnotation, program)
+                : contextualElementMemberNames(fn);
+            if (!memberNames || memberNames.size <= destructuredNames.length) {
+                return false;
+            }
+            return destructuredNames.every((name) => memberNames.has(name));
+        }
         function checkFunction(fn) {
             // Must have exactly one parameter that is an ObjectPattern.
             if (fn.params.length !== 1)
@@ -547,6 +833,11 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
                     return;
                 }
             }
+            // The pick may exist precisely because the omitted members must not flow
+            // through; spreading would reinstate them.
+            if (isProvablyNarrowingPick(fn, param, destructuredNames)) {
+                return;
+            }
             context.report({
                 node: param,
                 messageId: 'preferSpread',

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,72 @@
 [
+  {
+    "version": "1.20.84",
+    "date": "2026-08-03T02:56:38.740Z",
+    "rules": [
+      {
+        "name": "prefer-spread-over-reassembly",
+        "changeType": "fix",
+        "issues": [
+          1642
+        ],
+        "summary": "stay silent on a provably narrowing pick (closes #1642)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.83",
+    "date": "2026-08-03T02:05:36.672Z",
+    "rules": [
+      {
+        "name": "enforce-identifiable-firestore-type",
+        "changeType": "fix",
+        "issues": [
+          1635
+        ],
+        "summary": "require the folder-matching type to be exported (closes #1635)"
+      },
+      {
+        "name": "no-always-true-false-conditions",
+        "changeType": "fix",
+        "issues": [
+          1625
+        ],
+        "summary": "fold Math.max/min operands inside comparisons (closes #1625)"
+      },
+      {
+        "name": "no-conditional-literals-in-jsx",
+        "changeType": "fix",
+        "issues": [
+          1627
+        ],
+        "summary": "count every non-comment expression container as adjacent content (closes #1627)"
+      },
+      {
+        "name": "no-direct-function-state",
+        "changeType": "fix",
+        "issues": [
+          1636
+        ],
+        "summary": "see function types behind a same-file alias (closes #1636)"
+      },
+      {
+        "name": "no-useless-fragment",
+        "changeType": "fix",
+        "issues": [
+          1634
+        ],
+        "summary": "stop the fixer corrupting source and count meaningful children (closes #1634)"
+      },
+      {
+        "name": "prefer-map-over-conditional-dispatch",
+        "changeType": "fix",
+        "issues": [
+          1626
+        ],
+        "summary": "extend the narrowing exemption to this-rooted discriminants (closes #1626)"
+      }
+    ]
+  },
   {
     "version": "1.20.82",
     "date": "2026-08-02T21:42:12.697Z",