@blumintinc/eslint-plugin-blumint 1.13.0 → 1.15.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