@blumintinc/eslint-plugin-blumint 1.18.0 → 1.18.1

package/lib/index.js

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

package/lib/rules/consistent-callback-naming.js

@@ -142,6 +142,45 @@ module.exports = (0, createRule_1.createRule)({
                 return false;
             });
         }
+        // An event-handler callback's return value is discarded: `void`, `undefined`,
+        // `never`, or a `Promise` thereof. Anything else is a value the caller
+        // consumes, which marks the prop as an accessor rather than a handler.
+        function returnsVoidLike(type) {
+            if (type.isUnion()) {
+                return type.types.every((member) => returnsVoidLike(member));
+            }
+            if (type.flags &
+                (ts.TypeFlags.Void | ts.TypeFlags.Undefined | ts.TypeFlags.Never)) {
+                return true;
+            }
+            // `Promise<void>` (async handlers) unwraps to its resolved type.
+            if (type.getSymbol()?.getName() === 'Promise') {
+                const typeArgs = checker.getTypeArguments(type);
+                if (typeArgs.length === 1) {
+                    return returnsVoidLike(typeArgs[0]);
+                }
+            }
+            return false;
+        }
+        // A function-typed prop is an accessor (getRowId, valueGetter, filterOptions,
+        // a per-item props deriver, ...) rather than an event handler when its call
+        // signature returns a value the component consumes instead of a discarded
+        // `void`. The `on` prefix signals event handlers, so accessors are exempt.
+        // The prop's declared (contextual) type is authoritative because the passed
+        // value's inferred return type can be wider than the prop contract.
+        function isValueAccessor(node) {
+            const tsNode = parserServices.esTreeNodeToTSNodeMap.get(node);
+            const contextualType = checker.getContextualType(tsNode);
+            const type = contextualType ?? checker.getTypeAtLocation(tsNode);
+            const members = type.isUnion() ? type.types : [type];
+            const signatures = members.flatMap((member) => member.getCallSignatures());
+            if (signatures.length === 0) {
+                return false;
+            }
+            // Exempt only when every call signature returns a consumed value; a mix
+            // that includes a void-returning signature keeps the handler semantics.
+            return signatures.every((signature) => !returnsVoidLike(checker.getReturnTypeOfSignature(signature)));
+        }
         return {
             // Check JSX attributes for callback props
             JSXAttribute(node) {
@@ -190,6 +229,7 @@ module.exports = (0, createRule_1.createRule)({
                         !propName.startsWith('on') &&
                         !propName.startsWith('render') &&
                         !acceptsNonFunctionValue(node.value.expression) &&
+                        !isValueAccessor(node.value.expression) &&
                         !isRenderFunction(node.value.expression) &&
                         !isReactComponentType(node.value.expression)) {
                         const eventName = propName.charAt(0).toUpperCase() + propName.slice(1);

package/lib/rules/enforce-positive-naming.js

@@ -851,6 +851,12 @@ const DIS_EXCEPTIONS = [
     'disputed',
     'disputes',
     'disputing',
+    // "disabled" is a single English adjective and the native HTML/React/MUI prop
+    // name; its "dis" is a bound morpheme, not a separable negation of "abled".
+    'disable',
+    'disabled',
+    'disables',
+    'disabling',
 ];
 // Words that contain negative prefixes but should be treated as valid
 const EXCEPTION_WORDS_SET = new Set([...IN_EXCEPTIONS, ...NO_EXCEPTIONS, ...UN_EXCEPTIONS, ...DIS_EXCEPTIONS].map((word) => word.toLowerCase()));

package/lib/rules/enforce-types-directory-placement.d.ts

@@ -3,6 +3,7 @@ type Options = [
         typesDirectory?: string;
         excludePatterns?: string[];
         includePaths?: string[];
+        frontendCoupledImportPatterns?: string[];
     }
 ];
 export declare const enforceTypesDirectoryPlacement: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"typeOnlyFileOutsideTypesDir", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;

package/lib/rules/enforce-types-directory-placement.js

@@ -9,6 +9,18 @@ const utils_1 = require("@typescript-eslint/utils");
 const minimatch_1 = require("minimatch");
 const createRule_1 = require("../utils/createRule");
 const DEFAULT_TYPES_DIRECTORY = 'functions/src/types';
+// A type-only file that imports one of these frontend-only module families is
+// frontend-scoped: it cannot be relocated under `functions/src/types/**`, since
+// that directory is compiled by the backend tsconfig and the backend must not
+// import from `src/` (frontend). Such files have no valid backend target and
+// legitimately live under `src/`, so the rule exempts them. Matched against
+// absolute specifiers directly and against relative specifiers after resolving
+// them relative to the importing file (so backend files importing relatively —
+// which resolve to `functions/src/**` — stay flagged).
+const DEFAULT_FRONTEND_COUPLED_IMPORT_PATTERNS = [
+    'src/components/**',
+    'src/hooks/**',
+];
 const DEFAULT_EXCLUDE_PATTERNS = [
     '**/*.d.ts',
     '**/*.test.ts',
@@ -62,6 +74,57 @@ function suggestTargetPath(filePath, typesDirectory) {
     }
     return null;
 }
+/**
+ * Extracts the repo-relative portion of a path starting at `functions/src/`
+ * (backend) or `src/` (frontend), so absolute filenames and resolved relative
+ * specifiers match the same globs the rest of the rule uses. Backend is checked
+ * first because a backend path also contains `src/`.
+ */
+function toRepoRelative(filePath) {
+    const normalized = normalizePath(filePath);
+    const match = normalized.match(/(?:^|\/)(functions\/src\/.*|src\/.*)$/);
+    return match ? match[1] : normalized;
+}
+/**
+ * Resolves an import/export module specifier to a repo-relative path for glob
+ * matching. Relative specifiers are resolved against the importing file's
+ * directory (so `./DialogHeader` from `src/components/dialog/x.ts` becomes
+ * `src/components/dialog/DialogHeader`); bare/absolute specifiers are used as-is.
+ */
+function resolveSpecifier(specifier, fromFile) {
+    if (specifier.startsWith('.')) {
+        const dir = path_1.default.posix.dirname(normalizePath(fromFile));
+        return toRepoRelative(path_1.default.posix.join(dir, specifier));
+    }
+    return toRepoRelative(specifier);
+}
+/**
+ * Returns the module specifier of a top-level import/export statement that
+ * carries a `from '...'` source, or null for statements that don't.
+ */
+function importSourceOf(node) {
+    if (node.type === utils_1.AST_NODE_TYPES.ImportDeclaration ||
+        node.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration ||
+        node.type === utils_1.AST_NODE_TYPES.ExportAllDeclaration) {
+        const source = node.source;
+        return source && typeof source.value === 'string' ? source.value : null;
+    }
+    return null;
+}
+/**
+ * Returns true when the file imports at least one frontend-coupled module,
+ * meaning it cannot be relocated under the backend types directory.
+ */
+function isFrontendCoupled(body, fromFile, matchers) {
+    return body.some((stmt) => {
+        const specifier = importSourceOf(stmt);
+        if (specifier === null) {
+            return false;
+        }
+        const resolved = resolveSpecifier(specifier, fromFile);
+        return matchers.some((mm) => mm.match(resolved));
+    });
+}
 /**
  * Returns true when the given top-level statement is "type-only":
  * - ImportDeclaration (imports alone are not runtime code)
@@ -194,6 +257,11 @@ exports.enforceTypesDirectoryPlacement = (0, createRule_1.createRule)({
                         items: { type: 'string' },
                         default: DEFAULT_INCLUDE_PATHS,
                     },
+                    frontendCoupledImportPatterns: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: DEFAULT_FRONTEND_COUPLED_IMPORT_PATTERNS,
+                    },
                 },
                 additionalProperties: false,
             },
@@ -208,12 +276,15 @@ exports.enforceTypesDirectoryPlacement = (0, createRule_1.createRule)({
             typesDirectory: DEFAULT_TYPES_DIRECTORY,
             excludePatterns: DEFAULT_EXCLUDE_PATTERNS,
             includePaths: DEFAULT_INCLUDE_PATHS,
+            frontendCoupledImportPatterns: DEFAULT_FRONTEND_COUPLED_IMPORT_PATTERNS,
         },
     ],
     create(context, [options]) {
         const typesDirectory = options.typesDirectory ?? DEFAULT_TYPES_DIRECTORY;
         const excludePatterns = options.excludePatterns ?? DEFAULT_EXCLUDE_PATTERNS;
         const includePaths = options.includePaths ?? DEFAULT_INCLUDE_PATHS;
+        const frontendCoupledImportPatterns = options.frontendCoupledImportPatterns ??
+            DEFAULT_FRONTEND_COUPLED_IMPORT_PATTERNS;
         const filename = context.getFilename();
         // Skip synthetic filenames used by RuleTester when no filename is provided.
         if (filename === '<input>' || filename === '<text>') {
@@ -251,9 +322,16 @@ exports.enforceTypesDirectoryPlacement = (0, createRule_1.createRule)({
                 return {};
             }
         }
+        const frontendCoupledMatchers = frontendCoupledImportPatterns.map((pattern) => new minimatch_1.Minimatch(pattern, { dot: true }));
         return {
             Program(programNode) {
-                if (!isTypeOnlyFile(programNode.body)) {
+                const body = programNode.body;
+                if (!isTypeOnlyFile(body)) {
+                    return;
+                }
+                // A frontend-coupled type file has no valid target under the backend
+                // types directory, so it must not be flagged (issue #1263).
+                if (isFrontendCoupled(body, normalizedFilename, frontendCoupledMatchers)) {
                     return;
                 }
                 const suggested = suggestTargetPath(normalizedFilename, typesDirectory);

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

@@ -3,6 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const isUpperSnakeCase = (str) => /^[A-Z][A-Z0-9_]*$/.test(str);
+// Next.js recognizes these export names by their literal identifier, so
+// renaming them to UPPER_SNAKE_CASE silently breaks the framework contract
+// (e.g. `export const config` controls the API-route body parser / runtime).
+// Only the export name matters to Next.js, so the exemption is gated on the
+// declaration being exported — a local, unexported `config` is safe to rename.
+const NEXTJS_RESERVED_EXPORTS = new Set([
+    'config',
+    'getServerSideProps',
+    'getStaticProps',
+    'getStaticPaths',
+    'getInitialProps',
+    'middleware',
+]);
 exports.default = (0, createRule_1.createRule)({
     name: 'global-const-style',
     meta: {
@@ -185,6 +198,15 @@ exports.default = (0, createRule_1.createRule)({
                             });
                         }
                     }
+                    // Skip the rename for exported Next.js reserved export names. Their
+                    // identifier is an external framework contract that cannot be
+                    // statically verified as safe to rename, so autofixing the rename
+                    // silently regresses behavior (Issue #1257). The `as const` check
+                    // above still applies since it never touches the export name.
+                    const isExported = node.parent?.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration;
+                    if (isExported && NEXTJS_RESERVED_EXPORTS.has(name)) {
+                        return;
+                    }
                     // Check for UPPER_SNAKE_CASE
                     if (!isUpperSnakeCase(name)) {
                         const newName = name

package/lib/rules/no-hungarian.js

@@ -339,7 +339,31 @@ exports.noHungarian = (0, createRule_1.createRule)({
                 if (normalizedVarName === normalizedMarker) {
                     return false;
                 }
-                // Check if it's a prefix with proper boundary (e.g., strName, numCount)
+                // Abbreviation markers (str, num, int, bool, arr, obj) are short enough
+                // that the raw-character boundary checks below fire on them as
+                // substrings inside real English words (e.g. "int" inside "Mint", "str"
+                // inside "stream"). The ONLY correct test for an abbreviation marker is
+                // therefore an exact match against a full camelCase segment: "Mint" →
+                // ["Mint"] never matches "int", while genuine Hungarian like intValue →
+                // ["int","Value"] still does.
+                //
+                // This guard MUST run before the prefix/suffix boundary checks. A
+                // capitalized terminal segment makes its own initial capital double as
+                // the raw suffix-boundary character: "appendHoldHint" ends with the
+                // marker "int" AND its preceding char is the capital "H" of "Hint", so
+                // the suffix check below would short-circuit to `true` and short-circuit
+                // this guard entirely (issue #1258). Because it always returns, an
+                // abbreviation marker never reaches the raw-character heuristics, so
+                // words like Hint/Blueprint/Waypoint/Checkpoint/Paint are spared.
+                if (ABBREVIATION_MARKER_SET.has(normalizedMarker)) {
+                    const segments = splitCamelSegments(variableName);
+                    return segments.some((s) => s.toLowerCase() === normalizedMarker);
+                }
+                // The prefix/suffix boundary checks below apply only to FULL type-word
+                // markers (String, Number, Boolean, Array, Object, ...); abbreviation
+                // markers have already returned above.
+                // Check if it's a prefix with proper boundary (e.g., stringValue,
+                // numberCount)
                 if (normalizedVarName.startsWith(normalizedMarker) &&
                     normalizedVarName.length > normalizedMarker.length &&
                     /[A-Z0-9]/.test(variableName[normalizedMarker.length])) {
@@ -352,16 +376,6 @@ exports.noHungarian = (0, createRule_1.createRule)({
                         /[A-Z]/.test(variableName[variableName.length - normalizedMarker.length]))) {
                     return true;
                 }
-                // Abbreviation markers (str, num, int, bool, arr, obj, fn, func) are
-                // short enough that a raw-character boundary check can fire on them as
-                // substrings inside real English words (e.g. "int" inside "Mint", "str"
-                // inside "stream"). Require an exact match against a full camelCase
-                // token so that "Mint" → ["Mint"] never matches "int", while genuine
-                // Hungarian like intValue → ["int","Value"] still does.
-                if (ABBREVIATION_MARKER_SET.has(normalizedMarker)) {
-                    const segments = splitCamelSegments(variableName);
-                    return segments.some((s) => s.toLowerCase() === normalizedMarker);
-                }
                 // Full type-word markers (non-abbreviations: String, Number, Function,
                 // Array, Object, Boolean, …) are Hungarian only when they occupy the
                 // first or last camelCase segment — a genuine prefix or suffix that

package/lib/rules/prefer-use-theme.d.ts

@@ -1 +1,3 @@
-export declare const preferUseTheme: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"preferUseTheme", [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+type MessageIds = 'preferUseTheme' | 'preferUseThemeNoEquivalent';
+export declare const preferUseTheme: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<MessageIds, [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};

package/lib/rules/prefer-use-theme.js

@@ -50,7 +50,9 @@ const BANNED_CONSTANTS = new Set([
 /**
  * Map from constant name to its theme-object equivalent path, used in the
  * error message so that developers know exactly where to find the value on the
- * theme object.
+ * theme object. Only constants that map to a value the theme actually carries
+ * appear here; constants without a faithful location are listed in
+ * CONSTANTS_WITHOUT_THEME_EQUIVALENT and get the no-equivalent message instead.
  */
 const THEME_EQUIVALENTS = {
     PALETTE: 'theme.palette',
@@ -70,9 +72,20 @@ const THEME_EQUIVALENTS = {
     ZINDEX: 'theme.zIndex',
     ASPECT_RATIO: 'theme.aspectRatio',
     BREAKPOINTS: 'theme.breakpoints',
-    BORDER_RADIUS: 'theme.shape.borderRadius',
-    CONTAINER_WIDTH: 'theme.mixins',
 };
+/**
+ * Banned constants that have NO faithful single location on the theme object:
+ * - BORDER_RADIUS is the full M3 shape scale; `theme.shape.borderRadius` is
+ *   MUI's default `4`, not this scale — following that hint ships a visual
+ *   regression, so the message points at real alternatives instead.
+ * - CONTAINER_WIDTH is not carried anywhere on the theme today.
+ * These still bypass the theme system, so they remain flagged — but with the
+ * no-equivalent message rather than a mapping that misdirects developers.
+ */
+const CONSTANTS_WITHOUT_THEME_EQUIVALENT = new Set([
+    'BORDER_RADIUS',
+    'CONTAINER_WIDTH',
+]);
 /**
  * Target file path fragments that the rule enforces inside. Files outside
  * these directories are not flagged — this avoids false positives in utility
@@ -130,13 +143,20 @@ exports.preferUseTheme = (0, createRule_1.createRule)({
         schema: [],
         messages: {
             preferUseTheme: "Import '{{importName}}' from '{{sourceModule}}' bypasses the MUI theme system. Use useTheme() and access {{themeEquivalent}} instead.",
+            preferUseThemeNoEquivalent: "Import '{{importName}}' from '{{sourceModule}}' bypasses the MUI theme system. This constant has no direct equivalent on the theme object: reuse a theme token that already carries the value (e.g. theme.panels[n].borderRadius) or add {{importName}} to the theme in src/styles/theme.ts and read it via useTheme().",
         },
     },
     defaultOptions: [],
     create(context) {
-        const filename = context.getFilename?.() ??
+        const rawFilename = context.getFilename?.() ??
             context.filename ??
             '';
+        // Normalize Windows backslash separators to forward slashes so the
+        // forward-slash path fragments below (`src/components/`, `src/styles/`,
+        // `__tests__/`) match on every platform. Without this, `getFilename()`
+        // returns `C:\repo\src\components\Foo.tsx` on Windows, `isInTargetPath`
+        // never matches, and the rule silently no-ops for every file (issue #1259).
+        const filename = rawFilename.replace(/\\/g, '/');
         // Files that build the theme are always exempt.
         if (isInStylesDir(filename)) {
             return {};
@@ -186,6 +206,19 @@ exports.preferUseTheme = (0, createRule_1.createRule)({
                         if (!BANNED_CONSTANTS.has(importedName)) {
                             continue;
                         }
+                        // Constants without a faithful theme location get guidance toward
+                        // real alternatives rather than a mapping that misdirects (issue #1260).
+                        if (CONSTANTS_WITHOUT_THEME_EQUIVALENT.has(importedName)) {
+                            context.report({
+                                node: specifier,
+                                messageId: 'preferUseThemeNoEquivalent',
+                                data: {
+                                    importName: importedName,
+                                    sourceModule: source,
+                                },
+                            });
+                            continue;
+                        }
                         const themeEquivalent = THEME_EQUIVALENTS[importedName] ??
                             'the theme object via useTheme()';
                         context.report({

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,59 @@
 [
+  {
+    "version": "1.18.1",
+    "date": "2026-07-06T03:35:53.804Z",
+    "rules": [
+      {
+        "name": "consistent-callback-naming",
+        "changeType": "fix",
+        "issues": [
+          1262
+        ],
+        "summary": "exempt value-returning accessor props (closes #1262)"
+      },
+      {
+        "name": "enforce-positive-naming",
+        "changeType": "fix",
+        "issues": [
+          1261
+        ],
+        "summary": "treat the \"disabled\" word family as valid (closes #1261)"
+      },
+      {
+        "name": "enforce-types-directory-placement",
+        "changeType": "fix",
+        "issues": [
+          1263
+        ],
+        "summary": "exempt frontend-coupled type files (closes #1263)"
+      },
+      {
+        "name": "global-const-style",
+        "changeType": "fix",
+        "issues": [
+          1257
+        ],
+        "summary": "exempt Next.js reserved exports from autofix rename (closes #1257)"
+      },
+      {
+        "name": "no-hungarian",
+        "changeType": "fix",
+        "issues": [
+          1258
+        ],
+        "summary": "don't flag words ending in an abbreviation marker (closes #1258)"
+      },
+      {
+        "name": "prefer-use-theme",
+        "changeType": "fix",
+        "issues": [
+          1259,
+          1260
+        ],
+        "summary": "stop pointing BORDER_RADIUS/CONTAINER_WIDTH at absent theme paths (closes #1260); normalize Windows path separators before path checks (closes #1259)"
+      }
+    ]
+  },
   {
     "version": "1.18.0",
     "date": "2026-07-02T16:19:34.385Z",