@blumintinc/eslint-plugin-blumint 1.20.111 → 1.20.113

package/lib/index.js

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

package/lib/rules/enforce-css-media-queries.d.ts

@@ -2,5 +2,17 @@ import { TSESLint } from '@typescript-eslint/utils';
 /**
  * This rule enforces the use of CSS media queries instead of JavaScript-based breakpoints
  * in React components for better performance and separation of concerns.
+ *
+ * Two exemptions exist, both resting on the same principle: the rule reports
+ * only where its remedy exists. A query testing capability or preference has no
+ * CSS remedy, and neither does a viewport breakpoint whose result never reaches
+ * a style.
+ *
+ * Known limitation of the destination exemption: a value handed to a child
+ * component through an ordinary prop is exempt here even if the child applies it
+ * to a class, because the walk stops at this file's props. That false negative
+ * is the accepted price of an analysis that stays inside one file; the
+ * alternative — reporting every value that leaves the component — is the
+ * unactionable report this exemption exists to remove.
  */
 export declare const enforceCssMediaQueries: TSESLint.RuleModule<"enforceCssMediaQueries", [], TSESLint.RuleListener>;

package/lib/rules/enforce-css-media-queries.js

@@ -55,6 +55,18 @@ const NON_LAYOUT_FEATURES = new Set([
 ]);
 /** Every `prefers-*` feature is a user preference, never a layout measurement. */
 const PREFERENCE_FEATURE_PREFIX = 'prefers-';
+/**
+ * JSX attributes and object properties that carry CSS. A value reaching one of
+ * these has the remedy the report prescribes — declare the breakpoint in a
+ * `@media` rule and let the class name change — so it keeps reporting.
+ */
+const STYLE_DESTINATIONS = new Set([
+    'sx',
+    'style',
+    'className',
+    'classes',
+    'css',
+]);
 /**
  * Guards the text a query carries outside its feature groups — media types and
  * combinators such as `screen`, `and`, `not`. A layout name appearing there
@@ -65,6 +77,12 @@ const LAYOUT_NAME = new RegExp([...LAYOUT_FEATURES].join('|'));
 const FEATURE_GROUP = /\(([^()]*)\)/g;
 /** Follows at most this many indirections while resolving a query argument. */
 const MAX_RESOLUTION_DEPTH = 4;
+/**
+ * Follows at most this many hops while tracing a value to its destinations. A
+ * chain longer than this is unresolved and therefore reported, so the bound only
+ * ever costs an exemption.
+ */
+const MAX_DESTINATION_DEPTH = 8;
 /**
  * The feature a parenthesized query group tests, or `null` when the group's
  * shape leaves it ambiguous (range syntax such as `(width >= 600px)`, a nested
@@ -154,9 +172,133 @@ function resolveBinding(node, scope, depth) {
     }
     return resolveQuery(definition.node.init, scope, depth + 1);
 }
+/** The name a property is keyed by, or `null` when the key is computed. */
+function propertyKeyName(property) {
+    const { key } = property;
+    if (!property.computed && key.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return key.name;
+    }
+    if (key.type === utils_1.AST_NODE_TYPES.Literal && typeof key.value === 'string') {
+        return key.value;
+    }
+    return null;
+}
+/**
+ * Whether a JSX expression container hands its value to a prop CSS cannot
+ * express. A container in children position decides which markup renders, which
+ * a class name can do, so it is not exempt; neither is a style attribute nor a
+ * namespaced one, whose name this walk does not read.
+ */
+function isNonStyleAttributeValue(container) {
+    const attribute = container.parent;
+    if (attribute?.type !== utils_1.AST_NODE_TYPES.JSXAttribute) {
+        return false;
+    }
+    return (attribute.name.type === utils_1.AST_NODE_TYPES.JSXIdentifier &&
+        !STYLE_DESTINATIONS.has(attribute.name.name));
+}
+/**
+ * Whether every destination the value reaches is one CSS cannot express — a
+ * `timeout`, an `anchorOrigin`, any prop a stylesheet has no way to select.
+ *
+ * The walk climbs from the value through the expressions that merely carry it
+ * (a conditional, an object it is nested in, a `const` it is bound to) until it
+ * reaches somewhere the value is consumed. It answers `false` for a style
+ * destination AND for every shape it does not model, because the exemption
+ * exists only where the rule's remedy is provably unavailable: a value returned,
+ * exported, passed to a call, or spread into props escapes to a destination this
+ * walk cannot see, and an unseen destination may well be a stylesheet.
+ */
+function reachesOnlyNonStyleDestinations(node, context, depth) {
+    if (depth > MAX_DESTINATION_DEPTH) {
+        return false;
+    }
+    const parent = node.parent;
+    if (!parent) {
+        return false;
+    }
+    switch (parent.type) {
+        // Expressions that pass the value along: where their own result lands is
+        // the question that decides the original value.
+        case utils_1.AST_NODE_TYPES.ArrayExpression:
+        case utils_1.AST_NODE_TYPES.BinaryExpression:
+        case utils_1.AST_NODE_TYPES.ConditionalExpression:
+        case utils_1.AST_NODE_TYPES.LogicalExpression:
+        case utils_1.AST_NODE_TYPES.ObjectExpression:
+        case utils_1.AST_NODE_TYPES.SpreadElement:
+        case utils_1.AST_NODE_TYPES.TemplateLiteral:
+        case utils_1.AST_NODE_TYPES.TSAsExpression:
+        case utils_1.AST_NODE_TYPES.TSNonNullExpression:
+        case utils_1.AST_NODE_TYPES.TSSatisfiesExpression:
+        case utils_1.AST_NODE_TYPES.TSTypeAssertion:
+        case utils_1.AST_NODE_TYPES.UnaryExpression:
+            return reachesOnlyNonStyleDestinations(parent, context, depth + 1);
+        // A `sx`/`style`/`classes` key names a style destination wherever the object
+        // itself ends up, so the property is checked before the object is followed.
+        case utils_1.AST_NODE_TYPES.Property: {
+            const key = propertyKeyName(parent);
+            return ((key === null || !STYLE_DESTINATIONS.has(key)) &&
+                reachesOnlyNonStyleDestinations(parent, context, depth + 1));
+        }
+        case utils_1.AST_NODE_TYPES.JSXExpressionContainer:
+            return isNonStyleAttributeValue(parent);
+        case utils_1.AST_NODE_TYPES.VariableDeclarator:
+            return (parent.init === node &&
+                bindingReachesOnlyNonStyleDestinations(parent, context, depth));
+        default:
+            return false;
+    }
+}
+/**
+ * Whether every read of the binding this declarator introduces reaches a
+ * non-style destination.
+ *
+ * A binding with no reads is not exempt, mirroring `testsOnlyNonLayoutFeatures`
+ * on the query axis: a query naming no feature proves nothing, and neither does
+ * a value going nowhere.
+ */
+function bindingReachesOnlyNonStyleDestinations(declarator, context, depth) {
+    if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier) {
+        return false;
+    }
+    // Only a `const` proves the reads below observe the value declared here; a
+    // `let` may hold something else by the time a style reads it. An exported
+    // binding is read in files this walk cannot open.
+    const declaration = declarator.parent;
+    if (declaration?.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
+        declaration.kind !== 'const' ||
+        declaration.parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration) {
+        return false;
+    }
+    const scope = ASTHelpers_1.ASTHelpers.getScope(context, declarator.id);
+    const variable = ASTHelpers_1.ASTHelpers.findVariableInScope(scope, declarator.id.name);
+    if (!variable || variable.defs.length !== 1) {
+        return false;
+    }
+    const reads = variable.references.filter((reference) => reference.identifier !== declarator.id);
+    if (reads.length === 0) {
+        return false;
+    }
+    return reads.every((reference) => reference.isRead() &&
+        // `export { isMobile }` hands the value to another file.
+        reference.identifier.parent?.type !== utils_1.AST_NODE_TYPES.ExportSpecifier &&
+        reachesOnlyNonStyleDestinations(reference.identifier, context, depth + 1));
+}
 /**
  * This rule enforces the use of CSS media queries instead of JavaScript-based breakpoints
  * in React components for better performance and separation of concerns.
+ *
+ * Two exemptions exist, both resting on the same principle: the rule reports
+ * only where its remedy exists. A query testing capability or preference has no
+ * CSS remedy, and neither does a viewport breakpoint whose result never reaches
+ * a style.
+ *
+ * Known limitation of the destination exemption: a value handed to a child
+ * component through an ordinary prop is exempt here even if the child applies it
+ * to a class, because the walk stops at this file's props. That false negative
+ * is the accepted price of an analysis that stays inside one file; the
+ * alternative — reporting every value that leaves the component — is the
+ * unactionable report this exemption exists to remove.
  */
 exports.enforceCssMediaQueries = (0, createRule_1.createRule)({
     name: 'enforce-css-media-queries',
@@ -187,7 +329,8 @@ exports.enforceCssMediaQueries = (0, createRule_1.createRule)({
             data: { source },
         });
         const localNamesOf = (node) => node.specifiers.map((specifier) => specifier.local.name);
-        const isExemptCall = (node) => {
+        /** Whether the query the call carries is provably free of layout. */
+        const testsExemptQuery = (node) => {
             const [argument] = node.arguments;
             if (!argument) {
                 return false;
@@ -195,6 +338,11 @@ exports.enforceCssMediaQueries = (0, createRule_1.createRule)({
             const query = resolveQuery(argument, ASTHelpers_1.ASTHelpers.getScope(context, node));
             return query !== null && testsOnlyNonLayoutFeatures(query);
         };
+        // A zero-argument hook such as `useMobile` carries no query, so the
+        // query axis can never clear it; the destination axis is the only one that
+        // can, and it applies to every media hook alike.
+        const isExemptCall = (node) => testsExemptQuery(node) ||
+            reachesOnlyNonStyleDestinations(node, context, 0);
         return {
             // Only react-responsive is handled at the declaration level to avoid duplicates.
             ImportDeclaration(node) {

package/lib/rules/enforce-serializable-params.d.ts

@@ -5,5 +5,6 @@ declare const _default: import("@typescript-eslint/utils/dist/ts-eslint/Rule").R
 }[], {
     TSTypeAliasDeclaration(node: TSESTree.TSTypeAliasDeclaration): void;
     TSTypeReference(node: TSESTree.TSTypeReference): void;
+    'Program:exit'(): void;
 }>;
 export default _default;

package/lib/rules/enforce-serializable-params.js

@@ -100,6 +100,13 @@ exports.default = (0, createRule_1.createRule)({
                     break;
             }
         }
+        /**
+         * TypeScript hoists type aliases, so a request type may be declared below
+         * the function that consumes it. Collecting the wrapper references and
+         * resolving them once traversal is finished decouples the check from
+         * declaration order, which `typeAliasMap` alone cannot do.
+         */
+        const wrapperReferences = [];
         return {
             TSTypeAliasDeclaration(node) {
                 typeAliasMap.set(node.id.name, node);
@@ -108,13 +115,25 @@ exports.default = (0, createRule_1.createRule)({
                 const typeName = node.typeName.name;
                 if (options.functionTypes.includes(typeName) &&
                     node.typeParameters?.params[0]) {
-                    const typeParam = node.typeParameters.params[0];
+                    wrapperReferences.push(node);
+                }
+            },
+            'Program:exit'() {
+                for (const node of wrapperReferences) {
+                    const typeParam = node.typeParameters?.params[0];
+                    if (!typeParam)
+                        continue;
                     if (typeParam.type === utils_1.AST_NODE_TYPES.TSTypeReference) {
                         const referencedTypeName = typeParam.typeName.name;
                         const typeAlias = typeAliasMap.get(referencedTypeName);
-                        if (typeAlias) {
-                            checkTypeNode(typeAlias.typeAnnotation);
-                        }
+                        /**
+                         * A reference that names no local alias is still a type in its own
+                         * right — `CallableRequest<Timestamp>` is the plainest form of the
+                         * violation. Checking the node itself lets the non-serializable
+                         * lookup and the generic descent apply; an unrecognized name simply
+                         * yields no report, so an imported request type stays silent.
+                         */
+                        checkTypeNode(typeAlias ? typeAlias.typeAnnotation : typeParam);
                     }
                     else {
                         checkTypeNode(typeParam);

package/lib/rules/no-uuidv4-base62-as-key.js

@@ -4,6 +4,33 @@ exports.noUuidv4Base62AsKey = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+/**
+ * The helper's own module, identified by its file name rather than by a fixed
+ * list of specifiers: it is reachable as a package subpath, a tsconfig alias,
+ * or a relative path, and every one of those spellings imports the same
+ * function.
+ */
+const UUIDV4_BASE62_MODULE = 'uuidv4Base62';
+/** The barrel that re-exports the helper alongside unrelated utilities. */
+const UUIDV4_BASE62_BARREL = '@blumint/utils';
+const MODULE_EXTENSION = /\.(?:tsx?|jsx?)$/;
+/**
+ * Matches the final path segment exactly rather than testing the whole
+ * specifier with a suffix check. A suffix test has no module resolution behind
+ * it, so it conflates monorepo tiers (`functions/src/util/uuidv4Base62` versus
+ * `src/util/uuidv4Base62`) and, worse, accepts sibling modules whose names
+ * merely end with the helper's name. An exact basename comparison keeps
+ * `../../util/uuidv4Base62Stable` — a different helper — out.
+ */
+function isUuidv4Base62Module(source) {
+    if (typeof source !== 'string')
+        return false;
+    if (source === UUIDV4_BASE62_BARREL)
+        return true;
+    const segments = source.split('/');
+    const basename = segments[segments.length - 1].replace(MODULE_EXTENSION, '');
+    return basename === UUIDV4_BASE62_MODULE;
+}
 exports.noUuidv4Base62AsKey = (0, createRule_1.createRule)({
     name: 'no-uuidv4-base62-as-key',
     meta: {
@@ -236,8 +263,7 @@ exports.noUuidv4Base62AsKey = (0, createRule_1.createRule)({
             },
             // Track imports of uuidv4Base62
             ImportDeclaration(node) {
-                if (node.source.value === '@blumint/utils/uuidv4Base62' ||
-                    node.source.value === '@blumint/utils') {
+                if (isUuidv4Base62Module(node.source.value)) {
                     for (const specifier of node.specifiers) {
                         if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier) {
                             if (specifier.imported.name === 'uuidv4Base62' ||

package/lib/rules/prefer-clone-deep.js

@@ -96,10 +96,14 @@ exports.preferCloneDeep = (0, createRule_1.createRule)({
          *
          * Merging unrelated sources copies nothing twice and is safe, which is why
          * shapes such as `{ ...a, nested: { ...b } }`, MUI `sx` style maps and
-         * static config maps must not be flagged (#1371). A spread of the exact
-         * same path (`{ ...a, x: { ...a } }`) is deliberately excluded as well: it
-         * is a redundant copy rather than a partial one, and this repo prefers
-         * false negatives over false positives.
+         * static config maps must not be flagged (#1371). That verdict depends on
+         * ALL of a literal's sources, not on any one of them: `{ ...props, sx: {
+         * ...DEFAULT_SX, ...props.sx } }` builds `sx` fresh out of two sources and
+         * aliases neither, so it is a merge even though one source happens to be a
+         * sub-path of the base (#1745). A spread of the exact same path
+         * (`{ ...a, x: { ...a } }`) is deliberately excluded as well: it is a
+         * redundant copy rather than a partial one, and this repo prefers false
+         * negatives over false positives.
          */
         function isPartialDeepCopy(node) {
             const cached = partialDeepCopyCache.get(node);
@@ -109,15 +113,18 @@ exports.preferCloneDeep = (0, createRule_1.createRule)({
             let hasFunction = false;
             let hasSymbol = false;
             const basePaths = new Set();
-            const nestedPaths = [];
-            function visit(current, depth = 0) {
+            // Spread paths kept grouped by the literal that writes them, because a
+            // literal is classified by its sources as a set: flattening them loses
+            // the co-spread relation the merge exemption is stated over.
+            const nestedGroups = [];
+            function visit(current, depth = 0, group = []) {
                 if (current.type === utils_1.AST_NODE_TYPES.SpreadElement) {
                     const path = accessPathOf(current.argument);
                     if (depth === 0) {
                         basePaths.add(path);
                     }
                     else {
-                        nestedPaths.push(path);
+                        group.push(path);
                     }
                 }
                 else if (current.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
@@ -145,24 +152,35 @@ exports.preferCloneDeep = (0, createRule_1.createRule)({
                 // `...spread` at depth 0, where it names a base rather than a
                 // hand-copied sub-path.
                 if (current.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
-                    current.properties.forEach((prop) => visit(prop, depth));
+                    // Every literal owns the spreads written directly inside it. The
+                    // root's spreads name bases instead, so only descendants contribute
+                    // a group.
+                    const ownGroup = [];
+                    if (current !== node) {
+                        nestedGroups.push(ownGroup);
+                    }
+                    current.properties.forEach((prop) => visit(prop, depth, ownGroup));
                 }
                 else if (current.type === utils_1.AST_NODE_TYPES.Property) {
-                    visit(current.value, depth + 1);
+                    visit(current.value, depth + 1, group);
                 }
                 else if (current.type === utils_1.AST_NODE_TYPES.SpreadElement) {
-                    visit(current.argument, depth);
+                    visit(current.argument, depth, group);
                 }
             }
             visit(node);
+            // The separators guard against a sibling whose name merely starts with a
+            // base's name (`abc.x` is not a sub-path of `ab`).
+            const isBaseSubPath = (nested) => [...basePaths].some((base) => nested.startsWith(`${base}.`) || nested.startsWith(`${base}[`));
             // cloneDeep cannot faithfully reproduce functions or symbol keys, so
             // their presence suppresses the report regardless of the copy shape.
             const result = !hasFunction &&
                 !hasSymbol &&
-                nestedPaths.some((nested) => 
-                // The separators guard against a sibling whose name merely starts
-                // with a base's name (`abc.x` is not a sub-path of `ab`).
-                [...basePaths].some((base) => nested.startsWith(`${base}.`) || nested.startsWith(`${base}[`)));
+                // A nested literal is a hand-written partial copy only when EVERY
+                // source it spreads is a sub-path of a spread base. One foreign source
+                // makes the literal a fresh merge of both, which aliases nothing and is
+                // not expressible as cloneDeep overrides.
+                nestedGroups.some((group) => group.length > 0 && group.every(isBaseSubPath));
             partialDeepCopyCache.set(node, result);
             return result;
         }

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,48 @@
 [
+  {
+    "version": "1.20.113",
+    "date": "2026-08-05T17:37:08.020Z",
+    "rules": [
+      {
+        "name": "enforce-serializable-params",
+        "changeType": "fix",
+        "issues": [
+          1750
+        ],
+        "summary": "report a non-JSON-safe type used directly as the request type parameter (closes #1750)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.112",
+    "date": "2026-08-05T16:17:08.283Z",
+    "rules": [
+      {
+        "name": "enforce-css-media-queries",
+        "changeType": "fix",
+        "issues": [
+          1746
+        ],
+        "summary": "exempt breakpoints that reach no style (closes #1746)"
+      },
+      {
+        "name": "no-uuidv4-base62-as-key",
+        "changeType": "fix",
+        "issues": [
+          1744
+        ],
+        "summary": "recognize the helper by module basename (closes #1744)"
+      },
+      {
+        "name": "prefer-clone-deep",
+        "changeType": "fix",
+        "issues": [
+          1745
+        ],
+        "summary": "classify a nested literal by all its sources (closes #1745)"
+      }
+    ]
+  },
   {
     "version": "1.20.111",
     "date": "2026-08-05T13:37:20.101Z",