@blumintinc/eslint-plugin-blumint 1.12.6 → 1.14.0

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 {};