@blumintinc/eslint-plugin-blumint 1.20.83 → 1.20.85

package/lib/index.js

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

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,219 @@ 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']);
+/**
+ * Type operators that are homomorphic over their argument: each one rewrites
+ * the modifiers of every member and leaves the key set identical, so a member
+ * list read through them describes the wrapped type exactly. `Readonly<{...}>`
+ * is the idiomatic spelling of a data record, and refusing to see through it
+ * makes the narrowing proof inert on the code it exists to protect (#1643).
+ *
+ * `Pick`, `Omit`, `Record`, `Exclude` and `Extract` are deliberately absent:
+ * they rewrite the key set, and a wrong proof silences a report the rule owes
+ * rather than merely failing to find one.
+ */
+const KEY_PRESERVING_TYPE_OPERATORS = new Set([
+    'Readonly',
+    'Required',
+    'Partial',
+]);
+/**
+ * Collects every name the file itself binds in a way that can stand in front of
+ * a type argument list — a type alias, an interface, a class, an enum, a
+ * namespace or an import. A file spelling `Readonly` as one of these is talking
+ * about its own declaration rather than the lib utility, so the key-preserving
+ * unwrap must not apply to it.
+ *
+ * The walk covers nested declarations too, since a `type Partial<T>` inside a
+ * function body shadows the global just as effectively as a top-level one.
+ */
+function collectLocallyBoundNames(node, names) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration:
+        case utils_1.AST_NODE_TYPES.TSInterfaceDeclaration:
+        case utils_1.AST_NODE_TYPES.TSEnumDeclaration:
+        case utils_1.AST_NODE_TYPES.TSImportEqualsDeclaration:
+            names.add(node.id.name);
+            break;
+        case utils_1.AST_NODE_TYPES.ClassDeclaration:
+        case utils_1.AST_NODE_TYPES.ClassExpression:
+            if (node.id) {
+                names.add(node.id.name);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.TSModuleDeclaration:
+            if (node.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+                names.add(node.id.name);
+            }
+            break;
+        case utils_1.AST_NODE_TYPES.ImportSpecifier:
+        case utils_1.AST_NODE_TYPES.ImportDefaultSpecifier:
+        case utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier:
+            names.add(node.local.name);
+            break;
+        default:
+            break;
+    }
+    for (const key of Object.keys(node)) {
+        if (key === 'parent')
+            continue;
+        const value = node[key];
+        if (Array.isArray(value)) {
+            for (const child of value) {
+                if (child && typeof child === 'object' && 'type' in child) {
+                    collectLocallyBoundNames(child, names);
+                }
+            }
+        }
+        else if (value && typeof value === 'object' && 'type' in value) {
+            collectLocallyBoundNames(value, names);
+        }
+    }
+}
+/**
+ * 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, reached either
+ * directly or through the key-preserving operators in
+ * {@link KEY_PRESERVING_TYPE_OPERATORS}. A union, an intersection, a mapped or
+ * conditional type, any other 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, scope, 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) {
+        return null;
+    }
+    const name = typeNode.typeName.name;
+    if (typeNode.typeParameters) {
+        // An arity other than one is not the lib utility this name spells, so
+        // nothing about the wrapped member list follows from it.
+        if (!KEY_PRESERVING_TYPE_OPERATORS.has(name) ||
+            typeNode.typeParameters.params.length !== 1 ||
+            scope.isLocallyBound(name)) {
+            return null;
+        }
+        return memberNamesOf(typeNode.typeParameters.params[0], scope, seen);
+    }
+    // A self-referential alias (`type T = T`) would otherwise recur forever.
+    if (seen.has(name)) {
+        return null;
+    }
+    seen.add(name);
+    const declaration = findLocalTypeDeclaration(scope.program, name);
+    if (!declaration || declaration.typeParameters) {
+        return null;
+    }
+    if (declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
+        return memberNamesOf(declaration.typeAnnotation, scope, 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 +706,173 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
     create(context, [options]) {
         const minFields = options?.minFields ?? DEFAULT_MIN_FIELDS;
         const sourceCode = context.getSourceCode();
+        const program = sourceCode.ast;
+        // The scan walks the whole file, so it is deferred until a key-preserving
+        // operator actually turns up in a position the proof depends on — most
+        // files never reach it.
+        let locallyBoundNames = null;
+        const typeScope = {
+            program,
+            isLocallyBound: (name) => {
+                if (!locallyBoundNames) {
+                    locallyBoundNames = new Set();
+                    collectLocallyBoundNames(program, locallyBoundNames);
+                }
+                return locallyBoundNames.has(name);
+            },
+        };
+        /**
+         * 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, typeScope) : 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, a union, an
+         * index signature, or an instantiation of anything but a key-preserving
+         * operator — 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, typeScope)
+                : 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 +928,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.83",
+  "version": "1.20.85",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "1.20.85",
+    "date": "2026-08-03T03:21:29.711Z",
+    "rules": [
+      {
+        "name": "prefer-spread-over-reassembly",
+        "changeType": "fix",
+        "issues": [
+          1643
+        ],
+        "summary": "read the narrowing proof through Readonly (closes #1643)"
+      }
+    ]
+  },
+  {
+    "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",