@blumintinc/eslint-plugin-blumint 1.20.173 → 1.20.174

package/lib/index.js

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

package/lib/rules/enforce-firestore-set-merge.js

@@ -685,7 +685,8 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
         }
         /**
          * The edits that add `appended` to the end of a call's argument list, laid
-         * out the way the consumer's formatter prints the result.
+         * out the way the consumer's formatter prints the result — or `null` for
+         * the one tail no edit can extend without retargeting a directive.
          *
          * Neither layout re-emits an argument from its text. The broken one
          * rewrites the SEPARATORS between the arguments and shifts the indentation
@@ -708,16 +709,36 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
                 return inline();
             }
             const { openParen, closeParen, spans } = layout;
-            const tail = spans[spans.length - 1];
-            // Between the last span and the closing parenthesis is the one gap the
-            // spans do not absorb, because a trailing comma may sit there. A comment
-            // past it would be inside a replaced range, so the list is left as it is
-            // and the option appended in place instead of deleting one.
-            if (sourceCode
-                .getCommentsInside(node)
-                .some((comment) => comment.range[0] >= tail.end)) {
+            // Between the last argument's own last token and the closing parenthesis
+            // sit the trailing comma, if one was written, and any comment. The tail
+            // SPAN absorbs such a comment whenever no comma follows it, so the span's
+            // end is not a safe place to write a separator: a `,` emitted after a
+            // line comment is swallowed into the comment's text and the call no
+            // longer parses (#2140). Both boundaries are therefore taken from the
+            // TOKEN stream, where a comment can never be the answer.
+            const beforeClose = sourceCode.getTokenBefore(closeParen);
+            const lastArgumentToken = beforeClose?.value === ','
+                ? sourceCode.getTokenBefore(beforeClose)
+                : beforeClose;
+            if (!beforeClose || !lastArgumentToken) {
                 return inline();
             }
+            const gapComments = sourceCode
+                .getCommentsInside(node)
+                .filter((comment) => comment.range[0] >= lastArgumentToken.range[1]);
+            const sameLineComments = gapComments.filter((comment) => comment.loc.start.line === lastArgumentToken.loc.end.line);
+            const ownLineComments = gapComments.filter((comment) => comment.loc.start.line !== lastArgumentToken.loc.end.line);
+            // A directive trailing the argument's line means the line that FOLLOWS
+            // it: emitting anything there hands `{ merge: true }` the suppression
+            // that was written for the closing line, and re-exposes whatever it was
+            // suppressing. No layout preserves both the option's position and the
+            // directive's subject, so the fix is withheld and the report left to the
+            // developer, who restructures the call with the directive in view
+            // (#1877). A directive on a line of its OWN is safe: the option lands
+            // BEFORE it, so everything the directive is adjacent to stays adjacent.
+            if (sameLineComments.some(isPositionalDirective)) {
+                return null;
+            }
             // A broken list is indented one step past the line its parenthesis opens
             // on, whatever depth that line sits at, and closes at that line's own
             // column. A constant indent is right for exactly one call site.
@@ -740,9 +761,48 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
                     fixes.push(fixer.replaceText(argument, relocated));
                 }
             }
-            fixes.push(fixer.replaceTextRange([tail.end, closeParen.range[0]], `${appended
-                .map((argument) => `,\n${body}${argument}`)
-                .join('')},\n${indent}`));
+            if (gapComments.length === 0) {
+                fixes.push(fixer.replaceTextRange([lastArgumentToken.range[1], closeParen.range[0]], `${appended
+                    .map((argument) => `,\n${body}${argument}`)
+                    .join('')},\n${indent}`));
+                return fixes;
+            }
+            const separatorPresent = beforeClose.value === ',';
+            const lastSameLine = sameLineComments[sameLineComments.length - 1];
+            if (ownLineComments.length === 0) {
+                // The comment trails the argument it annotates, so it keeps that line
+                // and the option opens the next one. The separator has to sit between
+                // the argument and the comment — after a line comment it is comment
+                // text — so one is inserted at the argument's own last token unless
+                // the author already wrote it, and everything through the end of the
+                // annotation is left byte for byte as written.
+                if (!separatorPresent) {
+                    fixes.push(fixer.insertTextAfter(lastArgumentToken, ','));
+                }
+                const annotationEnd = Math.max(lastSameLine.range[1], beforeClose.range[1]);
+                fixes.push(fixer.replaceTextRange([annotationEnd, closeParen.range[0]], `${appended
+                    .map((argument) => `\n${body}${argument},`)
+                    .join('')}\n${indent}`));
+                return fixes;
+            }
+            // A comment on a line of its own before the `)` was not written against
+            // the last argument, so the option lands BEFORE it — after the trailing
+            // annotation, if the line carries one — and the comment keeps both its
+            // bytes and its neighbours: what it sat above, it still sits above.
+            const appendedText = appended
+                .map((argument) => `\n${body}${argument},`)
+                .join('');
+            const anchor = Math.max(separatorPresent ? beforeClose.range[1] : lastArgumentToken.range[1], lastSameLine ? lastSameLine.range[1] : 0);
+            if (separatorPresent || lastSameLine) {
+                if (!separatorPresent) {
+                    fixes.push(fixer.insertTextAfter(lastArgumentToken, ','));
+                }
+                fixes.push(fixer.insertTextAfterRange([anchor, anchor], appendedText));
+                return fixes;
+            }
+            // With neither a comma nor a trailing comment, the separator and the
+            // option travel as one insertion, since both land at the same offset.
+            fixes.push(fixer.insertTextAfterRange([anchor, anchor], `,${appendedText}`));
             return fixes;
         }
         /**
@@ -800,10 +860,11 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
                         `${indent}})`),
                 ];
             }
-            return [
-                fixer.replaceText(callee.property, 'set'),
-                ...appendArguments(fixer, node, [MERGE_OPTION], 'set'.length - callee.property.name.length),
-            ];
+            const appended = appendArguments(fixer, node, [MERGE_OPTION], 'set'.length - callee.property.name.length);
+            if (!appended) {
+                return null;
+            }
+            return [fixer.replaceText(callee.property, 'set'), ...appended];
         }
         /**
          * The source the removal planner reads, with the comments inside a
@@ -970,17 +1031,23 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
             const overlaps = ordered.some((rewrite, index) => index > 0 && rewrite.call.range[0] < ordered[index - 1].call.range[1]);
             return overlaps ? null : rewrites;
         }
-        /** `updateDoc(ref, data)` → `setDoc(ref, data, { merge: true })`. */
+        /**
+         * `updateDoc(ref, data)` → `setDoc(ref, data, { merge: true })`, or `null`
+         * where the argument list cannot be extended. No state is touched on the
+         * way to that answer: the caller marks the call batched only once every
+         * edit riding in the same fix is known to land, since a call marked by a
+         * fix that never ships would make its own report decline too.
+         */
         function rewriteCall(fixer, rewrite) {
-            batchedCalls.add(rewrite.call);
-            return [
-                fixer.replaceText(rewrite.identifier, SET_DOC),
-                // `setDoc` takes the document data between the reference and the
-                // options, so a call that passed no data gets an empty object to merge.
-                ...appendArguments(fixer, rewrite.call, rewrite.call.arguments.length > 1
-                    ? [MERGE_OPTION]
-                    : [EMPTY_DATA, MERGE_OPTION], SET_DOC.length - rewrite.identifier.name.length),
-            ];
+            // `setDoc` takes the document data between the reference and the
+            // options, so a call that passed no data gets an empty object to merge.
+            const appended = appendArguments(fixer, rewrite.call, rewrite.call.arguments.length > 1
+                ? [MERGE_OPTION]
+                : [EMPTY_DATA, MERGE_OPTION], SET_DOC.length - rewrite.identifier.name.length);
+            if (!appended) {
+                return null;
+            }
+            return [fixer.replaceText(rewrite.identifier, SET_DOC), ...appended];
         }
         /**
          * `updateDoc(ref, data)` becomes `setDoc(ref, data, { merge: true })`, which
@@ -1030,15 +1097,37 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
             if (!rewrites) {
                 // A reference survives the pass, so the name stays bound and `setDoc` is
                 // added alongside it. Only the first surviving violation carries the
-                // binding; the rest emit the call against it.
+                // binding; the rest emit the call against it. The call rewrite is asked
+                // for FIRST: a declined rewrite must leave the binding plan untouched,
+                // or a later violation would trust an import this fix never emitted.
+                const callFixes = rewriteCall(fixer, {
+                    identifier: callee,
+                    call: node,
+                });
+                if (!callFixes) {
+                    return null;
+                }
                 const fixes = [];
                 if (!setDocVariable && !plannedSetDocBinding) {
                     fixes.push(fixer.insertTextAfter(updateBinding.node, `, ${SET_DOC}`));
                     plannedSetDocBinding = true;
                 }
-                fixes.push(...rewriteCall(fixer, { identifier: callee, call: node }));
+                batchedCalls.add(node);
+                fixes.push(...callFixes);
                 return fixes;
             }
+            // One call whose tail cannot be extended declines the WHOLE batch, before
+            // any flag records it as handled: a partial batch would retire an import
+            // some call still reads, and a call marked batched by a fix that never
+            // shipped would silently lose its own report's fix as well.
+            const rewriteFixes = [];
+            for (const rewrite of rewrites) {
+                const callFixes = rewriteCall(fixer, rewrite);
+                if (!callFixes) {
+                    return null;
+                }
+                rewriteFixes.push(...callFixes);
+            }
             const fixes = [];
             if (setDocVariable) {
                 // The name is already bound to firestore's own `setDoc`, so the entry
@@ -1062,8 +1151,9 @@ exports.enforceFirestoreSetMerge = (0, createRule_1.createRule)({
                 plannedSetDocBinding = true;
             }
             for (const rewrite of rewrites) {
-                fixes.push(...rewriteCall(fixer, rewrite));
+                batchedCalls.add(rewrite.call);
             }
+            fixes.push(...rewriteFixes);
             return fixes;
         }
         return {

package/lib/rules/no-usememo-for-pass-by-value.js

@@ -519,8 +519,8 @@ exports.noUsememoForPassByValue = (0, createRule_1.createRule)({
                 // exactly as in the comment-free fix, never by the comments themselves.
                 // The call can start mid-line, so the indentation of the line it opens
                 // on is the only anchor the carried comments have.
-                const startLine = sourceCode.lines[node.loc.start.line - 1] ?? '';
-                const indent = /^[\t ]*/.exec(startLine)?.[0] ?? '';
+                const indentOf = (line) => /^[\t ]*/.exec(line)?.[0] ?? '';
+                const indent = indentOf(sourceCode.lines[node.loc.start.line - 1] ?? '');
                 const text = sourceCode.getText();
                 /**
                  * A block comment's text carries the indentation of where it was
@@ -552,10 +552,11 @@ exports.noUsememoForPassByValue = (0, createRule_1.createRule)({
                         }),
                     ].join('\n');
                 };
-                const toSegment = (comment) => ({
-                    text: reindented(comment, indent),
+                const segmentAt = (comment, toIndent) => ({
+                    text: reindented(comment, toIndent),
                     breakAfter: (0, replacementSegments_1.requiresLineBreakAfter)(comment),
                 });
+                const toSegment = (comment) => segmentAt(comment, indent);
                 // A stranded comment lies wholly on one side of the expression, since
                 // a comment is a token and cannot straddle a node; keeping each on its
                 // own side preserves what it annotates.
@@ -613,18 +614,43 @@ exports.noUsememoForPassByValue = (0, createRule_1.createRule)({
                             text: hoisted,
                         });
                     }
+                    // A comment carried from behind the expression rides out past the
+                    // punctuator that closes the statement the call stood in, where one
+                    // is available to take over. Kept inside the replacement, the line
+                    // break such a comment demands strands that punctuator on a line of
+                    // its own — layout a formatter folds straight back, and the fold
+                    // moves an `eslint-disable-next-line` written there onto a different
+                    // subject, so the rule's own output decides which violations the
+                    // next run enforces (#2138). Where no punctuator can be taken over,
+                    // the comment stays inside the replacement and keeps its break.
+                    const closingPunctuator = trailingComments.length > 0
+                        ? (0, replacementSegments_1.absorbableClosingPunctuator)(sourceCode, node, trailingComments)
+                        : null;
                     const segments = [
                         ...leadingComments
                             .filter((comment) => !(0, replacementSegments_1.requiresOwnLine)(comment))
                             .map(toSegment),
                         { text: replacementText, breakAfter: false },
-                        ...trailingComments.map(toSegment),
+                        ...(closingPunctuator ? [] : trailingComments.map(toSegment)),
                     ];
                     const body = (0, replacementSegments_1.joinSegmentBody)(segments, indent);
-                    const trailing = segments[segments.length - 1].breakAfter
-                        ? `\n${indent}`
-                        : '';
-                    edits.push({ range: node.range, text: `${body}${trailing}` });
+                    if (!closingPunctuator) {
+                        const trailing = segments[segments.length - 1].breakAfter
+                            ? `\n${indent}`
+                            : '';
+                        edits.push({ range: node.range, text: `${body}${trailing}` });
+                    }
+                    else {
+                        // A comment that lands out here annotates the statement rather
+                        // than the expression, so it re-indents to the line the punctuator
+                        // closes instead of to the line the call opened on.
+                        const tailIndent = indentOf(sourceCode.lines[closingPunctuator.loc.end.line - 1] ?? '');
+                        const tail = (0, replacementSegments_1.joinSegmentBody)(trailingComments.map((comment) => segmentAt(comment, tailIndent)), tailIndent);
+                        edits.push({
+                            range: [node.range[0], closingPunctuator.range[1]],
+                            text: `${body}${closingPunctuator.value} ${tail}`,
+                        });
+                    }
                 }
             }
             return {

package/lib/rules/prefer-nullish-coalescing-boolean-props.js

@@ -1235,11 +1235,50 @@ exports.preferNullishCoalescingBooleanProps = (0, createRule_1.createRule)({
                                     ? landingOperator(node, sourceCode)
                                     : null;
                                 const leading = landing ? `\n${bodyIndent}` : '';
-                                const body = (0, replacementSegments_1.joinSegmentBody)(segments, tailIndent);
-                                const trailing = segments[segments.length - 1].breakAfter
+                                const range = replacementRange(node, sourceCode, landing);
+                                // A comment trailing the whole expression rides out past the
+                                // punctuator that closes the statement the chain stands in,
+                                // where one is available to take over. Kept inside the
+                                // replacement, the line break such a comment demands strands
+                                // that punctuator on a line of its own — layout a formatter
+                                // folds straight back, and the fold moves an
+                                // `eslint-disable-next-line` written on the comment's line
+                                // onto a different subject, so the pipeline's formatting order
+                                // decides which violations are enforced (#2139). The span this
+                                // fix replaces can end PAST the node, at a redundant paren the
+                                // widening claims, so the lookup anchors on the span's own
+                                // last token: asked of the node, it answers with that paren —
+                                // a token inside the span — instead of the punctuator behind
+                                // it.
+                                const spanEndToken = range[1] > node.range[1]
+                                    ? sourceCode.getTokenAfter(node)
+                                    : sourceCode.getLastToken(node);
+                                const closingPunctuator = comments.trailing.length > 0 && spanEndToken
+                                    ? (0, replacementSegments_1.absorbableClosingPunctuator)(sourceCode, spanEndToken, comments.trailing)
+                                    : null;
+                                const bodySegments = closingPunctuator
+                                    ? segments.slice(0, segments.length - comments.trailing.length)
+                                    : segments;
+                                const body = (0, replacementSegments_1.joinSegmentBody)(bodySegments, tailIndent);
+                                const trailing = !closingPunctuator && segments[segments.length - 1].breakAfter
                                     ? `\n${lineIndent}`
                                     : '';
-                                const replacement = fixer.replaceTextRange(replacementRange(node, sourceCode, landing), `${leading}${body}${trailing}`);
+                                // A comment that lands out past the punctuator annotates the
+                                // statement rather than the expression, so it re-indents to
+                                // the line the punctuator closes instead of to the chain's own
+                                // depth.
+                                const closingLine = closingPunctuator
+                                    ? sourceCode.lines[closingPunctuator.loc.end.line - 1] ?? ''
+                                    : '';
+                                const carriedTail = closingPunctuator
+                                    ? (0, replacementSegments_1.joinSegmentBody)(comments.trailing.map(toSegment), /^[\t ]*/.exec(closingLine)?.[0] ?? '')
+                                    : '';
+                                const claimedRange = closingPunctuator
+                                    ? [range[0], closingPunctuator.range[1]]
+                                    : range;
+                                const replacement = fixer.replaceTextRange(claimedRange, closingPunctuator
+                                    ? `${leading}${body}${closingPunctuator.value} ${carriedTail}`
+                                    : `${leading}${body}${trailing}`);
                                 if (!keyword || hoisted.length === 0) {
                                     return replacement;
                                 }

package/lib/utils/replacementSegments.d.ts

@@ -1,4 +1,4 @@
-import { TSESTree } from '@typescript-eslint/utils';
+import { TSESLint, TSESTree } from '@typescript-eslint/utils';
 /**
  * Building blocks for fixers that inline an expression in place of a larger
  * span (e.g. a `useMemo(...)` call) and must carry the comments stranded by
@@ -40,6 +40,36 @@ export declare function spansMultipleLines(comment: TSESTree.Comment): boolean;
  * and can keep such a comment inline.
  */
 export declare function requiresOwnLine(comment: TSESTree.Comment): boolean;
+/**
+ * The punctuator a comment carried from behind the expression may move past.
+ *
+ * Such a comment annotates the statement the node stood in, and prettier
+ * prints it AFTER the token that closes that statement — `const x = 1; /* c
+ * *\/`, never `const x = 1 /* c *\/;`. Leaving it inside the statement is
+ * layout prettier rewrites, so the fixed file fails `prettier --check`
+ * (#2079). Leaving it there also strands the punctuator on a line of its own
+ * behind a line-bound comment, which retargets an `eslint-disable-next-line`
+ * onto that stray line the moment prettier folds it back (#2138).
+ *
+ * A comma is a weaker claim and takes only the comments that need a line of
+ * their own. Measured against this repo's prettier: a line comment on a list
+ * element is printed after the comma, while a block comment on one is
+ * printed before it — the opposite of what a semicolon gets. Moving a block
+ * comment past a comma would trade one layout prettier rewrites for another.
+ *
+ * Only a punctuator with nothing but line ending behind it may be taken
+ * over: a line-bound comment landing after it would otherwise swallow
+ * whatever shared that line. Asking for the next token INCLUDING comments
+ * also keeps a comment the fixer does not own from being stepped over.
+ *
+ * The anchor is whatever the replaced SPAN ends at. Where that span is
+ * exactly the node, the node itself serves; where a widening claims tokens
+ * past the node — redundant parentheses the rewrite discards — the anchor
+ * must be the span's own last token, because asked of the node the lookup
+ * answers with a token INSIDE the span instead of the punctuator behind it
+ * (#2139).
+ */
+export declare function absorbableClosingPunctuator(sourceCode: Readonly<TSESLint.SourceCode>, anchor: TSESTree.Node | TSESTree.Token, trailingComments: readonly TSESTree.Comment[]): TSESTree.Token | null;
 export type ReplacementSegment = {
     text: string;
     breakAfter: boolean;

package/lib/utils/replacementSegments.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.joinSegments = exports.joinSegmentBody = exports.requiresOwnLine = exports.spansMultipleLines = exports.requiresLineBreakAfter = void 0;
+exports.joinSegments = exports.joinSegmentBody = exports.absorbableClosingPunctuator = exports.requiresOwnLine = exports.spansMultipleLines = exports.requiresLineBreakAfter = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const disableDirectives_1 = require("./disableDirectives");
 /**
@@ -56,6 +56,49 @@ function requiresOwnLine(comment) {
     return requiresLineBreakAfter(comment) || spansMultipleLines(comment);
 }
 exports.requiresOwnLine = requiresOwnLine;
+/**
+ * The punctuator a comment carried from behind the expression may move past.
+ *
+ * Such a comment annotates the statement the node stood in, and prettier
+ * prints it AFTER the token that closes that statement — `const x = 1; /* c
+ * *\/`, never `const x = 1 /* c *\/;`. Leaving it inside the statement is
+ * layout prettier rewrites, so the fixed file fails `prettier --check`
+ * (#2079). Leaving it there also strands the punctuator on a line of its own
+ * behind a line-bound comment, which retargets an `eslint-disable-next-line`
+ * onto that stray line the moment prettier folds it back (#2138).
+ *
+ * A comma is a weaker claim and takes only the comments that need a line of
+ * their own. Measured against this repo's prettier: a line comment on a list
+ * element is printed after the comma, while a block comment on one is
+ * printed before it — the opposite of what a semicolon gets. Moving a block
+ * comment past a comma would trade one layout prettier rewrites for another.
+ *
+ * Only a punctuator with nothing but line ending behind it may be taken
+ * over: a line-bound comment landing after it would otherwise swallow
+ * whatever shared that line. Asking for the next token INCLUDING comments
+ * also keeps a comment the fixer does not own from being stepped over.
+ *
+ * The anchor is whatever the replaced SPAN ends at. Where that span is
+ * exactly the node, the node itself serves; where a widening claims tokens
+ * past the node — redundant parentheses the rewrite discards — the anchor
+ * must be the span's own last token, because asked of the node the lookup
+ * answers with a token INSIDE the span instead of the punctuator behind it
+ * (#2139).
+ */
+function absorbableClosingPunctuator(sourceCode, anchor, trailingComments) {
+    const next = sourceCode.getTokenAfter(anchor, { includeComments: true });
+    if (!next ||
+        next.type !== utils_1.AST_TOKEN_TYPES.Punctuator ||
+        (next.value !== ';' && next.value !== ',')) {
+        return null;
+    }
+    if (next.value === ',' && !trailingComments.every(requiresLineBreakAfter)) {
+        return null;
+    }
+    const line = sourceCode.lines[next.loc.end.line - 1] ?? '';
+    return line.slice(next.loc.end.column).trim() === '' ? next : null;
+}
+exports.absorbableClosingPunctuator = absorbableClosingPunctuator;
 /**
  * Joins the inlined expression and its carried comments into one run of text,
  * keeping each comment on the side of the expression it was written on and

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "1.20.174",
+    "date": "2026-08-26T04:47:21.242Z",
+    "rules": [
+      {
+        "name": "enforce-firestore-set-merge",
+        "changeType": "fix",
+        "issues": [
+          2140
+        ],
+        "summary": "emit the appended option's separator before a trailing comment (closes #2140)"
+      },
+      {
+        "name": "no-usememo-for-pass-by-value",
+        "changeType": "fix",
+        "issues": [
+          2138
+        ],
+        "summary": "carry the trailing comment past the statement terminator (closes #2138)"
+      },
+      {
+        "name": "prefer-nullish-coalescing-boolean-props",
+        "changeType": "fix",
+        "issues": [
+          2139
+        ],
+        "summary": "carry the trailing comment past the statement terminator (closes #2139)"
+      }
+    ]
+  },
   {
     "version": "1.20.173",
     "date": "2026-08-25T23:22:38.601Z",