@blumintinc/eslint-plugin-blumint 1.20.202 → 1.21.0

package/README.md

@@ -139,6 +139,7 @@ full closed loop is documented in agora's `.claude/skills/eslint-autonomy/SKILL.
 | [enforce-types-directory-placement](docs/rules/enforce-types-directory-placement.md)                         | Enforce that type-only files (containing only type/interface/enum declarations) live under the canonical types directory                                                                                                                                                                                                                                                                         | ✅  |    |    |    |    |
 | [enforce-typescript-markdown-code-blocks](docs/rules/enforce-typescript-markdown-code-blocks.md)             | Ensure Markdown fenced code blocks without a language specifier default to typescript for consistent highlighting.                                                                                                                                                                                                                                                                               | ✅  |    | 🔧 |    |    |
 | [enforce-unique-cursor-headers](docs/rules/enforce-unique-cursor-headers.md)                                 | Ensure files have exactly one cursor header containing required tags (e.g., @fileoverview) before any code                                                                                                                                                                                                                                                                                       | ✅  |    | 🔧 |    |    |
+| [enforce-use-flex-gap-on-wrap](docs/rules/enforce-use-flex-gap-on-wrap.md)                                   | Require `useFlexGap` on a MUI `Stack` that wraps and passes `spacing`, because margin-based spacing leaves the wrapped line with no row gap and a phantom leading indent                                                                                                                                                                                                                         | ✅  |    | 🔧 |    |    |
 | [enforce-verb-noun-naming](docs/rules/enforce-verb-noun-naming.md)                                           | Enforce verb phrases for functions and methods                                                                                                                                                                                                                                                                                                                                                   | ✅  |    |    |    |    |
 | [ensure-pointer-events-none](docs/rules/ensure-pointer-events-none.md)                                       | Ensure pointer-events: none is added to non-interactive pseudo-elements                                                                                                                                                                                                                                                                                                                          | ✅  |    | 🔧 |    |    |
 | [export-if-in-doubt](docs/rules/export-if-in-doubt.md)                                                       | All top-level variable declarations, type definitions, and functions should be exported                                                                                                                                                                                                                                                                                                          | ✅  |    |    |    |    |

package/lib/index.js

@@ -197,6 +197,7 @@ const no_portal_inside_tooltip_1 = require("./rules/no-portal-inside-tooltip");
 const no_satisfies_in_frontend_bundle_1 = require("./rules/no-satisfies-in-frontend-bundle");
 const prefer_utility_function_own_file_1 = require("./rules/prefer-utility-function-own-file");
 const no_render_function_components_1 = require("./rules/no-render-function-components");
+const enforce_use_flex_gap_on_wrap_1 = require("./rules/enforce-use-flex-gap-on-wrap");
 const NO_FRONTEND_IMPORTS_FROM_FUNCTIONS_MESSAGE = 'Backend Cloud Functions (.f.ts under functions/) must not import frontend modules from the repo root src/**. Frontend code can depend on browser-only APIs and bundling it into Cloud Functions breaks server execution; move shared logic into functions/src or a shared package.';
 function noFrontendImportsFromFunctionsPatterns(pattern) {
     return [
@@ -223,7 +224,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.202',
+        version: '1.21.0',
     },
     parseOptions: {
         ecmaVersion: 2020,
@@ -431,6 +432,7 @@ module.exports = {
                 '@blumintinc/blumint/no-satisfies-in-frontend-bundle': 'error',
                 '@blumintinc/blumint/prefer-utility-function-own-file': 'error',
                 '@blumintinc/blumint/no-render-function-components': 'error',
+                '@blumintinc/blumint/enforce-use-flex-gap-on-wrap': 'error',
             },
             /**
              * Depth-specific overrides block only import strings that traverse to the
@@ -708,6 +710,7 @@ module.exports = {
         'no-satisfies-in-frontend-bundle': no_satisfies_in_frontend_bundle_1.noSatisfiesInFrontendBundle,
         'prefer-utility-function-own-file': prefer_utility_function_own_file_1.preferUtilityFunctionOwnFile,
         'no-render-function-components': no_render_function_components_1.noRenderFunctionComponents,
+        'enforce-use-flex-gap-on-wrap': enforce_use_flex_gap_on_wrap_1.enforceUseFlexGapOnWrap,
     },
 };
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,14 @@
+import { TSESLint } from '@typescript-eslint/utils';
+/**
+ * `applyDefault` deep merges `defaultOptions` into whatever the consumer passes
+ * and an array value replaces rather than extends, so both keys are present by
+ * the time `create` reads them.
+ */
+type Options = [
+    {
+        stackComponents: string[];
+        importSources: string[];
+    }
+];
+export declare const enforceUseFlexGapOnWrap: TSESLint.RuleModule<"useFlexGapRequired", Options, TSESLint.RuleListener>;
+export {};

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

@@ -0,0 +1,436 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceUseFlexGapOnWrap = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_STACK_COMPONENTS = ['Stack'];
+/**
+ * Both spellings occur in the consuming codebase: the deep default path in the
+ * overwhelming majority of files, the barrel in a handful.
+ */
+const DEFAULT_IMPORT_SOURCES = ['@mui/material/Stack', '@mui/material'];
+/** The attribute whose presence exempts, and the one the fixer writes. */
+const USE_FLEX_GAP = 'useFlexGap';
+/**
+ * The two `flex-wrap` values that put children on more than one line. Everything
+ * else — `nowrap`, the initial value, an unresolvable expression — leaves a
+ * single line, where margin-based spacing renders correctly.
+ */
+const WRAPPING_VALUES = new Set(['wrap', 'wrap-reverse']);
+/**
+ * `x as T`, `<T>x`, `x satisfies T` and `x!` assert a type about the expression
+ * they wrap without contributing a value, so a read that classifies the SHAPE or
+ * the VALUE of an expression must look through all four alike.
+ *
+ * This is load-bearing rather than defensive here: `global-const-style` rewrites
+ * hoisted style constants into `const ROW_SX = { ... } as const`, so the `sx`
+ * constants this rule resolves arrive assertion-wrapped and a resolver keyed on
+ * `ObjectExpression` alone goes silently quiet on them (#1805).
+ */
+const ASSERTION_EXPRESSION_TYPES = new Set([
+    utils_1.AST_NODE_TYPES.TSAsExpression,
+    utils_1.AST_NODE_TYPES.TSSatisfiesExpression,
+    utils_1.AST_NODE_TYPES.TSNonNullExpression,
+    utils_1.AST_NODE_TYPES.TSTypeAssertion,
+]);
+const isAssertionExpression = (node) => ASSERTION_EXPRESSION_TYPES.has(node.type);
+/** Peels every assertion wrapper, since assertions nest. */
+function unwrapAssertions(node) {
+    let target = node;
+    while (isAssertionExpression(target)) {
+        target = target.expression;
+    }
+    return target;
+}
+/**
+ * The component a deep import path names. `@mui/material/Stack` denotes `Stack`
+ * whatever the local binding is called, which is what separates the real import
+ * from the copy-paste defect `import Stack from '@mui/material/Typography'`.
+ */
+function finalSegmentOf(source) {
+    const segments = source.split('/').filter(Boolean);
+    return segments[segments.length - 1] ?? source;
+}
+exports.enforceUseFlexGapOnWrap = (0, createRule_1.createRule)({
+    name: 'enforce-use-flex-gap-on-wrap',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require `useFlexGap` on a MUI `Stack` that wraps and passes `spacing`, because margin-based spacing leaves the wrapped line with no row gap and a phantom leading indent',
+            recommended: 'error',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    stackComponents: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Component names treated as MUI Stack. A name here is checked only after its binding resolves to an allowed import source, so a local component that shadows the name is never flagged.',
+                    },
+                    importSources: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Import sources whose Stack binding this rule governs.',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            useFlexGapRequired: "`Stack` sets `flexWrap: 'wrap'` with margin-based `spacing`: the wrapped line gets no row gap and a phantom leading indent. Add `useFlexGap` to route `spacing` onto CSS `gap`.",
+        },
+    },
+    defaultOptions: [
+        {
+            stackComponents: DEFAULT_STACK_COMPONENTS,
+            importSources: DEFAULT_IMPORT_SOURCES,
+        },
+    ],
+    create(context, [options]) {
+        const stackComponents = new Set(options.stackComponents ?? DEFAULT_STACK_COMPONENTS);
+        const importSources = new Set(options.importSources ?? DEFAULT_IMPORT_SOURCES);
+        const sourceCode = context.getSourceCode();
+        /**
+         * The single expression a name is initialized with, or undefined when the
+         * name is not a write-once local. Resolution walks the real scope chain, so
+         * a module constant read from inside a component is found while a parameter
+         * or any other inner binding of the same name shadows it correctly.
+         *
+         * A name written more than once does not denote its initializer, so
+         * following it would trade a conservative miss for a wrong answer.
+         */
+        function initializerOf(node) {
+            const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, node.name);
+            if (!variable || variable.defs.length !== 1) {
+                return undefined;
+            }
+            const [definition] = variable.defs;
+            if (definition.node.type !== utils_1.AST_NODE_TYPES.VariableDeclarator ||
+                !definition.node.init) {
+                return undefined;
+            }
+            return unwrapAssertions(definition.node.init);
+        }
+        /** Whether one import binding is MUI's `Stack` under the configured sets. */
+        function bindsMuiStack(definition) {
+            const declaration = definition.parent;
+            if (!declaration ||
+                declaration.type !== utils_1.AST_NODE_TYPES.ImportDeclaration ||
+                typeof declaration.source.value !== 'string' ||
+                !importSources.has(declaration.source.value)) {
+                return false;
+            }
+            const specifier = definition.node;
+            if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier) {
+                const { imported } = specifier;
+                return (imported.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    stackComponents.has(imported.name));
+            }
+            if (specifier.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier) {
+                // The PATH names the component for a default import, which is what makes
+                // `import Stack from '@mui/material/Typography'` a non-match.
+                return stackComponents.has(finalSegmentOf(declaration.source.value));
+            }
+            // A namespace import is reached as `<Mui.Stack>`, a member expression this
+            // rule does not visit.
+            return false;
+        }
+        /**
+         * Whether the element name denotes MUI's `Stack` at this point in the file.
+         * Every definition must qualify: a name bound both by an import and by a
+         * local declaration is not provably the import at the use site.
+         */
+        function resolvesToMuiStack(node) {
+            const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);
+            const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, node.name);
+            if (!variable || variable.defs.length === 0) {
+                return false;
+            }
+            return variable.defs.every(bindsMuiStack);
+        }
+        /** The expression an attribute carries, or undefined for a bare attribute. */
+        function attributeValueOf(attribute) {
+            const { value } = attribute;
+            if (!value) {
+                return undefined;
+            }
+            if (value.type === utils_1.AST_NODE_TYPES.Literal) {
+                return value;
+            }
+            if (value.type === utils_1.AST_NODE_TYPES.JSXExpressionContainer) {
+                const expression = unwrapAssertions(value.expression);
+                return expression.type === utils_1.AST_NODE_TYPES.JSXEmptyExpression
+                    ? undefined
+                    : expression;
+            }
+            return undefined;
+        }
+        /** The static name of an object property key, or undefined when computed. */
+        function propertyNameOf(property) {
+            const key = unwrapAssertions(property.key);
+            if (key.type === utils_1.AST_NODE_TYPES.Identifier && !property.computed) {
+                return key.name;
+            }
+            if (key.type === utils_1.AST_NODE_TYPES.Literal) {
+                return typeof key.value === 'string' ? key.value : undefined;
+            }
+            return undefined;
+        }
+        /**
+         * Whether a `flexWrap` value puts children on more than one line.
+         *
+         * A responsive object answers true when ANY breakpoint wraps: the seam is
+         * real at that width, and the rule deliberately does not reconcile a
+         * responsive `flexWrap` against a responsive `spacing` breakpoint by
+         * breakpoint.
+         */
+        function wrapVerdict(node, seen) {
+            if (!node) {
+                return undefined;
+            }
+            const target = unwrapAssertions(node);
+            switch (target.type) {
+                case utils_1.AST_NODE_TYPES.Literal:
+                    return typeof target.value === 'string'
+                        ? WRAPPING_VALUES.has(target.value)
+                        : undefined;
+                case utils_1.AST_NODE_TYPES.TemplateLiteral:
+                    return target.expressions.length === 0
+                        ? WRAPPING_VALUES.has(target.quasis[0]?.value.cooked ?? '')
+                        : undefined;
+                case utils_1.AST_NODE_TYPES.Identifier: {
+                    if (seen.has(target)) {
+                        return undefined;
+                    }
+                    seen.add(target);
+                    return wrapVerdict(initializerOf(target), seen);
+                }
+                case utils_1.AST_NODE_TYPES.ObjectExpression: {
+                    let verdict = false;
+                    for (const property of target.properties) {
+                        const value = property.type === utils_1.AST_NODE_TYPES.SpreadElement
+                            ? wrapVerdict(property.argument, seen)
+                            : wrapVerdict(property.value, seen);
+                        if (value === true) {
+                            return true;
+                        }
+                        if (value === undefined) {
+                            verdict = undefined;
+                        }
+                    }
+                    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;
+                }
+                default:
+                    return undefined;
+            }
+        }
+        /** Whether an object literal states a wrapping `flexWrap`. */
+        function objectWraps(object, seen) {
+            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;
+                    }
+                    continue;
+                }
+                if (propertyNameOf(property) !== 'flexWrap') {
+                    continue;
+                }
+                if (wrapVerdict(property.value, seen) === true) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        /**
+         * 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.
+         */
+        function sxWraps(node, seen) {
+            if (!node) {
+                return false;
+            }
+            const target = unwrapAssertions(node);
+            switch (target.type) {
+                case utils_1.AST_NODE_TYPES.ObjectExpression:
+                    return objectWraps(target, seen);
+                case utils_1.AST_NODE_TYPES.Identifier: {
+                    if (seen.has(target)) {
+                        return false;
+                    }
+                    seen.add(target);
+                    return sxWraps(initializerOf(target), seen);
+                }
+                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 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);
+                default:
+                    // A call expression is opaque. Guessing at what it returns would
+                    // report on code the rule cannot read.
+                    return false;
+            }
+        }
+        /**
+         * Whether a `spacing` value is statically zero. The value is not interpreted
+         * further: `spacing={0}` exists precisely so an `sx` gap owns the rhythm,
+         * while every non-zero value emits the sibling margins this rule is about.
+         */
+        function isZeroSpacing(node, seen) {
+            if (!node) {
+                // A bare `spacing` attribute is not zero.
+                return false;
+            }
+            const target = unwrapAssertions(node);
+            if (target.type === utils_1.AST_NODE_TYPES.Literal) {
+                return target.value === 0 || target.value === '0';
+            }
+            if (target.type === utils_1.AST_NODE_TYPES.Identifier) {
+                if (seen.has(target)) {
+                    return false;
+                }
+                seen.add(target);
+                return isZeroSpacing(initializerOf(target), seen);
+            }
+            return false;
+        }
+        /**
+         * The whitespace run that ends the gap before a node, reused so the inserted
+         * attribute lands in the layout the author (and prettier) already chose.
+         * Only the whitespace is copied: a comment can sit between two attributes,
+         * and carrying the whole gap would duplicate it.
+         */
+        function separatorBefore(node) {
+            const previous = sourceCode.getTokenBefore(node, {
+                includeComments: true,
+            });
+            const gap = previous
+                ? sourceCode.text.slice(previous.range[1], node.range[0])
+                : ' ';
+            const trailing = /\s*$/.exec(gap)?.[0] ?? '';
+            const lastBreak = trailing.lastIndexOf('\n');
+            return lastBreak === -1 ? ' ' : `\n${trailing.slice(lastBreak + 1)}`;
+        }
+        /**
+         * Inserts the bare `useFlexGap` attribute in alphabetical position, which is
+         * how this codebase orders JSX attributes: appending at the end would land a
+         * second lint error on top of the fix.
+         *
+         * The insert joins the run of named attributes FOLLOWING the last spread. A
+         * spread can carry `useFlexGap` of its own, and JSX resolves the later
+         * writer, so writing after it is what makes the fix take effect.
+         */
+        function insertUseFlexGap(fixer, node) {
+            const { attributes } = node;
+            if (attributes.length === 0) {
+                return null;
+            }
+            let groupStart = 0;
+            attributes.forEach((attribute, index) => {
+                if (attribute.type === utils_1.AST_NODE_TYPES.JSXSpreadAttribute) {
+                    groupStart = index + 1;
+                }
+            });
+            const successor = attributes
+                .slice(groupStart)
+                .find((attribute) => attribute.type === utils_1.AST_NODE_TYPES.JSXAttribute &&
+                attribute.name.type === utils_1.AST_NODE_TYPES.JSXIdentifier &&
+                attribute.name.name > USE_FLEX_GAP);
+            if (successor) {
+                return fixer.insertTextBefore(successor, `${USE_FLEX_GAP}${separatorBefore(successor)}`);
+            }
+            const last = attributes[attributes.length - 1];
+            return fixer.insertTextAfter(last, `${separatorBefore(last)}${USE_FLEX_GAP}`);
+        }
+        return {
+            JSXOpeningElement(node) {
+                const elementName = node.name;
+                if (elementName.type !== utils_1.AST_NODE_TYPES.JSXIdentifier) {
+                    return;
+                }
+                if (!stackComponents.has(elementName.name)) {
+                    return;
+                }
+                const named = new Map();
+                for (const attribute of node.attributes) {
+                    if (attribute.type === utils_1.AST_NODE_TYPES.JSXAttribute &&
+                        attribute.name.type === utils_1.AST_NODE_TYPES.JSXIdentifier) {
+                        named.set(attribute.name.name, attribute);
+                    }
+                }
+                // Whatever else it sets, an element that already states the pairing is
+                // compliant — including an explicit opt-out, which is a decision rather
+                // than an oversight.
+                if (named.has(USE_FLEX_GAP)) {
+                    return;
+                }
+                // `spacing` is the trigger, never the absence of a gap. A wrapping Stack
+                // that reaches past `useFlexGap` for `rowGap` or an `sx` `gap` buys some
+                // separation and leaves the phantom indent in place, so neither shape
+                // can exempt.
+                const spacing = named.get('spacing');
+                if (!spacing || isZeroSpacing(attributeValueOf(spacing), new Set())) {
+                    return;
+                }
+                const flexWrap = named.get('flexWrap');
+                const attributeVerdict = flexWrap
+                    ? wrapVerdict(attributeValueOf(flexWrap), new Set())
+                    : undefined;
+                const sx = named.get('sx');
+                // 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) {
+                    return;
+                }
+                if (!resolvesToMuiStack(elementName)) {
+                    return;
+                }
+                context.report({
+                    node: elementName,
+                    messageId: 'useFlexGapRequired',
+                    fix: (fixer) => insertUseFlexGap(fixer, node),
+                });
+            },
+        };
+    },
+});
+//# sourceMappingURL=enforce-use-flex-gap-on-wrap.js.map

package/lib/rules/enforce-verb-noun-naming.js

@@ -372,6 +372,7 @@ const ALLOWLIST = {
         'bottle',
         'bottom',
         'bounce',
+        'bound',
         'bow',
         'box',
         'boycott',
@@ -1126,6 +1127,7 @@ const ALLOWLIST = {
         'electron',
         'elevate',
         'elicit',
+        'elide',
         'eliminate',
         'elongate',
         'emancipate',

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

@@ -407,6 +407,64 @@ const sxSlotOf = (sxAttr) => {
     }
     return { kind: 'spread', expression: value };
 };
+/**
+ * The property names an `sx` object literal declares, or null when one of its
+ * keys is not statically readable. A computed key built from anything but a
+ * literal resolves to a name only at runtime, so it is reported as unknown
+ * rather than as no key at all, and the caller reads that as a possible
+ * collision with every moved prop.
+ *
+ * A spread's own members are deliberately not counted: the moved props are
+ * spliced in as new members of this literal, and a name the spread happens to
+ * carry is not duplicated by that splice — it is overridden, exactly as any
+ * other member written beside the spread overrides it.
+ */
+const declaredKeysOf = (object) => {
+    const keys = new Set();
+    for (const property of object.properties) {
+        if (property.type !== utils_1.AST_NODE_TYPES.Property) {
+            continue;
+        }
+        const { key } = property;
+        if (!property.computed && key.type === utils_1.AST_NODE_TYPES.Identifier) {
+            keys.add(key.name);
+            continue;
+        }
+        // A literal key is readable whether or not it is written computed:
+        // `'display'` and `['display']` both name the same property.
+        if (key.type === utils_1.AST_NODE_TYPES.Literal &&
+            (typeof key.value === 'string' || typeof key.value === 'number')) {
+            keys.add(String(key.value));
+            continue;
+        }
+        return null;
+    }
+    return keys;
+};
+/**
+ * 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).
+ *
+ * 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.
+ */
+const collidingPropsOf = (systemPropAttrs, sxAttr) => {
+    const slot = sxSlotOf(sxAttr);
+    if (slot.kind !== 'object') {
+        return new Set();
+    }
+    const declared = declaredKeysOf(slot.object);
+    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)));
+};
 /**
  * Plans every edit the autofix makes for one JSX element.
  *
@@ -1000,9 +1058,16 @@ exports.preferSxPropOverSystemProps = (0, createRule_1.createRule)({
                 if (systemPropAttrs.length === 0)
                     return;
                 const sourceCode = context.getSourceCode();
-                // Report each system prop. Only the first carries the fixer to avoid
-                // overlapping fix ranges on the same element.
-                systemPropAttrs.forEach((attr, index) => {
+                // 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.
+                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
+                // to avoid overlapping fix ranges on the same element.
+                const fixAnchor = fixableAttrs[0] ?? null;
+                systemPropAttrs.forEach((attr) => {
                     const propName = attr.name.type === utils_1.AST_NODE_TYPES.JSXIdentifier
                         ? attr.name.name
                         : '';
@@ -1010,8 +1075,8 @@ exports.preferSxPropOverSystemProps = (0, createRule_1.createRule)({
                         node: attr,
                         messageId: 'preferSxProp',
                         data: { prop: propName },
-                        fix: index === 0
-                            ? (fixer) => planSxEdits(sourceCode, node, systemPropAttrs, sxAttr, printWidth).map((edit) => fixer.replaceTextRange(edit.range, edit.text))
+                        fix: attr === fixAnchor
+                            ? (fixer) => planSxEdits(sourceCode, node, fixableAttrs, sxAttr, printWidth).map((edit) => fixer.replaceTextRange(edit.range, edit.text))
                             : null,
                     });
                 });

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "1.21.0",
+    "date": "2026-09-02T18:04:18.331Z",
+    "rules": [
+      {
+        "name": "enforce-use-flex-gap-on-wrap",
+        "changeType": "feat",
+        "issues": [
+          2289
+        ],
+        "summary": "flag a wrapping Stack that spaces with spacing but omits useFlexGap (closes #2289)"
+      },
+      {
+        "name": "enforce-verb-noun-naming",
+        "changeType": "fix",
+        "issues": [
+          2295
+        ],
+        "summary": "admit elide and bound as verbs (closes #2295)"
+      },
+      {
+        "name": "prefer-sx-prop-over-system-props",
+        "changeType": "fix",
+        "issues": [
+          2296
+        ],
+        "summary": "decline the fix when the sx literal already declares the moved key (closes #2296)"
+      }
+    ]
+  },
   {
     "version": "1.20.202",
     "date": "2026-09-02T04:11:09.443Z",