@blumintinc/eslint-plugin-blumint 1.15.0 → 1.16.0

package/lib/rules/enforce-dynamic-imports.js

@@ -1,21 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RULE_NAME = void 0;
+exports.DEFAULT_IGNORED_LIBRARIES = exports.RULE_NAME = void 0;
 const createRule_1 = require("../utils/createRule");
+const minimatch_1 = require("minimatch");
 exports.RULE_NAME = 'enforce-dynamic-imports';
+exports.DEFAULT_IGNORED_LIBRARIES = [
+    'react',
+    'react/**',
+    'react-dom',
+    'react-dom/**',
+    'next',
+    'next/**',
+    '@mui/material',
+    '@mui/material/**',
+    '@mui/icons-material',
+    '@mui/icons-material/**',
+    '@emotion/**',
+    'clsx',
+    'tailwind-merge',
+];
 exports.default = (0, createRule_1.createRule)({
     name: exports.RULE_NAME,
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Enforce dynamic imports for specified libraries to optimize bundle size',
+            description: 'Enforce dynamic imports for external libraries by default to optimize bundle size, unless explicitly ignored',
             recommended: 'error',
         },
         schema: [
             {
                 type: 'object',
                 properties: {
-                    libraries: {
+                    ignoredLibraries: {
                         type: 'array',
                         items: {
                             type: 'string',
@@ -29,46 +45,51 @@ exports.default = (0, createRule_1.createRule)({
             },
         ],
         messages: {
-            dynamicImportRequired: 'Static import from "{{source}}" eagerly pulls the entire package into the entry bundle, inflating download size and delaying the first render. Load it lazily with a dynamic import (for example, useDynamic(() => import("{{source}}"))) so the code is fetched only when needed; if you only need types, use a type-only import with allowImportType enabled.',
+            dynamicImportRequired: 'Static import from "{{source}}" loads the full package into the initial bundle. → This increases download size and delays first render, undermining our lazy‑loading pattern for external dependencies. → Use a dynamic import (e.g., useDynamic(() => import("{{source}}"))), add "{{source}}" to ignoredLibraries for intentional static usage, or use a type‑only import when you only need types.',
         },
     },
     defaultOptions: [
         {
-            libraries: ['@stream-io/video-react-sdk'],
+            ignoredLibraries: exports.DEFAULT_IGNORED_LIBRARIES,
             allowImportType: true,
         },
     ],
     create(context, [options]) {
-        const { libraries, allowImportType = true } = options;
-        // Check if the import source matches any of the specified libraries
-        const isLibraryMatch = (source) => {
-            return libraries.some((lib) => {
-                // Simple glob pattern matching
-                if (lib.includes('*')) {
-                    const pattern = lib.replace(/\*/g, '.*');
-                    const regex = new RegExp(`^${pattern}$`);
-                    return regex.test(source);
-                }
-                return source === lib;
-            });
+        const { ignoredLibraries = exports.DEFAULT_IGNORED_LIBRARIES, allowImportType = true, } = options;
+        const exactIgnored = new Set();
+        const globIgnored = [];
+        for (const lib of ignoredLibraries) {
+            const mm = new minimatch_1.Minimatch(lib);
+            if (mm.hasMagic()) {
+                globIgnored.push(mm);
+            }
+            else {
+                exactIgnored.add(lib);
+            }
+        }
+        const isIgnored = (source) => {
+            return (exactIgnored.has(source) ||
+                globIgnored.some((mm) => mm.match(source)));
+        };
+        const isExternal = (source) => {
+            // Treat npm-style specifiers (including numeric names like '3d-force-graph') as external; internal paths are excluded.
+            return /^[a-z0-9@]/i.test(source) && !source.startsWith('@/');
         };
         return {
             ImportDeclaration(node) {
                 const importSource = node.source.value;
                 // Skip type-only imports if allowed
                 if (allowImportType) {
-                    // Check if it's a type-only import declaration
                     if (node.importKind === 'type') {
                         return;
                     }
-                    // Check if all specifiers are type imports
                     if (node.specifiers.length > 0 &&
                         node.specifiers.every((spec) => spec.type === 'ImportSpecifier' && spec.importKind === 'type')) {
                         return;
                     }
                 }
-                // Check if the import is from a library that should be dynamically imported
-                if (typeof importSource === 'string' && isLibraryMatch(importSource)) {
+                // Only enforce for external libraries that are NOT ignored
+                if (isExternal(importSource) && !isIgnored(importSource)) {
                     context.report({
                         node,
                         messageId: 'dynamicImportRequired',

package/lib/rules/enforce-memoize-async.js

@@ -4,10 +4,7 @@ exports.enforceMemoizeAsync = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const MEMOIZE_MODULE = '@blumintinc/typescript-memoize';
-const ALLOWED_MEMOIZE_MODULES = new Set([
-    MEMOIZE_MODULE,
-    'typescript-memoize',
-]);
+const ALLOWED_MEMOIZE_MODULES = new Set([MEMOIZE_MODULE, 'typescript-memoize']);
 /**
  * Matches a memoize decorator in supported syntaxes:
  * - @Alias()

package/lib/rules/enforce-mui-rounded-icons.js

@@ -3,6 +3,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceMuiRoundedIcons = void 0;
 const createRule_1 = require("../utils/createRule");
 const utils_1 = require("@typescript-eslint/utils");
+/**
+ * Non-Rounded MUI variant suffixes. An icon imported as one of these variants
+ * (e.g. `AddReactionOutlined`) maps to the Rounded variant of its BASE name
+ * (`AddReactionRounded`), not `AddReactionOutlinedRounded` (which doesn't exist).
+ * Matched exactly, so a distinct icon like `MailOutline` (ends in "Outline", not
+ * "Outlined") is left intact → `MailOutlineRounded`, which does exist.
+ */
+const VARIANT_SUFFIXES = ['Outlined', 'Sharp', 'TwoTone'];
+/**
+ * @mui/icons-material brand icons that ship in a single (Filled) variant only —
+ * they have no Rounded counterpart, so the rule must not demand one. Computed
+ * from @mui/icons-material (the only base icons lacking a `*Rounded` sibling).
+ */
+const ICONS_WITHOUT_ROUNDED = new Set([
+    'Apple',
+    'GitHub',
+    'Google',
+    'Instagram',
+    'LinkedIn',
+    'Microsoft',
+    'Pinterest',
+    'Reddit',
+    'Telegram',
+    'Twitter',
+    'WhatsApp',
+    'X',
+    'YouTube',
+]);
+/** Strips a trailing non-Rounded variant suffix to recover the base icon name. */
+const toBaseIconName = (iconName) => {
+    const suffix = VARIANT_SUFFIXES.find((variant) => iconName.endsWith(variant));
+    return suffix ? iconName.slice(0, -suffix.length) : iconName;
+};
 exports.enforceMuiRoundedIcons = (0, createRule_1.createRule)({
     name: 'enforce-mui-rounded-icons',
     meta: {
@@ -36,8 +69,16 @@ exports.enforceMuiRoundedIcons = (0, createRule_1.createRule)({
                     if (!iconName) {
                         return;
                     }
+                    // Map a non-Rounded variant import to its base icon so the Rounded
+                    // suggestion/fix targets a name that actually exists.
+                    const baseIconName = toBaseIconName(iconName);
+                    // Brand icons have no Rounded variant — demanding one is a false
+                    // positive and the fix would point at a non-existent module.
+                    if (ICONS_WITHOUT_ROUNDED.has(baseIconName)) {
+                        return;
+                    }
                     // Create the rounded variant name
-                    const roundedVariant = `${iconName}Rounded`;
+                    const roundedVariant = `${baseIconName}Rounded`;
                     context.report({
                         node,
                         messageId: 'enforceRoundedVariant',

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

@@ -20,6 +20,7 @@ const ALLOWLIST = {
     domain: new Set([
         'ai',
         'blumint',
+        'main',
         'middleware',
         'noop',
         'nth',
@@ -406,6 +407,8 @@ const ALLOWLIST = {
         'brush',
         'bubble',
         'buck',
+        'bucket',
+        'bucketize',
         'buckle',
         'bud',
         'budge',

package/lib/rules/global-const-style.js

@@ -158,6 +158,15 @@ exports.default = (0, createRule_1.createRule)({
                             if (target.type === utils_1.AST_NODE_TYPES.Literal && 'regex' in target) {
                                 return false;
                             }
+                            // Skip null and boolean literals. `null as const` is invalid
+                            // TypeScript (TS1355), so the autofix would produce uncompilable
+                            // code; `true`/`false` already have literal types, so `as const`
+                            // is redundant. (`undefined` is an Identifier, not a Literal, so
+                            // it never reaches the literal branch below.)
+                            if (target.type === utils_1.AST_NODE_TYPES.Literal &&
+                                (target.value === null || typeof target.value === 'boolean')) {
+                                return false;
+                            }
                             return (target.type === utils_1.AST_NODE_TYPES.Literal ||
                                 target.type === utils_1.AST_NODE_TYPES.ArrayExpression ||
                                 target.type === utils_1.AST_NODE_TYPES.ObjectExpression);

package/lib/rules/logical-top-to-bottom-grouping.js

@@ -760,18 +760,26 @@ function handleGuardHoists(ruleContext, body, parent) {
 }
 function handleDerivedGrouping(ruleContext, body, parent) {
     const declaredIndices = new Map();
+    /**
+     * Each binding name → the declarator that introduced it. Sibling bindings of
+     * one multi-target declarator (e.g. `const [a, b] = ...`) share one node, so
+     * a statement deriving from `a` is recognizable as a sibling of one deriving
+     * from `b` even though `a` separates `b` from its declaration.
+     */
+    const sourceDeclarators = new Map();
     const { sourceCode } = ruleContext;
     body.forEach((statement, index) => {
         if (isVariableDeclaration(statement)) {
-            processVariableDeclaration(ruleContext, statement, index, body, declaredIndices, parent, sourceCode);
+            processVariableDeclaration(ruleContext, statement, index, body, declaredIndices, sourceDeclarators, parent, sourceCode);
         }
         trackDeclaredNames(statement, index, declaredIndices);
+        trackSourceDeclarators(statement, sourceDeclarators);
     });
 }
 function isVariableDeclaration(statement) {
     return statement.type === utils_1.AST_NODE_TYPES.VariableDeclaration;
 }
-function processVariableDeclaration(ruleContext, statement, index, body, declaredIndices, parent, sourceCode) {
+function processVariableDeclaration(ruleContext, statement, index, body, declaredIndices, sourceDeclarators, parent, sourceCode) {
     const dependencies = collectDependencies(statement);
     const priorDependencies = findPriorDependencies(dependencies, declaredIndices);
     if (priorDependencies.length === 0 ||
@@ -784,6 +792,9 @@ function processVariableDeclaration(ruleContext, statement, index, body, declare
     }
     const declaredNames = getDeclaredNames(statement);
     const priorDependencySet = new Set(priorDependencies);
+    if (interveningAreSiblingDerivations(body, lastDependencyIndex, index, priorDependencySet, sourceDeclarators)) {
+        return;
+    }
     if (hasBlockers(body, lastDependencyIndex, index, priorDependencySet, declaredNames)) {
         return;
     }
@@ -829,6 +840,73 @@ function trackDeclaredNames(statement, index, declaredIndices) {
     const declared = getDeclaredNames(statement);
     declared.forEach((name) => declaredIndices.set(name, index));
 }
+function trackSourceDeclarators(statement, sourceDeclarators) {
+    if (statement.type !== utils_1.AST_NODE_TYPES.VariableDeclaration) {
+        return;
+    }
+    statement.declarations.forEach((declarator) => {
+        const names = new Set();
+        collectDeclaredNamesFromPattern(declarator.id, names);
+        names.forEach((name) => sourceDeclarators.set(name, declarator));
+    });
+}
+/**
+ * True when every statement between a dependency and the statement deriving from
+ * it is itself a pure derivation from a *sibling binding of the same declarator*.
+ *
+ * `const [a, b] = await Promise.all([...]); const x = a; const y = b;` is already
+ * grouped: `x` and `y` unpack one source declaration in order, so the `x` line is
+ * not "unrelated" separation between `b` and `y`. Suppressing here keeps such
+ * cohesive sibling-destructure groups intact instead of reordering them.
+ */
+function interveningAreSiblingDerivations(body, lastDependencyIndex, currentIndex, priorDependencySet, sourceDeclarators) {
+    const sourceNodes = new Set();
+    priorDependencySet.forEach((name) => {
+        const declarator = sourceDeclarators.get(name);
+        if (declarator) {
+            sourceNodes.add(declarator);
+        }
+    });
+    if (sourceNodes.size === 0) {
+        return false;
+    }
+    const intervening = body.slice(lastDependencyIndex + 1, currentIndex);
+    if (intervening.length === 0) {
+        return false;
+    }
+    return intervening.every((between) => isSiblingSourceDerivation(between, sourceNodes, sourceDeclarators));
+}
+/**
+ * A statement is a sibling-source derivation when it is a pure declaration whose
+ * every prior-declared dependency was introduced by one of `sourceNodes` — i.e.
+ * it unpacks a sibling binding of the same multi-target declaration the dependent
+ * statement derives from.
+ */
+function isSiblingSourceDerivation(statement, sourceNodes, sourceDeclarators) {
+    if (statement.type !== utils_1.AST_NODE_TYPES.VariableDeclaration ||
+        !isPureDeclaration(statement, { allowHooks: false })) {
+        return false;
+    }
+    const dependencies = collectDependencies(statement);
+    const siblingSourced = Array.from(dependencies).filter((name) => {
+        const declarator = sourceDeclarators.get(name);
+        return Boolean(declarator && sourceNodes.has(declarator));
+    });
+    if (siblingSourced.length === 0) {
+        return false;
+    }
+    /**
+     * Reject when the statement also pulls in any prior-declared name from outside
+     * the sibling source: that would be genuine extra coupling, not a clean sibling
+     * unpack.
+     */
+    return Array.from(dependencies).every((name) => {
+        if (siblingSourced.includes(name)) {
+            return true;
+        }
+        return !sourceDeclarators.has(name);
+    });
+}
 function handleLateDeclarations(ruleContext, body, parent) {
     const { sourceCode } = ruleContext;
     body.forEach((statement, index) => {

package/lib/rules/memo-compare-deeply-complex-props.js

@@ -6,6 +6,19 @@ const createRule_1 = require("../utils/createRule");
 function isUtilMemoModulePath(path) {
     return /(?:^|\/|\\)util\/memo$/.test(path);
 }
+/**
+ * Reserved React slots that never reach a component's props object at runtime.
+ * React extracts `ref` and `key` before invoking the memo equality function, so
+ * a deep comparator can never observe them. Some prop-type sources (notably the
+ * `forwardRef<T, P>` exotic-component signature, whose params include the
+ * synthetic `RefAttributes<T> = { ref?: Ref<T> }` member) surface them as
+ * structural members anyway; flagging them would emit dead `compareDeeply('ref')`
+ * advice. Excluded the same way `children` is.
+ */
+const RESERVED_REACT_PROP_NAMES = new Set(['ref', 'key', 'children']);
+function isReservedReactPropName(name) {
+    return RESERVED_REACT_PROP_NAMES.has(name);
+}
 /**
  * Checks if a property name is handled by the default deep equality logic
  * in our custom memo implementation (blumintAreEqual).
@@ -296,6 +309,91 @@ function ensureCompareDeeplyImportFixes(sourceCode, fixer, usedNames, preferredS
         localName: preferredLocalName,
     };
 }
+/**
+ * Names of React types that represent renderable UI or component references.
+ * Props typed as any of these are stable references (JSX elements, component
+ * constructors, render-prop functions) and do NOT benefit from deep value
+ * comparison — flagging them would produce false positives.
+ */
+const REACT_RENDER_TYPE_NAMES = new Set([
+    'ReactNode',
+    'ReactChild',
+    'ReactElement',
+    'ReactPortal',
+    'ReactFragment',
+    // JSX.Element resolves to a global symbol named 'Element' in the JSX namespace
+    'Element',
+    'Component',
+    'PureComponent',
+    'ComponentClass',
+    'FunctionComponent',
+    'FC',
+    'ComponentType',
+    'ExoticComponent',
+    'NamedExoticComponent',
+    'MemoExoticComponent',
+    'ForwardRefExoticComponent',
+    'LazyExoticComponent',
+    'JSXElementConstructor',
+    'RefObject',
+    'RefCallback',
+    'Ref',
+]);
+/**
+ * Returns true when `sym` is declared inside a `.d.ts` file whose path
+ * contains "react" — indicating it originates from @types/react rather than
+ * from user code that happens to use the same name.
+ *
+ * Also returns true when the symbol has NO declarations at all: this happens
+ * when TypeScript resolves the type as `any` because the source module (e.g.
+ * @types/react) is not included in the tsconfig `types` array.  A symbol with
+ * no declarations cannot be a user-defined type, so treating it as "from
+ * React" is safe — it avoids flagging props that would otherwise be excluded
+ * once the types are properly wired.
+ */
+function isSymbolFromReactDeclarationFile(sym) {
+    const declarations = sym.declarations;
+    // No declarations ⟹ the type was resolved from an unresolvable external
+    // module (common when @types/react is absent from the tsconfig types list).
+    // User-defined types always have at least one declaration.
+    if (!declarations || declarations.length === 0)
+        return true;
+    return declarations.some((decl) => {
+        const fileName = decl.getSourceFile?.()?.fileName ?? '';
+        return fileName.endsWith('.d.ts') && /react/i.test(fileName);
+    });
+}
+/**
+ * Returns true when `type` is a React render-related type that should be
+ * excluded from the "complex prop" check.  Detects by matching the type's
+ * alias symbol or own symbol name against a known React-type allowlist AND
+ * verifying the matched symbol's declaration originates from a React `.d.ts`
+ * file to avoid false negatives for user types that coincidentally share the
+ * same name.
+ */
+function isReactRenderType(type) {
+    // Check the aliasSymbol first (covers type aliases like ReactNode, FC, etc.)
+    const aliasSymbol = type
+        .aliasSymbol;
+    if (aliasSymbol) {
+        const name = aliasSymbol.escapedName;
+        if (REACT_RENDER_TYPE_NAMES.has(name) &&
+            isSymbolFromReactDeclarationFile(aliasSymbol)) {
+            return true;
+        }
+    }
+    // Check the type's own symbol (covers interfaces / classes like ReactElement,
+    // ComponentClass, ForwardRefExoticComponent, etc.)
+    const sym = type.symbol;
+    if (sym) {
+        const name = sym.escapedName;
+        if (REACT_RENDER_TYPE_NAMES.has(name) &&
+            isSymbolFromReactDeclarationFile(sym)) {
+            return true;
+        }
+    }
+    return false;
+}
 function isComplexType(ts, type, checker) {
     return isComplexTypeInternal(ts, type, checker, new Set());
 }
@@ -303,6 +401,13 @@ function isComplexTypeInternal(ts, type, checker, visited) {
     if (visited.has(type))
         return false;
     visited.add(type);
+    // Exclude React render-related types before any structural checks.
+    // This must come early so that ReactElement (an object type) and ReactNode
+    // (a union containing ReactElement) are both short-circuited here rather
+    // than being caught by the isObjectType / checkUnionType branches below.
+    if (isReactRenderType(type)) {
+        return false;
+    }
     const flags = type.flags ?? 0;
     if (isUnionType(ts, flags)) {
         return checkUnionType(ts, type, checker, visited);
@@ -389,13 +494,72 @@ function extractAnnotationType(propDeclaration) {
     }
     return undefined;
 }
-function shouldTreatAnyAsComplex(prop, propType, ts, treatAnyAsComplex, parentTypeFlags) {
+/**
+ * Returns true when an annotation TypeNode (the explicit type written in
+ * source, e.g. `React.ComponentType` or `React.ReactNode | null`) resolves to
+ * a React render type that must be excluded from the complex-prop check.
+ *
+ * This path is taken when the prop type resolves to `any` (common when
+ * @types/react is not listed in the tsconfig `types` array) but the
+ * annotation still carries the original alias name via the TypeScript
+ * type-checker.
+ *
+ * For union annotation nodes (e.g. `ReactNode | null`), all non-null /
+ * non-undefined members must themselves be React render types for the whole
+ * union to be considered a React render type.
+ */
+function isAnnotationReactRenderType(annotationType, checker, ts) {
+    try {
+        const tsModule = ts;
+        // Handle union annotation nodes like `React.ReactNode | null`.
+        if (tsModule.isUnionTypeNode?.(annotationType)) {
+            const nonNullishMembers = annotationType.types.filter((member) => {
+                // Nullish keywords appearing directly (older TypeScript AST forms)
+                if (member.kind === tsModule.SyntaxKind.NullKeyword ||
+                    member.kind === tsModule.SyntaxKind.UndefinedKeyword ||
+                    member.kind === tsModule.SyntaxKind.VoidKeyword) {
+                    return false;
+                }
+                // `null` and `undefined` appear as LiteralTypeNode wrapping the
+                // corresponding keyword in modern TypeScript AST.
+                if (tsModule.isLiteralTypeNode?.(member)) {
+                    const lit = member.literal;
+                    if (lit.kind === tsModule.SyntaxKind.NullKeyword ||
+                        lit.kind === tsModule.SyntaxKind.UndefinedKeyword) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+            // If every non-nullish member is a React render type, the union is too.
+            return (nonNullishMembers.length > 0 &&
+                nonNullishMembers.every((member) => isAnnotationReactRenderType(member, checker, ts)));
+        }
+        // For plain TypeReference nodes (the common case), resolve via the checker.
+        const resolvedType = checker.getTypeFromTypeNode?.(annotationType);
+        if (!resolvedType)
+            return false;
+        return isReactRenderType(resolvedType);
+    }
+    catch {
+        return false;
+    }
+}
+function shouldTreatAnyAsComplex(prop, propType, ts, treatAnyAsComplex, parentTypeFlags, checker) {
     if (!(propType.flags & ts.TypeFlags.Any))
         return false;
     if (treatAnyAsComplex)
         return true;
     const propDeclaration = extractPropertyDeclaration(prop);
     const annotationType = extractAnnotationType(propDeclaration);
+    // When the annotation resolves to a React render type, the prop is a
+    // stable component/render-prop reference that does not benefit from deep
+    // value comparison — exclude it regardless of the any-as-complex heuristic.
+    if (annotationType &&
+        checker &&
+        isAnnotationReactRenderType(annotationType, checker, ts)) {
+        return false;
+    }
     return ((annotationType && annotationType.kind !== ts.SyntaxKind.AnyKeyword) ||
         (!annotationType && Boolean(parentTypeFlags & ts.TypeFlags.Object)));
 }
@@ -404,13 +568,13 @@ function isPropertyComplex(prop, checker, tsNode, ts, treatAnyAsComplex, parentT
     if (isComplexType(ts, propType, checker)) {
         return true;
     }
-    return shouldTreatAnyAsComplex(prop, propType, ts, treatAnyAsComplex, parentTypeFlags);
+    return shouldTreatAnyAsComplex(prop, propType, ts, treatAnyAsComplex, parentTypeFlags, checker);
 }
 function getComplexPropertiesFromType(type, checker, tsNode, ts, treatAnyAsComplex = false, parentTypeFlags = 0) {
     const properties = checker.getPropertiesOfType(type);
     const complexProps = [];
     for (const prop of properties) {
-        if (prop.name === 'children')
+        if (isReservedReactPropName(prop.name))
             continue;
         if (isPropertyComplex(prop, checker, tsNode, ts, treatAnyAsComplex, parentTypeFlags)) {
             complexProps.push(prop.name);