@blumintinc/eslint-plugin-blumint 1.22.0 → 1.23.0

package/README.md

@@ -267,6 +267,7 @@ full closed loop is documented in agora's `.claude/skills/eslint-autonomy/SKILL.
 | [require-migration-script-metadata](docs/rules/require-migration-script-metadata.md)                         | Enforce JSDoc migration metadata in callable scripts                                                                                                                                                                                                                                                                                                                                             | ✅  |    |    |    |    |
 | [require-props-composition](docs/rules/require-props-composition.md)                                         | Require React component Props types to compose (via Pick/Omit) with the props types of non-leaf child components rendered in JSX                                                                                                                                                                                                                                                                 | ✅  |    |    |    |    |
 | [require-server-timestamp-for-firestore-dates](docs/rules/require-server-timestamp-for-firestore-dates.md)   | Enforce serverTimestamp() instead of new Date() for Firestore timestamp fields                                                                                                                                                                                                                                                                                                                   | ✅  |    |    |    |    |
+| [require-sx-props-theme](docs/rules/require-sx-props-theme.md)                                               | Require MUI `SxProps` to carry the app theme as `SxProps<Theme>`, because the bare type defaults to `SxProps<{}>`: `sx` callbacks lose the theme's typing and TypeScript pays for a structural comparison against MUI's own `SxProps<Theme>`                                                                                                                                                     | ✅  |    | 🔧 |    |    |
 | [semantic-function-prefixes](docs/rules/semantic-function-prefixes.md)                                       | Require semantic function prefixes instead of generic verbs so callers know whether a function fetches data, transforms input, or mutates state                                                                                                                                                                                                                                                  | ✅  |    |    |    |    |
 | [sync-onwrite-name-func](docs/rules/sync-onwrite-name-func.md)                                               | Ensure that the name field matches the func field in onWrite handlers                                                                                                                                                                                                                                                                                                                            | ✅  |    | 🔧 |    |    |
 | [test-file-location-enforcement](docs/rules/test-file-location-enforcement.md)                               | Enforce colocating *.test.ts or *.test.tsx files with the code they cover.                                                                                                                                                                                                                                                                                                                       | ✅  |    |    |    |    |

package/lib/index.js

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

package/lib/rules/require-sx-props-theme.d.ts

@@ -0,0 +1,2 @@
+import { TSESLint } from '@typescript-eslint/utils';
+export declare const requireSxPropsTheme: TSESLint.RuleModule<"requireSxPropsTheme", [], TSESLint.RuleListener>;

package/lib/rules/require-sx-props-theme.js

@@ -0,0 +1,361 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireSxPropsTheme = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
+const createRule_1 = require("../utils/createRule");
+/**
+ * Every module MUI re-exports `SxProps` from. Matching on the module and the
+ * imported name, never the local name, is what lets a renamed import report
+ * and a same-named local type or shim stay silent.
+ */
+const SX_PROPS_SOURCES = new Set([
+    '@mui/material',
+    '@mui/material/styles',
+    '@mui/system',
+    '@mui/system/styleFunctionSx',
+]);
+/**
+ * The module a MUI app augments its theme through
+ * (`declare module '@mui/material/styles' { interface Theme { … } }`), so it is
+ * the only source whose `Theme` is provably the app theme, whichever module
+ * `SxProps` itself came from.
+ */
+const THEME_SOURCE = '@mui/material/styles';
+const SX_PROPS_NAME = 'SxProps';
+const THEME_NAME = 'Theme';
+/**
+ * The type argument list, read from whichever property the host
+ * `@typescript-eslint` version populates: v5 fills `typeParameters`, v6 adds
+ * `typeArguments`, and v8 drops `typeParameters` from `TSTypeReference`.
+ */
+function hasTypeArguments(node) {
+    const { typeArguments } = node;
+    return Boolean(typeArguments ?? node.typeParameters);
+}
+/**
+ * `import { "SxProps" as Sx }` arrives as a string literal on parsers that
+ * support arbitrary module namespace names, so both spellings are read.
+ */
+function importedNameOf(specifier) {
+    const imported = specifier.imported;
+    return imported.type === utils_1.AST_NODE_TYPES.Identifier
+        ? imported.name
+        : imported.value;
+}
+/**
+ * ES import declarations sit at the top level or directly inside an ambient
+ * `declare module '…' { }` block; nothing else can hold one.
+ */
+function collectImportDeclarations(statements, into) {
+    for (const statement of statements) {
+        if (statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration) {
+            into.push(statement);
+        }
+        else if (statement.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration &&
+            statement.body?.type === utils_1.AST_NODE_TYPES.TSModuleBlock) {
+            collectImportDeclarations(statement.body.body, into);
+        }
+    }
+}
+/**
+ * The innermost binding of `name` visible from `scope`. A value-only binding
+ * stops the walk even though TypeScript would look past it for a type name;
+ * that errs toward silence, never toward a wrong report or fix.
+ */
+function findVariable(scope, name) {
+    let current = scope;
+    while (current) {
+        const variable = current.set.get(name);
+        if (variable) {
+            return variable;
+        }
+        current = current.upper;
+    }
+    return undefined;
+}
+function importClauseOf(variable) {
+    if (!variable || variable.defs.length !== 1) {
+        return undefined;
+    }
+    const [definition] = variable.defs;
+    if (definition.type !== 'ImportBinding') {
+        return undefined;
+    }
+    const clause = definition.node;
+    return clause.type === utils_1.AST_NODE_TYPES.ImportSpecifier ||
+        clause.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier ||
+        clause.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier
+        ? clause
+        : undefined;
+}
+function sourceOf(clause) {
+    return clause.parent.source.value;
+}
+function isNamedImportOf(clause, importedName, isAllowedSource) {
+    return (clause?.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+        importedNameOf(clause) === importedName &&
+        isAllowedSource(sourceOf(clause)));
+}
+const isSxPropsSource = (source) => SX_PROPS_SOURCES.has(source);
+const isThemeSource = (source) => source === THEME_SOURCE;
+/**
+ * Inside `declare module '@mui/material/styles' { … }` the `Theme` in reach is
+ * the interface being augmented, and an import spliced into or above the
+ * ambient block changes what the declaration file means.
+ */
+function isInsideThemeAugmentation(node) {
+    let current = node.parent;
+    while (current) {
+        if (current.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration &&
+            current.id.type === utils_1.AST_NODE_TYPES.Literal &&
+            current.id.value === THEME_SOURCE) {
+            return true;
+        }
+        current = current.parent;
+    }
+    return false;
+}
+function isTypeOnlyImport(clause) {
+    const declaration = clause.parent;
+    return declaration.importKind === 'type' || clause.importKind === 'type';
+}
+exports.requireSxPropsTheme = (0, createRule_1.createRule)({
+    name: 'require-sx-props-theme',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: "Require MUI `SxProps` to carry the app theme as `SxProps<Theme>`, because the bare type defaults to `SxProps<{}>`: `sx` callbacks lose the theme's typing and TypeScript pays for a structural comparison against MUI's own `SxProps<Theme>`",
+            recommended: 'error',
+        },
+        fixable: 'code',
+        schema: [],
+        messages: {
+            requireSxPropsTheme: "`{{typeName}}` has no theme argument, so MUI defaults it to `SxProps<{}>`: an `sx` callback's `theme` is typed `{}`, and TypeScript compares this type structurally against MUI's `SxProps<Theme>` wherever the two meet, which can cost seconds of type checking per file. Write `{{typeName}}<Theme>` with `Theme` from '@mui/material/styles'.",
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        const program = sourceCode.ast;
+        const allImports = [];
+        collectImportDeclarations(program.body, allImports);
+        const sxPropsLocalNames = new Set();
+        const sxNamespaceLocalNames = new Set();
+        for (const declaration of allImports) {
+            if (!isSxPropsSource(declaration.source.value)) {
+                continue;
+            }
+            for (const specifier of declaration.specifiers) {
+                if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                    importedNameOf(specifier) === SX_PROPS_NAME) {
+                    sxPropsLocalNames.add(specifier.local.name);
+                }
+                else if (specifier.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier) {
+                    sxNamespaceLocalNames.add(specifier.local.name);
+                }
+            }
+        }
+        const importsSxProps = sxPropsLocalNames.size > 0 || sxNamespaceLocalNames.size > 0;
+        /**
+         * Only a top-level import can be extended or anchored after: one inside an
+         * ambient module block binds nothing outside it, and a file with no
+         * top-level import is a global script that a new import would turn into a
+         * module.
+         */
+        const topLevelImports = program.body.filter((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
+        const themeSourceImports = topLevelImports.filter((declaration) => isThemeSource(declaration.source.value));
+        /**
+         * An unresolved `Theme` elsewhere in the file (a global, or a name the file
+         * never declared) would silently change meaning once an import binds the
+         * name at module scope.
+         */
+        let hasUnresolvedTheme;
+        const themeIsReferencedUnresolved = () => {
+            if (hasUnresolvedTheme === undefined) {
+                const globalScope = sourceCode.scopeManager?.globalScope;
+                hasUnresolvedTheme = Boolean(globalScope?.through.some((reference) => reference.identifier.name === THEME_NAME));
+            }
+            return hasUnresolvedTheme;
+        };
+        function resolvesTo(scope, name, clause) {
+            return importClauseOf(findVariable(scope, name)) === clause;
+        }
+        function isReportableSxProps(typeName, scope) {
+            if (typeName.type === utils_1.AST_NODE_TYPES.Identifier) {
+                return (sxPropsLocalNames.has(typeName.name) &&
+                    isNamedImportOf(importClauseOf(findVariable(scope, typeName.name)), SX_PROPS_NAME, isSxPropsSource));
+            }
+            if (typeName.type !== utils_1.AST_NODE_TYPES.TSQualifiedName ||
+                typeName.right.name !== SX_PROPS_NAME ||
+                typeName.left.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                !sxNamespaceLocalNames.has(typeName.left.name)) {
+                return false;
+            }
+            const clause = importClauseOf(findVariable(scope, typeName.left.name));
+            return (clause?.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier &&
+                isSxPropsSource(sourceOf(clause)));
+        }
+        /** An existing `Theme` import, under whatever local name reaches the node. */
+        function existingThemeName(scope) {
+            if (isNamedImportOf(importClauseOf(findVariable(scope, THEME_NAME)), THEME_NAME, isThemeSource)) {
+                return THEME_NAME;
+            }
+            for (const declaration of themeSourceImports) {
+                for (const specifier of declaration.specifiers) {
+                    if (specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                        importedNameOf(specifier) === THEME_NAME &&
+                        resolvesTo(scope, specifier.local.name, specifier)) {
+                        return specifier.local.name;
+                    }
+                }
+            }
+            return undefined;
+        }
+        /** `Styles.Theme` through a namespace import, which adds no binding. */
+        function namespaceThemeText(scope) {
+            for (const declaration of themeSourceImports) {
+                for (const specifier of declaration.specifiers) {
+                    if (specifier.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier &&
+                        resolvesTo(scope, specifier.local.name, specifier)) {
+                        return `${specifier.local.name}.${THEME_NAME}`;
+                    }
+                }
+            }
+            return undefined;
+        }
+        /**
+         * Mirrors the declaration's own convention so a `verbatimModuleSyntax` or
+         * `consistent-type-imports` project stays clean: a type-only declaration
+         * takes a plain specifier, inline `type` specifiers call for another, and a
+         * declaration with no type marker follows how `SxProps` itself arrived.
+         */
+        function themeSpecifierText(declaration, sxPropsClause) {
+            if (declaration.importKind === 'type') {
+                return THEME_NAME;
+            }
+            const usesInlineType = declaration.specifiers.some((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier &&
+                specifier.importKind === 'type');
+            const sxPropsIsTypeOnly = sxPropsClause !== undefined &&
+                sxPropsClause.parent !== declaration &&
+                isTypeOnlyImport(sxPropsClause);
+            return usesInlineType || sxPropsIsTypeOnly
+                ? `type ${THEME_NAME}`
+                : THEME_NAME;
+        }
+        function extendNamedImport(declaration, specifiers, sxPropsClause) {
+            const text = themeSpecifierText(declaration, sxPropsClause);
+            const lastSpecifier = specifiers[specifiers.length - 1];
+            const openingBrace = sourceCode.getTokenBefore(specifiers[0]);
+            const isMultiline = openingBrace !== null &&
+                openingBrace.loc.end.line !== lastSpecifier.loc.start.line;
+            if (!isMultiline) {
+                return (fixer) => fixer.insertTextAfter(lastSpecifier, `, ${text}`);
+            }
+            const lineText = sourceCode.lines[lastSpecifier.loc.start.line - 1];
+            const indent = /^[\t ]*/.exec(lineText)?.[0] ?? '';
+            const trailingComma = sourceCode.getTokenAfter(lastSpecifier);
+            if (trailingComma?.value !== ',') {
+                return (fixer) => fixer.insertTextAfter(lastSpecifier, `,\n${indent}${text}`);
+            }
+            // A same-line comment after the trailing comma annotates the specifier
+            // above it, so the new specifier goes on the next line, below the comment.
+            let anchor = trailingComma;
+            for (const comment of sourceCode.getCommentsAfter(trailingComma)) {
+                if (comment.loc.start.line !== trailingComma.loc.end.line) {
+                    break;
+                }
+                anchor = comment;
+            }
+            return (fixer) => fixer.insertTextAfterRange(anchor.range, `\n${indent}${text},`);
+        }
+        function insertNewImport(lastImport) {
+            const quote = lastImport.source.raw.startsWith('"') ? '"' : "'";
+            const lastToken = sourceCode.getLastToken(lastImport);
+            const semicolon = lastToken?.value === ';' ? ';' : '';
+            const statement = `import type { ${THEME_NAME} } from ${quote}${THEME_SOURCE}${quote}${semicolon}`;
+            // A trailing same-line comment stays with the import it annotates.
+            let anchor = lastImport;
+            for (const comment of sourceCode.getCommentsAfter(lastImport)) {
+                if (comment.loc.start.line !== lastImport.loc.end.line) {
+                    break;
+                }
+                anchor = comment;
+            }
+            return (fixer) => fixer.insertTextAfterRange(anchor.range, `\n${statement}`);
+        }
+        function planFix(node, scope) {
+            if (isInsideThemeAugmentation(node)) {
+                return undefined;
+            }
+            const existing = existingThemeName(scope);
+            if (existing) {
+                return { themeText: existing };
+            }
+            // Adding a `Theme` binding is safe only where the name is free, both at
+            // the node and everywhere else in the file.
+            if (findVariable(scope, THEME_NAME) !== undefined ||
+                themeIsReferencedUnresolved()) {
+                const namespaced = namespaceThemeText(scope);
+                return namespaced ? { themeText: namespaced } : undefined;
+            }
+            const sxPropsClause = node.typeName.type === utils_1.AST_NODE_TYPES.Identifier
+                ? importClauseOf(findVariable(scope, node.typeName.name))
+                : undefined;
+            for (const declaration of themeSourceImports) {
+                const specifiers = declaration.specifiers.filter((specifier) => specifier.type === utils_1.AST_NODE_TYPES.ImportSpecifier);
+                if (specifiers.length > 0) {
+                    return {
+                        themeText: THEME_NAME,
+                        importFix: extendNamedImport(declaration, specifiers, sxPropsClause),
+                    };
+                }
+            }
+            const namespaced = namespaceThemeText(scope);
+            if (namespaced) {
+                return { themeText: namespaced };
+            }
+            const lastImport = topLevelImports[topLevelImports.length - 1];
+            if (!lastImport) {
+                return undefined;
+            }
+            return {
+                themeText: THEME_NAME,
+                importFix: insertNewImport(lastImport),
+            };
+        }
+        return {
+            TSTypeReference(node) {
+                if (!importsSxProps || hasTypeArguments(node)) {
+                    return;
+                }
+                const scope = ASTHelpers_1.ASTHelpers.getScope(context, node);
+                if (!isReportableSxProps(node.typeName, scope)) {
+                    return;
+                }
+                const plan = planFix(node, scope);
+                context.report({
+                    node,
+                    messageId: 'requireSxPropsTheme',
+                    data: { typeName: sourceCode.getText(node.typeName) },
+                    // Each report carries its own import edit so any single fix is
+                    // complete on its own. Two reports editing the same import overlap,
+                    // so ESLint applies one per pass and the next pass sees `Theme`
+                    // imported and needs only the insertions.
+                    fix: plan
+                        ? (fixer) => {
+                            const fixes = [
+                                fixer.insertTextAfter(node.typeName, `<${plan.themeText}>`),
+                            ];
+                            if (plan.importFix) {
+                                fixes.push(plan.importFix(fixer));
+                            }
+                            return fixes;
+                        }
+                        : null,
+                });
+            },
+        };
+    },
+});
+//# sourceMappingURL=require-sx-props-theme.js.map

package/lib/utils/fixtureTypeProgram.js

@@ -465,6 +465,51 @@ declare module 'functions/src/util/assertSafe' {
   export function assertSafe<T extends PropertyKey>(key: T): T;
 }
 `;
+/**
+ * `@mui/material/styles`, the module `require-sx-props-theme` draws `Theme`
+ * from, and `@mui/system/styleFunctionSx`, the deepest `SxProps` it rewrites.
+ * Under the wildcard alone a named import is a VALUE of type `any`, so writing
+ * `SxProps` or `Theme` in a type position is TS2709 on the input and output
+ * alike, and every pair of that fixer was held out. It earns a shape under the
+ * stated policy: the fix writes a type argument drawn from this module, and a
+ * wrong one — an unbound `Theme`, a second `Theme` import, a namespace member
+ * that does not exist — is a type error.
+ *
+ * `SxProps` is the shipped union from `styleFunctionSx.d.ts`, with
+ * `SystemStyleObject` reduced to an open record: the CSS property types add
+ * noise, not detection. `Theme` is open for the same reason, so a fixture
+ * reading `theme.palette.*` or augmenting the interface still compiles.
+ * `useTheme` and `createTheme` carry their shipped signatures because other
+ * rules' fixtures import them from here; the barrel `@mui/material` and
+ * `@mui/system` stay on the wildcard, since fixtures import members from them
+ * that exist in no typings (`FlexRow`, `CustomWidget`).
+ */
+const MUI_SX_PROPS_SHAPE = `
+  type SystemStyleObject<Theme extends object = {}> = { [key: string]: any };
+  export type SxProps<Theme extends object = {}> =
+    | SystemStyleObject<Theme>
+    | ((theme: Theme) => SystemStyleObject<Theme>)
+    | ReadonlyArray<
+        | boolean
+        | SystemStyleObject<Theme>
+        | ((theme: Theme) => SystemStyleObject<Theme>)
+      >;
+`;
+const MUI_STYLES_STUB = `
+declare module '@mui/material/styles' {
+  export interface Theme { [key: string]: any }
+  ${MUI_SX_PROPS_SHAPE}
+  export function useTheme<T = Theme>(): T;
+  export function createTheme(options?: any, ...args: object[]): Theme;
+  export const styled: any;
+  export type CSSObject = any;
+  export type Mixins = any;
+  export type Shadows = any;
+}
+declare module '@mui/system/styleFunctionSx' {
+  ${MUI_SX_PROPS_SHAPE}
+}
+`;
 exports.STUBS = `
 declare module '*';
 ${exports.REACT_STUB}
@@ -472,6 +517,7 @@ ${exports.FIRESTORE_ADMIN_STUB}
 ${exports.FIRESTORE_CLIENT_STUB}
 ${exports.SUBSTITUTION_PARTNER_STUBS}
 ${ASSERT_SAFE_STUB}
+${MUI_STYLES_STUB}
 declare namespace JSX {
   interface IntrinsicElements { [k: string]: any }
   interface Element {}

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "1.23.0",
+    "date": "2026-09-30T00:56:19.228Z",
+    "rules": [
+      {
+        "name": "require-sx-props-theme",
+        "changeType": "feat",
+        "issues": [
+          2399
+        ],
+        "summary": "require a theme argument on MUI SxProps (closes #2399) (#2401)"
+      }
+    ]
+  },
   {
     "version": "1.22.0",
     "date": "2026-09-27T06:08:08.588Z",