@blumintinc/eslint-plugin-blumint 1.13.0 → 1.14.0

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

@@ -14,8 +14,8 @@ exports.default = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            upperSnakeCase: 'Global constants should be in UPPER_SNAKE_CASE',
-            asConst: 'Global constants should use "as const"',
+            upperSnakeCase: 'Global constant "{{name}}" should be written in UPPER_SNAKE_CASE (e.g., "{{suggestedName}}") so it reads as a module-level configuration value that never changes; rename it to make its immutability obvious.',
+            asConst: 'Global constant "{{name}}" is initialized with {{valueKind}} but lacks `as const`, so TypeScript widens the type and code can mutate it accidentally; append `as const` to freeze the value and preserve literal types.',
         },
     },
     defaultOptions: [],
@@ -23,6 +23,27 @@ exports.default = (0, createRule_1.createRule)({
         // Check if the file is a TypeScript file
         const isTypeScript = context.getFilename().endsWith('.ts') ||
             context.getFilename().endsWith('.tsx');
+        const unwrapAssertions = (node) => {
+            let target = node;
+            while (target.type === utils_1.AST_NODE_TYPES.TSTypeAssertion ||
+                target.type === utils_1.AST_NODE_TYPES.TSAsExpression) {
+                target = target.expression;
+            }
+            return target;
+        };
+        const describeValueKind = (node) => {
+            const target = unwrapAssertions(node);
+            if (target.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
+                return 'an array literal';
+            }
+            if (target.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                return 'an object literal';
+            }
+            if (target.type === utils_1.AST_NODE_TYPES.Literal) {
+                return 'a literal value';
+            }
+            return 'a value';
+        };
         return {
             VariableDeclaration(node) {
                 // Only check top-level const declarations
@@ -87,7 +108,7 @@ exports.default = (0, createRule_1.createRule)({
                         init.type === utils_1.AST_NODE_TYPES.NewExpression) {
                         return;
                     }
-                    const sourceCode = context.getSourceCode();
+                    const sourceCode = context.sourceCode;
                     const initText = sourceCode.getText(init);
                     const typeAnnotation = declaration.id.typeAnnotation;
                     const typeText = typeAnnotation
@@ -95,42 +116,48 @@ exports.default = (0, createRule_1.createRule)({
                         : '';
                     // Only check for as const in TypeScript files
                     if (isTypeScript) {
-                        const isAsConstExpression = (node) => {
-                            if (node.type === utils_1.AST_NODE_TYPES.TSAsExpression) {
-                                return (node.typeAnnotation?.type ===
-                                    utils_1.AST_NODE_TYPES.TSTypeReference &&
-                                    node.typeAnnotation?.typeName
-                                        ?.name === 'const');
+                        const hasAsConstAssertion = (node) => {
+                            let current = node;
+                            while (current &&
+                                (current.type === utils_1.AST_NODE_TYPES.TSAsExpression ||
+                                    current.type === utils_1.AST_NODE_TYPES.TSTypeAssertion)) {
+                                const { typeAnnotation } = current;
+                                if (typeAnnotation?.type === utils_1.AST_NODE_TYPES.TSTypeReference &&
+                                    typeAnnotation.typeName.type === utils_1.AST_NODE_TYPES.Identifier &&
+                                    typeAnnotation.typeName.name === 'const') {
+                                    return true;
+                                }
+                                current = current.expression;
                             }
                             return false;
                         };
                         const shouldHaveAsConst = (node) => {
                             // Skip if it's already an as const expression
-                            if (isAsConstExpression(node)) {
+                            if (hasAsConstAssertion(node)) {
                                 return false;
                             }
-                            // Handle type assertions
-                            if (node.type === utils_1.AST_NODE_TYPES.TSTypeAssertion ||
-                                node.type === utils_1.AST_NODE_TYPES.TSAsExpression) {
-                                return shouldHaveAsConst(node.expression);
-                            }
+                            const target = unwrapAssertions(node);
                             // Skip if there's an explicit type annotation
                             if (declaration.id.typeAnnotation) {
                                 return false;
                             }
                             // Check if it's a literal, array, or object that should have as const
                             // Skip regular expressions as they are already immutable
-                            if (node.type === utils_1.AST_NODE_TYPES.Literal && 'regex' in node) {
+                            if (target.type === utils_1.AST_NODE_TYPES.Literal && 'regex' in target) {
                                 return false;
                             }
-                            return (node.type === utils_1.AST_NODE_TYPES.Literal ||
-                                node.type === utils_1.AST_NODE_TYPES.ArrayExpression ||
-                                node.type === utils_1.AST_NODE_TYPES.ObjectExpression);
+                            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);
                         };
                         if (shouldHaveAsConst(init)) {
                             context.report({
                                 node: declaration,
                                 messageId: 'asConst',
+                                data: {
+                                    name,
+                                    valueKind: describeValueKind(init),
+                                },
                                 fix(fixer) {
                                     return fixer.replaceText(init, `${initText} as const`);
                                 },
@@ -146,6 +173,10 @@ exports.default = (0, createRule_1.createRule)({
                         context.report({
                             node: declaration,
                             messageId: 'upperSnakeCase',
+                            data: {
+                                name,
+                                suggestedName: newName,
+                            },
                             fix(fixer) {
                                 if (typeAnnotation) {
                                     return fixer.replaceText(declaration, `${newName}${typeText} = ${initText}`);

package/lib/rules/jsdoc-above-field.d.ts

@@ -0,0 +1,11 @@
+type Options = [
+    {
+        /**
+         * When true, the rule also flags inline JSDoc on object literal properties.
+         * By default, only interface/type literals and class fields are checked.
+         */
+        checkObjectLiterals?: boolean;
+    }
+];
+export declare const jsdocAboveField: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<"moveJsdocAbove", Options, import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+export {};

package/lib/rules/jsdoc-above-field.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsdocAboveField = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createRule_1 = require("../utils/createRule");
+const defaultOptions = [{ checkObjectLiterals: false }];
+exports.jsdocAboveField = (0, createRule_1.createRule)({
+    name: 'jsdoc-above-field',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require JSDoc blocks to sit above fields instead of trailing inline so IDE hovers surface the documentation.',
+            recommended: 'error',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    checkObjectLiterals: {
+                        type: 'boolean',
+                        description: 'Also enforce JSDoc placement for object literal properties.',
+                        default: false,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            moveJsdocAbove: 'Inline JSDoc for "{{name}}" sits after the {{kind}} → IDE hovers and autocomplete skip trailing inline JSDoc, so tags like @deprecated/@default never surface when developers hover → Move the JSDoc block above the {{kind}} (and above any decorators or modifiers) so the documentation stays visible where it is needed.',
+        },
+    },
+    defaultOptions,
+    create(context, [options = defaultOptions[0]]) {
+        const sourceCode = context.getSourceCode();
+        const { checkObjectLiterals = false } = options;
+        const allComments = sourceCode.getAllComments();
+        const isRelevantNode = (node) => {
+            if (node.type === utils_1.AST_NODE_TYPES.TSPropertySignature) {
+                return true;
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.PropertyDefinition) {
+                return true;
+            }
+            if (checkObjectLiterals &&
+                node.type === utils_1.AST_NODE_TYPES.Property &&
+                node.parent?.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                return true;
+            }
+            return false;
+        };
+        const isJSDocBlock = (comment) => comment.type === 'Block' && comment.value.startsWith('*');
+        const getPropertyName = (node) => {
+            const key = node.key;
+            if (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 'computed property';
+        };
+        const getKind = (node) => {
+            if (node.type === utils_1.AST_NODE_TYPES.PropertyDefinition) {
+                return 'class field';
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.Property) {
+                return 'object property';
+            }
+            return 'type field';
+        };
+        const inlineJSDocOnSameLine = (node) => {
+            return allComments.find((comment) => {
+                if (!isJSDocBlock(comment)) {
+                    return false;
+                }
+                if (comment.loc.start.line !== node.loc.end.line) {
+                    return false;
+                }
+                if (comment.range[0] < node.range[1]) {
+                    return false;
+                }
+                const between = sourceCode.text.slice(node.range[1], comment.range[0]);
+                return /^[\s;,]*$/.test(between);
+            });
+        };
+        const indentForNode = (node) => {
+            const line = sourceCode.lines[node.loc.start.line - 1] ?? '';
+            const beforeColumn = line.slice(0, node.loc.start.column);
+            const trailingWhitespace = beforeColumn.match(/\s*$/);
+            return trailingWhitespace?.[0] ?? '';
+        };
+        const formatCommentWithIndent = (comment, indent) => {
+            const rawText = sourceCode.getText(comment);
+            const rawLines = rawText.split('\n');
+            let minIndentAfterStar;
+            // Calculate minimum indentation across all lines (excluding the first line and standard closing line)
+            rawLines.slice(1).forEach((line, index, arr) => {
+                const isLastLine = index === arr.length - 1;
+                const starMatch = line.match(/^\s*\*(.*)$/);
+                if (!starMatch) {
+                    return;
+                }
+                const afterStar = starMatch[1];
+                // Skip the standard " */" closing line
+                if (isLastLine && afterStar.trim() === '/') {
+                    return;
+                }
+                const contentIndent = afterStar.match(/^([ \t]*)\S/);
+                if (contentIndent) {
+                    const indentLength = contentIndent[1].length;
+                    minIndentAfterStar =
+                        minIndentAfterStar === undefined
+                            ? indentLength
+                            : Math.min(minIndentAfterStar, indentLength);
+                }
+            });
+            // Normalize indentation: we want the minimum indentation after '*' to be exactly 1 space.
+            // (e.g., if min indent is 3, we strip 2; if min indent is 0, we add 1).
+            const indentToAdjustment = minIndentAfterStar === undefined ? 0 : minIndentAfterStar - 1;
+            const normalize = (text) => {
+                if (indentToAdjustment > 0) {
+                    return text.replace(new RegExp(`^[ \\t]{0,${indentToAdjustment}}`), '');
+                }
+                if (indentToAdjustment < 0) {
+                    return ' '.repeat(-indentToAdjustment) + text;
+                }
+                return text;
+            };
+            const normalizedLines = rawLines.map((line, index) => {
+                if (index === 0) {
+                    return line.trimStart();
+                }
+                const starMatch = line.match(/^\s*\*(.*)$/);
+                if (!starMatch) {
+                    return line.trimStart();
+                }
+                const afterStar = normalize(starMatch[1]);
+                if (afterStar.trim() === '/') {
+                    return ' */';
+                }
+                if (afterStar.trim() === '') {
+                    return ' *';
+                }
+                const needsSpace = !afterStar.startsWith(' ') && !afterStar.startsWith('\t');
+                const content = needsSpace ? ` ${afterStar}` : afterStar;
+                return ` *${content}`;
+            });
+            return normalizedLines.map((line) => `${indent}${line}`).join('\n');
+        };
+        const reportInlineJSDoc = (node, comment) => {
+            const insertTarget = node.type === utils_1.AST_NODE_TYPES.PropertyDefinition &&
+                node.decorators &&
+                node.decorators.length > 0
+                ? node.decorators[0]
+                : node;
+            const indent = indentForNode(insertTarget);
+            const commentText = formatCommentWithIndent(comment, indent);
+            let removalStart = comment.range[0];
+            const removalEnd = comment.range[1];
+            const lineStart = insertTarget.range[0] - insertTarget.loc.start.column;
+            const textBeforeNode = sourceCode.text.slice(lineStart, insertTarget.range[0]);
+            const hasCodeBeforeNode = /\S/.test(textBeforeNode);
+            const insertionPoint = hasCodeBeforeNode
+                ? insertTarget.range[0]
+                : lineStart;
+            const insertionText = hasCodeBeforeNode
+                ? `\n${commentText}\n${indent}`
+                : `${commentText}\n`;
+            while (removalStart > node.range[1] &&
+                /\s/.test(sourceCode.text[removalStart - 1])) {
+                removalStart -= 1;
+            }
+            context.report({
+                node,
+                loc: comment.loc,
+                messageId: 'moveJsdocAbove',
+                data: {
+                    name: getPropertyName(node),
+                    kind: getKind(node),
+                },
+                fix(fixer) {
+                    return [
+                        fixer.insertTextBeforeRange([insertionPoint, insertionPoint], insertionText),
+                        fixer.removeRange([removalStart, removalEnd]),
+                    ];
+                },
+            });
+        };
+        const checkNode = (node) => {
+            if (!isRelevantNode(node)) {
+                return;
+            }
+            const jsdocComment = inlineJSDocOnSameLine(node);
+            if (!jsdocComment) {
+                return;
+            }
+            reportInlineJSDoc(node, jsdocComment);
+        };
+        return {
+            TSPropertySignature: checkNode,
+            PropertyDefinition: checkNode,
+            ...(checkObjectLiterals && { Property: checkNode }),
+        };
+    },
+});
+//# sourceMappingURL=jsdoc-above-field.js.map

package/lib/rules/key-only-outermost-element.js

@@ -2,6 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.keyOnlyOutermostElement = void 0;
 const createRule_1 = require("../utils/createRule");
+const getJSXElementName = (name) => {
+    if (name.type === 'JSXIdentifier') {
+        return name.name;
+    }
+    if (name.type === 'JSXMemberExpression') {
+        const objectName = name.object.type === 'JSXIdentifier'
+            ? name.object.name
+            : getJSXElementName(name.object);
+        return `${objectName}.${name.property.name}`;
+    }
+    if (name.type === 'JSXNamespacedName') {
+        return `${name.namespace.name}:${name.name.name}`;
+    }
+    return 'element';
+};
 exports.keyOnlyOutermostElement = (0, createRule_1.createRule)({
     name: 'key-only-outermost-element',
     meta: {
@@ -11,8 +26,8 @@ exports.keyOnlyOutermostElement = (0, createRule_1.createRule)({
             recommended: 'error',
         },
         messages: {
-            keyOnlyOutermostElement: 'Only the outermost element in a list rendering should have a key prop. Remove the key from this nested element.',
-            fragmentShouldHaveKey: 'Fragment used as the outermost element in a list should use <React.Fragment key={...}> instead of shorthand syntax.',
+            keyOnlyOutermostElement: 'Nested element "{{elementName}}" has a key even though the list item already owns the identity. React reconciles list items using the key on the outermost element; nested keys create redundant identities and can mask ordering bugs. Remove this nested key and keep the key only on the element returned from map().',
+            fragmentShouldHaveKey: 'List items returned as fragments need a key on the fragment. Shorthand fragments (<></>) cannot accept keys, so React cannot track each item when the list reorders. Replace the shorthand with <React.Fragment key={...}> or another keyed wrapper so every list item has a stable identity.',
         },
         schema: [],
         fixable: 'code',
@@ -104,10 +119,13 @@ exports.keyOnlyOutermostElement = (0, createRule_1.createRule)({
                         if (isNestedInMapCallback) {
                             // Mark this attribute as reported to avoid duplicate reports
                             reportedAttributes.add(attr);
-                            const sourceCode = context.getSourceCode();
+                            const sourceCode = context.sourceCode;
                             context.report({
                                 node: attr,
                                 messageId: 'keyOnlyOutermostElement',
+                                data: {
+                                    elementName: getJSXElementName(openingElement.name),
+                                },
                                 fix(fixer) {
                                     // Find the exact range of the attribute in the source code
                                     const startPos = attr.range[0];

package/lib/rules/logical-top-to-bottom-grouping.d.ts

@@ -0,0 +1,5 @@
+import { TSESLint } from '@typescript-eslint/utils';
+type MessageIds = 'moveGuardUp' | 'groupDerived' | 'moveDeclarationCloser' | 'moveSideEffect';
+type Options = [];
+export declare const logicalTopToBottomGrouping: TSESLint.RuleModule<MessageIds, Options>;
+export {};