@blumintinc/eslint-plugin-blumint 1.13.0 → 1.14.0

package/lib/rules/enforce-unique-cursor-headers.js

@@ -0,0 +1,365 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceUniqueCursorHeaders = exports.RULE_NAME = void 0;
+const path_1 = __importDefault(require("path"));
+const minimatch_1 = require("minimatch");
+const createRule_1 = require("../utils/createRule");
+const DEFAULT_OPTIONS = {
+    requiredPatterns: ['**/*.{ts,tsx,js,jsx}'],
+    excludedPatterns: [
+        '**/*.d.ts',
+        '**/dist/**',
+        '**/build/**',
+        '**/coverage/**',
+    ],
+    requiredTags: ['@fileoverview'],
+    allowSplitHeaders: true,
+    headerTemplate: null,
+    ignoreGeneratedFiles: true,
+    generatedMarkers: [
+        '@generated',
+        'auto-generated',
+        'autogenerated',
+        'do not edit',
+        'do not edit manually',
+    ],
+    excludedAtDirectives: [
+        '@ts-nocheck',
+        '@ts-check',
+        '@ts-ignore',
+        '@ts-expect-error',
+        '@jsx',
+        '@jsxRuntime',
+        '@jsxImportSource',
+        '@format',
+        '@flow',
+        '@jest-environment',
+        '@vitest-environment',
+    ],
+};
+/**
+ * Maximum number of characters to scan at the beginning of a file to detect generated markers.
+ */
+const GENERATED_MARKER_SCAN_LENGTH = 500;
+const normalizeArrayOption = (values, fallback) => values && values.length > 0 ? values : fallback;
+const normalizeArrayOptionAllowEmpty = (values, fallback) => (values === undefined ? fallback : values);
+const normalizeBooleanOption = (value, fallback) => value ?? fallback;
+const normalizeNullableOption = (value, fallback) => (value === undefined ? fallback : value);
+const normalizeOptions = (options) => ({
+    requiredPatterns: normalizeArrayOption(options?.requiredPatterns, DEFAULT_OPTIONS.requiredPatterns),
+    excludedPatterns: normalizeArrayOptionAllowEmpty(options?.excludedPatterns, DEFAULT_OPTIONS.excludedPatterns),
+    requiredTags: normalizeArrayOption(options?.requiredTags, DEFAULT_OPTIONS.requiredTags),
+    allowSplitHeaders: normalizeBooleanOption(options?.allowSplitHeaders, DEFAULT_OPTIONS.allowSplitHeaders),
+    headerTemplate: normalizeNullableOption(options?.headerTemplate, DEFAULT_OPTIONS.headerTemplate),
+    ignoreGeneratedFiles: normalizeBooleanOption(options?.ignoreGeneratedFiles, DEFAULT_OPTIONS.ignoreGeneratedFiles),
+    generatedMarkers: normalizeArrayOptionAllowEmpty(options?.generatedMarkers, DEFAULT_OPTIONS.generatedMarkers),
+    excludedAtDirectives: normalizeArrayOptionAllowEmpty(options?.excludedAtDirectives, DEFAULT_OPTIONS.excludedAtDirectives).map((directive) => directive.toLowerCase()),
+});
+const normalizeCommentValue = (comment) => comment.value
+    .split('\n')
+    .map((line) => line.replace(/^\s*\*\s?/, '').trim())
+    .join('\n')
+    .trim();
+const hasRequiredTags = (text, requiredTagsLower) => {
+    const lowerText = text.toLowerCase();
+    return requiredTagsLower.some((tag) => lowerText.includes(tag));
+};
+const hasAllRequiredTags = (text, requiredTagsLower) => {
+    const lowerText = text.toLowerCase();
+    return requiredTagsLower.every((tag) => lowerText.includes(tag));
+};
+const hasHeaderMarker = (text, excludedAtDirectives) => text.split('\n').some((line) => {
+    const trimmed = line.trimStart();
+    if (!trimmed.startsWith('@')) {
+        return false;
+    }
+    const marker = trimmed.split(/\s+/u)[0].toLowerCase();
+    return !excludedAtDirectives.has(marker);
+});
+const isHeaderCandidate = (text, requiredTagsLower, excludedAtDirectives) => hasRequiredTags(text, requiredTagsLower) ||
+    hasHeaderMarker(text, excludedAtDirectives);
+const isCommentAdjacent = (nextComment, lastComment) => nextComment.loc.start.line <= lastComment.loc.end.line + 1;
+const shouldStopMerging = (groupedHasAllTags, nextHasAllTags) => groupedHasAllTags && nextHasAllTags;
+const updateMergedState = (mergedComments, mergedText, nextComment, nextNormalized, requiredTagsLower) => {
+    const updatedText = `${mergedText}\n${nextNormalized}`.trim();
+    const updatedComments = [...mergedComments, nextComment];
+    const updatedHasAllTags = hasAllRequiredTags(updatedText, requiredTagsLower);
+    return {
+        mergedComments: updatedComments,
+        mergedText: updatedText,
+        groupedHasAllTags: updatedHasAllTags,
+    };
+};
+/**
+ * Merges adjacent header candidate comments into a single group if they are not already complete headers.
+ * This handles "split headers" where metadata is spread across multiple comment blocks.
+ */
+const mergeAdjacentHeaderCandidates = (comments, startIndex, initialComment, initialText, requiredTagsLower, excludedAtDirectives) => {
+    let mergedComments = [initialComment];
+    let mergedText = initialText;
+    let groupedHasAllTags = hasAllRequiredTags(mergedText, requiredTagsLower);
+    let nextIndex = startIndex + 1;
+    while (nextIndex < comments.length) {
+        const nextComment = comments[nextIndex];
+        const lastComment = mergedComments[mergedComments.length - 1];
+        if (!isCommentAdjacent(nextComment, lastComment)) {
+            break;
+        }
+        const nextNormalized = normalizeCommentValue(nextComment);
+        if (!isHeaderCandidate(nextNormalized, requiredTagsLower, excludedAtDirectives)) {
+            break;
+        }
+        const nextHasAllTags = hasAllRequiredTags(nextNormalized, requiredTagsLower);
+        if (shouldStopMerging(groupedHasAllTags, nextHasAllTags)) {
+            break;
+        }
+        const updatedState = updateMergedState(mergedComments, mergedText, nextComment, nextNormalized, requiredTagsLower);
+        mergedComments = updatedState.mergedComments;
+        mergedText = updatedState.mergedText;
+        groupedHasAllTags = updatedState.groupedHasAllTags;
+        nextIndex += 1;
+    }
+    return {
+        mergedComments,
+        mergedText,
+        lastIndex: nextIndex - 1,
+    };
+};
+const collectHeaderGroups = (comments, options, excludedAtDirectives) => {
+    const requiredTagsLower = options.requiredTags.map((tag) => tag.toLowerCase());
+    const groups = [];
+    for (let index = 0; index < comments.length; index += 1) {
+        const comment = comments[index];
+        const normalized = normalizeCommentValue(comment);
+        if (!isHeaderCandidate(normalized, requiredTagsLower, excludedAtDirectives)) {
+            continue;
+        }
+        let groupedComments = [comment];
+        let groupedText = normalized;
+        if (options.allowSplitHeaders) {
+            const merged = mergeAdjacentHeaderCandidates(comments, index, comment, normalized, requiredTagsLower, excludedAtDirectives);
+            groupedComments = merged.mergedComments;
+            groupedText = merged.mergedText;
+            index = merged.lastIndex;
+        }
+        groups.push({ comments: groupedComments, text: groupedText });
+    }
+    return groups;
+};
+const expandRangeToFullLines = (range, sourceText) => {
+    let [start, end] = range;
+    while (start > 0 && sourceText[start - 1] !== '\n') {
+        start -= 1;
+    }
+    while (end < sourceText.length && sourceText[end] !== '\n') {
+        end += 1;
+    }
+    if (end < sourceText.length) {
+        end += 1;
+    }
+    return [start, end];
+};
+// Preserve author-provided trailing newlines while guaranteeing a blank line after the header.
+const buildHeaderInsertionText = (template) => {
+    const normalizedWhitespace = template
+        .replace(/[ \t]+(\r?\n)/gu, '$1')
+        .replace(/[ \t]+$/u, '');
+    const trailingNewlines = normalizedWhitespace.match(/\n+$/u)?.[0].length ?? 0;
+    const requiredNewlines = trailingNewlines >= 2 ? 0 : 2 - trailingNewlines;
+    return `${normalizedWhitespace}${'\n'.repeat(requiredNewlines)}`;
+};
+const shouldSkipGeneratedFile = (sourceText, options) => {
+    if (!options.ignoreGeneratedFiles) {
+        return false;
+    }
+    const prefix = sourceText
+        .slice(0, GENERATED_MARKER_SCAN_LENGTH)
+        .toLowerCase();
+    return options.generatedMarkers.some((marker) => prefix.includes(marker.toLowerCase()));
+};
+const getTopComments = (sourceCode, node) => {
+    const allComments = sourceCode.getAllComments();
+    const firstToken = sourceCode.getFirstToken(node);
+    const firstTokenLine = firstToken?.loc.start.line ?? Infinity;
+    return allComments.filter((comment) => comment.loc.start.line < firstTokenLine);
+};
+const analyzeHeaderGroups = (candidateGroups, options) => {
+    const requiredTagsLower = options.requiredTags.map((tag) => tag.toLowerCase());
+    const headerGroups = candidateGroups.filter((group) => hasAllRequiredTags(group.text, requiredTagsLower));
+    const primaryHeader = headerGroups[0];
+    const duplicateGroups = headerGroups.slice(1);
+    const splitHeaderGroups = options.allowSplitHeaders
+        ? []
+        : candidateGroups.filter((group) => {
+            if (group === primaryHeader || !primaryHeader) {
+                return false;
+            }
+            const groupStart = group.comments[0].loc.start.line;
+            const groupEnd = group.comments[group.comments.length - 1].loc.end.line;
+            const primaryStart = primaryHeader.comments[0].loc.start.line;
+            const primaryEnd = primaryHeader.comments[primaryHeader.comments.length - 1].loc.end
+                .line;
+            /**
+             * Check if group is adjacent to primary (before or after).
+             * The +1 allows for touching lines (no blank line in between).
+             */
+            const isAdjacentToPrimary = groupStart <= primaryEnd + 1 && groupEnd + 1 >= primaryStart;
+            const hasAllTags = hasAllRequiredTags(group.text, requiredTagsLower);
+            return isAdjacentToPrimary && !hasAllTags;
+        });
+    return { primaryHeader, duplicateGroups, splitHeaderGroups };
+};
+const computeHeaderInsertion = (sourceText, headerTemplate) => {
+    const headerText = buildHeaderInsertionText(headerTemplate);
+    if (!sourceText.startsWith('#!')) {
+        return { index: 0, text: headerText };
+    }
+    const shebangNewlineIndex = sourceText.indexOf('\n');
+    if (shebangNewlineIndex === -1) {
+        /** Shebang exists but file has no newline - append after shebang */
+        return { index: sourceText.length, text: `\n${headerText}` };
+    }
+    /** Insert after shebang line */
+    return { index: shebangNewlineIndex + 1, text: headerText };
+};
+const reportMissingHeader = (context, fileName, sourceText, options) => {
+    const template = options.headerTemplate;
+    context.report({
+        loc: { line: 1, column: 0 },
+        messageId: 'missingHeader',
+        data: {
+            fileName: path_1.default.basename(fileName),
+            tags: options.requiredTags.join(', '),
+        },
+        fix: template !== null
+            ? (fixer) => {
+                const { index, text } = computeHeaderInsertion(sourceText, template);
+                return fixer.insertTextBeforeRange([index, index], text);
+            }
+            : null,
+    });
+};
+const reportDuplicates = (context, duplicateGroups, sourceText) => {
+    duplicateGroups.forEach((group) => {
+        const firstComment = group.comments[0];
+        const removalRange = expandRangeToFullLines([
+            firstComment.range[0],
+            group.comments[group.comments.length - 1].range[1],
+        ], sourceText);
+        context.report({
+            loc: firstComment.loc,
+            messageId: 'duplicateHeader',
+            data: {
+                line: firstComment.loc.start.line.toString(),
+            },
+            fix: (fixer) => fixer.removeRange(removalRange),
+        });
+    });
+};
+const reportSplitFragments = (context, splitHeaderGroups, options) => {
+    splitHeaderGroups.forEach((group) => {
+        const firstComment = group.comments[0];
+        context.report({
+            loc: firstComment.loc,
+            messageId: 'splitHeaderFragment',
+            data: {
+                tags: options.requiredTags.join(', '),
+            },
+            fix: null,
+        });
+    });
+};
+exports.RULE_NAME = 'enforce-unique-cursor-headers';
+exports.enforceUniqueCursorHeaders = (0, createRule_1.createRule)({
+    name: exports.RULE_NAME,
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Ensure files have exactly one cursor header containing required tags (e.g., @fileoverview) before any code',
+            recommended: 'error',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    requiredPatterns: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    excludedPatterns: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    requiredTags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    allowSplitHeaders: {
+                        type: 'boolean',
+                    },
+                    headerTemplate: {
+                        type: ['string', 'null'],
+                    },
+                    ignoreGeneratedFiles: {
+                        type: 'boolean',
+                    },
+                    generatedMarkers: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    excludedAtDirectives: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            missingHeader: 'File "{{fileName}}" is missing a cursor header before any imports or code → Cursor headers keep ownership and metadata discoverable for automation → Add one top-of-file cursor header containing: {{tags}}.',
+            duplicateHeader: 'Multiple cursor headers detected before the first statement (extra header starts on line {{line}}) → Duplicate metadata blocks conflict and make ownership ambiguous → Keep exactly one cursor header at the top and remove the extra block.',
+            splitHeaderFragment: 'Cursor header metadata is split across adjacent comment blocks → Fragmented headers are easy to miss and let required tags drift out of sync → Merge the fragments into a single top-of-file header containing: {{tags}}.',
+        },
+    },
+    defaultOptions: [DEFAULT_OPTIONS],
+    create(context, [userOptions]) {
+        const options = normalizeOptions(userOptions);
+        const fileName = context.getFilename();
+        const matchPath = fileName.split(path_1.default.sep).join('/');
+        const excludedAtDirectives = new Set(options.excludedAtDirectives);
+        if (fileName === '<input>') {
+            return {};
+        }
+        const matchesRequired = options.requiredPatterns.some((pattern) => (0, minimatch_1.minimatch)(matchPath, pattern, { dot: true }));
+        if (!matchesRequired) {
+            return {};
+        }
+        const matchesExcluded = options.excludedPatterns.some((pattern) => (0, minimatch_1.minimatch)(matchPath, pattern, { dot: true }));
+        if (matchesExcluded) {
+            return {};
+        }
+        return {
+            Program(node) {
+                const sourceCode = context.getSourceCode();
+                const sourceText = sourceCode.getText();
+                if (shouldSkipGeneratedFile(sourceText, options)) {
+                    return;
+                }
+                const topComments = getTopComments(sourceCode, node);
+                const candidateGroups = collectHeaderGroups(topComments, options, excludedAtDirectives);
+                const { primaryHeader, duplicateGroups, splitHeaderGroups } = analyzeHeaderGroups(candidateGroups, options);
+                if (!primaryHeader) {
+                    reportMissingHeader(context, fileName, sourceText, options);
+                    return;
+                }
+                reportDuplicates(context, duplicateGroups, sourceText);
+                reportSplitFragments(context, splitHeaderGroups, options);
+            },
+        };
+    },
+});
+//# sourceMappingURL=enforce-unique-cursor-headers.js.map

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

@@ -4537,7 +4537,7 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            functionVerbPhrase: 'Function names should start with a verb phrase (e.g., fetchData, processRequest)',
+            functionVerbPhrase: 'Function "{{name}}" should start with an action verb followed by the thing it acts on. Verb-first names tell readers this symbol performs work instead of representing data, which keeps APIs predictable and prevents accidental misuse. Rename "{{name}}" to a verb-noun phrase such as "fetchUsers" or "processRequest".',
         },
     },
     defaultOptions: [],
@@ -4718,9 +4718,7 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
                             const id = parent.id;
                             if (id.type === utils_1.AST_NODE_TYPES.Identifier &&
                                 id.typeAnnotation?.type === utils_1.AST_NODE_TYPES.TSTypeAnnotation) {
-                                const typeText = context
-                                    .getSourceCode()
-                                    .getText(id.typeAnnotation.typeAnnotation);
+                                const typeText = context.sourceCode.getText(id.typeAnnotation.typeAnnotation);
                                 return (typeText.includes('React.') ||
                                     typeText.includes('FC') ||
                                     typeText.includes('FunctionComponent'));
@@ -4755,6 +4753,7 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
                     context.report({
                         node: node.id,
                         messageId: 'functionVerbPhrase',
+                        data: { name: node.id.name },
                     });
                 }
             },
@@ -4771,6 +4770,7 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
                         context.report({
                             node: node.id,
                             messageId: 'functionVerbPhrase',
+                            data: { name: node.id.name },
                         });
                     }
                 }
@@ -4788,6 +4788,7 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
                     context.report({
                         node: node.key,
                         messageId: 'functionVerbPhrase',
+                        data: { name: node.key.name },
                     });
                 }
             },

package/lib/rules/ensure-pointer-events-none.js

@@ -23,6 +23,24 @@ function isAbsoluteOrFixedPosition(propertyName, propertyValue) {
 function isPointerEventsProperty(propertyName) {
     return propertyName === 'pointerEvents' || propertyName === 'pointer-events';
 }
+function formatSelector(selector) {
+    if (!selector)
+        return 'pseudo-element';
+    const trimmedSelector = selector.trim();
+    const candidates = trimmedSelector
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    for (const candidate of candidates) {
+        const match = candidate.match(/::?(before|after)\b/i);
+        if (match)
+            return `::${match[1].toLowerCase()}`;
+    }
+    if (trimmedSelector.length === 0)
+        return 'pseudo-element';
+    const snippet = trimmedSelector.slice(0, 40);
+    return trimmedSelector.length > 40 ? `${snippet}...` : trimmedSelector;
+}
 exports.ensurePointerEventsNone = (0, createRule_1.createRule)({
     name: 'ensure-pointer-events-none',
     meta: {
@@ -34,7 +52,9 @@ exports.ensurePointerEventsNone = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            missingPointerEventsNone: 'Pseudo-elements (::before, ::after) with position: absolute or fixed should have pointer-events: none to prevent blocking interactions with underlying elements',
+            missingPointerEventsNone: 'What\'s wrong: pseudo-element "{{selector}}" uses absolute or fixed positioning without pointer-events: none. ' +
+                'Why it matters: positioned overlays capture clicks, hover, and focus, blocking the underlying control and harming accessibility. ' +
+                'How to fix: add pointer-events: none so the pseudo-element stays decorative and does not intercept interactions.',
         },
     },
     defaultOptions: [],
@@ -104,9 +124,12 @@ exports.ensurePointerEventsNone = (0, createRule_1.createRule)({
                 context.report({
                     node,
                     messageId: 'missingPointerEventsNone',
+                    data: {
+                        selector: formatSelector(selector),
+                    },
                     fix(fixer) {
                         // Find the last property in the object
-                        const sourceCode = context.getSourceCode();
+                        const sourceCode = context.sourceCode;
                         const properties = node.properties;
                         if (properties.length === 0)
                             return null;
@@ -155,6 +178,9 @@ exports.ensurePointerEventsNone = (0, createRule_1.createRule)({
                             context.report({
                                 node,
                                 messageId: 'missingPointerEventsNone',
+                                data: {
+                                    selector: formatSelector(template),
+                                },
                             });
                         }
                     }

package/lib/rules/export-if-in-doubt.js

@@ -8,20 +8,31 @@ exports.exportIfInDoubt = (0, createRule_1.createRule)({
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'All top-level const definitions, type definitions, and functions should be exported',
+            description: 'All top-level variable declarations, type definitions, and functions should be exported',
             recommended: 'error',
         },
         schema: [],
         messages: {
-            exportIfInDoubt: 'Top-level const definitions, type definitions, and functions should be exported.',
+            exportIfInDoubt: 'What\'s wrong: Top-level {{kind}} "{{name}}" is not exported. Why it matters: Top-level declarations define your module\'s public API; leaving this unexported makes it unusable from other files and hides reusable utilities (often resulting in dead code or duplicated implementations). How to fix: Export it (for example: {{exportExample}}) or move it into a narrower scope if it is intentionally private.',
         },
     },
     defaultOptions: [],
     create(context) {
-        // List of top-level declarations
-        // List of exported identifiers
         const topLevelDeclarations = [];
         const exportedIdentifiers = [];
+        const getDeclarationKind = (node) => {
+            if (node.type === 'VariableDeclarator') {
+                const variableParent = node.parent;
+                if (variableParent?.type === 'VariableDeclaration') {
+                    return variableParent.kind;
+                }
+                return 'const';
+            }
+            if (node.type === 'FunctionDeclaration') {
+                return 'function';
+            }
+            return 'type';
+        };
         return {
             'Program > VariableDeclaration > VariableDeclarator, Program > FunctionDeclaration, Program > TSTypeAliasDeclaration'(node) {
                 topLevelDeclarations.push(node);
@@ -55,9 +66,21 @@ exports.exportIfInDoubt = (0, createRule_1.createRule)({
                             node.type === 'TSTypeAliasDeclaration') &&
                         node.id.type === 'Identifier' &&
                         !exportedIdentifiers.includes(node.id.name)) {
+                        const name = node.id.name;
+                        const kind = getDeclarationKind(node);
+                        const exportExample = node.type === 'VariableDeclarator'
+                            ? `export ${kind} ${name} = undefined;`
+                            : node.type === 'FunctionDeclaration'
+                                ? `export function ${name}() {}`
+                                : `export type ${name} = unknown;`;
                         context.report({
                             node,
                             messageId: 'exportIfInDoubt',
+                            data: {
+                                name,
+                                kind,
+                                exportExample,
+                            },
                         });
                     }
                 });

package/lib/rules/extract-global-constants.js

@@ -124,6 +124,19 @@ function isAsConstExpression(node) {
     }
     return false;
 }
+function analyzeDeclarator(declaration) {
+    const init = declaration.init ?? null;
+    const isFunctionOrMutable = isFunctionDefinition(init) || isMutableValue(init);
+    return {
+        isFunctionOrMutable,
+        hasDependencies: !isFunctionOrMutable && init
+            ? ASTHelpers_1.ASTHelpers.declarationIncludesIdentifier(init)
+            : false,
+        hasAsConstAssertion: !isFunctionOrMutable && init ? isAsConstExpression(init) : false,
+        hasReportableIdentifier: declaration.id?.type === utils_1.AST_NODE_TYPES.Identifier &&
+            !isFunctionOrMutable,
+    };
+}
 exports.extractGlobalConstants = (0, createRule_1.createRule)({
     create(context) {
         return {
@@ -131,27 +144,41 @@ exports.extractGlobalConstants = (0, createRule_1.createRule)({
                 if (node.kind !== 'const') {
                     return;
                 }
-                // Skip if any of the declarations are function definitions or mutable values
-                if (node.declarations.some((d) => isFunctionDefinition(d.init) || isMutableValue(d.init))) {
+                const declarations = node.declarations.filter((declaration) => declaration !== null && declaration !== undefined);
+                if (declarations.length === 0) {
+                    return;
+                }
+                let hasFunctionOrMutableValue = false;
+                let hasDependencies = false;
+                let hasAsConstAssertion = false;
+                let hasReportableIdentifierDeclaration = false;
+                for (const declaration of declarations) {
+                    const analysis = analyzeDeclarator(declaration);
+                    if (analysis.isFunctionOrMutable) {
+                        hasFunctionOrMutableValue = true;
+                        break;
+                    }
+                    hasDependencies ||= analysis.hasDependencies;
+                    hasAsConstAssertion ||= analysis.hasAsConstAssertion;
+                    hasReportableIdentifierDeclaration ||=
+                        analysis.hasReportableIdentifier;
+                }
+                if (hasFunctionOrMutableValue) {
                     return;
                 }
                 const scope = context.getScope();
-                const hasDependencies = node.declarations.some((declaration) => declaration.init &&
-                    ASTHelpers_1.ASTHelpers.declarationIncludesIdentifier(declaration.init));
-                // Skip constants with 'as const' type assertions used in loops
-                const hasAsConstAssertion = node.declarations.some((declaration) => declaration.init && isAsConstExpression(declaration.init));
                 // Only check function/block scoped constants without dependencies
                 if (!hasDependencies &&
                     !hasAsConstAssertion &&
                     (scope.type === 'function' || scope.type === 'block') &&
                     isInsideFunction(node) &&
-                    node.declarations.some((d) => d.id.type === 'Identifier')) {
-                    for (const d of node.declarations) {
-                        if (d.id.type !== 'Identifier')
+                    hasReportableIdentifierDeclaration) {
+                    for (const declaration of declarations) {
+                        if (declaration.id?.type !== utils_1.AST_NODE_TYPES.Identifier)
                             continue;
-                        const constName = d.id.name;
+                        const constName = declaration.id.name;
                         context.report({
-                            node: d,
+                            node: declaration,
                             messageId: 'extractGlobalConstants',
                             data: { declarationName: constName },
                         });
@@ -283,8 +310,8 @@ exports.extractGlobalConstants = (0, createRule_1.createRule)({
         },
         schema: [],
         messages: {
-            extractGlobalConstants: 'Move this declaration {{ declarationName }} to the global scope and rename it to UPPER_SNAKE_CASE if necessary.',
-            requireAsConst: 'Numeric literal {{ value }} in loop expression should be extracted to a constant with "as const" type assertion.',
+            extractGlobalConstants: 'What\'s wrong: Declaration "{{declarationName}}" does not reference values from this scope.\nWhy it matters: Keeping it nested recreates the same constant/helper on every call, which adds avoidable allocations and obscures that the value can be shared.\nHow to fix: Hoist it to module scope (use UPPER_SNAKE_CASE for immutable constants) so it is created once and can be imported.',
+            requireAsConst: 'What\'s wrong: Numeric literal {{value}} is used directly as a loop boundary.\nWhy it matters: Without "as const", TypeScript widens it to number, so if you later extract or reuse the value you lose the literal-type boundary and it is easier for related loops to drift out of sync.\nHow to fix: Extract it to a named constant with "as const" (or add "as const" inline) to keep the boundary explicit and reusable.',
         },
     },
     defaultOptions: [],