@blumintinc/eslint-plugin-blumint 1.21.0 → 1.21.2

package/README.md

@@ -241,7 +241,7 @@ full closed loop is documented in agora's `.claude/skills/eslint-autonomy/SKILL.
 | [prefer-nullish-coalescing-boolean-props](docs/rules/prefer-nullish-coalescing-boolean-props.md)             | Prefer nullish coalescing over logical OR, but allow logical OR in boolean contexts                                                                                                                                                                                                                                                                                                              | ✅  |    | 🔧 |    |    |
 | [prefer-params-over-parent-id](docs/rules/prefer-params-over-parent-id.md)                                   | Prefer event.params over ref.parent.id for type-safe Firebase trigger paths.                                                                                                                                                                                                                                                                                                                     | ✅  |    | 🔧 |    |    |
 | [prefer-settings-object](docs/rules/prefer-settings-object.md)                                               | Enforce using a settings object for functions with multiple parameters                                                                                                                                                                                                                                                                                                                           | ✅  |    |    |    |    |
-| [prefer-spread-over-reassembly](docs/rules/prefer-spread-over-reassembly.md)                                 | Prefer spread syntax over destructure-then-reassemble when all destructured fields are forwarded identically to a single target                                                                                                                                                                                                                                                                  | ✅  |    | 🔧 |    |    |
+| [prefer-spread-over-reassembly](docs/rules/prefer-spread-over-reassembly.md)                                 | Prefer spread syntax over destructure-then-reassemble when all destructured fields are forwarded identically to a single target                                                                                                                                                                                                                                                                  | ✅  |    | 🔧 | 💡 |    |
 | [prefer-sx-prop-over-system-props](docs/rules/prefer-sx-prop-over-system-props.md)                           | Enforce using the MUI `sx` prop instead of deprecated system props (e.g. `mt`, `display`, `flexDirection`) on MUI components.                                                                                                                                                                                                                                                                    | ✅  |    | 🔧 |    |    |
 | [prefer-type-alias-over-typeof-constant](docs/rules/prefer-type-alias-over-typeof-constant.md)               | Prefer named type aliases over `typeof` on same-file global constants; ensure types are declared before constants.                                                                                                                                                                                                                                                                               | ✅  |    |    |    |    |
 | [prefer-type-over-interface](docs/rules/prefer-type-over-interface.md)                                       | Prefer using type alias over interface                                                                                                                                                                                                                                                                                                                                                           | ✅  |    | 🔧 |    |    |

package/lib/index.js

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

package/lib/rules/enforce-use-flex-gap-on-wrap.js

@@ -52,6 +52,33 @@ function finalSegmentOf(source) {
     const segments = source.split('/').filter(Boolean);
     return segments[segments.length - 1] ?? source;
 }
+/**
+ * The verdict over alternatives only one of which renders: the branches of a
+ * conditional, the operands of a logical, the several returns of a function
+ * `sx`. A wrapping alternative is a real seam whatever the others say, and only
+ * an all-`false` set proves the absence of one.
+ */
+function eitherBranchWraps(verdicts) {
+    if (verdicts.includes(true)) {
+        return true;
+    }
+    return verdicts.length > 0 && verdicts.every((verdict) => verdict === false)
+        ? false
+        : undefined;
+}
+/**
+ * The verdict over members merged in source order. An object literal and a MUI
+ * `sx` array are both last-write-wins, so a member that resolves `flexWrap`
+ * overrides every earlier one — including back to `false`, which is what makes
+ * `{ flexWrap: 'wrap', ...NOWRAP }` a non-wrapping object (#2299).
+ *
+ * An `undefined` member is opaque rather than empty: an imported or
+ * caller-supplied spread may or may not carry `flexWrap`, so it leaves the last
+ * known verdict standing rather than erasing it.
+ */
+function mergeVerdict(previous, next) {
+    return next === undefined ? previous : next;
+}
 exports.enforceUseFlexGapOnWrap = (0, createRule_1.createRule)({
     name: 'enforce-use-flex-gap-on-wrap',
     meta: {
@@ -224,58 +251,56 @@ exports.enforceUseFlexGapOnWrap = (0, createRule_1.createRule)({
                     }
                     return verdict;
                 }
-                case utils_1.AST_NODE_TYPES.ConditionalExpression: {
-                    const consequent = wrapVerdict(target.consequent, seen);
-                    const alternate = wrapVerdict(target.alternate, seen);
-                    if (consequent === true || alternate === true) {
-                        return true;
-                    }
-                    return consequent === false && alternate === false
-                        ? false
-                        : undefined;
-                }
-                case utils_1.AST_NODE_TYPES.LogicalExpression: {
-                    const left = wrapVerdict(target.left, seen);
-                    const right = wrapVerdict(target.right, seen);
-                    if (left === true || right === true) {
-                        return true;
-                    }
-                    return left === false && right === false ? false : undefined;
-                }
+                case utils_1.AST_NODE_TYPES.ConditionalExpression:
+                    return eitherBranchWraps([
+                        wrapVerdict(target.consequent, seen),
+                        wrapVerdict(target.alternate, seen),
+                    ]);
+                case utils_1.AST_NODE_TYPES.LogicalExpression:
+                    return eitherBranchWraps([
+                        wrapVerdict(target.left, seen),
+                        wrapVerdict(target.right, seen),
+                    ]);
                 default:
                     return undefined;
             }
         }
-        /** Whether an object literal states a wrapping `flexWrap`. */
+        /**
+         * What an object literal states about `flexWrap`. The members are merged in
+         * source order rather than scanned for any wrapping one, because an `sx`
+         * object is last-write-wins: `{ flexWrap: 'wrap', ...BASE }` renders
+         * whatever `BASE` says, and only the mirror ordering wraps.
+         */
         function objectWraps(object, seen) {
+            let verdict = undefined;
             for (const property of object.properties) {
                 if (property.type === utils_1.AST_NODE_TYPES.SpreadElement) {
                     // A spread of a local constant is read through; a spread of an
                     // imported or caller-supplied value stays opaque, because resolving it
                     // would need the cross-module analysis this rule declines.
-                    if (sxWraps(property.argument, seen)) {
-                        return true;
-                    }
+                    verdict = mergeVerdict(verdict, sxWraps(property.argument, seen));
                     continue;
                 }
                 if (propertyNameOf(property) !== 'flexWrap') {
                     continue;
                 }
-                if (wrapVerdict(property.value, seen) === true) {
-                    return true;
-                }
+                verdict = mergeVerdict(verdict, wrapVerdict(property.value, seen));
             }
-            return false;
+            return verdict;
         }
         /**
-         * Whether an `sx` expression states a wrapping `flexWrap` anywhere the rule
-         * can read statically. Four of the six wrapping Stacks in the consuming
-         * codebase hoist their `sx` to a module constant, including both live
-         * violations, so identifier resolution is the path that matters most.
+         * What an `sx` expression states about `flexWrap` where the rule can read it
+         * statically. Four of the six wrapping Stacks in the consuming codebase
+         * hoist their `sx` to a module constant, including both live violations, so
+         * identifier resolution is the path that matters most.
+         *
+         * The verdict is the tri-state rather than a boolean because this answer
+         * feeds a merge: a spread of `{ flexWrap: 'nowrap' }` has to override an
+         * earlier wrapping member, which a `false` meaning "nothing known" cannot.
          */
         function sxWraps(node, seen) {
             if (!node) {
-                return false;
+                return undefined;
             }
             const target = unwrapAssertions(node);
             switch (target.type) {
@@ -283,7 +308,7 @@ exports.enforceUseFlexGapOnWrap = (0, createRule_1.createRule)({
                     return objectWraps(target, seen);
                 case utils_1.AST_NODE_TYPES.Identifier: {
                     if (seen.has(target)) {
-                        return false;
+                        return undefined;
                     }
                     seen.add(target);
                     return sxWraps(initializerOf(target), seen);
@@ -291,21 +316,31 @@ exports.enforceUseFlexGapOnWrap = (0, createRule_1.createRule)({
                 case utils_1.AST_NODE_TYPES.ArrowFunctionExpression: {
                     const body = unwrapAssertions(target.body);
                     if (body.type === utils_1.AST_NODE_TYPES.BlockStatement) {
-                        return body.body.some((statement) => statement.type === utils_1.AST_NODE_TYPES.ReturnStatement &&
-                            sxWraps(statement.argument ?? undefined, seen));
+                        return eitherBranchWraps(body.body
+                            .filter((statement) => statement.type === utils_1.AST_NODE_TYPES.ReturnStatement)
+                            .map((statement) => sxWraps(statement.argument ?? undefined, seen)));
                     }
                     return sxWraps(body, seen);
                 }
                 case utils_1.AST_NODE_TYPES.ConditionalExpression:
                     // Either branch renders, so either branch wrapping is a real seam.
-                    return (sxWraps(target.consequent, seen) || sxWraps(target.alternate, seen));
-                case utils_1.AST_NODE_TYPES.ArrayExpression:
-                    // MUI merges an array of sx entries left to right.
-                    return target.elements.some((element) => element ? sxWraps(element, seen) : false);
+                    return eitherBranchWraps([
+                        sxWraps(target.consequent, seen),
+                        sxWraps(target.alternate, seen),
+                    ]);
+                case utils_1.AST_NODE_TYPES.ArrayExpression: {
+                    // MUI merges an array of sx entries left to right, so the entry that
+                    // resolves `flexWrap` last owns the value.
+                    let verdict = undefined;
+                    for (const element of target.elements) {
+                        verdict = mergeVerdict(verdict, element ? sxWraps(element, seen) : undefined);
+                    }
+                    return verdict;
+                }
                 default:
                     // A call expression is opaque. Guessing at what it returns would
                     // report on code the rule cannot read.
-                    return false;
+                    return undefined;
             }
         }
         /**
@@ -417,8 +452,8 @@ exports.enforceUseFlexGapOnWrap = (0, createRule_1.createRule)({
                 // The attribute wins where both spell `flexWrap` and disagree; an
                 // unreadable attribute is not a disagreement, so it falls through.
                 const wraps = attributeVerdict ??
-                    (sx ? sxWraps(attributeValueOf(sx), new Set()) : false);
-                if (!wraps) {
+                    (sx ? sxWraps(attributeValueOf(sx), new Set()) : undefined);
+                if (wraps !== true) {
                     return;
                 }
                 if (!resolvesToMuiStack(elementName)) {

package/lib/rules/no-hungarian.js

@@ -202,6 +202,27 @@ const DOMAIN_CLASS_HEAD_NOUNS = new Set([
     'drug',
     'vehicle',
 ]);
+// Conversion heads: the verb or preposition a CONVERTER function's name opens
+// with. In <head><Type> the trailing type word names what the function
+// PRODUCES (or consumes, for `from`), never the type of the value the
+// identifier holds — the identifier holds a function. Hungarian notation tags a
+// value with its own type, so `toNumber` is outside the notation entirely, and
+// stripping the type word destroys the name (`to`, `parse` and `from` denote
+// nothing on their own), which is this rule's own test for a domain compound
+// versus a tag. The same reasoning the rule already applies to the type-concept
+// names it exempts (`StringToNumber`) and to the `Parsed` / `Converted`
+// suffixes, applied to function names (#2302).
+//
+// `convertto` is the two-segment head `convertTo`, stored joined because the
+// lookup is done on the head segments concatenated and lowercased.
+const CONVERSION_HEADS = new Set([
+    'to',
+    'as',
+    'from',
+    'parse',
+    'into',
+    'convertto',
+]);
 // Common built-in JavaScript prototype methods
 const BUILT_IN_METHODS = new Set([
     // String methods
@@ -578,6 +599,63 @@ function isClassValuedDeclaration(node) {
             return false;
     }
 }
+// Is `name` a conversion compound of the form <head><Type> (toNumber,
+// parseBoolean, fromString, asArray, convertToNumber), where the FINAL segment
+// is a full type word and everything before it is a conversion head? The type
+// word must be final and must follow the head directly, so a name that merely
+// contains a head keeps firing: `toNumberValue` names a value (the type word is
+// not the target), `numberToValue` leads with the type word, and `strToNumber`
+// carries an abbreviation marker, which no English word is spelled with.
+// Abbreviation markers are excluded by construction — FULL_TYPE_WORDS holds only
+// the spelled-out type words — so `toNum` / `toStr` are untouched.
+function isConversionTargetCompound(name) {
+    const segments = splitCamelSegments(name);
+    if (segments.length < 2) {
+        return false;
+    }
+    const target = segments[segments.length - 1];
+    if (!FULL_TYPE_WORDS.has(target.toLowerCase())) {
+        return false;
+    }
+    const head = segments.slice(0, -1).join('').toLowerCase();
+    return CONVERSION_HEADS.has(head);
+}
+// Does the declaration site PROVE, syntactically, that the named value is a
+// function? Only a function declaration's own name, a function/arrow
+// initializer, or a class METHOD are conclusive without type information — an
+// aliased function (`const toNumber = parseFloat`) and a bare `(v: string) =>
+// number` annotation are deliberately not read, keeping the carve-out on the
+// shapes where the function body is written at the declaration itself.
+//
+// This is the mirror image of isSymbolTypedDeclaration (#1835) and
+// isClassValuedDeclaration (#2030): there the syntactic proof WITHDRAWS a
+// carve-out because it confirms the suffix encodes the value's type; here it
+// GRANTS one, because a function value is precisely what the type word cannot
+// be describing. Accessors are excluded (`get toNumber()` is read as a value at
+// every use site, so its `Number` does tag that value), as are computed keys,
+// whose identifier is a reference to some other binding rather than a
+// declaration.
+function isFunctionValuedDeclaration(node) {
+    const parent = node.parent;
+    if (!parent) {
+        return false;
+    }
+    const isFunctionValue = (value) => !!value &&
+        (value.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+            value.type === utils_1.AST_NODE_TYPES.FunctionExpression);
+    switch (parent.type) {
+        case utils_1.AST_NODE_TYPES.FunctionDeclaration:
+            return parent.id === node;
+        case utils_1.AST_NODE_TYPES.VariableDeclarator:
+            return parent.id === node && isFunctionValue(parent.init);
+        case utils_1.AST_NODE_TYPES.MethodDefinition:
+            return (parent.key === node && !parent.computed && parent.kind === 'method');
+        case utils_1.AST_NODE_TYPES.PropertyDefinition:
+            return (parent.key === node && !parent.computed && isFunctionValue(parent.value));
+        default:
+            return false;
+    }
+}
 // Rebuild a SCREAMING_SNAKE_CASE identifier's segments into a PascalCase compound
 // (["MATCH","NUMBER"] -> "MatchNumber") so the snake-case branch can reuse the
 // camelCase isDomainNumberCompound / DOMAIN_NUMBER_HEAD_NOUNS exemption verbatim,
@@ -616,7 +694,9 @@ exports.noHungarian = (0, createRule_1.createRule)({
         // `symbol` value, which vetoes the <domain>Symbol glyph exemption.
         // `isClassValued` is true when the declaration syntactically proves a JS
         // class value, which vetoes the <taxonomy>Class exemption.
-        function hasTypeMarker(variableName, isTypeName = false, isSymbolTyped = false, isClassValued = false) {
+        // `isFunctionValued` is true when the declaration syntactically proves a
+        // function value, which GRANTS the converter-function exemption.
+        function hasTypeMarker(variableName, isTypeName = false, isSymbolTyped = false, isClassValued = false, isFunctionValued = false) {
             // Type names whose type-word denotes a concept/relation (StringToNumber,
             // CapitalizedString, FuncKeys, PromiseOrValue) are not Hungarian — the word
             // is part of the type's meaning, like the allowed compound noun PhoneNumber.
@@ -702,6 +782,17 @@ exports.noHungarian = (0, createRule_1.createRule)({
                         if (index !== 0 && index !== lastIndex) {
                             return false;
                         }
+                        // A trailing "..._TYPE" word directly after a conversion head on a
+                        // declaration that proves a function (TO_NUMBER, PARSE_BOOLEAN as
+                        // arrow consts) names the conversion TARGET, not the constant's own
+                        // type — the same carve-out as camelCase toNumber (#2302), routed
+                        // through the shared PascalCase helper so the two casings cannot
+                        // diverge (the #1294 asymmetry).
+                        if (isFunctionValued &&
+                            index === lastIndex &&
+                            isConversionTargetCompound(screamingSnakePartsToPascalCase(parts))) {
+                            return false;
+                        }
                         // A trailing "..._NUMBER" whose preceding head noun is a domain
                         // entity (MATCH_NUMBER, ISSUE_NUMBER, CURRENT_LINE_NUMBER) is a
                         // domain compound, not a Hungarian type tag — route through the same
@@ -782,6 +873,18 @@ exports.noHungarian = (0, createRule_1.createRule)({
                     normalizedVarName.length > normalizedMarker.length &&
                     (/[A-Z0-9]/.test(variableName[variableName.length - normalizedMarker.length - 1]) ||
                         /[A-Z]/.test(variableName[variableName.length - normalizedMarker.length]))) {
+                    // A trailing full type word directly after a conversion head, on a
+                    // declaration that syntactically proves a function (toNumber,
+                    // parseBoolean, fromString, asArray, convertToNumber), names what the
+                    // conversion PRODUCES — the identifier itself holds a function, so
+                    // there is no value type being tagged, and stripping the word leaves
+                    // `to` / `parse` / `from`, which name nothing (#2302). Scoped to
+                    // full-word markers in SUFFIX position on a proven function, so
+                    // `const toNumber = 5`, `toNum` / `toStr` / `strToNumber`, and
+                    // `numberToValue` all keep firing.
+                    if (isFunctionValued && isConversionTargetCompound(variableName)) {
+                        return false;
+                    }
                     // A trailing "...Number" whose head noun is a domain entity
                     // (issueNumber, lineNumber, roundNumber, versionNumber) is a domain
                     // compound, not a Hungarian type tag: the suffix names WHAT the value
@@ -899,7 +1002,7 @@ exports.noHungarian = (0, createRule_1.createRule)({
             if (isExternalOrBuiltIn(node))
                 return;
             // Check for type markers
-            if (hasTypeMarker(name, isTypeName, isSymbolTypedDeclaration(node), isClassValuedDeclaration(node))) {
+            if (hasTypeMarker(name, isTypeName, isSymbolTypedDeclaration(node), isClassValuedDeclaration(node), isFunctionValuedDeclaration(node))) {
                 context.report({
                     node,
                     messageId: 'noHungarian',

package/lib/rules/prefer-spread-over-reassembly.d.ts

@@ -1,6 +1,7 @@
 import { TSESLint } from '@typescript-eslint/utils';
+type MessageIds = 'preferSpread' | 'applySpread';
 type Options = [{
     minFields?: number;
 }];
-export declare const preferSpreadOverReassembly: TSESLint.RuleModule<"preferSpread", Options, TSESLint.RuleListener>;
+export declare const preferSpreadOverReassembly: TSESLint.RuleModule<MessageIds, Options, TSESLint.RuleListener>;
 export {};

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

@@ -433,8 +433,8 @@ function findRelativeTypeImport(program, localName) {
     return null;
 }
 /**
- * Enumerates every property name a type node declares, or null when the member
- * list cannot be established with certainty.
+ * Resolves a type node to the member list it writes down, or null when the
+ * member set cannot be established with certainty.
  *
  * Only an unambiguous, fully written-out member list qualifies, reached either
  * directly or through the key-preserving operators in
@@ -446,9 +446,9 @@ function findRelativeTypeImport(program, localName) {
  * A name the file does not declare is looked up in the relative module that
  * imports it, once; see {@link importedTypeMemberNames}.
  */
-function memberNamesOf(typeNode, scope, seen = new Set()) {
+function resolveTypeMembers(typeNode, scope, seen = new Set()) {
     if (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeLiteral) {
-        return namesOfMembers(typeNode.members);
+        return { kind: 'members', members: typeNode.members };
     }
     if (typeNode.type !== utils_1.AST_NODE_TYPES.TSTypeReference ||
         typeNode.typeName.type !== utils_1.AST_NODE_TYPES.Identifier) {
@@ -463,13 +463,14 @@ function memberNamesOf(typeNode, scope, seen = new Set()) {
             scope.isLocallyBound(name)) {
             return null;
         }
-        return memberNamesOf(typeNode.typeParameters.params[0], scope, seen);
+        return resolveTypeMembers(typeNode.typeParameters.params[0], scope, seen);
     }
     const declaration = findLocalTypeDeclaration(scope.program, typeNode, name);
     if (!declaration) {
         // The file does not declare the name, so the only remaining source of a
         // written-down member list is the module it comes from.
-        return scope.resolveImportedMembers?.(name) ?? null;
+        const names = scope.resolveImportedMembers?.(name);
+        return names ? { kind: 'names', names } : null;
     }
     // A self-referential alias (`type T = T`) would otherwise recur forever. The
     // guard is keyed on the DECLARATION rather than the name: one name denotes
@@ -479,24 +480,166 @@ function memberNamesOf(typeNode, scope, seen = new Set()) {
         return null;
     }
     seen.add(declaration);
-    return memberNamesOfDeclaration(declaration, scope, seen);
+    return resolveTypeMembersOfDeclaration(declaration, scope, seen);
 }
 /**
- * The member names a type alias or interface declares. A generic declaration
+ * The members a type alias or interface declares. A generic declaration
  * describes a different member set per instantiation and an interface with an
  * `extends` clause inherits members written elsewhere, so neither enumerates.
  */
-function memberNamesOfDeclaration(declaration, scope, seen) {
+function resolveTypeMembersOfDeclaration(declaration, scope, seen) {
     if (declaration.typeParameters) {
         return null;
     }
     if (declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
-        return memberNamesOf(declaration.typeAnnotation, scope, seen);
+        return resolveTypeMembers(declaration.typeAnnotation, scope, seen);
     }
     if (declaration.extends && declaration.extends.length > 0) {
         return null;
     }
-    return namesOfMembers(declaration.body.body);
+    return { kind: 'members', members: declaration.body.body };
+}
+/**
+ * Enumerates every property name a type node declares, or null when the member
+ * list cannot be established with certainty.
+ */
+function memberNamesOf(typeNode, scope, seen = new Set()) {
+    const resolved = resolveTypeMembers(typeNode, scope, seen);
+    if (!resolved) {
+        return null;
+    }
+    return resolved.kind === 'names'
+        ? resolved.names
+        : namesOfMembers(resolved.members);
+}
+/**
+ * The type a chain of non-generic local aliases finally spells, or the node
+ * itself when the chain cannot be followed.
+ *
+ * A catalog names its element and callback shapes through aliases rather than
+ * writing them inline, so a reader that only recognises the literal spelling
+ * loses the proof on the layout it exists to serve.
+ */
+function unwrapLocalTypeAlias(typeNode, scope, seen = new Set()) {
+    if (typeNode.type !== utils_1.AST_NODE_TYPES.TSTypeReference ||
+        typeNode.typeName.type !== utils_1.AST_NODE_TYPES.Identifier ||
+        typeNode.typeParameters) {
+        return typeNode;
+    }
+    const declaration = findLocalTypeDeclaration(scope.program, typeNode, typeNode.typeName.name);
+    if (!declaration ||
+        declaration.type !== utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
+        declaration.typeParameters ||
+        seen.has(declaration)) {
+        return typeNode;
+    }
+    seen.add(declaration);
+    return unwrapLocalTypeAlias(declaration.typeAnnotation, scope, seen);
+}
+/**
+ * The declared type of one named member of a type, or null when the type does
+ * not write that member down exactly once.
+ *
+ * A name carried twice is an overload set or a declaration merge, whose
+ * effective signature is not the one written at either site, so it proves
+ * nothing about the parameter a callback receives.
+ */
+function memberTypeNodeOf(typeNode, scope, memberName) {
+    const resolved = resolveTypeMembers(typeNode, scope);
+    if (!resolved || resolved.kind !== 'members') {
+        return null;
+    }
+    let matches = 0;
+    let annotation = null;
+    for (const member of resolved.members) {
+        if (member.type !== utils_1.AST_NODE_TYPES.TSPropertySignature || member.computed) {
+            continue;
+        }
+        const key = member.key;
+        const name = key.type === utils_1.AST_NODE_TYPES.Identifier
+            ? key.name
+            : key.type === utils_1.AST_NODE_TYPES.Literal && typeof key.value === 'string'
+                ? key.value
+                : null;
+        if (name !== memberName) {
+            continue;
+        }
+        matches += 1;
+        annotation = member.typeAnnotation?.typeAnnotation ?? null;
+    }
+    return matches === 1 ? annotation : null;
+}
+/**
+ * The declared type of the sole parameter of a function type, or null when the
+ * type is not a one-parameter signature that writes its parameter's type down.
+ *
+ * More than one parameter means the callback under lint is not the one this
+ * signature describes, and a rest parameter names no fixed member set at all.
+ */
+function soleParameterTypeOf(typeNode, scope) {
+    const signature = unwrapLocalTypeAlias(typeNode, scope);
+    if (signature.type !== utils_1.AST_NODE_TYPES.TSFunctionType ||
+        signature.params.length !== 1) {
+        return null;
+    }
+    const param = signature.params[0];
+    if (param.type === utils_1.AST_NODE_TYPES.RestElement ||
+        param.type === utils_1.AST_NODE_TYPES.TSParameterProperty) {
+        return null;
+    }
+    return param.typeAnnotation?.typeAnnotation ?? null;
+}
+/**
+ * The type node an expression is declared to have by the binding or assertion
+ * it is written into.
+ *
+ * A codebase that centralises its shapes states them once at the binding —
+ * `const CASES: readonly CaseEntry[] = [...]` — and leaves every callback
+ * inside to be contextually typed by it, so a reader that only consults
+ * parameter annotations never sees the type that is actually written (#2298).
+ */
+function declaredTypeOfInitializer(node) {
+    const parent = node.parent;
+    if (!parent) {
+        return null;
+    }
+    if ((parent.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+        parent.type === utils_1.AST_NODE_TYPES.TSSatisfiesExpression) &&
+        parent.expression === node) {
+        // `as const` states immutability rather than a shape, and it is written
+        // BELOW the binding's annotation, so the walk continues past it.
+        if (isConstAssertionType(parent.typeAnnotation)) {
+            return declaredTypeOfInitializer(parent);
+        }
+        return parent.typeAnnotation;
+    }
+    if (parent.type === utils_1.AST_NODE_TYPES.VariableDeclarator &&
+        parent.init === node &&
+        parent.id.type === utils_1.AST_NODE_TYPES.Identifier &&
+        parent.id.typeAnnotation) {
+        return parent.id.typeAnnotation.typeAnnotation;
+    }
+    return null;
+}
+function isConstAssertionType(typeNode) {
+    return (typeNode.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+        typeNode.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+        typeNode.typeName.name === 'const');
+}
+/**
+ * The declared type of the entry an object literal spells, looking through the
+ * array literal a catalog wraps its entries in.
+ */
+function declaredEntryTypeOf(literal, scope) {
+    const array = literal.parent;
+    if (array?.type === utils_1.AST_NODE_TYPES.ArrayExpression &&
+        array.elements.includes(literal)) {
+        const declared = declaredTypeOfInitializer(array);
+        return declared
+            ? arrayElementTypeOf(unwrapLocalTypeAlias(declared, scope))
+            : null;
+    }
+    return declaredTypeOfInitializer(literal);
 }
 /**
  * The member names of a type the file under lint imports from a relative
@@ -555,7 +698,15 @@ function readExportedTypeMembers(filePath, exported) {
             return siblingBoundNames.has(name);
         },
     };
-    return memberNamesOfDeclaration(declaration, siblingScope, new Set([declaration]));
+    const resolved = resolveTypeMembersOfDeclaration(declaration, siblingScope, new Set([declaration]));
+    if (!resolved) {
+        return null;
+    }
+    // The sibling's scope carries no import resolver, so the walk inside it can
+    // only ever end at member nodes the sibling itself writes down.
+    return resolved.kind === 'names'
+        ? resolved.names
+        : namesOfMembers(resolved.members);
 }
 /**
  * For a JSX element, returns the set of destructured names that are forwarded
@@ -958,6 +1109,7 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
             recommended: 'error',
         },
         fixable: 'code',
+        hasSuggestions: true,
         schema: [
             {
                 type: 'object',
@@ -973,6 +1125,8 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
         messages: {
             preferSpread: 'Prefer spread over destructure-then-reassemble: replace the destructured parameter with a single identifier and use spread syntax on the target. ' +
                 'This avoids silent bugs when new fields are added to the type.',
+            applySpread: 'Replace the destructured parameter with a single identifier and spread it onto the target. ' +
+                'Check first that the parameter carries no members beyond the ones destructured, since the spread forwards every member it has.',
         },
     },
     defaultOptions: [{ minFields: DEFAULT_MIN_FIELDS }],
@@ -1137,29 +1291,83 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
             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 member names of the parameter type a typed binding gives the
+         * function through the object literal it is a property of.
+         *
+         * A catalog states its entries' shape once, on the binding
+         * (`const CASES: readonly CaseEntry[] = [...]`), and leaves every callback
+         * inside to be contextually typed by it. Such a parameter narrows exactly
+         * as an annotated one does, so a reader that stops at annotations rewrites
+         * a deliberate pick into a widening spread (#2298).
+         */
+        function contextualBindingMemberNames(fn) {
+            const property = fn.parent;
+            if (!property ||
+                property.type !== utils_1.AST_NODE_TYPES.Property ||
+                property.value !== fn ||
+                property.computed) {
+                return null;
+            }
+            const key = property.key;
+            const propertyName = key.type === utils_1.AST_NODE_TYPES.Identifier
+                ? key.name
+                : key.type === utils_1.AST_NODE_TYPES.Literal && typeof key.value === 'string'
+                    ? key.value
+                    : null;
+            if (propertyName === null) {
+                return null;
+            }
+            const literal = property.parent;
+            if (!literal || literal.type !== utils_1.AST_NODE_TYPES.ObjectExpression) {
+                return null;
+            }
+            const entryType = declaredEntryTypeOf(literal, typeScope);
+            if (!entryType) {
+                return null;
+            }
+            const memberType = memberTypeNodeOf(entryType, typeScope, propertyName);
+            if (!memberType) {
+                return null;
+            }
+            const parameterType = soleParameterTypeOf(memberType, typeScope);
+            return parameterType ? memberNamesOf(parameterType, typeScope) : null;
+        }
+        /**
+         * How much the source object's own type proves about the destructured pick.
          *
-         * 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 — a union, an index
-         * signature, an instantiation of anything but a key-preserving operator, or
-         * an import whose module it declines to follow — yields no proof and the
-         * rule likewise still reports. Silence is reserved for the case where the
-         * widening is demonstrated.
+         * `narrowing` — the pick is a PROPER subset of a resolved member set, so
+         * spreading the parameter would reinstate the members the author left out
+         * and change what the function produces (#1642: a GitHub review payload
+         * gained unknown keys). The rule stays silent.
+         *
+         * `exhaustive` — the resolved member set is exactly the pick, so the
+         * rewrite is demonstrably behavior-preserving and is applied.
+         *
+         * `unproven` — no member set resolves, or one resolves that does not even
+         * contain the pick. A union, an index signature, an instantiation of
+         * anything but a key-preserving operator, a `Parameters<>` indirection or
+         * an import whose module the walk declines to follow all land here. The
+         * finding still stands, but nothing about the rewrite's safety follows, so
+         * it is offered rather than applied.
          */
-        function isProvablyNarrowingPick(fn, param, destructuredNames) {
+        function classifyPick(fn, param, destructuredNames) {
             // An explicit annotation overrides whatever the call site would imply,
-            // so the contextual route is consulted only in its absence.
+            // so the contextual routes are consulted only in its absence.
             const memberNames = param.typeAnnotation
                 ? memberNamesOf(param.typeAnnotation.typeAnnotation, typeScope)
-                : contextualElementMemberNames(fn);
-            if (!memberNames || memberNames.size <= destructuredNames.length) {
-                return false;
+                : contextualElementMemberNames(fn) ?? contextualBindingMemberNames(fn);
+            if (!memberNames) {
+                return 'unproven';
+            }
+            // A pick naming something the resolved type does not declare means the
+            // resolution describes a different shape than the one destructured, so
+            // its size says nothing about what a spread would forward.
+            if (!destructuredNames.every((name) => memberNames.has(name))) {
+                return 'unproven';
             }
-            return destructuredNames.every((name) => memberNames.has(name));
+            return memberNames.size > destructuredNames.length
+                ? 'narrowing'
+                : 'exhaustive';
         }
         function checkFunction(fn) {
             // Must have exactly one parameter that is an ObjectPattern.
@@ -1218,37 +1426,48 @@ exports.preferSpreadOverReassembly = (0, createRule_1.createRule)({
             }
             // The pick may exist precisely because the omitted members must not flow
             // through; spreading would reinstate them.
-            if (isProvablyNarrowingPick(fn, param, destructuredNames)) {
+            const classification = classifyPick(fn, param, destructuredNames);
+            if (classification === 'narrowing') {
                 return;
             }
+            const applySpread = (fixer) => {
+                const fixes = [];
+                // Choose a fresh name for the props parameter that does not collide
+                // with any binding currently in scope.
+                const propsName = freshPropsName(namesSet);
+                // 1. Replace the destructured parameter with `props` (or fresh name),
+                // keeping any type annotation intact.
+                const paramFix = replacePatternWithName(fixer, sourceCode, param, propsName);
+                if (!paramFix) {
+                    return null;
+                }
+                fixes.push(paramFix);
+                // 2. Collapse the forwarded fields into a single spread. Only the
+                // ranges of the fields being collapsed are spliced out; the retained
+                // ones — and the comments attached to them, which may be
+                // `eslint-disable` directives — are left exactly as authored.
+                const targetFix = target.kind === 'jsx'
+                    ? buildJsxSpreadFix(fixer, sourceCode, target.openingElement, forwardedNodes, propsName)
+                    : buildObjectSpreadFix(fixer, sourceCode, target.expression, forwardedNodes, propsName);
+                if (!targetFix) {
+                    return null;
+                }
+                fixes.push(targetFix);
+                return fixes;
+            };
             context.report({
                 node: param,
                 messageId: 'preferSpread',
-                fix(fixer) {
-                    const fixes = [];
-                    // Choose a fresh name for the props parameter that does not collide
-                    // with any binding currently in scope.
-                    const propsName = freshPropsName(namesSet);
-                    // 1. Replace the destructured parameter with `props` (or fresh name),
-                    // keeping any type annotation intact.
-                    const paramFix = replacePatternWithName(fixer, sourceCode, param, propsName);
-                    if (!paramFix) {
-                        return null;
-                    }
-                    fixes.push(paramFix);
-                    // 2. Collapse the forwarded fields into a single spread. Only the
-                    // ranges of the fields being collapsed are spliced out; the retained
-                    // ones — and the comments attached to them, which may be
-                    // `eslint-disable` directives — are left exactly as authored.
-                    const targetFix = target.kind === 'jsx'
-                        ? buildJsxSpreadFix(fixer, sourceCode, target.openingElement, forwardedNodes, propsName)
-                        : buildObjectSpreadFix(fixer, sourceCode, target.expression, forwardedNodes, propsName);
-                    if (!targetFix) {
-                        return null;
-                    }
-                    fixes.push(targetFix);
-                    return fixes;
-                },
+                // An exhaustive pick is PROVEN to spread to the same member set, so the
+                // rewrite is applied. Everything else is offered rather than applied:
+                // the spread forwards whatever the parameter's real type turns out to
+                // carry, and a widening this reader cannot disprove has silently
+                // changed consumer behaviour five times (#1642, #1643, #1644, #1769,
+                // #2298). A suggestion costs the author one keystroke; a wrong
+                // `--fix` costs a behaviour change nobody reviewed.
+                ...(classification === 'exhaustive'
+                    ? { fix: applySpread }
+                    : { suggest: [{ messageId: 'applySpread', fix: applySpread }] }),
             });
         }
         return {

package/lib/rules/prefer-sx-prop-over-system-props.js

@@ -441,29 +441,50 @@ const declaredKeysOf = (object) => {
     }
     return keys;
 };
+/** The names carried by more than one of the moved props. */
+const duplicatedNamesOf = (systemPropAttrs) => {
+    const seen = new Set();
+    const duplicated = new Set();
+    for (const attr of systemPropAttrs) {
+        if (attr.name.type !== utils_1.AST_NODE_TYPES.JSXIdentifier) {
+            continue;
+        }
+        const { name } = attr.name;
+        if (seen.has(name)) {
+            duplicated.add(name);
+            continue;
+        }
+        seen.add(name);
+    }
+    return duplicated;
+};
 /**
- * The moved props whose name the `sx` object literal already declares. Splicing
- * one in emits `{ display: 'flex', display: 'block' }` — TS1117, and whichever
- * value the runtime keeps, one of the two spellings the author wrote is
- * discarded. The two disagree and only the author can say which wins, so the
- * fix stands down for those props while every other prop on the element still
- * merges (#2296).
+ * The moved props that cannot be spliced into one object literal without
+ * duplicating a key. Doing so emits `{ display: 'flex', display: 'block' }` —
+ * TS1117, and whichever value the runtime keeps, one of the two spellings the
+ * author wrote is discarded. The two disagree and only the author can say which
+ * wins, so the fix stands down for those props while every other prop on the
+ * element still merges (#2296).
  *
- * Only the object slot is merged into in place. A new `sx`, an array entry and
- * the `{ ...moved, ...expr }` wrap each emit a fresh object literal, whose keys
- * cannot duplicate a name written elsewhere.
+ * A name is duplicated two ways. The `sx` object literal may already declare
+ * it, which only the object slot can do because only that slot is merged into
+ * in place. Or two moved props may carry the SAME name (`<Box display="flex"
+ * display="block" />`, itself TS17001): the fresh object literal a new `sx`, an
+ * array entry or the `{ ...moved, ...expr }` wrap emits carries one entry per
+ * moved prop, so it duplicates that name on its own with no `sx` involved
+ * (#2300). Both duplicates stand down — the rule cannot know which the author
+ * meant — while the report on each stays, so the author is still told to move
+ * the prop.
  */
 const collidingPropsOf = (systemPropAttrs, sxAttr) => {
+    const duplicated = duplicatedNamesOf(systemPropAttrs);
     const slot = sxSlotOf(sxAttr);
-    if (slot.kind !== 'object') {
-        return new Set();
-    }
-    const declared = declaredKeysOf(slot.object);
+    const declared = slot.kind === 'object' ? declaredKeysOf(slot.object) : new Set();
     if (declared === null) {
         return new Set(systemPropAttrs);
     }
     return new Set(systemPropAttrs.filter((attr) => attr.name.type === utils_1.AST_NODE_TYPES.JSXIdentifier &&
-        declared.has(attr.name.name)));
+        (declared.has(attr.name.name) || duplicated.has(attr.name.name))));
 };
 /**
  * Plans every edit the autofix makes for one JSX element.
@@ -1058,10 +1079,10 @@ exports.preferSxPropOverSystemProps = (0, createRule_1.createRule)({
                 if (systemPropAttrs.length === 0)
                     return;
                 const sourceCode = context.getSourceCode();
-                // A prop whose name the `sx` literal already declares is reported
-                // without a fix: merging it would duplicate the key. The rest of the
-                // element is still merged, so one disagreeing pair does not hold the
-                // other props back.
+                // A prop whose name the `sx` literal already declares, or that another
+                // moved prop on this element repeats, is reported without a fix:
+                // merging it would duplicate the key. The rest of the element is still
+                // merged, so one disagreeing pair does not hold the other props back.
                 const collidingProps = collidingPropsOf(systemPropAttrs, sxAttr);
                 const fixableAttrs = systemPropAttrs.filter((attr) => !collidingProps.has(attr));
                 // Report each system prop. Only the first fixable one carries the fixer

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,49 @@
 [
+  {
+    "version": "1.21.2",
+    "date": "2026-09-03T01:55:23.074Z",
+    "rules": [
+      {
+        "name": "enforce-use-flex-gap-on-wrap",
+        "changeType": "fix",
+        "issues": [
+          2299,
+          2301
+        ],
+        "summary": "merge sx members last-write-wins (closes #2299, closes #2301)"
+      },
+      {
+        "name": "no-hungarian",
+        "changeType": "fix",
+        "issues": [
+          2302
+        ],
+        "summary": "exempt converter functions whose final segment names the conversion target (closes #2302)"
+      },
+      {
+        "name": "prefer-sx-prop-over-system-props",
+        "changeType": "fix",
+        "issues": [
+          2300
+        ],
+        "summary": "decline a name written twice among the moved props (closes #2300)"
+      }
+    ]
+  },
+  {
+    "version": "1.21.1",
+    "date": "2026-09-02T22:30:34.104Z",
+    "rules": [
+      {
+        "name": "prefer-spread-over-reassembly",
+        "changeType": "fix",
+        "issues": [
+          2298
+        ],
+        "summary": "apply the spread only where the pick is proven exhaustive (closes #2298)"
+      }
+    ]
+  },
   {
     "version": "1.21.0",
     "date": "2026-09-02T18:04:18.331Z",