@blumintinc/eslint-plugin-blumint 1.12.6 → 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: [],
@@ -4600,18 +4600,86 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
             }
             return false;
         }
+        function bodyContainsJsx(node) {
+            const stack = [node];
+            while (stack.length) {
+                const current = stack.pop();
+                if (current.type === utils_1.AST_NODE_TYPES.JSXElement ||
+                    current.type === utils_1.AST_NODE_TYPES.JSXFragment) {
+                    return true;
+                }
+                for (const key of Object.keys(current)) {
+                    if (key === 'parent')
+                        continue;
+                    const value = current[key];
+                    if (Array.isArray(value)) {
+                        for (const child of value) {
+                            if (child && typeof child.type === 'string') {
+                                stack.push(child);
+                            }
+                        }
+                    }
+                    else if (value && typeof value.type === 'string') {
+                        stack.push(value);
+                    }
+                }
+            }
+            return false;
+        }
         function hasJsxReturn(node) {
-            const sourceCode = context.getSourceCode();
-            const text = sourceCode.getText(node);
-            // Check for direct JSX returns
-            if (text.includes('return <') || text.includes('=> <')) {
-                return true;
+            /**
+             * Recursively checks if an expression looks like JSX
+             */
+            function isJsxExpression(expr) {
+                if (!expr)
+                    return false;
+                // Handle parenthesized expressions
+                if (expr.type === 'ParenthesizedExpression') {
+                    return isJsxExpression(expr.expression);
+                }
+                switch (expr.type) {
+                    case utils_1.AST_NODE_TYPES.JSXElement:
+                    case utils_1.AST_NODE_TYPES.JSXFragment:
+                        return true;
+                    case utils_1.AST_NODE_TYPES.ConditionalExpression:
+                        return (isJsxExpression(expr.consequent) ||
+                            isJsxExpression(expr.alternate));
+                    case utils_1.AST_NODE_TYPES.LogicalExpression:
+                        // e.g. condition && <div />
+                        return isJsxExpression(expr.right);
+                    default:
+                        return false;
+                }
             }
-            // Check for JSX assigned to variables then returned
-            if (text.includes('const ') &&
-                text.includes('<') &&
-                text.includes('return')) {
-                return true;
+            /**
+             * Recursively checks if a statement/body returns JSX
+             */
+            function checkBodyForJsx(body) {
+                if (body.type === utils_1.AST_NODE_TYPES.BlockStatement) {
+                    for (const stmt of body.body) {
+                        if (stmt.type === utils_1.AST_NODE_TYPES.ReturnStatement) {
+                            if (isJsxExpression(stmt.argument))
+                                return true;
+                        }
+                        else if (stmt.type === utils_1.AST_NODE_TYPES.IfStatement) {
+                            if (checkBodyForJsx(stmt.consequent))
+                                return true;
+                            if (stmt.alternate && checkBodyForJsx(stmt.alternate))
+                                return true;
+                        }
+                        // We could traverse more (try/catch, switch), but this covers most idiomatic React
+                    }
+                }
+                else {
+                    // Implicit return (arrow function expression body)
+                    return isJsxExpression(body);
+                }
+                return false;
+            }
+            if (node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+                node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+                node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+                return checkBodyForJsx(node.body);
             }
             return false;
         }
@@ -4650,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'));
@@ -4664,6 +4730,13 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
                 // 5. Component name ends with "Unmemoized" (common React pattern)
                 functionName && functionName.endsWith('Unmemoized'),
             ];
+            // If the function has a PascalCase name AND returns JSX, it's definitely a React component
+            if (functionName && isPascalCase(functionName) && hasJsxReturn(node)) {
+                return true;
+            }
+            if (functionName && isPascalCase(functionName) && bodyContainsJsx(node)) {
+                return true;
+            }
             // Consider it a React component if it matches at least 2 indicators
             // OR if it has the Unmemoized suffix (strong indicator of a React component)
             return (indicators.filter(Boolean).length >= 2 ||
@@ -4680,6 +4753,7 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
                     context.report({
                         node: node.id,
                         messageId: 'functionVerbPhrase',
+                        data: { name: node.id.name },
                     });
                 }
             },
@@ -4696,6 +4770,7 @@ exports.enforceVerbNounNaming = (0, createRule_1.createRule)({
                         context.report({
                             node: node.id,
                             messageId: 'functionVerbPhrase',
+                            data: { name: node.id.name },
                         });
                     }
                 }
@@ -4713,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,
+                            },
                         });
                     }
                 });