@blumintinc/eslint-plugin-blumint 1.20.69 → 1.20.71

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.69',
+        version: '1.20.71',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/class-methods-read-top-to-bottom.js

@@ -80,25 +80,42 @@ exports.classMethodsReadTopToBottom = (0, createRule_1.createRule)({
                     if (actualMember !== expectedMember) {
                         const classNameReport = className || 'this class';
                         const sourceCode = context.getSourceCode();
-                        const newClassBody = sortedOrder
-                            .map((n) => {
-                            // Fetch the actual AST node corresponding to the name
-                            const memberNode = node.body.find((member) => getMemberName(member) === n);
-                            if (!memberNode) {
-                                return '';
-                            }
-                            const comments = sourceCode.getCommentsBefore(memberNode) || [];
-                            const nodeRange = memberNode.range;
-                            const newRange = comments.length > 0
-                                ? [
-                                    Math.min(nodeRange[0], Math.min(...comments.map((comment) => comment.range[0]))),
-                                    Math.max(nodeRange[1], Math.max(...comments.map((comment) => comment.range[1]))),
-                                ]
-                                : nodeRange;
-                            return sourceCode.getText({ ...memberNode, range: newRange });
-                        })
-                            .filter(Boolean)
-                            .join('\n');
+                        const sourceText = sourceCode.getText();
+                        // A member's block spans its leading comments through its own end,
+                        // so documentation travels with the member it describes. Because
+                        // every comment in the body is thereby absorbed into some block,
+                        // the text between two adjacent blocks is pure whitespace.
+                        const memberBlocks = node.body.map((member) => {
+                            const comments = sourceCode.getCommentsBefore(member) || [];
+                            const start = Math.min(member.range[0], ...comments.map((comment) => comment.range[0]));
+                            return {
+                                name: getMemberName(member),
+                                text: sourceText.slice(start, member.range[1]),
+                                start,
+                                end: member.range[1],
+                            };
+                        });
+                        // Reuse those whitespace runs positionally instead of joining with
+                        // a bare '\n'. The blank lines between members are the part that
+                        // matters: prettier preserves existing blank lines but never
+                        // inserts new ones, so collapsing them is irreversible (#1592).
+                        // Carrying the runs verbatim also reproduces the newline and
+                        // indentation after `{` and the newline before `}` for free, since
+                        // every member sits at the same depth.
+                        const separators = memberBlocks
+                            .slice(1)
+                            .map((block, index) => sourceText.slice(memberBlocks[index].end, block.start));
+                        const prefix = sourceText.slice(node.range[0] + 1, memberBlocks[0].start);
+                        const suffix = sourceText.slice(memberBlocks[memberBlocks.length - 1].end, node.range[1] - 1);
+                        const newClassBody = prefix +
+                            sortedOrder
+                                .map((n) => {
+                                const block = memberBlocks.find(({ name }) => name === n);
+                                return block ? block.text : '';
+                            })
+                                .map((text, index) => index === 0 ? text : separators[index - 1] + text)
+                                .join('') +
+                            suffix;
                         return context.report({
                             node,
                             messageId: 'classMethodsReadTopToBottom',

package/lib/rules/no-firestore-object-arrays.js

@@ -43,6 +43,42 @@ const isParenthesizedType = (node) => {
     return (candidate.type === 'TSParenthesizedType' &&
         candidate.typeAnnotation !== undefined);
 };
+const unwrapParenthesizedTypeNode = (node) => {
+    let current = node;
+    // Cap iterations for the same reason as unwrapArrayElementType: wrappers are
+    // finite, but a future wrapper case must not be able to loop forever.
+    for (let i = 0; i < 10; i++) {
+        if (isParenthesizedType(current)) {
+            current = current.typeAnnotation;
+            continue;
+        }
+        break;
+    }
+    return current;
+};
+// Assertion wrappers never change the runtime value, so `[...] as const` and
+// `[...] as const satisfies readonly string[]` both still describe an array.
+const EXPRESSION_ASSERTION_TYPES = new Set([
+    utils_1.AST_NODE_TYPES.TSAsExpression,
+    utils_1.AST_NODE_TYPES.TSNonNullExpression,
+    utils_1.AST_NODE_TYPES.TSTypeAssertion,
+    'TSSatisfiesExpression',
+]);
+const unwrapExpressionAssertions = (node) => {
+    let current = node;
+    for (let i = 0; i < 10; i++) {
+        if (EXPRESSION_ASSERTION_TYPES.has(current.type)) {
+            const inner = current
+                .expression;
+            if (!inner)
+                break;
+            current = inner;
+            continue;
+        }
+        break;
+    }
+    return current;
+};
 const unwrapArrayElementType = (node) => {
     let current = node;
     // Fixpoint loop: peel wrappers in any order until none remain
@@ -181,6 +217,7 @@ exports.noFirestoreObjectArrays = (0, createRule_1.createRule)({
         const aliasNameToType = new Map();
         const interfaceNames = new Set();
         const enumNames = new Set();
+        const constArrayNameToLiteral = new Map();
         const visitNode = (n) => {
             switch (n.type) {
                 case utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration: {
@@ -195,6 +232,22 @@ exports.noFirestoreObjectArrays = (0, createRule_1.createRule)({
                     enumNames.add(n.id.name);
                     break;
                 }
+                case utils_1.AST_NODE_TYPES.VariableDeclaration: {
+                    // Only `const` bindings can back a `(typeof X)[number]` element union
+                    if (n.kind !== 'const')
+                        break;
+                    for (const declarator of n.declarations) {
+                        if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier ||
+                            !declarator.init) {
+                            continue;
+                        }
+                        const init = unwrapExpressionAssertions(declarator.init);
+                        if (init.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
+                            constArrayNameToLiteral.set(declarator.id.name, init);
+                        }
+                    }
+                    break;
+                }
                 case utils_1.AST_NODE_TYPES.ExportNamedDeclaration: {
                     if (n.declaration)
                         visitNode(n.declaration);
@@ -235,6 +288,85 @@ exports.noFirestoreObjectArrays = (0, createRule_1.createRule)({
         }
         const seenAlias = new Set();
         const visitingAliases = new Set();
+        const isPrimitiveLiteralElement = (element, visitedConstArrays) => {
+            // Array holes resolve to `undefined`, but the shape is unusual enough
+            // that refusing to classify it keeps the narrowing conservative.
+            if (!element)
+                return false;
+            if (element.type === utils_1.AST_NODE_TYPES.SpreadElement) {
+                const argument = unwrapExpressionAssertions(element.argument);
+                if (argument.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
+                    return argument.elements.every((nested) => isPrimitiveLiteralElement(nested, visitedConstArrays));
+                }
+                if (argument.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    return isPrimitiveConstArray(argument.name, visitedConstArrays);
+                }
+                return false;
+            }
+            const expression = unwrapExpressionAssertions(element);
+            switch (expression.type) {
+                case utils_1.AST_NODE_TYPES.Literal: {
+                    // A regex literal is an object; its `value` is engine-dependent, so
+                    // reject it explicitly rather than relying on the typeof check.
+                    if (expression.regex)
+                        return false;
+                    const value = expression.value;
+                    return (value === null ||
+                        typeof value === 'string' ||
+                        typeof value === 'number' ||
+                        typeof value === 'boolean' ||
+                        typeof value === 'bigint');
+                }
+                case utils_1.AST_NODE_TYPES.TemplateLiteral:
+                    return true; // a template literal always produces a string
+                case utils_1.AST_NODE_TYPES.ArrayExpression:
+                    // Nested primitive arrays mirror the allowance for `string[][]` and
+                    // tuples of primitives elsewhere in this rule.
+                    return expression.elements.every((nested) => isPrimitiveLiteralElement(nested, visitedConstArrays));
+                case utils_1.AST_NODE_TYPES.UnaryExpression: {
+                    const unary = expression;
+                    if (unary.operator !== '-' && unary.operator !== '+')
+                        return false;
+                    return isPrimitiveLiteralElement(unary.argument, visitedConstArrays);
+                }
+                case utils_1.AST_NODE_TYPES.Identifier:
+                    return expression.name === 'undefined';
+                default:
+                    return false;
+            }
+        };
+        const isPrimitiveConstArray = (name, visitedConstArrays) => {
+            // A cyclic spread cannot be resolved syntactically; refuse to classify it
+            if (visitedConstArrays.has(name))
+                return false;
+            const arrayLiteral = constArrayNameToLiteral.get(name);
+            if (!arrayLiteral)
+                return false;
+            visitedConstArrays.add(name);
+            const result = arrayLiteral.elements.every((element) => isPrimitiveLiteralElement(element, visitedConstArrays));
+            visitedConstArrays.delete(name);
+            return result;
+        };
+        /**
+         * Recognizes `(typeof VALUES)[number]` where VALUES is a same-file const
+         * array of primitive literals. That form denotes the union of those
+         * literals, not an object lookup, and it is exactly what the sibling
+         * rule prefer-union-from-const-array autofixes toward.
+         */
+        const isConstArrayElementUnion = (node) => {
+            const indexType = unwrapParenthesizedTypeNode(node.indexType);
+            // Only a `number` index yields the element union; `['length']` or any key
+            // lookup resolves to something this syntactic check cannot vouch for.
+            if (indexType.type !== utils_1.AST_NODE_TYPES.TSNumberKeyword)
+                return false;
+            const objectType = unwrapParenthesizedTypeNode(node.objectType);
+            if (objectType.type !== utils_1.AST_NODE_TYPES.TSTypeQuery)
+                return false;
+            const exprName = objectType.exprName;
+            if (exprName.type !== utils_1.AST_NODE_TYPES.Identifier)
+                return false;
+            return isPrimitiveConstArray(exprName.name, new Set());
+        };
         const isPrimitiveLikeAlias = (name, recursionDepth) => {
             if (seenAlias.has(name))
                 return true;
@@ -286,6 +418,8 @@ exports.noFirestoreObjectArrays = (0, createRule_1.createRule)({
                     return false;
                 case utils_1.AST_NODE_TYPES.TSLiteralType:
                     return true; // string/number/boolean literals
+                case utils_1.AST_NODE_TYPES.TSIndexedAccessType:
+                    return isConstArrayElementUnion(node);
                 case utils_1.AST_NODE_TYPES.TSTypeReference: {
                     // Allow known primitive-like references and enums or primitive-like aliases
                     const ref = node;
@@ -361,8 +495,10 @@ exports.noFirestoreObjectArrays = (0, createRule_1.createRule)({
                 case utils_1.AST_NODE_TYPES.TSMappedType:
                     return true;
                 case utils_1.AST_NODE_TYPES.TSIndexedAccessType:
-                    // Treat indexed access as object-like to align with existing tests
-                    return true;
+                    // An indexed access such as `DataShape['user']` is an object lookup,
+                    // but `(typeof VALUES)[number]` over a const array of primitive
+                    // literals is a primitive union and must not be flagged.
+                    return !isConstArrayElementUnion(node);
                 case utils_1.AST_NODE_TYPES.TSTypeOperator:
                     if (node.operator === 'readonly') {
                         return isObjectType(node

package/lib/rules/no-useless-usememo-primitives.js

@@ -381,6 +381,22 @@ exports.noUselessUsememoPrimitives = (0, createRule_1.createRule)({
                         valueKind,
                     },
                     fix(fixer) {
+                        // Inlining replaces the entire useMemo(...) call with the returned
+                        // expression's text, so any comment inside the call but outside
+                        // that expression — an eslint-disable-next-line directive on the
+                        // return statement among them — has no representation in the
+                        // replacement and would be silently destroyed, changing which
+                        // rules report on the file (#1591). The inlined expression lands
+                        // mid-line (e.g. `const label = <expr>;`), where a -next-line
+                        // directive cannot be hosted, so the autofix declines and leaves
+                        // the report for a manual fix.
+                        const strandedComments = sourceCode
+                            .getCommentsInside(node)
+                            .filter((comment) => comment.range[0] < returnedExpression.range[0] ||
+                            comment.range[1] > returnedExpression.range[1]);
+                        if (strandedComments.length > 0) {
+                            return null;
+                        }
                         const replacement = `(${sourceCode.getText(returnedExpression)})`;
                         return fixer.replaceText(node, replacement);
                     },

package/lib/rules/parallelize-async-operations.js

@@ -785,6 +785,61 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                 return null;
             }
             const awaitArguments = awaitExpressions.map((expr) => sourceCode.getText(expr.argument));
+            const startPos = awaitNodes[0].range[0];
+            const endPos = awaitNodes[awaitNodes.length - 1].range[1];
+            // The replacement text is rebuilt from the awaited expressions alone, so
+            // a comment inside the replaced span has no representation in it and
+            // would be silently deleted. Deleting an eslint-disable-next-line
+            // directive re-enables the suppressed rule on the code that survives
+            // inside the Promise.all (#1589). Each span comment is therefore either
+            // re-hosted directly above the array element built from the statement it
+            // annotates, or the fix is declined so no comment is ever destroyed. The
+            // report fires either way.
+            const spanComments = sourceCode
+                .getAllComments()
+                .filter((comment) => comment.range[0] >= startPos && comment.range[1] <= endPos);
+            const hostedComments = awaitNodes.map(() => []);
+            if (spanComments.length > 0) {
+                // Re-hosting maps the comments preceding statement i onto element i,
+                // which requires the element list to line up 1:1 with the statement
+                // list.
+                if (awaitExpressions.length !== awaitNodes.length) {
+                    return null;
+                }
+                for (const comment of spanComments) {
+                    const hostIndex = awaitNodes.findIndex((node, index) => index > 0 &&
+                        comment.range[0] >= awaitNodes[index - 1].range[1] &&
+                        comment.range[1] <= node.range[0]);
+                    if (hostIndex === -1) {
+                        // The comment sits inside one of the merged statements. A comment
+                        // within the awaited expression itself travels verbatim with
+                        // getText; anywhere else (between `await` and its operand, or
+                        // around a declarator's `=`) has no slot in the rebuilt text.
+                        const isInsideArgument = awaitExpressions.some((expr) => comment.range[0] >= expr.argument.range[0] &&
+                            comment.range[1] <= expr.argument.range[1]);
+                        if (!isInsideArgument) {
+                            return null;
+                        }
+                        continue;
+                    }
+                    // A comment that shares the previous statement's last line is a
+                    // trailing comment (e.g. an eslint-disable-line directive) governing
+                    // THAT line; moving it above the next element would change which
+                    // line it applies to.
+                    if (comment.loc.start.line <= awaitNodes[hostIndex - 1].loc.end.line) {
+                        return null;
+                    }
+                    // A directive above `const x = await f();` may target the
+                    // declaration's identifier, which the rewrite moves into the
+                    // destructuring pattern on the Promise.all line — away from every
+                    // line the re-hosted directive could govern.
+                    if (/^\s*eslint-/u.test(comment.value) &&
+                        awaitNodes[hostIndex].type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
+                        return null;
+                    }
+                    hostedComments[hostIndex].push(comment);
+                }
+            }
             const idsText = [];
             const declKinds = new Set();
             let hasVariableDeclarations = false;
@@ -817,7 +872,17 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
             // the contents of a template literal, where whitespace is significant
             // data rather than formatting and re-indenting would silently change the
             // produced string.
-            const elementsText = awaitArguments.join(`,\n${elementIndent}`);
+            const elementsText = awaitArguments
+                .map((argumentText, index) => {
+                // Each re-hosted comment lands on its own line directly above the
+                // element, which is the only placement where a disable-next-line
+                // directive keeps suppressing it.
+                const leadingText = (hostedComments[index] ?? [])
+                    .map((comment) => `${sourceCode.getText(comment)}\n${elementIndent}`)
+                    .join('');
+                return `${leadingText}${argumentText}`;
+            })
+                .join(`,\n${elementIndent}`);
             let promiseAllText;
             if (hasVariableDeclarations) {
                 if (declKinds.size !== 1) {
@@ -834,8 +899,6 @@ exports.parallelizeAsyncOperations = (0, createRule_1.createRule)({
                 // Simple Promise.all without variable assignments
                 promiseAllText = `await Promise.all([\n${elementIndent}${elementsText}\n${baseIndent}]);`;
             }
-            const startPos = awaitNodes[0].range[0];
-            const endPos = awaitNodes[awaitNodes.length - 1].range[1];
             return fixer.replaceTextRange([startPos, endPos], promiseAllText);
         }
         /**

package/lib/rules/prefer-map-over-conditional-dispatch.js

@@ -62,6 +62,37 @@ function parenthesizeForUnion(text) {
     const needsParens = text.includes('=>') || /^new\b/.test(text) || /\bextends\b/.test(text);
     return needsParens ? `(${text})` : text;
 }
+/**
+ * How position-sensitive a comment is when the fix relocates it onto the
+ * generated Record:
+ *
+ * - `next-line`: suppresses exactly the following line
+ *   (`eslint-disable-next-line`, `@ts-expect-error`, `@ts-ignore`) — hosting
+ *   it anywhere but directly above the line it suppressed silently changes
+ *   which rules report.
+ * - `own-line`: suppresses its own line (`eslint-disable-line`) — must stay on
+ *   the same line as the value it annotates.
+ * - `range`: opens/closes a suppression region or configures the linter
+ *   (`eslint-disable`, `eslint-enable`, `eslint-env`, `eslint`, `global`,
+ *   `exported`) — ESLint honors these only in block-comment form, and
+ *   relocation can move the region boundary across reported lines, so the fix
+ *   is never attempted around one.
+ * - `none`: prose; content preservation suffices.
+ */
+function directiveKindOf(comment) {
+    const text = comment.value.trim();
+    if (/^(eslint-disable-next-line|@ts-expect-error|@ts-ignore)\b/.test(text)) {
+        return 'next-line';
+    }
+    if (/^eslint-disable-line\b/.test(text)) {
+        return 'own-line';
+    }
+    if (comment.type === utils_1.AST_TOKEN_TYPES.Block &&
+        /^(eslint-disable|eslint-enable|eslint-env|eslint\b|globals?\b|exported\b)/.test(text)) {
+        return 'range';
+    }
+    return 'none';
+}
 exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
     name: 'prefer-map-over-conditional-dispatch',
     meta: {
@@ -360,7 +391,7 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
             }
             const stmt = stmts[0];
             if (stmt.type === utils_1.AST_NODE_TYPES.ReturnStatement && stmt.argument) {
-                return { kind: 'return', expr: stmt.argument };
+                return { kind: 'return', expr: stmt.argument, stmt };
             }
             if (stmt.type === utils_1.AST_NODE_TYPES.ExpressionStatement &&
                 stmt.expression.type === utils_1.AST_NODE_TYPES.AssignmentExpression &&
@@ -369,6 +400,7 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
                     kind: 'assign',
                     target: stmt.expression.left,
                     expr: stmt.expression.right,
+                    stmt,
                 };
             }
             return null;
@@ -504,13 +536,92 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
             return match ? match[0] : '';
         }
         function buildRecordText(name, dText, vText, entries, baseIndent) {
-            const lines = entries.map((e) => `${baseIndent}  ${formatKey(e.key)}: ${e.valueText},`);
+            const lines = entries.flatMap((e) => {
+                const hosted = (e.leadingComments ?? []).map((comment) => `${baseIndent}  ${comment}`);
+                const trailing = e.trailingComments && e.trailingComments.length > 0
+                    ? ` ${e.trailingComments.join(' ')}`
+                    : '';
+                hosted.push(`${baseIndent}  ${formatKey(e.key)}: ${e.valueText},${trailing}`);
+                return hosted;
+            });
             return [
                 `const ${name}: Record<${dText}, ${vText}> = {`,
                 ...lines,
                 `${baseIndent}};`,
             ].join('\n');
         }
+        /**
+         * Decides where every comment inside the replaced construct lands on the
+         * generated Record, mutating `entries` with the hosted text. Comments
+         * inside a carried span (a branch value expression, the discriminant, the
+         * assignment target) survive verbatim inside the copied text; comments
+         * inside a dropped span (an unreachable default/tail) die together with
+         * the code they annotate, which is not an orphaning. Every other comment
+         * must be hosted onto a map entry — leading comments go on the line(s)
+         * directly above the entry, same-line trailing comments append after it.
+         * Returns false when a comment cannot be hosted without changing what it
+         * annotates or suppresses; the caller then withholds the autofix so a
+         * directive is never silently deleted or retargeted.
+         */
+        function planCommentHosting(args) {
+            const { container, carriedSpans, droppedSpans, anchors, entries } = args;
+            const ordered = [...anchors].sort((a, b) => a.range[0] - b.range[0]);
+            const hostLeading = (entry, text) => {
+                entry.leadingComments = [...(entry.leadingComments ?? []), text];
+            };
+            const hostTrailing = (entry, text) => {
+                entry.trailingComments = [...(entry.trailingComments ?? []), text];
+            };
+            for (const comment of sourceCode.getCommentsInside(container)) {
+                const [cStart, cEnd] = comment.range;
+                const within = (spans) => spans.some(([start, end]) => cStart >= start && cEnd <= end);
+                if (within(carriedSpans) || within(droppedSpans)) {
+                    continue;
+                }
+                const kind = directiveKindOf(comment);
+                if (kind === 'range') {
+                    return false;
+                }
+                const text = sourceCode.getText(comment);
+                // Same-line trailing (`doThing(); // note`): append to the entry line
+                // so an `eslint-disable-line` keeps suppressing the line its value
+                // lands on. The last matching anchor wins so a comment trailing two
+                // same-line statements attaches to the nearer one.
+                const trailingCandidates = ordered.filter((anchor) => anchor.endLine === comment.loc.start.line &&
+                    cStart >= anchor.range[1]);
+                const trailingAnchor = trailingCandidates[trailingCandidates.length - 1];
+                if (trailingAnchor) {
+                    if (kind === 'next-line') {
+                        // A trailing disable-next-line targets whatever follows the
+                        // statement; the generated map has no equivalent following line.
+                        return false;
+                    }
+                    if (kind === 'own-line' && trailingAnchor.entryCount > 1) {
+                        return false;
+                    }
+                    hostTrailing(entries[trailingAnchor.entryIndex], text);
+                    continue;
+                }
+                // A comment inside the value statement but outside the copied
+                // expression (`return /* why */ value;`) belongs to that branch.
+                const containingAnchor = ordered.find((anchor) => cStart >= anchor.range[0] && cEnd <= anchor.range[1]);
+                const leadingAnchor = containingAnchor ?? ordered.find((anchor) => anchor.range[0] >= cEnd);
+                if (!leadingAnchor) {
+                    return false;
+                }
+                if (kind === 'next-line') {
+                    // Host a line-targeted directive only when it provably targeted the
+                    // branch's value line, so relocation preserves — never widens or
+                    // drops — the suppression.
+                    if (leadingAnchor.entryCount > 1 ||
+                        leadingAnchor.startLine !== comment.loc.end.line + 1) {
+                        return false;
+                    }
+                }
+                hostLeading(entries[leadingAnchor.entryIndex], text);
+            }
+            return true;
+        }
         /**
          * Given ordered explicit branches + optional tail, resolve coverage against
          * the union's literal keys and (when full) the ordered Record entries.
@@ -564,20 +675,28 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
             if (!flags.canPlaceFix) {
                 return 'the dispatch sits inside an expression-bodied function; extract the Record manually so it stays in scope';
             }
+            if (!flags.commentSafe) {
+                return 'a comment inside the dispatch cannot be carried onto the generated Record without changing what it annotates or suppresses — relocate the comment, then convert';
+            }
             return 'a collision-free lookup name could not be derived from the discriminant';
         }
         function report(node, analysis) {
-            const { entries, contributingValues, dText, form, assignTargetText, fullCoverage, hasNullish, canPlaceFix, } = analysis;
+            const { entries, contributingValues, dText, form, assignTargetText, fullCoverage, hasNullish, canPlaceFix, commentBlocked, } = analysis;
             const eagerSafe = contributingValues.every((expr) => !containsEagerUnsafe(expr));
             let name = null;
             // Name derivation is only needed for the autofix path.
-            if (fullCoverage && !hasNullish && eagerSafe && canPlaceFix) {
+            if (fullCoverage &&
+                !hasNullish &&
+                eagerSafe &&
+                canPlaceFix &&
+                !commentBlocked) {
                 name = deriveLookupName(discriminantOf(node));
             }
             const autofixable = fullCoverage &&
                 !hasNullish &&
                 eagerSafe &&
                 canPlaceFix &&
+                !commentBlocked &&
                 name !== null;
             if (!autofixable) {
                 context.report({
@@ -589,6 +708,7 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
                             hasNullish,
                             eagerSafe,
                             canPlaceFix,
+                            commentSafe: !commentBlocked,
                         }),
                     },
                 });
@@ -700,7 +820,7 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
                     continue;
                 }
                 const value = extractBranchValue(c.consequent);
-                parsed.push({ tests: [...pending, c.test], value });
+                parsed.push({ tests: [...pending, c.test], value, caseNode: c });
                 pending = [];
             }
             if (pending.length > 0) {
@@ -714,6 +834,7 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
             const explicit = [];
             let defaultValue;
             let hasDefault = false;
+            let defaultCaseNode = null;
             for (const branch of parsed) {
                 const literalTests = branch.tests.filter((t) => t !== null);
                 const isDefaultGroup = literalTests.length !== branch.tests.length;
@@ -724,6 +845,7 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
                     }
                     hasDefault = true;
                     defaultValue = branch.value;
+                    defaultCaseNode = branch.caseNode;
                     continue;
                 }
                 if (!branch.value) {
@@ -798,6 +920,57 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
             if (isNarrowingExempt(node.discriminant, contributingValues)) {
                 return;
             }
+            // Comment hosting only gates the autofix path (partial coverage is
+            // already report-only), so it is planned for full coverage alone.
+            let commentBlocked = false;
+            if (coverage.fullCoverage) {
+                const tailUsed = coverage.remainingCount === 1 && defaultVal !== null;
+                const carriedSpans = [node.discriminant.range];
+                const droppedSpans = [];
+                const anchors = [];
+                let entryIndex = 0;
+                for (const branch of explicit) {
+                    carriedSpans.push(branch.value.expr.range);
+                    anchors.push({
+                        range: branch.value.stmt.range,
+                        startLine: branch.value.stmt.loc.start.line,
+                        endLine: branch.value.stmt.loc.end.line,
+                        entryIndex,
+                        entryCount: branch.keys.length,
+                    });
+                    entryIndex += branch.keys.length;
+                }
+                if (kind === 'assign' && explicit[0].value.kind === 'assign') {
+                    carriedSpans.push(explicit[0].value.target.range);
+                }
+                if (tailUsed && defaultVal) {
+                    carriedSpans.push(defaultVal.expr.range);
+                    anchors.push({
+                        range: defaultVal.stmt.range,
+                        startLine: defaultVal.stmt.loc.start.line,
+                        endLine: defaultVal.stmt.loc.end.line,
+                        entryIndex: coverage.entries.length - 1,
+                        entryCount: 1,
+                    });
+                }
+                else if (defaultCaseNode) {
+                    // The unreachable default is deleted wholesale; its comments —
+                    // including any directly above the `default:` label — annotate
+                    // deleted code and die with it.
+                    const caseIndex = node.cases.indexOf(defaultCaseNode);
+                    const droppedStart = caseIndex > 0
+                        ? node.cases[caseIndex - 1].range[1]
+                        : node.discriminant.range[1];
+                    droppedSpans.push([droppedStart, defaultCaseNode.range[1]]);
+                }
+                commentBlocked = !planCommentHosting({
+                    container: node,
+                    carriedSpans,
+                    droppedSpans,
+                    anchors,
+                    entries: coverage.entries,
+                });
+            }
             report(node, {
                 entries: coverage.entries,
                 contributingValues,
@@ -807,6 +980,7 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
                 fullCoverage: coverage.fullCoverage,
                 hasNullish,
                 canPlaceFix: true,
+                commentBlocked,
             });
         }
         // ---- Ternary form -------------------------------------------------------
@@ -906,6 +1080,47 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
                     crossesFunction = true;
                 }
             }
+            let commentBlocked = false;
+            if (coverage.fullCoverage) {
+                const tailUsed = coverage.remainingCount === 1;
+                const carriedSpans = [
+                    head.discNode.range,
+                    ...links.map((l) => l.expr.range),
+                ];
+                const droppedSpans = [];
+                const anchors = links.map((l, i) => ({
+                    range: l.expr.range,
+                    startLine: l.expr.loc.start.line,
+                    endLine: l.expr.loc.end.line,
+                    entryIndex: i,
+                    entryCount: 1,
+                }));
+                if (tailUsed) {
+                    carriedSpans.push(tailExpr.range);
+                    anchors.push({
+                        range: tailExpr.range,
+                        startLine: tailExpr.loc.start.line,
+                        endLine: tailExpr.loc.end.line,
+                        entryIndex: coverage.entries.length - 1,
+                        entryCount: 1,
+                    });
+                }
+                else {
+                    // The unreachable tail is deleted; comments between the last kept
+                    // consequent and the tail's end annotate deleted code.
+                    droppedSpans.push([
+                        links[links.length - 1].expr.range[1],
+                        tailExpr.range[1],
+                    ]);
+                }
+                commentBlocked = !planCommentHosting({
+                    container: node,
+                    carriedSpans,
+                    droppedSpans,
+                    anchors,
+                    entries: coverage.entries,
+                });
+            }
             discriminantMap.set(node, head.discNode);
             report(node, {
                 entries: coverage.entries,
@@ -915,6 +1130,7 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
                 fullCoverage: coverage.fullCoverage,
                 hasNullish,
                 canPlaceFix: !crossesFunction,
+                commentBlocked,
             });
         }
         // ---- if / else-if form --------------------------------------------------
@@ -935,6 +1151,10 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
             }
             const links = [];
             let tail = null;
+            // The final else statement/block and the end of the consequent before
+            // it — the source region a dropped tail's comments die with.
+            let tailNode = null;
+            let tailPrevEnd = 0;
             let cur = node;
             while (cur) {
                 const link = equalityDiscriminant(cur.test);
@@ -960,6 +1180,8 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
                     return;
                 }
                 tail = tailValue;
+                tailNode = alt;
+                tailPrevEnd = cur.consequent.range[1];
                 cur = null;
             }
             if (links.length === 0) {
@@ -1012,6 +1234,48 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
             if (isNarrowingExempt(head.discNode, contributingValues)) {
                 return;
             }
+            let commentBlocked = false;
+            if (coverage.fullCoverage) {
+                const tailUsed = coverage.remainingCount === 1 && tail !== null;
+                const carriedSpans = [head.discNode.range];
+                const droppedSpans = [];
+                const anchors = [];
+                links.forEach((link, i) => {
+                    carriedSpans.push(link.value.expr.range);
+                    anchors.push({
+                        range: link.value.stmt.range,
+                        startLine: link.value.stmt.loc.start.line,
+                        endLine: link.value.stmt.loc.end.line,
+                        entryIndex: i,
+                        entryCount: 1,
+                    });
+                });
+                if (kind === 'assign' && links[0].value.kind === 'assign') {
+                    carriedSpans.push(links[0].value.target.range);
+                }
+                if (tailUsed && tail) {
+                    carriedSpans.push(tail.expr.range);
+                    anchors.push({
+                        range: tail.stmt.range,
+                        startLine: tail.stmt.loc.start.line,
+                        endLine: tail.stmt.loc.end.line,
+                        entryIndex: coverage.entries.length - 1,
+                        entryCount: 1,
+                    });
+                }
+                else if (tailNode) {
+                    // The unreachable else is deleted; comments from the last kept
+                    // consequent through the else's end annotate deleted code.
+                    droppedSpans.push([tailPrevEnd, tailNode.range[1]]);
+                }
+                commentBlocked = !planCommentHosting({
+                    container: node,
+                    carriedSpans,
+                    droppedSpans,
+                    anchors,
+                    entries: coverage.entries,
+                });
+            }
             discriminantMap.set(node, head.discNode);
             report(node, {
                 entries: coverage.entries,
@@ -1022,6 +1286,7 @@ exports.preferMapOverConditionalDispatch = (0, createRule_1.createRule)({
                 fullCoverage: coverage.fullCoverage,
                 hasNullish,
                 canPlaceFix: true,
+                commentBlocked,
             });
         }
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.69",
+  "version": "1.20.71",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "1.20.71",
+    "date": "2026-08-02T01:25:22.489Z",
+    "rules": [
+      {
+        "name": "no-firestore-object-arrays",
+        "changeType": "fix",
+        "issues": [
+          1594
+        ],
+        "summary": "treat (typeof X)[number] over a primitive const array as a primitive union (closes #1594)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.70",
+    "date": "2026-08-01T23:31:02.214Z",
+    "rules": [
+      {
+        "name": "class-methods-read-top-to-bottom",
+        "changeType": "fix",
+        "issues": [
+          1592
+        ],
+        "summary": "preserve the whitespace separating reordered class members (closes #1592)"
+      },
+      {
+        "name": "no-useless-usememo-primitives",
+        "changeType": "fix",
+        "issues": [
+          1591
+        ],
+        "summary": "decline the autofix when inlining would strand a comment (closes #1591)"
+      },
+      {
+        "name": "parallelize-async-operations",
+        "changeType": "fix",
+        "issues": [
+          1589
+        ],
+        "summary": "preserve comments between merged awaits (closes #1589)"
+      },
+      {
+        "name": "prefer-map-over-conditional-dispatch",
+        "changeType": "fix",
+        "issues": [
+          1590
+        ],
+        "summary": "preserve branch comments in the generated map (closes #1590)"
+      }
+    ]
+  },
   {
     "version": "1.20.69",
     "date": "2026-08-01T20:48:40.484Z",