@dereekb/util 13.11.3 → 13.11.4

package/eslint/index.cjs.js

@@ -76,7 +76,11 @@
     if (((_implNode_id = implNode.id) === null || _implNode_id === void 0 ? void 0 : _implNode_id.type) !== 'Identifier') {
         return {
             jsdoc: null,
-            orphanLineComments: []
+            orphanLineComments: [],
+            hasOverloads: false,
+            implLineComment: null,
+            implHasSurvivingAnnotation: false,
+            chainStartStatement: getStatementAnchor(implNode)
         };
     }
     var name = implNode.id.name;
@@ -97,10 +101,16 @@
             }
         }
     }
+    var hasOverloads = chainStartIdx >= 0 && implIdx >= 0 && chainStartIdx < implIdx;
     var firstJsdoc = null;
     var anyJsdocHasNoSideEffects = false;
+    var implJsdocHasNoSideEffects = false;
     var orphanLineComments = [];
-    function processCommentsForStatement(stmt) {
+    
+    // declaration is required (TS erases overload signatures, so only this annotation survives).
+    // Track it separately so callers don't accidentally remove it.
+    var implLineComment = null;
+    function processCommentsForStatement(stmt, isImplStatement) {
         var comments = sourceCode.getCommentsBefore(stmt) || [];
         var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
         try {
@@ -110,6 +120,9 @@
                     var hasMarker = commentContainsNoSideEffects(comment.value);
                     if (hasMarker) {
                         anyJsdocHasNoSideEffects = true;
+                        if (isImplStatement) {
+                            implJsdocHasNoSideEffects = true;
+                        }
                     }
                     // Auto-fix target: the first JSDoc in the chain (where the function's docs conventionally live).
                     if (!firstJsdoc) {
@@ -120,7 +133,17 @@
                         };
                     }
                 } else if (commentContainsNoSideEffects(comment.value)) {
-                    orphanLineComments.push(comment);
+                    // Only the impl-leading annotation on an overloaded function is "required"; others are orphans.
+                    // When multiple line/block comments stack above the impl, keep the closest one (last in source
+                    // order) as the canonical impl annotation and treat the rest as orphans to consolidate.
+                    if (isImplStatement && hasOverloads) {
+                        if (implLineComment) {
+                            orphanLineComments.push(implLineComment);
+                        }
+                        implLineComment = comment;
+                    } else {
+                        orphanLineComments.push(comment);
+                    }
                 }
             }
         } catch (err) {
@@ -140,11 +163,11 @@
     }
     if (chainStartIdx >= 0 && implIdx >= 0) {
         for(var i1 = chainStartIdx; i1 <= implIdx; i1 += 1){
-            processCommentsForStatement(container.body[i1]);
+            processCommentsForStatement(container.body[i1], i1 === implIdx);
         }
     } else {
         // Fallback: no container body found; just look at comments before the implementation.
-        processCommentsForStatement(implStmt);
+        processCommentsForStatement(implStmt, false);
     }
     // Report the first JSDoc as the canonical jsdoc, but reflect any-in-chain satisfaction
     // so callers don't re-annotate when the marker is already present elsewhere in the chain.
@@ -157,9 +180,18 @@
             hasNoSideEffects: anyJsdocHasNoSideEffects
         };
     }
+    // The implementation's emitted JS carries the marker when:
+    //   - non-overloaded: the function's (only) JSDoc has the tag (it's directly attached to the impl), OR
+    //   - overloaded: a line/block comment sits above the impl, OR the impl has its own tagged JSDoc.
+    var implHasSurvivingAnnotation = hasOverloads ? implLineComment !== null || implJsdocHasNoSideEffects : anyJsdocHasNoSideEffects;
+    var chainStartStatement = chainStartIdx >= 0 && container && Array.isArray(container.body) ? container.body[chainStartIdx] : implStmt;
     return {
         jsdoc: resolved,
-        orphanLineComments: orphanLineComments
+        orphanLineComments: orphanLineComments,
+        hasOverloads: hasOverloads,
+        implLineComment: implLineComment,
+        implHasSurvivingAnnotation: implHasSurvivingAnnotation,
+        chainStartStatement: chainStartStatement
     };
 }
 
@@ -258,15 +290,7 @@ function _unsupported_iterable_to_array$1(o, minLen) {
     });
     return _to_consumable_array(DEFAULT_NAME_PATTERNS).concat(_to_consumable_array(additional));
 }
-/**
- * ESLint rule requiring the side-effect-free annotation inside the JSDoc of every
- * factory function — that is, declarations carrying the dbxUtilKind factory JSDoc tag,
- * and optionally functions matching factory name patterns.
- *
- * Auto-fix inserts the annotation as the last line of the JSDoc, removes any
- * redundant standalone-comment annotation between the JSDoc and the declaration,
- * and (when matched by name with no JSDoc) creates a minimal JSDoc carrying both tags.
- */ var utilRequireNoSideEffectsRule = {
+ var utilRequireNoSideEffectsRule = {
     meta: {
         type: 'suggestion',
         fixable: 'code',
@@ -276,7 +300,8 @@ function _unsupported_iterable_to_array$1(o, minLen) {
         },
         messages: {
             missingNoSideEffectsJsdoc: 'Factory function "{{name}}" is missing the `@__NO_SIDE_EFFECTS__` annotation in its JSDoc. Add it as the last tag inside the JSDoc block so esbuild can drop unused calls during tree-shaking.',
-            missingJsdocForFactory: 'Factory-named function "{{name}}" has no JSDoc block. Add a JSDoc block containing `@__NO_SIDE_EFFECTS__` so esbuild can drop unused calls during tree-shaking.'
+            missingJsdocForFactory: 'Factory-named function "{{name}}" has no JSDoc block. Add a JSDoc block containing `@__NO_SIDE_EFFECTS__` so esbuild can drop unused calls during tree-shaking.',
+            missingImplAnnotationOverloaded: 'Overloaded factory function "{{name}}" needs `@__NO_SIDE_EFFECTS__` directly on its implementation — TypeScript erases overload signatures during emit, so the JSDoc tag on the first overload is dropped from the bundled JavaScript. Add a `// @__NO_SIDE_EFFECTS__` line comment immediately above the implementation declaration.'
         },
         schema: [
             {
@@ -319,19 +344,32 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             if (!name) {
                 return;
             }
-            // Walks the overload chain (if any) so we read the JSDoc on the first overload
-            // and any orphan annotations placed between overloads or above the implementation.
-            var _findFunctionLeadingContext = findFunctionLeadingContext(sourceCode, node), jsdoc = _findFunctionLeadingContext.jsdoc, redundantLineComments = _findFunctionLeadingContext.orphanLineComments;
+            // Walks the overload chain (if any) so we read the JSDoc on the first overload,
+            // any orphan annotations placed between overloads, and the (preserved) impl-leading annotation.
+            var _findFunctionLeadingContext = findFunctionLeadingContext(sourceCode, node), jsdoc = _findFunctionLeadingContext.jsdoc, redundantLineComments = _findFunctionLeadingContext.orphanLineComments, hasOverloads = _findFunctionLeadingContext.hasOverloads, implLineComment = _findFunctionLeadingContext.implLineComment, implHasSurvivingAnnotation = _findFunctionLeadingContext.implHasSurvivingAnnotation, chainStartStatement = _findFunctionLeadingContext.chainStartStatement;
             var taggedAsFactory = (jsdoc === null || jsdoc === void 0 ? void 0 : (_jsdoc_text = jsdoc.text) === null || _jsdoc_text === void 0 ? void 0 : _jsdoc_text.includes(FACTORY_JSDOC_TAG)) === true;
             var matchedByName = !taggedAsFactory && namePatterns.length > 0 && nameMatchesFactoryPattern(name);
             if (!taggedAsFactory && !matchedByName) {
                 return;
             }
-            // Already annotated inside the JSDoc — passing.
-            if (jsdoc === null || jsdoc === void 0 ? void 0 : jsdoc.hasNoSideEffects) {
+            // The bundled implementation already carries the marker — passing. This covers:
+            //   - non-overloaded with the tag in the (only) JSDoc, AND
+            
+            if (implHasSurvivingAnnotation) {
                 return;
             }
-            var messageId = jsdoc ? 'missingNoSideEffectsJsdoc' : 'missingJsdocForFactory';
+            // Choose the most specific message:
+            //   - overloaded + JSDoc with the tag on first overload but no impl annotation → impl-specific.
+            //   - has any JSDoc → JSDoc tag missing.
+            //   - no JSDoc → JSDoc must be created.
+            var messageId;
+            if (hasOverloads && (jsdoc === null || jsdoc === void 0 ? void 0 : jsdoc.hasNoSideEffects)) {
+                messageId = 'missingImplAnnotationOverloaded';
+            } else if (jsdoc) {
+                messageId = 'missingNoSideEffectsJsdoc';
+            } else {
+                messageId = 'missingJsdocForFactory';
+            }
             context.report({
                 node: node.id,
                 messageId: messageId,
@@ -340,7 +378,10 @@ function _unsupported_iterable_to_array$1(o, minLen) {
                 },
                 fix: function fix(fixer) {
                     var fixes = [];
-                    if (jsdoc) {
+                    // Add the JSDoc tag (or create the JSDoc) so consumer-facing docs reflect the marker.
+                    // Skipped when the existing JSDoc already carries the tag — only the impl-line comment
+                    // would be missing in that case (handled below).
+                    if (jsdoc && !jsdoc.hasNoSideEffects) {
                         var jsdocText = jsdoc.text; // text excludes /* and */
                         var jsdocStart = jsdoc.node.range[0];
                         var jsdocEnd = jsdoc.node.range[1];
@@ -370,11 +411,10 @@ function _unsupported_iterable_to_array$1(o, minLen) {
                                 closingLineStart
                             ], insertion));
                         }
-                    } else {
-                        // No JSDoc — create one above the function declaration with matching indent.
-                        // Use the function's leading position. Account for `export` keyword: getCommentsBefore
-                        // attaches to the declaration including its modifiers, so node.range[0] is correct.
-                        var nodeStart = node.range[0];
+                    } else if (!jsdoc) {
+                        // No JSDoc anywhere — create one above the FIRST statement in the chain. For overloaded
+                        // functions the canonical doc placement is on the first overload, not the implementation.
+                        var nodeStart = chainStartStatement.range[0];
                         var indent = getLineIndent(sourceText, nodeStart);
                         var newJsdoc = "/**\n".concat(indent, " * @dbxUtilKind factory\n").concat(indent, " * ").concat(NO_SIDE_EFFECTS_TAG, "\n").concat(indent, " */\n").concat(indent);
                         fixes.push(fixer.insertTextBeforeRange([
@@ -382,6 +422,18 @@ function _unsupported_iterable_to_array$1(o, minLen) {
                             nodeStart
                         ], newJsdoc));
                     }
+                    
+                    // implementation so the marker survives TypeScript's overload-signature erasure and reaches
+                    // the bundled JavaScript. Skipped when one is already in place.
+                    if (hasOverloads && !implLineComment) {
+                        var implAnchor = getStatementAnchor(node);
+                        var implStart = implAnchor.range[0];
+                        var indent1 = getLineIndent(sourceText, implStart);
+                        fixes.push(fixer.insertTextBeforeRange([
+                            implStart,
+                            implStart
+                        ], "// ".concat(NO_SIDE_EFFECTS_TAG, "\n").concat(indent1)));
+                    }
                     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
                     try {
                         // Remove any redundant adjacent annotation comments now that JSDoc carries the tag.
@@ -485,7 +537,8 @@ function _unsupported_iterable_to_array(o, minLen) {
             recommended: true
         },
         messages: {
-            preferJsdocPlacement: 'Move the `@__NO_SIDE_EFFECTS__` annotation into the JSDoc block of "{{name}}" (as the last tag before the closing) instead of a separate line comment.'
+            preferJsdocPlacement: 'Move the `@__NO_SIDE_EFFECTS__` annotation into the JSDoc block of "{{name}}" (as the last tag before the closing) instead of a separate line comment.',
+            missingImplAnnotationOverloaded: '"{{name}}" carries `@__NO_SIDE_EFFECTS__` in its first-overload JSDoc but is overloaded — TypeScript erases overload signatures during emit, so the JSDoc tag is dropped from the bundled JavaScript. Add a `// @__NO_SIDE_EFFECTS__` line comment immediately above the implementation declaration.'
         },
         schema: []
     },
@@ -501,16 +554,32 @@ function _unsupported_iterable_to_array(o, minLen) {
                 return;
             }
             var name = node.id.name;
-            // Walks the overload chain (if any) so we find the JSDoc on the first overload
-            // and any orphan annotations between overloads or above the implementation.
-            var _findFunctionLeadingContext = findFunctionLeadingContext(sourceCode, node), jsdoc = _findFunctionLeadingContext.jsdoc, orphanLineComments = _findFunctionLeadingContext.orphanLineComments;
-            // Only flag when both signals are present: a JSDoc to absorb the tag, AND an orphan annotation.
-            if (!jsdoc || orphanLineComments.length === 0) {
+            // Walks the overload chain (if any) so we find the JSDoc on the first overload,
+            // any orphan annotations between overloads, and the (preserved) impl-leading annotation.
+            var _findFunctionLeadingContext = findFunctionLeadingContext(sourceCode, node), jsdoc = _findFunctionLeadingContext.jsdoc, orphanLineComments = _findFunctionLeadingContext.orphanLineComments, implLineComment = _findFunctionLeadingContext.implLineComment, hasOverloads = _findFunctionLeadingContext.hasOverloads, implHasSurvivingAnnotation = _findFunctionLeadingContext.implHasSurvivingAnnotation;
+            if (!jsdoc) {
+                return;
+            }
+            // Three reasons to fire:
+            //   1. There's an annotation form (orphan OR overload-impl line comment) and the JSDoc
+            //      doesn't yet carry the tag — the JSDoc needs the tag added (for docs/tooling).
+            //   2. There are orphan annotations to consolidate, regardless of JSDoc tag state.
+            //   3. Function is overloaded, JSDoc carries the tag, but the implementation lacks any
+            //      surviving annotation — TS erases overload signatures during emit, so the JSDoc tag
+            
+            //      above the impl so the bundler still sees the hint.
+            // The impl line comment on overloaded functions is REQUIRED for tree-shaking and is never
+            // removed — it is only counted as a signal that the JSDoc should also carry the tag.
+            var hasAnyAnnotationSource = orphanLineComments.length > 0 || implLineComment !== null;
+            var needsJsdocTag = !jsdoc.hasNoSideEffects && hasAnyAnnotationSource;
+            var needsOrphanRemoval = orphanLineComments.length > 0;
+            var needsImplLineCommentForOverload = jsdoc.hasNoSideEffects && hasOverloads && !implHasSurvivingAnnotation;
+            if (!needsJsdocTag && !needsOrphanRemoval && !needsImplLineCommentForOverload) {
                 return;
             }
             context.report({
                 node: node.id,
-                messageId: 'preferJsdocPlacement',
+                messageId: needsImplLineCommentForOverload && !needsJsdocTag && !needsOrphanRemoval ? 'missingImplAnnotationOverloaded' : 'preferJsdocPlacement',
                 data: {
                     name: name
                 },
@@ -520,8 +589,8 @@ function _unsupported_iterable_to_array(o, minLen) {
                     var jsdocStart = jsdoc.node.range[0];
                     var jsdocEnd = jsdoc.node.range[1];
                     var jsdocIndent = getLineIndent(sourceText, jsdocStart);
-                    // Insert into JSDoc only if the tag isn't already there (preserve idempotency).
-                    if (!jsdoc.hasNoSideEffects) {
+                    // Insert into JSDoc only if needed (preserve idempotency and skip when only orphans need removal).
+                    if (needsJsdocTag) {
                         if (!jsdocText.includes('\n')) {
                             // Single-line JSDoc — expand to multi-line so the new tag has its own line.
                             var bodyTrimmed = jsdocText.replace(/^\*\s*/, '').replace(/\s*$/, '');
@@ -544,6 +613,17 @@ function _unsupported_iterable_to_array(o, minLen) {
                             ], insertion));
                         }
                     }
+                    // Overloaded function with no surviving impl annotation — insert the bundler-required
+                    // line comment directly above the implementation declaration.
+                    if (needsImplLineCommentForOverload) {
+                        var implAnchor = getStatementAnchor(node);
+                        var implStart = implAnchor.range[0];
+                        var indent = getLineIndent(sourceText, implStart);
+                        fixes.push(fixer.insertTextBeforeRange([
+                            implStart,
+                            implStart
+                        ], "// ".concat(NO_SIDE_EFFECTS_TAG, "\n").concat(indent)));
+                    }
                     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
                     try {
                         // Remove the orphan line/block comment annotations.

package/eslint/index.esm.js

@@ -74,7 +74,11 @@
     if (((_implNode_id = implNode.id) === null || _implNode_id === void 0 ? void 0 : _implNode_id.type) !== 'Identifier') {
         return {
             jsdoc: null,
-            orphanLineComments: []
+            orphanLineComments: [],
+            hasOverloads: false,
+            implLineComment: null,
+            implHasSurvivingAnnotation: false,
+            chainStartStatement: getStatementAnchor(implNode)
         };
     }
     var name = implNode.id.name;
@@ -95,10 +99,16 @@
             }
         }
     }
+    var hasOverloads = chainStartIdx >= 0 && implIdx >= 0 && chainStartIdx < implIdx;
     var firstJsdoc = null;
     var anyJsdocHasNoSideEffects = false;
+    var implJsdocHasNoSideEffects = false;
     var orphanLineComments = [];
-    function processCommentsForStatement(stmt) {
+    
+    // declaration is required (TS erases overload signatures, so only this annotation survives).
+    // Track it separately so callers don't accidentally remove it.
+    var implLineComment = null;
+    function processCommentsForStatement(stmt, isImplStatement) {
         var comments = sourceCode.getCommentsBefore(stmt) || [];
         var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
         try {
@@ -108,6 +118,9 @@
                     var hasMarker = commentContainsNoSideEffects(comment.value);
                     if (hasMarker) {
                         anyJsdocHasNoSideEffects = true;
+                        if (isImplStatement) {
+                            implJsdocHasNoSideEffects = true;
+                        }
                     }
                     // Auto-fix target: the first JSDoc in the chain (where the function's docs conventionally live).
                     if (!firstJsdoc) {
@@ -118,7 +131,17 @@
                         };
                     }
                 } else if (commentContainsNoSideEffects(comment.value)) {
-                    orphanLineComments.push(comment);
+                    // Only the impl-leading annotation on an overloaded function is "required"; others are orphans.
+                    // When multiple line/block comments stack above the impl, keep the closest one (last in source
+                    // order) as the canonical impl annotation and treat the rest as orphans to consolidate.
+                    if (isImplStatement && hasOverloads) {
+                        if (implLineComment) {
+                            orphanLineComments.push(implLineComment);
+                        }
+                        implLineComment = comment;
+                    } else {
+                        orphanLineComments.push(comment);
+                    }
                 }
             }
         } catch (err) {
@@ -138,11 +161,11 @@
     }
     if (chainStartIdx >= 0 && implIdx >= 0) {
         for(var i1 = chainStartIdx; i1 <= implIdx; i1 += 1){
-            processCommentsForStatement(container.body[i1]);
+            processCommentsForStatement(container.body[i1], i1 === implIdx);
         }
     } else {
         // Fallback: no container body found; just look at comments before the implementation.
-        processCommentsForStatement(implStmt);
+        processCommentsForStatement(implStmt, false);
     }
     // Report the first JSDoc as the canonical jsdoc, but reflect any-in-chain satisfaction
     // so callers don't re-annotate when the marker is already present elsewhere in the chain.
@@ -155,9 +178,18 @@
             hasNoSideEffects: anyJsdocHasNoSideEffects
         };
     }
+    // The implementation's emitted JS carries the marker when:
+    //   - non-overloaded: the function's (only) JSDoc has the tag (it's directly attached to the impl), OR
+    //   - overloaded: a line/block comment sits above the impl, OR the impl has its own tagged JSDoc.
+    var implHasSurvivingAnnotation = hasOverloads ? implLineComment !== null || implJsdocHasNoSideEffects : anyJsdocHasNoSideEffects;
+    var chainStartStatement = chainStartIdx >= 0 && container && Array.isArray(container.body) ? container.body[chainStartIdx] : implStmt;
     return {
         jsdoc: resolved,
-        orphanLineComments: orphanLineComments
+        orphanLineComments: orphanLineComments,
+        hasOverloads: hasOverloads,
+        implLineComment: implLineComment,
+        implHasSurvivingAnnotation: implHasSurvivingAnnotation,
+        chainStartStatement: chainStartStatement
     };
 }
 
@@ -256,15 +288,7 @@ function _unsupported_iterable_to_array$1(o, minLen) {
     });
     return _to_consumable_array(DEFAULT_NAME_PATTERNS).concat(_to_consumable_array(additional));
 }
-/**
- * ESLint rule requiring the side-effect-free annotation inside the JSDoc of every
- * factory function — that is, declarations carrying the dbxUtilKind factory JSDoc tag,
- * and optionally functions matching factory name patterns.
- *
- * Auto-fix inserts the annotation as the last line of the JSDoc, removes any
- * redundant standalone-comment annotation between the JSDoc and the declaration,
- * and (when matched by name with no JSDoc) creates a minimal JSDoc carrying both tags.
- */ var utilRequireNoSideEffectsRule = {
+ var utilRequireNoSideEffectsRule = {
     meta: {
         type: 'suggestion',
         fixable: 'code',
@@ -274,7 +298,8 @@ function _unsupported_iterable_to_array$1(o, minLen) {
         },
         messages: {
             missingNoSideEffectsJsdoc: 'Factory function "{{name}}" is missing the `@__NO_SIDE_EFFECTS__` annotation in its JSDoc. Add it as the last tag inside the JSDoc block so esbuild can drop unused calls during tree-shaking.',
-            missingJsdocForFactory: 'Factory-named function "{{name}}" has no JSDoc block. Add a JSDoc block containing `@__NO_SIDE_EFFECTS__` so esbuild can drop unused calls during tree-shaking.'
+            missingJsdocForFactory: 'Factory-named function "{{name}}" has no JSDoc block. Add a JSDoc block containing `@__NO_SIDE_EFFECTS__` so esbuild can drop unused calls during tree-shaking.',
+            missingImplAnnotationOverloaded: 'Overloaded factory function "{{name}}" needs `@__NO_SIDE_EFFECTS__` directly on its implementation — TypeScript erases overload signatures during emit, so the JSDoc tag on the first overload is dropped from the bundled JavaScript. Add a `// @__NO_SIDE_EFFECTS__` line comment immediately above the implementation declaration.'
         },
         schema: [
             {
@@ -317,19 +342,32 @@ function _unsupported_iterable_to_array$1(o, minLen) {
             if (!name) {
                 return;
             }
-            // Walks the overload chain (if any) so we read the JSDoc on the first overload
-            // and any orphan annotations placed between overloads or above the implementation.
-            var _findFunctionLeadingContext = findFunctionLeadingContext(sourceCode, node), jsdoc = _findFunctionLeadingContext.jsdoc, redundantLineComments = _findFunctionLeadingContext.orphanLineComments;
+            // Walks the overload chain (if any) so we read the JSDoc on the first overload,
+            // any orphan annotations placed between overloads, and the (preserved) impl-leading annotation.
+            var _findFunctionLeadingContext = findFunctionLeadingContext(sourceCode, node), jsdoc = _findFunctionLeadingContext.jsdoc, redundantLineComments = _findFunctionLeadingContext.orphanLineComments, hasOverloads = _findFunctionLeadingContext.hasOverloads, implLineComment = _findFunctionLeadingContext.implLineComment, implHasSurvivingAnnotation = _findFunctionLeadingContext.implHasSurvivingAnnotation, chainStartStatement = _findFunctionLeadingContext.chainStartStatement;
             var taggedAsFactory = (jsdoc === null || jsdoc === void 0 ? void 0 : (_jsdoc_text = jsdoc.text) === null || _jsdoc_text === void 0 ? void 0 : _jsdoc_text.includes(FACTORY_JSDOC_TAG)) === true;
             var matchedByName = !taggedAsFactory && namePatterns.length > 0 && nameMatchesFactoryPattern(name);
             if (!taggedAsFactory && !matchedByName) {
                 return;
             }
-            // Already annotated inside the JSDoc — passing.
-            if (jsdoc === null || jsdoc === void 0 ? void 0 : jsdoc.hasNoSideEffects) {
+            // The bundled implementation already carries the marker — passing. This covers:
+            //   - non-overloaded with the tag in the (only) JSDoc, AND
+            
+            if (implHasSurvivingAnnotation) {
                 return;
             }
-            var messageId = jsdoc ? 'missingNoSideEffectsJsdoc' : 'missingJsdocForFactory';
+            // Choose the most specific message:
+            //   - overloaded + JSDoc with the tag on first overload but no impl annotation → impl-specific.
+            //   - has any JSDoc → JSDoc tag missing.
+            //   - no JSDoc → JSDoc must be created.
+            var messageId;
+            if (hasOverloads && (jsdoc === null || jsdoc === void 0 ? void 0 : jsdoc.hasNoSideEffects)) {
+                messageId = 'missingImplAnnotationOverloaded';
+            } else if (jsdoc) {
+                messageId = 'missingNoSideEffectsJsdoc';
+            } else {
+                messageId = 'missingJsdocForFactory';
+            }
             context.report({
                 node: node.id,
                 messageId: messageId,
@@ -338,7 +376,10 @@ function _unsupported_iterable_to_array$1(o, minLen) {
                 },
                 fix: function fix(fixer) {
                     var fixes = [];
-                    if (jsdoc) {
+                    // Add the JSDoc tag (or create the JSDoc) so consumer-facing docs reflect the marker.
+                    // Skipped when the existing JSDoc already carries the tag — only the impl-line comment
+                    // would be missing in that case (handled below).
+                    if (jsdoc && !jsdoc.hasNoSideEffects) {
                         var jsdocText = jsdoc.text; // text excludes /* and */
                         var jsdocStart = jsdoc.node.range[0];
                         var jsdocEnd = jsdoc.node.range[1];
@@ -368,11 +409,10 @@ function _unsupported_iterable_to_array$1(o, minLen) {
                                 closingLineStart
                             ], insertion));
                         }
-                    } else {
-                        // No JSDoc — create one above the function declaration with matching indent.
-                        // Use the function's leading position. Account for `export` keyword: getCommentsBefore
-                        // attaches to the declaration including its modifiers, so node.range[0] is correct.
-                        var nodeStart = node.range[0];
+                    } else if (!jsdoc) {
+                        // No JSDoc anywhere — create one above the FIRST statement in the chain. For overloaded
+                        // functions the canonical doc placement is on the first overload, not the implementation.
+                        var nodeStart = chainStartStatement.range[0];
                         var indent = getLineIndent(sourceText, nodeStart);
                         var newJsdoc = "/**\n".concat(indent, " * @dbxUtilKind factory\n").concat(indent, " * ").concat(NO_SIDE_EFFECTS_TAG, "\n").concat(indent, " */\n").concat(indent);
                         fixes.push(fixer.insertTextBeforeRange([
@@ -380,6 +420,18 @@ function _unsupported_iterable_to_array$1(o, minLen) {
                             nodeStart
                         ], newJsdoc));
                     }
+                    
+                    // implementation so the marker survives TypeScript's overload-signature erasure and reaches
+                    // the bundled JavaScript. Skipped when one is already in place.
+                    if (hasOverloads && !implLineComment) {
+                        var implAnchor = getStatementAnchor(node);
+                        var implStart = implAnchor.range[0];
+                        var indent1 = getLineIndent(sourceText, implStart);
+                        fixes.push(fixer.insertTextBeforeRange([
+                            implStart,
+                            implStart
+                        ], "// ".concat(NO_SIDE_EFFECTS_TAG, "\n").concat(indent1)));
+                    }
                     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
                     try {
                         // Remove any redundant adjacent annotation comments now that JSDoc carries the tag.
@@ -483,7 +535,8 @@ function _unsupported_iterable_to_array(o, minLen) {
             recommended: true
         },
         messages: {
-            preferJsdocPlacement: 'Move the `@__NO_SIDE_EFFECTS__` annotation into the JSDoc block of "{{name}}" (as the last tag before the closing) instead of a separate line comment.'
+            preferJsdocPlacement: 'Move the `@__NO_SIDE_EFFECTS__` annotation into the JSDoc block of "{{name}}" (as the last tag before the closing) instead of a separate line comment.',
+            missingImplAnnotationOverloaded: '"{{name}}" carries `@__NO_SIDE_EFFECTS__` in its first-overload JSDoc but is overloaded — TypeScript erases overload signatures during emit, so the JSDoc tag is dropped from the bundled JavaScript. Add a `// @__NO_SIDE_EFFECTS__` line comment immediately above the implementation declaration.'
         },
         schema: []
     },
@@ -499,16 +552,32 @@ function _unsupported_iterable_to_array(o, minLen) {
                 return;
             }
             var name = node.id.name;
-            // Walks the overload chain (if any) so we find the JSDoc on the first overload
-            // and any orphan annotations between overloads or above the implementation.
-            var _findFunctionLeadingContext = findFunctionLeadingContext(sourceCode, node), jsdoc = _findFunctionLeadingContext.jsdoc, orphanLineComments = _findFunctionLeadingContext.orphanLineComments;
-            // Only flag when both signals are present: a JSDoc to absorb the tag, AND an orphan annotation.
-            if (!jsdoc || orphanLineComments.length === 0) {
+            // Walks the overload chain (if any) so we find the JSDoc on the first overload,
+            // any orphan annotations between overloads, and the (preserved) impl-leading annotation.
+            var _findFunctionLeadingContext = findFunctionLeadingContext(sourceCode, node), jsdoc = _findFunctionLeadingContext.jsdoc, orphanLineComments = _findFunctionLeadingContext.orphanLineComments, implLineComment = _findFunctionLeadingContext.implLineComment, hasOverloads = _findFunctionLeadingContext.hasOverloads, implHasSurvivingAnnotation = _findFunctionLeadingContext.implHasSurvivingAnnotation;
+            if (!jsdoc) {
+                return;
+            }
+            // Three reasons to fire:
+            //   1. There's an annotation form (orphan OR overload-impl line comment) and the JSDoc
+            //      doesn't yet carry the tag — the JSDoc needs the tag added (for docs/tooling).
+            //   2. There are orphan annotations to consolidate, regardless of JSDoc tag state.
+            //   3. Function is overloaded, JSDoc carries the tag, but the implementation lacks any
+            //      surviving annotation — TS erases overload signatures during emit, so the JSDoc tag
+            
+            //      above the impl so the bundler still sees the hint.
+            // The impl line comment on overloaded functions is REQUIRED for tree-shaking and is never
+            // removed — it is only counted as a signal that the JSDoc should also carry the tag.
+            var hasAnyAnnotationSource = orphanLineComments.length > 0 || implLineComment !== null;
+            var needsJsdocTag = !jsdoc.hasNoSideEffects && hasAnyAnnotationSource;
+            var needsOrphanRemoval = orphanLineComments.length > 0;
+            var needsImplLineCommentForOverload = jsdoc.hasNoSideEffects && hasOverloads && !implHasSurvivingAnnotation;
+            if (!needsJsdocTag && !needsOrphanRemoval && !needsImplLineCommentForOverload) {
                 return;
             }
             context.report({
                 node: node.id,
-                messageId: 'preferJsdocPlacement',
+                messageId: needsImplLineCommentForOverload && !needsJsdocTag && !needsOrphanRemoval ? 'missingImplAnnotationOverloaded' : 'preferJsdocPlacement',
                 data: {
                     name: name
                 },
@@ -518,8 +587,8 @@ function _unsupported_iterable_to_array(o, minLen) {
                     var jsdocStart = jsdoc.node.range[0];
                     var jsdocEnd = jsdoc.node.range[1];
                     var jsdocIndent = getLineIndent(sourceText, jsdocStart);
-                    // Insert into JSDoc only if the tag isn't already there (preserve idempotency).
-                    if (!jsdoc.hasNoSideEffects) {
+                    // Insert into JSDoc only if needed (preserve idempotency and skip when only orphans need removal).
+                    if (needsJsdocTag) {
                         if (!jsdocText.includes('\n')) {
                             // Single-line JSDoc — expand to multi-line so the new tag has its own line.
                             var bodyTrimmed = jsdocText.replace(/^\*\s*/, '').replace(/\s*$/, '');
@@ -542,6 +611,17 @@ function _unsupported_iterable_to_array(o, minLen) {
                             ], insertion));
                         }
                     }
+                    // Overloaded function with no surviving impl annotation — insert the bundler-required
+                    // line comment directly above the implementation declaration.
+                    if (needsImplLineCommentForOverload) {
+                        var implAnchor = getStatementAnchor(node);
+                        var implStart = implAnchor.range[0];
+                        var indent = getLineIndent(sourceText, implStart);
+                        fixes.push(fixer.insertTextBeforeRange([
+                            implStart,
+                            implStart
+                        ], "// ".concat(NO_SIDE_EFFECTS_TAG, "\n").concat(indent)));
+                    }
                     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
                     try {
                         // Remove the orphan line/block comment annotations.

package/eslint/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util/eslint",
-  "version": "13.11.3",
+  "version": "13.11.4",
   "peerDependencies": {
     "@typescript-eslint/utils": "8.59.0"
   },

package/eslint/src/lib/comments.d.ts

@@ -10,7 +10,45 @@ export interface JsdocCommentInfo {
 }
 export interface FunctionLeadingContext {
     readonly jsdoc: JsdocCommentInfo | null;
+    /**
+     * Adjacent `@__NO_SIDE_EFFECTS__` line/block comments that should be migrated into the JSDoc
+     * and removed. Excludes the implementation-leading annotation on overloaded functions, which
+     * is tracked separately by {@link implLineComment} because it must be preserved.
+     */
     readonly orphanLineComments: readonly AstNode[];
+    /**
+     * True when this implementation is preceded by sibling overload signatures (`TSDeclareFunction`
+     * statements with the same name).
+     */
+    readonly hasOverloads: boolean;
+    /**
+     * The `@__NO_SIDE_EFFECTS__` line/block comment immediately above the implementation
+     * declaration when the function has overloads. TypeScript erases overload signatures during
+     * emit, so JSDoc placed only on the first overload is dropped from the bundled JS — the
+     * line comment directly above the implementation is what survives and reaches the bundler.
+     *
+     * `null` when the function is single-signature (the line comment is then a removable orphan)
+     * or when no such comment is present.
+     */
+    readonly implLineComment: AstNode | null;
+    /**
+     * True when the implementation will carry the `@__NO_SIDE_EFFECTS__` annotation in the emitted
+     * JavaScript:
+     *
+     * - Single-signature: true when the (only) JSDoc carries the tag.
+     * - Overloaded: true when a line/block comment with the tag sits immediately above the
+     *   implementation, OR the implementation has its own JSDoc carrying the tag.
+     *
+     * This is the signal upstream packages need so esbuild/rollup can tree-shake unused calls.
+     */
+    readonly implHasSurvivingAnnotation: boolean;
+    /**
+     * The first statement in the overload chain (i.e. the first overload's export wrapper, or the
+     * implementation itself when there are no overloads). Use this as the insertion anchor when
+     * creating a brand-new JSDoc for the function, since docs conventionally live on the first
+     * overload rather than the implementation.
+     */
+    readonly chainStartStatement: AstNode;
 }
 /**
  * Returns true if the given comment text contains the @__NO_SIDE_EFFECTS__ marker.
@@ -27,6 +65,15 @@ export declare function commentContainsNoSideEffects(text: string): boolean;
  * @returns The whitespace prefix (spaces/tabs) of that line.
  */
 export declare function getLineIndent(sourceText: string, offset: number): string;
+/**
+ * Returns the outermost statement node for a FunctionDeclaration — its `ExportNamedDeclaration`
+ * or `ExportDefaultDeclaration` parent if exported, otherwise the declaration itself. This is the
+ * node ESLint attaches leading comments to.
+ *
+ * @param node - The FunctionDeclaration AST node.
+ * @returns The statement node ESLint attaches leading comments to.
+ */
+export declare function getStatementAnchor(node: AstNode): AstNode;
 /**
  * Walks backward from the implementation FunctionDeclaration through any overload signatures
  * with the same name, collecting: