@blumintinc/eslint-plugin-blumint 1.21.17 → 1.22.0

package/lib/index.js

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

package/lib/rules/enforce-empty-object-check.d.ts

@@ -1,9 +1,23 @@
 import { TSESLint } from '@typescript-eslint/utils';
+/**
+ * The emptiness call the fixer emits, and where its binding comes from.
+ *
+ * Recognition and EMISSION are separate settings on purpose. `emptyCheckFunctions`
+ * is an allowlist of spellings the rule accepts and carries no import path, so
+ * reusing it to emit would write a bare call to an identifier the file does not
+ * import, and — since it defaults to `isEmpty` — would silently change what every
+ * existing consumer's `--fix` produces (#2360).
+ */
+type EmptyCheckFix = {
+    name: string;
+    importPath?: string;
+};
 type Options = [
     {
         objectNamePattern?: string[];
         ignoreInLoops?: boolean;
         emptyCheckFunctions?: string[];
+        emptyCheckFix?: EmptyCheckFix;
         printWidth?: number;
     }
 ];

package/lib/rules/enforce-empty-object-check.js

@@ -28,6 +28,7 @@ const utils_1 = require("@typescript-eslint/utils");
 const ts = __importStar(require("typescript"));
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+const importInsertion_1 = require("../utils/importInsertion");
 const DEFAULT_OBJECT_SUFFIXES = [
     'Config',
     'Configs',
@@ -79,6 +80,20 @@ const NON_OBJECT_LIKE_NAMES = [
     'array',
     'arr',
 ];
+/**
+ * The emptiness operand the fixer writes beside the falsiness check.
+ *
+ * `Object.keys(...).length === 0` needs nothing in scope, so it stays the
+ * default and every consumer that has not opted in keeps byte-identical output.
+ * A consumer whose config BANS the `Object` accessors names a helper instead,
+ * without which `--fix` has no fixed point: the rewrite it just wrote is
+ * rejected by the same run that produced it (#2360).
+ */
+function buildEmptyCheckText(identifierText, emptyCheckFix) {
+    return emptyCheckFix
+        ? `${emptyCheckFix.name}(${identifierText})`
+        : `Object.keys(${identifierText}).length === 0`;
+}
 function hasBooleanPrefixBoundary(name) {
     const lower = name.toLowerCase();
     return BOOLEAN_PREFIXES.some((prefix) => {
@@ -1163,7 +1178,7 @@ function getDeclarationStatement(declaration) {
  * width was measured (#2095).
  */
 function planWidenedFix(input) {
-    const { sourceCode, target, identifierText, needsParentheses } = input;
+    const { sourceCode, target, identifierText, emptyCheckText, needsParentheses, } = input;
     const source = sourceCode.getText();
     const root = getLayoutRoot(target);
     const parent = root.parent;
@@ -1175,7 +1190,7 @@ function planWidenedFix(input) {
         operator: '||',
         parts: [
             { kind: 'leaf', text: `${target.operator}${identifierText}` },
-            { kind: 'leaf', text: `Object.keys(${identifierText}).length === 0` },
+            { kind: 'leaf', text: emptyCheckText },
         ],
     };
     const docContext = {
@@ -1514,6 +1529,150 @@ function planReturnFix(root, parent, flat, doc, { sourceCode, printWidth }, sour
     }
     return { range: [root.range[0], root.range[1]], text: lines.join('\n') };
 }
+/** Every name a binding pattern introduces. */
+function collectPatternNames(pattern, names) {
+    switch (pattern.type) {
+        case utils_1.AST_NODE_TYPES.Identifier:
+            names.add(pattern.name);
+            return;
+        case utils_1.AST_NODE_TYPES.ObjectPattern:
+            for (const property of pattern.properties) {
+                collectPatternNames(property.type === utils_1.AST_NODE_TYPES.RestElement
+                    ? property.argument
+                    : property.value, names);
+            }
+            return;
+        case utils_1.AST_NODE_TYPES.ArrayPattern:
+            for (const element of pattern.elements) {
+                if (element) {
+                    collectPatternNames(element, names);
+                }
+            }
+            return;
+        case utils_1.AST_NODE_TYPES.AssignmentPattern:
+            collectPatternNames(pattern.left, names);
+            return;
+        case utils_1.AST_NODE_TYPES.RestElement:
+            collectPatternNames(pattern.argument, names);
+            return;
+        default:
+    }
+}
+/**
+ * The names already declared at the module's top level.
+ *
+ * An import is only safe to insert when the name is free: a second binding of a
+ * name the file already declares — imported from anywhere, or declared locally —
+ * is a redeclaration error, which is a worse outcome than the lint warning the
+ * insertion was meant to avoid.
+ */
+function moduleBindingNames(program) {
+    const names = new Set();
+    for (const statement of program.body) {
+        const node = statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+            statement.type === utils_1.AST_NODE_TYPES.ExportDefaultDeclaration
+            ? statement.declaration
+            : statement;
+        if (!node) {
+            continue;
+        }
+        if (node.type === utils_1.AST_NODE_TYPES.ImportDeclaration) {
+            for (const specifier of node.specifiers) {
+                names.add(specifier.local.name);
+            }
+            continue;
+        }
+        if (node.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
+            for (const declarator of node.declarations) {
+                collectPatternNames(declarator.id, names);
+            }
+            continue;
+        }
+        if ((node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+            node.type === utils_1.AST_NODE_TYPES.ClassDeclaration ||
+            node.type === utils_1.AST_NODE_TYPES.TSEnumDeclaration ||
+            node.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration ||
+            node.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
+            node.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration ||
+            node.type === utils_1.AST_NODE_TYPES.TSDeclareFunction ||
+            node.type === utils_1.AST_NODE_TYPES.TSImportEqualsDeclaration) &&
+            node.id?.type === utils_1.AST_NODE_TYPES.Identifier) {
+            names.add(node.id.name);
+        }
+    }
+    return names;
+}
+/** A module specifier written as source text, with its quotes escaped. */
+function quoteModuleSpecifier(importPath) {
+    return `'${importPath.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/**
+ * The edit that brings the emitted helper into scope, or null when nothing is
+ * needed.
+ *
+ * A helper call the file cannot resolve trades a lint warning for an undefined
+ * identifier, so emission and import travel together in ONE fixer. Four
+ * outcomes are distinguished, because they are four different mistakes:
+ *
+ * * the name is already bound — insert nothing, whatever path it came from,
+ *   since a second binding would not compile;
+ * * a value import from the same path already has a named-specifier list — join
+ *   it, so the file keeps one declaration per module;
+ * * a file with imports gains a declaration after the LAST of them, which is
+ *   past every prologue by construction;
+ * * a file with none defers to `importInsertion`, whose anchor owns the
+ *   placement a raw offset gets wrong: a `'use client'` demoted out of the
+ *   prologue, a `#!` pushed off line 1, or a line-binding suppression comment
+ *   severed from the line it covers.
+ */
+function planImportInsertion(sourceCode, emptyCheckFix) {
+    const { name, importPath } = emptyCheckFix;
+    if (!importPath) {
+        return null;
+    }
+    const program = sourceCode.ast;
+    if (moduleBindingNames(program).has(name)) {
+        return null;
+    }
+    const imports = program.body.filter((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
+    for (const declaration of imports) {
+        /** A type-only import carries no value binding for the call to resolve. */
+        if (declaration.importKind === 'type' ||
+            declaration.source.value !== importPath) {
+            continue;
+        }
+        const specifiers = declaration.specifiers.filter((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier);
+        const last = specifiers[specifiers.length - 1];
+        if (!last) {
+            continue;
+        }
+        /**
+         * A specifier list Prettier has already broken keeps one name per row, so
+         * joining it inline would emit a layout the next format run undoes.
+         */
+        const indent = declaration.loc.start.line === declaration.loc.end.line
+            ? null
+            : getLineIndent(last, sourceCode);
+        const text = indent === null ? `, ${name}` : `,\n${indent}${name}`;
+        return {
+            offset: last.range[1],
+            apply: (fixer) => fixer.insertTextAfter(last, text),
+        };
+    }
+    const statement = `import { ${name} } from ${quoteModuleSpecifier(importPath)};`;
+    const lastImport = imports[imports.length - 1];
+    if (lastImport) {
+        return {
+            offset: lastImport.range[1],
+            apply: (fixer) => fixer.insertTextAfter(lastImport, `\n${statement}`),
+        };
+    }
+    const anchor = (0, importInsertion_1.importInsertionAnchor)(sourceCode);
+    return {
+        offset: anchor.kind === 'before' ? anchor.target.range[0] : anchor.index,
+        apply: (fixer) => (0, importInsertion_1.insertAtImportAnchor)(sourceCode, fixer, anchor, `${statement}\n`),
+    };
+}
 exports.enforceEmptyObjectCheck = (0, createRule_1.createRule)({
     name: 'enforce-empty-object-check',
     meta: {
@@ -1538,6 +1697,20 @@ exports.enforceEmptyObjectCheck = (0, createRule_1.createRule)({
                         type: 'array',
                         items: { type: 'string' },
                     },
+                    emptyCheckFix: {
+                        type: 'object',
+                        properties: {
+                            /**
+                             * A bare identifier, so the emitted call is the shape the
+                             * recognition arm accepts — anything else would leave `--fix`
+                             * rewriting text it reports again on the next pass.
+                             */
+                            name: { type: 'string', pattern: '^[A-Za-z_$][A-Za-z0-9_$]*$' },
+                            importPath: { type: 'string', minLength: 1 },
+                        },
+                        required: ['name'],
+                        additionalProperties: false,
+                    },
                     printWidth: {
                         type: 'number',
                         minimum: 1,
@@ -1556,7 +1729,7 @@ exports.enforceEmptyObjectCheck = (0, createRule_1.createRule)({
         const parserServices = sourceCode.parserServices;
         const checker = parserServices?.program?.getTypeChecker();
         const options = context.options[0] ?? {};
-        const { objectNamePattern = [], ignoreInLoops = false, emptyCheckFunctions = [], } = options;
+        const { objectNamePattern = [], ignoreInLoops = false, emptyCheckFunctions = [], emptyCheckFix, } = options;
         const printWidth = typeof options.printWidth === 'number' && options.printWidth > 0
             ? options.printWidth
             : DEFAULT_PRINT_WIDTH;
@@ -1564,9 +1737,16 @@ exports.enforceEmptyObjectCheck = (0, createRule_1.createRule)({
             ...DEFAULT_OBJECT_SUFFIXES,
             ...objectNamePattern,
         ]);
+        /**
+         * The emitted helper counts as a satisfying check even when it is absent
+         * from `emptyCheckFunctions`. Without this the fixer would report its own
+         * output, so `--fix` would rewrite the same guard on every pass — the
+         * fixed point this option exists to restore (#2360).
+         */
         const emptyCheckFunctionsSet = new Set([
             ...DEFAULT_EMPTY_CHECK_FUNCTIONS,
             ...emptyCheckFunctions,
+            ...(emptyCheckFix ? [emptyCheckFix.name] : []),
         ]);
         const processedExpressions = new WeakSet();
         const processedNegations = new WeakSet();
@@ -1883,6 +2063,31 @@ exports.enforceEmptyObjectCheck = (0, createRule_1.createRule)({
             }
             return isObjectLikeName(identifier.name, patternSet);
         }
+        /**
+         * Whether a binding between the report site and the module scope would
+         * capture the emitted helper call.
+         *
+         * A bare call resolves wherever the CALL sits, so an inner binding of the
+         * same name silently takes it over — the rewrite compiles, reads
+         * correctly, and calls something else entirely (#1455, #1456 are this
+         * shape). No spelling of the call escapes that, so the fix is declined
+         * and the report stands on its own; the message already says what to
+         * write.
+         *
+         * The unconfigured emission is untouched by this: `Object` is a global
+         * rather than a module binding, and its output is a compatibility
+         * contract (#2360).
+         */
+        function emissionIsShadowed(node, name) {
+            let scope = ASTHelpers_1.ASTHelpers.getScope(context, node);
+            while (scope) {
+                if (scope.variables.some((variable) => variable.name === name)) {
+                    return scope.type !== 'module' && scope.type !== 'global';
+                }
+                scope = scope.upper;
+            }
+            return false;
+        }
         function reportNegation(node, identifier) {
             if (processedNegations.has(node)) {
                 return;
@@ -1906,8 +2111,12 @@ exports.enforceEmptyObjectCheck = (0, createRule_1.createRule)({
                     name: identifier.name,
                 },
                 fix(fixer) {
+                    if (emptyCheckFix && emissionIsShadowed(node, emptyCheckFix.name)) {
+                        return null;
+                    }
                     const identifierText = sourceCode.getText(identifier);
-                    const guard = `${node.operator}${identifierText} || Object.keys(${identifierText}).length === 0`;
+                    const emptyCheckText = buildEmptyCheckText(identifierText, emptyCheckFix);
+                    const guard = `${node.operator}${identifierText} || ${emptyCheckText}`;
                     const needsParentheses = replacementNeedsParentheses(node, sourceCode);
                     const replacement = needsParentheses ? `(${guard})` : guard;
                     /**
@@ -1923,13 +2132,27 @@ exports.enforceEmptyObjectCheck = (0, createRule_1.createRule)({
                         sourceCode,
                         target: node,
                         identifierText,
+                        emptyCheckText,
                         needsParentheses,
                         printWidth,
                     });
-                    if (widened) {
-                        return fixer.replaceTextRange(widened.range, widened.text);
+                    const guardEdit = widened ?? {
+                        range: node.range,
+                        text: replacement,
+                    };
+                    const importFix = emptyCheckFix
+                        ? planImportInsertion(sourceCode, emptyCheckFix)
+                        : null;
+                    if (!importFix) {
+                        return fixer.replaceTextRange(guardEdit.range, guardEdit.text);
                     }
-                    return fixer.replaceText(node, replacement);
+                    const guardFix = {
+                        offset: guardEdit.range[0],
+                        apply: (target) => target.replaceTextRange(guardEdit.range, guardEdit.text),
+                    };
+                    return [importFix, guardFix]
+                        .sort((left, right) => left.offset - right.offset)
+                        .map((edit) => edit.apply(fixer));
                 },
             });
         }

package/lib/rules/no-compositing-layer-props.d.ts

@@ -1 +1,8 @@
-export declare const noCompositingLayerProps: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"compositingLayer", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+type Options = [
+    {
+        exemptInteractionStates?: boolean;
+        exemptStateTransitions?: boolean;
+    }
+];
+export declare const noCompositingLayerProps: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"compositingLayer", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};

package/lib/rules/no-compositing-layer-props.js

@@ -15,6 +15,10 @@ function normalizePropertyName(name) {
     // Convert camelCase to kebab-case
     return toKebabCase(name).toLowerCase();
 }
+// `scale`, `rotate` and `translate` are the individual transform properties.
+// They promote a layer exactly as `transform` does, so leaving them out would
+// let a declaration the exemptions below refuse under `transform` through
+// under another spelling.
 const COMPOSITING_PROPERTIES = new Set([
     'filter',
     'backdrop-filter',
@@ -25,6 +29,21 @@ const COMPOSITING_PROPERTIES = new Set([
     'contain',
     'mix-blend-mode',
     'opacity',
+    'scale',
+    'rotate',
+    'translate',
+]);
+// The only properties the interaction-state and state-transition exemptions
+// may clear. Every other compositing property (`filter`, `backdrop-filter`,
+// `will-change`, `mix-blend-mode`, `perspective`, `backface-visibility`,
+// `contain`) stays reported in every context: none of them is the cheap,
+// compositor-only animation the exemptions exist to allow.
+const EXEMPTABLE_PROPERTIES = new Set([
+    'transform',
+    'opacity',
+    'scale',
+    'rotate',
+    'translate',
 ]);
 // Vendor-prefixed spellings name the same CSS property as their unprefixed
 // counterpart: `WebkitTransform` normalizes to `-webkit-transform`, `msTransform`
@@ -32,13 +51,10 @@ const COMPOSITING_PROPERTIES = new Set([
 function stripVendorPrefix(normalizedName) {
     return normalizedName.replace(/^-?(?:webkit|moz|ms|o)-/, '');
 }
-// 3D transform functions promote a layer, but only when applied through a
-// property whose value grammar accepts a transform function.
-const COMPOSITING_TRANSFORM_FUNCTIONS = [
-    'translate3d',
-    'scale3d',
-    'translateZ',
-];
+// 3D transform functions promote a layer on their own, whatever state the
+// element is in, so they are never exempt. Matched case-insensitively and only
+// as a function call, so a class name or prose containing the word is inert.
+const THREE_D_TRANSFORM_FUNCTION = /\b(?:translate3d|translatez|scale3d|scalez|rotate3d|rotatex|rotatey|rotatez|matrix3d|perspective)\s*\(/i;
 // `transform` is the only property that takes a transform function as its
 // value, so it is the whole key gate for the value-driven arm. A value can only
 // act through a property that accepts it; ungated, any key at all was named as
@@ -58,6 +74,9 @@ const NON_COMPOSITING_VALUES = {
     filter: new Set(['none']),
     'backdrop-filter': new Set(['none']),
     transform: new Set(['none']),
+    scale: new Set(['none', '1']),
+    rotate: new Set(['none']),
+    translate: new Set(['none']),
     contain: new Set(['none']),
     perspective: new Set(['none']),
     'will-change': new Set(['auto', 'unset', 'initial', 'inherit', 'revert']),
@@ -67,6 +86,461 @@ const NON_COMPOSITING_VALUES = {
     // it. `inherit` is excluded: it can resolve to a blending value set higher up.
     'mix-blend-mode': new Set(['normal', 'initial', 'unset', 'revert']),
 };
+// Stands in for the element the style object applies to while nested selector
+// keys are composed, so "on the `&` compound or to its right" is decidable
+// after `&` has been substituted away.
+const ROOT_MARKER = '\u0000';
+// Stands in for an interpolated `${...}` inside a selector key. It matches no
+// qualifier pattern, so an unreadable fragment can never qualify a selector.
+const INTERPOLATION_MARKER = '\u0001';
+// A pseudo-class or class that one element holds at a time (the pointer's
+// target, the pressed element, the focused element, and their ancestors). A
+// transform under it can never promote a whole list at once.
+const INTERACTION_PSEUDO_CLASS = /:(?:hover|active|focus|focus-visible|focus-within)(?![\w-])/i;
+const INTERACTION_MUI_CLASS = /\.Mui-(?:focusVisible|focused|active)(?![\w-])/;
+// A qualifier that flips at runtime rather than describing a static variant:
+// MUI's global state classes (`.Mui-checked`, `.Mui-expanded`, ...), state
+// pseudo-classes, and ARIA/data/boolean state attributes.
+const STATE_PSEUDO_CLASS = /:(?:hover|active|focus|focus-visible|focus-within|checked|disabled|enabled|indeterminate|open|popover-open|target|visited|invalid|valid|user-invalid|user-valid|placeholder-shown|autofill|read-only|read-write|fullscreen)(?![\w-])/i;
+const STATE_MUI_CLASS = /\.Mui-[a-z][\w]*(?![\w-])/;
+const STATE_ATTRIBUTE = /\[\s*(?:aria-[\w-]+|data-[\w-]+|open|hidden|disabled|checked|selected)\s*(?:[~|^$*]?=[^\]]*)?\]/i;
+const TRANSITION_PROPERTIES = new Set(['transition', 'transition-property']);
+const TRANSITION_TIME = /^[+-]?(?:\d+\.?\d*|\.\d+)m?s$/;
+const BARE_NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)$/;
+const TRANSITION_KEYWORDS = new Set([
+    'ease',
+    'ease-in',
+    'ease-out',
+    'ease-in-out',
+    'linear',
+    'step-start',
+    'step-end',
+    'normal',
+    'allow-discrete',
+]);
+const GLOBAL_KEYWORDS = new Set([
+    'inherit',
+    'initial',
+    'unset',
+    'revert',
+    'revert-layer',
+]);
+// Lexical iteration: a state-driven transform declared inside one of these
+// callbacks styles every rendered sibling, and many siblings can be "on" at
+// once, so the state-transition exemption is withheld there.
+const ITERATION_METHODS = new Set(['map', 'flatMap', 'forEach']);
+// Render props the host calls once per item. Every `render*` prop is treated
+// as one because the rule cannot tell `renderOption` from `renderInput`, and
+// withholding the exemption only keeps the pre-existing report.
+const ITEM_RENDER_PROP = /^(?:render[A-Z0-9_]\w*|itemContent|\w+Renderer)$/;
+// A template literal with no substitutions spells a literal exactly, so it is
+// read as one; any other non-literal value is unreadable (`null`).
+function readStaticText(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.Literal) {
+        return String(node.value);
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.TemplateLiteral &&
+        node.expressions.length === 0) {
+        return node.quasis[0].value.cooked ?? node.quasis[0].value.raw;
+    }
+    return null;
+}
+// Every literal fragment an expression can evaluate to or embed, so a 3D
+// transform function is found even inside a ternary or an interpolation.
+function collectStaticFragments(node) {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.Literal:
+            return typeof node.value === 'string' ? [node.value] : [];
+        case utils_1.AST_NODE_TYPES.TemplateLiteral:
+            return [
+                ...node.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw),
+                ...node.expressions.flatMap(collectStaticFragments),
+            ];
+        case utils_1.AST_NODE_TYPES.ConditionalExpression:
+            return [
+                ...collectStaticFragments(node.consequent),
+                ...collectStaticFragments(node.alternate),
+            ];
+        case utils_1.AST_NODE_TYPES.LogicalExpression:
+            return [
+                ...collectStaticFragments(node.left),
+                ...collectStaticFragments(node.right),
+            ];
+        case utils_1.AST_NODE_TYPES.TSAsExpression:
+        case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+        case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+        case utils_1.AST_NODE_TYPES.TSTypeAssertion:
+            return collectStaticFragments(node.expression);
+        default:
+            return [];
+    }
+}
+// Strip `!important` and normalize casing so reset/identity values written
+// as e.g. `none !important` are still recognized as non-promoting.
+function normalizePropertyValue(value) {
+    return value
+        .replace(/\s*!important\s*$/i, '')
+        .trim()
+        .toLowerCase();
+}
+// Splits on `separator` only outside parentheses, brackets and quotes, so
+// `cubic-bezier(0.4, 0, 0.2, 1)` and `:is(a, b)` stay whole.
+function splitTopLevel(text, isSeparator) {
+    const parts = [];
+    let depth = 0;
+    let quote = null;
+    let current = '';
+    for (const ch of text) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === '(' || ch === '[') {
+            depth += 1;
+        }
+        else if (ch === ')' || ch === ']') {
+            depth -= 1;
+        }
+        else if (depth === 0 && isSeparator(ch)) {
+            if (current.trim())
+                parts.push(current.trim());
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    return parts;
+}
+// Individual transform properties take a 3D form through their value grammar
+// rather than a function: a third `translate`/`scale` component, or a
+// `rotate` axis.
+function isThreeDLiteral(propertyName, value) {
+    const tokens = splitTopLevel(normalizePropertyValue(value), (ch) => /\s/.test(ch));
+    if (propertyName === 'translate' || propertyName === 'scale') {
+        return tokens.length >= 3;
+    }
+    if (propertyName === 'rotate') {
+        return tokens.length >= 2;
+    }
+    return false;
+}
+// `:not(:hover)` matches every element that is NOT hovered, the opposite of
+// singular, so a negated qualifier must never count.
+function stripNegations(compound) {
+    let result = compound;
+    let start = result.search(/:not\(/i);
+    while (start !== -1) {
+        let depth = 0;
+        let end = start + ':not'.length;
+        for (; end < result.length; end += 1) {
+            if (result[end] === '(')
+                depth += 1;
+            if (result[end] === ')') {
+                depth -= 1;
+                if (depth === 0)
+                    break;
+            }
+        }
+        result = result.slice(0, start) + result.slice(end + 1);
+        start = result.search(/:not\(/i);
+    }
+    return result;
+}
+// The compounds of a composed selector from the one holding the styled
+// element rightward. A qualifier to the LEFT of that compound belongs to an
+// ancestor (`.MuiList-root:hover &`), which matches every child at once.
+function compoundsFromRoot(member) {
+    const compounds = splitTopLevel(member, (ch) => /[\s>+~]/.test(ch));
+    const rootIndex = compounds.findIndex((compound) => compound.includes(ROOT_MARKER));
+    return rootIndex === -1 ? [] : compounds.slice(rootIndex).map(stripNegations);
+}
+// Nested selector keys compose the way emotion composes them: `&` is replaced
+// by the parent selector, a key opening with `:` attaches to the parent
+// compound, and any other key is a descendant of it.
+function composeSelectors(selectors) {
+    let members = [ROOT_MARKER];
+    for (const selector of selectors) {
+        const next = [];
+        for (const member of splitTopLevel(selector, (ch) => ch === ',')) {
+            for (const parent of members) {
+                if (member.includes('&')) {
+                    next.push(member.split('&').join(parent));
+                }
+                else if (member.startsWith(':')) {
+                    next.push(`${parent}${member}`);
+                }
+                else {
+                    next.push(`${parent} ${member}`);
+                }
+            }
+        }
+        members = next;
+    }
+    return members;
+}
+function carriesInteraction(compound) {
+    return (INTERACTION_PSEUDO_CLASS.test(compound) ||
+        INTERACTION_MUI_CLASS.test(compound));
+}
+function carriesState(compound) {
+    return (carriesInteraction(compound) ||
+        STATE_PSEUDO_CLASS.test(compound) ||
+        STATE_MUI_CLASS.test(compound) ||
+        STATE_ATTRIBUTE.test(compound));
+}
+// Every comma-separated member of the composed selector must qualify: one
+// unqualified member applies the declaration at rest.
+function everyMemberQualifies(chain, qualifies) {
+    if (chain.hasUnreadableSelector || chain.selectors.length === 0) {
+        return false;
+    }
+    return composeSelectors(chain.selectors).every((member) => compoundsFromRoot(member).some(qualifies));
+}
+function readKeyName(key) {
+    if (key.type === utils_1.AST_NODE_TYPES.Identifier)
+        return key.name;
+    if (key.type === utils_1.AST_NODE_TYPES.Literal)
+        return String(key.value);
+    return null;
+}
+// `[theme.breakpoints.up('md')]` compiles to an `@media` query, so it is
+// skipped exactly as a literal `@media` key is.
+function isBreakpointKey(key) {
+    let current = key;
+    for (;;) {
+        switch (current.type) {
+            case utils_1.AST_NODE_TYPES.ChainExpression:
+                current = current.expression;
+                break;
+            case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+                current = current.expression;
+                break;
+            case utils_1.AST_NODE_TYPES.CallExpression:
+                current = current.callee;
+                break;
+            case utils_1.AST_NODE_TYPES.MemberExpression:
+                if (current.property.type === utils_1.AST_NODE_TYPES.Identifier &&
+                    current.property.name === 'breakpoints') {
+                    return true;
+                }
+                current = current.object;
+                break;
+            default:
+                return false;
+        }
+    }
+}
+function classifyKey(property) {
+    const { key } = property;
+    if (key.type === utils_1.AST_NODE_TYPES.Literal && typeof key.value === 'string') {
+        return /^\s*@/.test(key.value)
+            ? { kind: 'at-rule' }
+            : { kind: 'selector', selector: key.value };
+    }
+    if (key.type === utils_1.AST_NODE_TYPES.TemplateLiteral) {
+        const selector = key.quasis
+            .map((quasi) => quasi.value.cooked ?? quasi.value.raw)
+            .join(INTERPOLATION_MARKER);
+        return /^\s*@/.test(selector)
+            ? { kind: 'at-rule' }
+            : { kind: 'selector', selector };
+    }
+    if (property.computed) {
+        return isBreakpointKey(key)
+            ? { kind: 'at-rule' }
+            : { kind: 'unreadable-selector' };
+    }
+    // A bare identifier key (`root`, `sx`, `style`, a slot name) names the
+    // element being styled rather than a selector below it.
+    return { kind: 'boundary' };
+}
+// Object entries of an `sx` array element, looking through the conditional
+// wrappers MUI's array form is written with.
+function objectsOfArrayEntry(node) {
+    if (!node)
+        return [];
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.ObjectExpression:
+            return [node];
+        case utils_1.AST_NODE_TYPES.LogicalExpression:
+            return objectsOfArrayEntry(node.right);
+        case utils_1.AST_NODE_TYPES.ConditionalExpression:
+            return [
+                ...objectsOfArrayEntry(node.consequent),
+                ...objectsOfArrayEntry(node.alternate),
+            ];
+        case utils_1.AST_NODE_TYPES.TSAsExpression:
+        case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+            return objectsOfArrayEntry(node.expression);
+        default:
+            return [];
+    }
+}
+// Climbs from a declaration to the root of the style object it belongs to,
+// collecting what both exemptions read. The climb crosses only constructs that
+// keep it inside one style value; anything else (a call argument, a JSX
+// attribute, a variable declarator, a statement) ends it.
+function climbStyleChain(property) {
+    const selectorsInnerFirst = [];
+    const objects = [];
+    let hasUnreadableSelector = false;
+    let isConditional = false;
+    let child = property;
+    let current = property.parent;
+    climb: while (current) {
+        switch (current.type) {
+            case utils_1.AST_NODE_TYPES.ObjectExpression:
+                objects.push(current);
+                break;
+            case utils_1.AST_NODE_TYPES.ArrayExpression:
+                for (const element of current.elements) {
+                    if (element !== child)
+                        objects.push(...objectsOfArrayEntry(element));
+                }
+                break;
+            case utils_1.AST_NODE_TYPES.Property: {
+                if (current.value !== child)
+                    break climb;
+                const key = classifyKey(current);
+                if (key.kind === 'boundary')
+                    break climb;
+                if (key.kind === 'selector')
+                    selectorsInnerFirst.push(key.selector);
+                if (key.kind === 'unreadable-selector')
+                    hasUnreadableSelector = true;
+                break;
+            }
+            case utils_1.AST_NODE_TYPES.ConditionalExpression:
+                if (current.test === child)
+                    break climb;
+                isConditional = true;
+                break;
+            case utils_1.AST_NODE_TYPES.LogicalExpression:
+                isConditional = true;
+                break;
+            case utils_1.AST_NODE_TYPES.ArrowFunctionExpression:
+                if (current.body !== child)
+                    break climb;
+                break;
+            case utils_1.AST_NODE_TYPES.SpreadElement:
+            case utils_1.AST_NODE_TYPES.TSAsExpression:
+            case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+            case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+            case utils_1.AST_NODE_TYPES.TSTypeAssertion:
+                break;
+            default:
+                break climb;
+        }
+        child = current;
+        current = current.parent;
+    }
+    return {
+        selectors: selectorsInnerFirst.reverse(),
+        hasUnreadableSelector,
+        objects,
+        isConditional,
+    };
+}
+// The properties a transition shorthand animates. An item naming no property
+// animates `all`, which is the shorthand's initial `transition-property`.
+function readTransitionShorthand(value) {
+    if (value === 'none')
+        return [];
+    return splitTopLevel(value, (ch) => ch === ',').map((item) => {
+        const tokens = splitTopLevel(item, (ch) => /\s/.test(ch));
+        const property = tokens.find((token) => !TRANSITION_TIME.test(token) &&
+            !BARE_NUMBER.test(token) &&
+            !TRANSITION_KEYWORDS.has(token) &&
+            !token.includes('('));
+        return property ?? 'all';
+    });
+}
+function transitionCovers(value, transitionProperty, target) {
+    // `isDragging ? 'none' : TRANSITIONS.transform` covers through the branch
+    // that animates.
+    if (value.type === utils_1.AST_NODE_TYPES.ConditionalExpression) {
+        return (transitionCovers(value.consequent, transitionProperty, target) ||
+            transitionCovers(value.alternate, transitionProperty, target));
+    }
+    const text = readStaticText(value);
+    // An expression the rule cannot read (`createTransition(...)`,
+    // `theme.transitions.create(...)`, a constant) is trusted to cover it.
+    if (text === null)
+        return true;
+    const normalized = normalizePropertyValue(text);
+    if (GLOBAL_KEYWORDS.has(normalized))
+        return true;
+    const animated = transitionProperty === 'transition'
+        ? readTransitionShorthand(normalized)
+        : splitTopLevel(normalized, (ch) => ch === ',');
+    return animated.some((name) => name === 'all' || stripVendorPrefix(name) === target);
+}
+function hasCoveringTransition(chain, target) {
+    return chain.objects.some((object) => object.properties.some((entry) => {
+        if (entry.type !== utils_1.AST_NODE_TYPES.Property || entry.computed) {
+            return false;
+        }
+        const name = readKeyName(entry.key);
+        if (name === null)
+            return false;
+        const transitionProperty = stripVendorPrefix(normalizePropertyName(name));
+        return (TRANSITION_PROPERTIES.has(transitionProperty) &&
+            transitionCovers(entry.value, transitionProperty, target));
+    }));
+}
+function isFunctionNode(node) {
+    return (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration);
+}
+function isIterationCallee(callee) {
+    if (callee.type !== utils_1.AST_NODE_TYPES.MemberExpression ||
+        callee.computed ||
+        callee.property.type !== utils_1.AST_NODE_TYPES.Identifier) {
+        return false;
+    }
+    if (ITERATION_METHODS.has(callee.property.name))
+        return true;
+    return (callee.property.name === 'from' &&
+        callee.object.type === utils_1.AST_NODE_TYPES.Identifier &&
+        callee.object.name === 'Array');
+}
+function isItemRenderProp(fn) {
+    const { parent } = fn;
+    if (parent?.type === utils_1.AST_NODE_TYPES.JSXExpressionContainer &&
+        parent.parent?.type === utils_1.AST_NODE_TYPES.JSXAttribute &&
+        parent.parent.name.type === utils_1.AST_NODE_TYPES.JSXIdentifier) {
+        return ITEM_RENDER_PROP.test(parent.parent.name.name);
+    }
+    if (parent?.type === utils_1.AST_NODE_TYPES.Property &&
+        parent.value === fn &&
+        parent.key.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return ITEM_RENDER_PROP.test(parent.key.name);
+    }
+    return false;
+}
+function isInsideIteration(node) {
+    for (let current = node.parent; current; current = current.parent) {
+        if (!isFunctionNode(current))
+            continue;
+        const { parent } = current;
+        if (parent?.type === utils_1.AST_NODE_TYPES.CallExpression &&
+            parent.arguments.some((argument) => argument === current) &&
+            isIterationCallee(parent.callee)) {
+            return true;
+        }
+        if (isItemRenderProp(current))
+            return true;
+    }
+    return false;
+}
 exports.noCompositingLayerProps = (0, createRule_1.createRule)({
     name: 'no-compositing-layer-props',
     meta: {
@@ -75,13 +549,35 @@ exports.noCompositingLayerProps = (0, createRule_1.createRule)({
             description: 'Discourage CSS properties that force GPU compositing layers (e.g., transform, filter, will-change). Extra layers consume GPU memory and split rendering work, which slows scrolling and animation when sprinkled across a page. The rule inspects inline style objects and MUI sx props so layer promotion stays intentional rather than incidental.',
             recommended: 'error',
         },
-        schema: [],
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    exemptInteractionStates: {
+                        type: 'boolean',
+                        default: true,
+                    },
+                    exemptStateTransitions: {
+                        type: 'boolean',
+                        default: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
         messages: {
-            compositingLayer: 'CSS property "{{property}}" promotes this element to its own GPU compositing layer. Extra layers allocate GPU memory and isolate painting, which slows scrolling and animation when used broadly. Remove "{{property}}" or keep it only when the layer promotion is intentional and documented (e.g., eslint-disable with a comment).',
+            compositingLayer: "CSS property \"{{property}}\" promotes this element to its own GPU compositing layer. On a component repeated in a list or scroll view, one layer per row exhausts GPU memory and tears during scroll. Animate transform/opacity under an interaction state ('&:hover', '&:active', '&:focus-visible'), or drive a state-dependent value with a 'transition'; both are exempt. Otherwise remove it, or keep it with an eslint-disable-next-line comment giving the reason.",
         },
     },
-    defaultOptions: [],
-    create(context) {
+    defaultOptions: [
+        {
+            exemptInteractionStates: true,
+            exemptStateTransitions: true,
+        },
+    ],
+    create(context, [options]) {
+        const exemptInteractionStates = options.exemptInteractionStates !== false;
+        const exemptStateTransitions = options.exemptStateTransitions !== false;
         const seenNodes = new WeakSet();
         // The value-driven arm exists to catch a layer-promoting value written under
         // a property spelling COMPOSITING_PROPERTIES misses (a vendor prefix). It
@@ -90,15 +586,7 @@ exports.noCompositingLayerProps = (0, createRule_1.createRule)({
         // half is never a CSS property being reported, so it is never reported.
         function checkPropertyValue(normalizedName, value) {
             return (TRANSFORM_VALUE_PROPERTIES.has(stripVendorPrefix(normalizedName)) &&
-                COMPOSITING_TRANSFORM_FUNCTIONS.some((fn) => value.includes(fn)));
-        }
-        // Strip `!important` and normalize casing so reset/identity values written
-        // as e.g. `none !important` are still recognized as non-promoting.
-        function normalizePropertyValue(value) {
-            return value
-                .replace(/\s*!important\s*$/i, '')
-                .trim()
-                .toLowerCase();
+                THREE_D_TRANSFORM_FUNCTION.test(value));
         }
         function checkProperty(propertyName, propertyValue) {
             const normalizedName = normalizePropertyName(propertyName);
@@ -127,6 +615,63 @@ exports.noCompositingLayerProps = (0, createRule_1.createRule)({
             }
             return false;
         }
+        // A responsive object or array holds one value per breakpoint, not per
+        // state, so it is state-driven only when no entry promotes a layer at rest.
+        function isStateDrivenValue(normalizedName, value) {
+            switch (value.type) {
+                case utils_1.AST_NODE_TYPES.TSAsExpression:
+                case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+                case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+                case utils_1.AST_NODE_TYPES.TSTypeAssertion:
+                    return isStateDrivenValue(normalizedName, value.expression);
+                case utils_1.AST_NODE_TYPES.ObjectExpression:
+                    return value.properties.every((entry) => entry.type !== utils_1.AST_NODE_TYPES.Property ||
+                        isStateDrivenValue(normalizedName, entry.value));
+                case utils_1.AST_NODE_TYPES.ArrayExpression:
+                    return value.elements.every((entry) => !entry ||
+                        entry.type === utils_1.AST_NODE_TYPES.SpreadElement ||
+                        isStateDrivenValue(normalizedName, entry));
+                default: {
+                    const literal = readStaticText(value);
+                    return literal === null || !checkProperty(normalizedName, literal);
+                }
+            }
+        }
+        // A 3D transform promotes a layer whatever state the element is in.
+        function writesThreeDTransform(normalizedName, value, literal) {
+            if (collectStaticFragments(value).some((fragment) => THREE_D_TRANSFORM_FUNCTION.test(fragment))) {
+                return true;
+            }
+            return literal !== null && isThreeDLiteral(normalizedName, literal);
+        }
+        // Both arms are list-safe by construction. A singular interaction state
+        // matches one element per pointer or focus however many siblings exist,
+        // and a CSS transition never runs on first paint, so a state-driven value
+        // promotes only the element whose state flipped, and only while it
+        // animates. The second arm is withheld inside lexical iteration, where
+        // many siblings can be "on" at once.
+        function isExempt(node, normalizedName, literal) {
+            if (!EXEMPTABLE_PROPERTIES.has(normalizedName))
+                return false;
+            if (!exemptInteractionStates && !exemptStateTransitions)
+                return false;
+            if (writesThreeDTransform(normalizedName, node.value, literal)) {
+                return false;
+            }
+            const chain = climbStyleChain(node);
+            if (exemptInteractionStates &&
+                everyMemberQualifies(chain, carriesInteraction)) {
+                return true;
+            }
+            if (!exemptStateTransitions)
+                return false;
+            const isStateDriven = (literal === null && isStateDrivenValue(normalizedName, node.value)) ||
+                chain.isConditional ||
+                everyMemberQualifies(chain, carriesState);
+            return (isStateDriven &&
+                hasCoveringTransition(chain, normalizedName) &&
+                !isInsideIteration(node));
+        }
         // A property key names a `@keyframes` at-rule when it is a string literal
         // (`'@keyframes spin'`) or a template literal whose leading text starts the
         // at-rule (`` [`@keyframes ${name}`] `` for a dynamically-named animation).
@@ -204,7 +749,6 @@ exports.noCompositingLayerProps = (0, createRule_1.createRule)({
             if (isInKeyframes(node))
                 return;
             let propertyName = '';
-            let propertyValue = '';
             // Get property name
             if (node.key.type === utils_1.AST_NODE_TYPES.Identifier) {
                 propertyName = node.key.name;
@@ -212,19 +756,18 @@ exports.noCompositingLayerProps = (0, createRule_1.createRule)({
             else if (node.key.type === utils_1.AST_NODE_TYPES.Literal) {
                 propertyName = String(node.key.value);
             }
-            // Get property value if it's a string literal or numeric literal
-            if (node.value.type === utils_1.AST_NODE_TYPES.Literal) {
-                propertyValue = String(node.value.value);
-            }
-            if (checkProperty(propertyName, propertyValue)) {
-                context.report({
-                    node,
-                    messageId: 'compositingLayer',
-                    data: {
-                        property: propertyName,
-                    },
-                });
-            }
+            const literal = readStaticText(node.value);
+            if (!checkProperty(propertyName, literal ?? ''))
+                return;
+            if (isExempt(node, normalizePropertyName(propertyName), literal))
+                return;
+            context.report({
+                node,
+                messageId: 'compositingLayer',
+                data: {
+                    property: propertyName,
+                },
+            });
         }
         return {
             // Handle object literal properties (inline styles)

package/lib/rules/no-margin-properties.d.ts

@@ -1 +1,9 @@
-export declare const noMarginProperties: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"noMarginProperties", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+type Options = [
+    {
+        exemptZero?: boolean;
+        exemptAuto?: boolean;
+        exemptNegative?: boolean;
+    }
+];
+export declare const noMarginProperties: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"noMarginProperties", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};

package/lib/rules/no-margin-properties.js

@@ -65,6 +65,110 @@ const MARGIN_PROPERTIES = new Set([
     'ml',
     'm',
 ]);
+const ZERO_LENGTH = /^[+-]?(?:0+\.?0*|\.0+)(?:[a-z]+|%)?$/;
+const NEGATIVE_LENGTH = /^-(?:\d+\.?\d*|\.\d+)(?:[a-z]+|%)?$/;
+function classifyMarginToken(token) {
+    if (token === 'auto')
+        return 'auto';
+    if (ZERO_LENGTH.test(token))
+        return 'zero';
+    if (NEGATIVE_LENGTH.test(token))
+        return 'negative';
+    return 'spacing';
+}
+/**
+ * A string value may be a 1-4 token `margin` shorthand (`'0 auto'`), so every
+ * token is classified; `!important` changes the cascade, not the value.
+ */
+function classifyMarginString(value) {
+    const tokens = value
+        .replace(/\s*!important\s*$/i, '')
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+    return tokens.length === 0 ? ['spacing'] : tokens.map(classifyMarginToken);
+}
+function classifyMarginNumber(value) {
+    if (value === 0)
+        return 'zero';
+    return value < 0 ? 'negative' : 'spacing';
+}
+/**
+ * Every kind a margin value can take, or `null` when any part of it is
+ * unreadable (a variable, a call, a template substitution). A conditional and
+ * MUI's responsive object and array forms yield the kinds of all their
+ * branches, since any one of them may render.
+ */
+function classifyMarginValue(node) {
+    const value = unwrapAssertions(node);
+    switch (value.type) {
+        case utils_1.AST_NODE_TYPES.Literal:
+            if (typeof value.value === 'number') {
+                return [classifyMarginNumber(value.value)];
+            }
+            return typeof value.value === 'string'
+                ? classifyMarginString(value.value)
+                : null;
+        case utils_1.AST_NODE_TYPES.UnaryExpression:
+            if ((value.operator === '-' || value.operator === '+') &&
+                value.argument.type === utils_1.AST_NODE_TYPES.Literal &&
+                typeof value.argument.value === 'number') {
+                return [
+                    classifyMarginNumber(value.operator === '-'
+                        ? -value.argument.value
+                        : value.argument.value),
+                ];
+            }
+            return null;
+        case utils_1.AST_NODE_TYPES.TemplateLiteral:
+            return value.expressions.length === 0
+                ? classifyMarginString(value.quasis[0].value.cooked ?? value.quasis[0].value.raw)
+                : null;
+        case utils_1.AST_NODE_TYPES.JSXExpressionContainer:
+            return value.expression.type === utils_1.AST_NODE_TYPES.JSXEmptyExpression
+                ? null
+                : classifyMarginValue(value.expression);
+        case utils_1.AST_NODE_TYPES.ConditionalExpression:
+            return combineMarginKinds([value.consequent, value.alternate]);
+        case utils_1.AST_NODE_TYPES.ObjectExpression:
+            return combineMarginKinds(value.properties.map((entry) => entry.type === utils_1.AST_NODE_TYPES.Property && !entry.computed
+                ? entry.value
+                : null));
+        case utils_1.AST_NODE_TYPES.ArrayExpression:
+            return combineMarginKinds(value.elements.filter((element) => element !== null));
+        default:
+            return null;
+    }
+}
+/**
+ * MUI's responsive array and object forms read a `null` entry as "skip this
+ * breakpoint" (`[null, 0]` sets a margin from `sm` up only), and `sx` drops a
+ * `null` value outright, so a `null` part renders no margin at all.
+ */
+function isNullLiteral(node) {
+    const value = unwrapAssertions(node);
+    return value.type === utils_1.AST_NODE_TYPES.Literal && value.raw === 'null';
+}
+/**
+ * The kinds of every part of a composite value. A `null` part adds no kind,
+ * and a composite left with none (`[]`, `{}`, `[null, null]`) sets no margin
+ * that could earn an exemption, so it keeps the report like an unreadable one.
+ */
+function combineMarginKinds(nodes) {
+    const kinds = [];
+    for (const node of nodes) {
+        if (!node || node.type === utils_1.AST_NODE_TYPES.SpreadElement)
+            return null;
+        if (isNullLiteral(node))
+            continue;
+        const nodeKinds = classifyMarginValue(node);
+        if (!nodeKinds)
+            return null;
+        kinds.push(...nodeKinds);
+    }
+    return kinds.length === 0 ? null : kinds;
+}
 exports.noMarginProperties = (0, createRule_1.createRule)({
     name: 'no-margin-properties',
     meta: {
@@ -73,18 +177,61 @@ exports.noMarginProperties = (0, createRule_1.createRule)({
             description: 'Prevent margin properties (margin, marginLeft, marginRight, marginTop, marginBottom, mx, my, etc.) in MUI styling because margins fight container-controlled spacing, double gutters, and misaligned breakpoints; keep spacing centralized with padding, gap, or spacing props instead.',
             recommended: 'error',
         },
-        schema: [],
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    exemptZero: {
+                        type: 'boolean',
+                        default: true,
+                    },
+                    exemptAuto: {
+                        type: 'boolean',
+                        default: true,
+                    },
+                    exemptNegative: {
+                        type: 'boolean',
+                        default: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
         messages: {
             noMarginProperties: 'Margin property "{{property}}" in MUI styling fights container-controlled spacing (Stack/Grid spacing, gap, responsive gutters) and produces double gutters, misalignment, and overflow as layouts shift. Keep spacing inside the component with padding or let the parent handle separation via gap/spacing so layout remains predictable.',
         },
     },
-    defaultOptions: [],
-    create(context) {
+    defaultOptions: [
+        {
+            exemptZero: true,
+            exemptAuto: true,
+            exemptNegative: true,
+        },
+    ],
+    create(context, [options]) {
         const seenNodes = new WeakSet();
+        const exemptKinds = new Set();
+        if (options.exemptZero !== false)
+            exemptKinds.add('zero');
+        if (options.exemptAuto !== false)
+            exemptKinds.add('auto');
+        if (options.exemptNegative !== false)
+            exemptKinds.add('negative');
         function checkProperty(propertyName) {
             const normalizedName = normalizePropertyName(propertyName);
             return MARGIN_PROPERTIES.has(normalizedName);
         }
+        /**
+         * A value is exempt only when every part of it is a reset, `auto` or a
+         * negative offset whose exemption is on: one spacing token (`'0 8px'`) or
+         * one unreadable branch keeps the report.
+         */
+        function isExemptValue(value) {
+            if (!value)
+                return false;
+            const kinds = classifyMarginValue(value);
+            return !!kinds && kinds.every((kind) => exemptKinds.has(kind));
+        }
         /**
          * True if node is in a flagged MUI styling context (sx attribute, sx
          * object property, or css() call). Excludes createTheme styleOverrides:
@@ -159,7 +306,9 @@ exports.noMarginProperties = (0, createRule_1.createRule)({
                     .join('');
                 propertyName = quasis + expressions;
             }
-            if (propertyName && checkProperty(propertyName)) {
+            if (propertyName &&
+                checkProperty(propertyName) &&
+                !isExemptValue(node.value)) {
                 // Check if in MUI styling context
                 if (isMuiStylingContext(node)) {
                     context.report({
@@ -283,7 +432,9 @@ exports.noMarginProperties = (0, createRule_1.createRule)({
                             else if (key.type === utils_1.AST_NODE_TYPES.Literal) {
                                 propertyName = String(key.value);
                             }
-                            if (propertyName && checkProperty(propertyName)) {
+                            if (propertyName &&
+                                checkProperty(propertyName) &&
+                                !isExemptValue(prop.value)) {
                                 // Check if this variable is used in an sx prop
                                 if (sourceText.includes(`sx={${variableName}}`) ||
                                     sourceText.includes(`sx={{ ...${variableName}`) ||
@@ -307,7 +458,7 @@ exports.noMarginProperties = (0, createRule_1.createRule)({
                     if (attr.type === utils_1.AST_NODE_TYPES.JSXAttribute &&
                         attr.name.type === utils_1.AST_NODE_TYPES.JSXIdentifier) {
                         const attrName = attr.name.name;
-                        if (checkProperty(attrName)) {
+                        if (checkProperty(attrName) && !isExemptValue(attr.value)) {
                             context.report({
                                 node: attr,
                                 messageId: 'noMarginProperties',

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

@@ -352,7 +352,17 @@ function typeNodeExcludesProperty(node, propertyName, resolveAlias, seen = new S
         if (node.typeParameters?.params) {
             const argumentsAreTheType = closedLiteralCounts &&
                 PROPERTY_PRESERVING_WRAPPERS.has(wrapperNameOf(node.typeName) ?? '');
-            return node.typeParameters.params.some((param) => typeNodeExcludesProperty(param, propertyName, resolveAlias, seen, argumentsAreTheType));
+            if (node.typeParameters.params.some((param) => typeNodeExcludesProperty(param, propertyName, resolveAlias, seen, argumentsAreTheType))) {
+                return true;
+            }
+            // Arguments that prove nothing are not proof that the referenced alias
+            // proves nothing, so a reference carrying them still falls through to its
+            // own body. Returning here made `type P<T> = Omit<X, 'children'>` report
+            // when referenced as `P<string>` while the byte-identical unparameterized
+            // spelling passed. Type arguments are deliberately NOT substituted into
+            // the body: an unbound parameter there proves nothing, which is the
+            // conservative answer, and an undeclared wrapper still resolves to
+            // nothing and still reports.
         }
         // Keyed by position as well as by name: the same alias proves different
         // things in a props position than inside an arbitrary generic, so a visit

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,48 @@
 [
+  {
+    "version": "1.22.0",
+    "date": "2026-09-27T06:08:08.588Z",
+    "rules": [
+      {
+        "name": "no-compositing-layer-props",
+        "changeType": "feat",
+        "issues": [
+          2383
+        ],
+        "summary": "exempt interaction-state and transition-toggled transform/opacity"
+      },
+      {
+        "name": "no-margin-properties",
+        "changeType": "feat",
+        "issues": [
+          1593
+        ],
+        "summary": "skip null breakpoints in responsive margin values; exempt resets, auto and negative offsets"
+      }
+    ]
+  },
+  {
+    "version": "1.21.18",
+    "date": "2026-09-07T22:15:12.507Z",
+    "rules": [
+      {
+        "name": "enforce-empty-object-check",
+        "changeType": "fix",
+        "issues": [
+          2360
+        ],
+        "summary": "emit a configurable empty-check helper (closes #2360)"
+      },
+      {
+        "name": "prevent-children-clobber",
+        "changeType": "fix",
+        "issues": [
+          2361
+        ],
+        "summary": "resolve a parameterized props alias (closes #2361)"
+      }
+    ]
+  },
   {
     "version": "1.21.17",
     "date": "2026-09-07T12:35:50.668Z",