@dereekb/util 13.11.2 → 13.11.3

package/eslint/index.esm.js

@@ -0,0 +1,603 @@
+/**
+ * The bundler hint string that marks a function call as side-effect-free.
+ */ var NO_SIDE_EFFECTS_TAG = '@__NO_SIDE_EFFECTS__';
+/**
+ * Returns true if the given comment text contains the @__NO_SIDE_EFFECTS__ marker.
+ *
+ * @param text - The comment body text (without the `/*` and `*\/` delimiters).
+ * @returns True when the marker substring is present.
+ */ function commentContainsNoSideEffects(text) {
+    return text.includes(NO_SIDE_EFFECTS_TAG);
+}
+/**
+ * Returns the leading whitespace (column indent) of the line containing the given offset.
+ *
+ * @param sourceText - The full source text being inspected.
+ * @param offset - A character offset into `sourceText` indicating the line of interest.
+ * @returns The whitespace prefix (spaces/tabs) of that line.
+ */ function getLineIndent(sourceText, offset) {
+    var lineStart = offset;
+    while(lineStart > 0 && sourceText.charAt(lineStart - 1) !== '\n'){
+        lineStart -= 1;
+    }
+    var cursor = lineStart;
+    while(cursor < sourceText.length && (sourceText.charAt(cursor) === ' ' || sourceText.charAt(cursor) === '\t')){
+        cursor += 1;
+    }
+    return sourceText.slice(lineStart, cursor);
+}
+/**
+ * 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.
+ */ function getStatementAnchor(node) {
+    return node.parent && (node.parent.type === 'ExportNamedDeclaration' || node.parent.type === 'ExportDefaultDeclaration') ? node.parent : node;
+}
+/**
+ * Returns true if the statement is an overload signature (TSDeclareFunction) sharing the given name.
+ *
+ * @param stmt - The statement node to check (may be an export wrapper).
+ * @param name - The function identifier name to match.
+ * @returns True when `stmt` is an overload signature for `name`.
+ */ function isOverloadSignature(stmt, name) {
+    var _inner_id;
+    var inner = stmt.type === 'ExportNamedDeclaration' || stmt.type === 'ExportDefaultDeclaration' ? stmt.declaration : stmt;
+    return (inner === null || inner === void 0 ? void 0 : inner.type) === 'TSDeclareFunction' && ((_inner_id = inner.id) === null || _inner_id === void 0 ? void 0 : _inner_id.type) === 'Identifier' && inner.id.name === name;
+}
+/**
+ * Walks backward from the implementation FunctionDeclaration through any overload signatures
+ * with the same name, collecting:
+ *
+ * - The leading JSDoc block (preferring the one attached to the **first** overload, since that's
+ *   where the function's documentation conventionally lives).
+ * - All orphan `@__NO_SIDE_EFFECTS__` line/block comments encountered between overloads or
+ *   between the last overload and the implementation.
+ *
+ * This handles the common pattern:
+ *
+ * ```ts
+ * \/\*\* doc \*\/
+ * export function foo(a: number): number;
+ * export function foo(a: string): string;
+ * \/\/ \@__NO_SIDE_EFFECTS__
+ * export function foo(a: any) { ... }
+ * ```
+ *
+ * @param sourceCode - The ESLint `SourceCode` object used to read leading comments.
+ * @param implNode - The implementation FunctionDeclaration node.
+ * @returns The leading JSDoc (if any) and any orphan side-effect annotation comments.
+ */ function findFunctionLeadingContext(sourceCode, implNode) {
+    var _implNode_id;
+    if (((_implNode_id = implNode.id) === null || _implNode_id === void 0 ? void 0 : _implNode_id.type) !== 'Identifier') {
+        return {
+            jsdoc: null,
+            orphanLineComments: []
+        };
+    }
+    var name = implNode.id.name;
+    var implStmt = getStatementAnchor(implNode);
+    var container = implStmt.parent;
+    var chainStartIdx = -1;
+    var implIdx = -1;
+    if (container && Array.isArray(container.body)) {
+        implIdx = container.body.indexOf(implStmt);
+        if (implIdx >= 0) {
+            chainStartIdx = implIdx;
+            for(var i = implIdx - 1; i >= 0; i -= 1){
+                if (isOverloadSignature(container.body[i], name)) {
+                    chainStartIdx = i;
+                } else {
+                    break;
+                }
+            }
+        }
+    }
+    var firstJsdoc = null;
+    var anyJsdocHasNoSideEffects = false;
+    var orphanLineComments = [];
+    function processCommentsForStatement(stmt) {
+        var comments = sourceCode.getCommentsBefore(stmt) || [];
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = comments[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var comment = _step.value;
+                if (comment.type === 'Block' && comment.value.startsWith('*')) {
+                    var hasMarker = commentContainsNoSideEffects(comment.value);
+                    if (hasMarker) {
+                        anyJsdocHasNoSideEffects = true;
+                    }
+                    // Auto-fix target: the first JSDoc in the chain (where the function's docs conventionally live).
+                    if (!firstJsdoc) {
+                        firstJsdoc = {
+                            node: comment,
+                            text: comment.value,
+                            hasNoSideEffects: hasMarker
+                        };
+                    }
+                } else if (commentContainsNoSideEffects(comment.value)) {
+                    orphanLineComments.push(comment);
+                }
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+    }
+    if (chainStartIdx >= 0 && implIdx >= 0) {
+        for(var i1 = chainStartIdx; i1 <= implIdx; i1 += 1){
+            processCommentsForStatement(container.body[i1]);
+        }
+    } else {
+        // Fallback: no container body found; just look at comments before the implementation.
+        processCommentsForStatement(implStmt);
+    }
+    // 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.
+    var resolved = null;
+    var captured = firstJsdoc;
+    if (captured) {
+        resolved = {
+            node: captured.node,
+            text: captured.text,
+            hasNoSideEffects: anyJsdocHasNoSideEffects
+        };
+    }
+    return {
+        jsdoc: resolved,
+        orphanLineComments: orphanLineComments
+    };
+}
+
+function _array_like_to_array$1(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_with_holes$1(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$1(arr);
+}
+function _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _iterable_to_array_limit$1(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
+    }
+    return _arr;
+}
+function _non_iterable_rest$1() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _sliced_to_array$1(arr, i) {
+    return _array_with_holes$1(arr) || _iterable_to_array_limit$1(arr, i) || _unsupported_iterable_to_array$1(arr, i) || _non_iterable_rest$1();
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array$1(arr) || _non_iterable_spread();
+}
+function _unsupported_iterable_to_array$1(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$1(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$1(o, minLen);
+}
+/**
+ * The JSDoc tag identifying a function as a factory in the @dereekb conventions.
+ */ var FACTORY_JSDOC_TAG = '@dbxUtilKind factory';
+/**
+ * Default suffix patterns considered factory-like by name when `checkNamePatterns` is enabled.
+ */ var DEFAULT_NAME_PATTERNS = [
+    /(?:Factory|Factories|Service|Services|Function|Functions)$/,
+    /^(?:make|build|create)[A-Z]/,
+    /^(?:firestore|optionalFirestore)[A-Z]/
+];
+/**
+ * Returns the function's identifier name, or null if anonymous.
+ *
+ * @param node - The FunctionDeclaration AST node.
+ * @returns The function's identifier name, or `null` for anonymous functions.
+ */ function getFunctionName(node) {
+    var _node_id;
+    if (((_node_id = node.id) === null || _node_id === void 0 ? void 0 : _node_id.type) === 'Identifier') {
+        return node.id.name;
+    }
+    return null;
+}
+/**
+ * Builds the merged set of name patterns based on rule options.
+ *
+ * @param options - The resolved rule options.
+ * @returns The combined default + additional regex patterns, or an empty list when name-pattern matching is disabled.
+ */ function buildNamePatterns(options) {
+    var _options_additionalNamePatterns;
+    if (!options.checkNamePatterns) {
+        return [];
+    }
+    var additional = ((_options_additionalNamePatterns = options.additionalNamePatterns) !== null && _options_additionalNamePatterns !== void 0 ? _options_additionalNamePatterns : []).map(function(source) {
+        return new RegExp(source);
+    });
+    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 = {
+    meta: {
+        type: 'suggestion',
+        fixable: 'code',
+        docs: {
+            description: 'Require @__NO_SIDE_EFFECTS__ inside the JSDoc block of factory functions so esbuild can drop unused calls during tree-shaking.',
+            recommended: true
+        },
+        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.'
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    checkNamePatterns: {
+                        type: 'boolean',
+                        description: 'Also flag functions whose names match factory naming patterns, in addition to JSDoc-tag detection.'
+                    },
+                    additionalNamePatterns: {
+                        type: 'array',
+                        items: {
+                            type: 'string'
+                        },
+                        description: 'Additional name pattern source strings to treat as factory signals when checkNamePatterns is true.'
+                    }
+                },
+                additionalProperties: false
+            }
+        ]
+    },
+    create: function create(context) {
+        var _context_options_;
+        var options = (_context_options_ = context.options[0]) !== null && _context_options_ !== void 0 ? _context_options_ : {};
+        var namePatterns = buildNamePatterns(options);
+        var sourceCode = context.sourceCode;
+        var sourceText = sourceCode.getText();
+        function nameMatchesFactoryPattern(name) {
+            return namePatterns.some(function(pattern) {
+                return pattern.test(name);
+            });
+        }
+        function checkFunction(node) {
+            var _jsdoc_text;
+            // Skip overload signatures (TSDeclareFunction) and bodyless declarations.
+            if (node.type !== 'FunctionDeclaration' || !node.body) {
+                return;
+            }
+            var name = getFunctionName(node);
+            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;
+            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) {
+                return;
+            }
+            var messageId = jsdoc ? 'missingNoSideEffectsJsdoc' : 'missingJsdocForFactory';
+            context.report({
+                node: node.id,
+                messageId: messageId,
+                data: {
+                    name: name
+                },
+                fix: function fix(fixer) {
+                    var fixes = [];
+                    if (jsdoc) {
+                        var jsdocText = jsdoc.text; // text excludes /* and */
+                        var jsdocStart = jsdoc.node.range[0];
+                        var jsdocEnd = jsdoc.node.range[1];
+                        // Determine the column the JSDoc starts at to align the new line.
+                        var jsdocIndent = getLineIndent(sourceText, jsdocStart);
+                        // If the JSDoc is single-line (e.g. `/** @dbxUtilKind factory */`),
+                        // expand it to multi-line. Detect by absence of newline in the body.
+                        if (!jsdocText.includes('\n')) {
+                            var bodyTrimmed = jsdocText.replace(/^\*\s*/, '').replace(/\s*$/, '');
+                            var newBody = "/**\n".concat(jsdocIndent, " * ").concat(bodyTrimmed, "\n").concat(jsdocIndent, " * ").concat(NO_SIDE_EFFECTS_TAG, "\n").concat(jsdocIndent, " */");
+                            fixes.push(fixer.replaceTextRange([
+                                jsdocStart,
+                                jsdocEnd
+                            ], newBody));
+                        } else {
+                            
+                            // immediately before the line containing the closing `*/`, so the closing line
+                            // and existing body lines remain untouched.
+                            var closingMarkerStart = jsdocEnd - 2; // start of `*/`
+                            var closingLineStart = closingMarkerStart;
+                            while(closingLineStart > 0 && sourceText.charAt(closingLineStart - 1) !== '\n'){
+                                closingLineStart -= 1;
+                            }
+                            var insertion = "".concat(jsdocIndent, " * ").concat(NO_SIDE_EFFECTS_TAG, "\n");
+                            fixes.push(fixer.insertTextBeforeRange([
+                                closingLineStart,
+                                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];
+                        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([
+                            nodeStart,
+                            nodeStart
+                        ], newJsdoc));
+                    }
+                    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    try {
+                        // Remove any redundant adjacent annotation comments now that JSDoc carries the tag.
+                        for(var _iterator = redundantLineComments[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                            var redundant = _step.value;
+                            var _redundant_range = _sliced_to_array$1(redundant.range, 2), start = _redundant_range[0], end = _redundant_range[1];
+                            // Extend the removal to include the trailing newline + indent so we don't leave a blank line.
+                            var removeEnd = end;
+                            while(removeEnd < sourceText.length && (sourceText.charAt(removeEnd) === ' ' || sourceText.charAt(removeEnd) === '\t')){
+                                removeEnd += 1;
+                            }
+                            if (sourceText.charAt(removeEnd) === '\n') {
+                                removeEnd += 1;
+                            }
+                            // Also drop leading indent on the comment's line.
+                            var removeStart = start;
+                            while(removeStart > 0 && (sourceText.charAt(removeStart - 1) === ' ' || sourceText.charAt(removeStart - 1) === '\t')){
+                                removeStart -= 1;
+                            }
+                            fixes.push(fixer.removeRange([
+                                removeStart,
+                                removeEnd
+                            ]));
+                        }
+                    } catch (err) {
+                        _didIteratorError = true;
+                        _iteratorError = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                _iterator.return();
+                            }
+                        } finally{
+                            if (_didIteratorError) {
+                                throw _iteratorError;
+                            }
+                        }
+                    }
+                    return fixes;
+                }
+            });
+        }
+        return {
+            FunctionDeclaration: checkFunction
+        };
+    }
+};
+
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_with_holes(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function _iterable_to_array_limit(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
+    }
+    return _arr;
+}
+function _non_iterable_rest() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _sliced_to_array(arr, i) {
+    return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array(arr, i) || _non_iterable_rest();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+ var utilPreferNoSideEffectsInJsdocRule = {
+    meta: {
+        type: 'suggestion',
+        fixable: 'code',
+        docs: {
+            description: "Prefer the @__NO_SIDE_EFFECTS__ annotation inside a function's JSDoc instead of a separate line comment between the JSDoc and the declaration.",
+            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.'
+        },
+        schema: []
+    },
+    create: function create(context) {
+        var sourceCode = context.sourceCode;
+        var sourceText = sourceCode.getText();
+        function checkFunction(node) {
+            var _node_id;
+            if (node.type !== 'FunctionDeclaration' || !node.body) {
+                return;
+            }
+            if (((_node_id = node.id) === null || _node_id === void 0 ? void 0 : _node_id.type) !== 'Identifier') {
+                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) {
+                return;
+            }
+            context.report({
+                node: node.id,
+                messageId: 'preferJsdocPlacement',
+                data: {
+                    name: name
+                },
+                fix: function fix(fixer) {
+                    var fixes = [];
+                    var jsdocText = jsdoc.text;
+                    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) {
+                        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*$/, '');
+                            var newBody = "/**\n".concat(jsdocIndent, " * ").concat(bodyTrimmed, "\n").concat(jsdocIndent, " * ").concat(NO_SIDE_EFFECTS_TAG, "\n").concat(jsdocIndent, " */");
+                            fixes.push(fixer.replaceTextRange([
+                                jsdocStart,
+                                jsdocEnd
+                            ], newBody));
+                        } else {
+                            // Multi-line JSDoc — insert a new tag line immediately before the closing `*/` line.
+                            var closingMarkerStart = jsdocEnd - 2;
+                            var closingLineStart = closingMarkerStart;
+                            while(closingLineStart > 0 && sourceText.charAt(closingLineStart - 1) !== '\n'){
+                                closingLineStart -= 1;
+                            }
+                            var insertion = "".concat(jsdocIndent, " * ").concat(NO_SIDE_EFFECTS_TAG, "\n");
+                            fixes.push(fixer.insertTextBeforeRange([
+                                closingLineStart,
+                                closingLineStart
+                            ], insertion));
+                        }
+                    }
+                    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    try {
+                        // Remove the orphan line/block comment annotations.
+                        for(var _iterator = orphanLineComments[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                            var orphan = _step.value;
+                            var _orphan_range = _sliced_to_array(orphan.range, 2), start = _orphan_range[0], end = _orphan_range[1];
+                            var removeEnd = end;
+                            while(removeEnd < sourceText.length && (sourceText.charAt(removeEnd) === ' ' || sourceText.charAt(removeEnd) === '\t')){
+                                removeEnd += 1;
+                            }
+                            if (sourceText.charAt(removeEnd) === '\n') {
+                                removeEnd += 1;
+                            }
+                            var removeStart = start;
+                            while(removeStart > 0 && (sourceText.charAt(removeStart - 1) === ' ' || sourceText.charAt(removeStart - 1) === '\t')){
+                                removeStart -= 1;
+                            }
+                            fixes.push(fixer.removeRange([
+                                removeStart,
+                                removeEnd
+                            ]));
+                        }
+                    } catch (err) {
+                        _didIteratorError = true;
+                        _iteratorError = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                _iterator.return();
+                            }
+                        } finally{
+                            if (_didIteratorError) {
+                                throw _iteratorError;
+                            }
+                        }
+                    }
+                    return fixes;
+                }
+            });
+        }
+        return {
+            FunctionDeclaration: checkFunction
+        };
+    }
+};
+
+/**
+ * ESLint plugin for @dereekb/util rules.
+ *
+ * Register as a plugin in your flat ESLint config, then enable individual rules
+ * under the chosen plugin prefix (e.g. 'dereekb-util/require-no-side-effects').
+ */ var utilEslintPlugin = {
+    rules: {
+        'require-no-side-effects': utilRequireNoSideEffectsRule,
+        'prefer-no-side-effects-in-jsdoc': utilPreferNoSideEffectsInJsdocRule
+    }
+};
+
+export { utilEslintPlugin, utilPreferNoSideEffectsInJsdocRule, utilRequireNoSideEffectsRule };

package/eslint/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@dereekb/util/eslint",
+  "version": "13.11.3",
+  "peerDependencies": {
+    "@typescript-eslint/utils": "8.59.0"
+  },
+  "devDependencies": {
+    "@typescript-eslint/parser": "8.59.0",
+    "eslint": "9.39.4"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/eslint/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

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

@@ -0,0 +1,54 @@
+/**
+ * The bundler hint string that marks a function call as side-effect-free.
+ */
+export declare const NO_SIDE_EFFECTS_TAG = "@__NO_SIDE_EFFECTS__";
+type AstNode = any;
+export interface JsdocCommentInfo {
+    readonly node: AstNode;
+    readonly text: string;
+    readonly hasNoSideEffects: boolean;
+}
+export interface FunctionLeadingContext {
+    readonly jsdoc: JsdocCommentInfo | null;
+    readonly orphanLineComments: readonly AstNode[];
+}
+/**
+ * Returns true if the given comment text contains the @__NO_SIDE_EFFECTS__ marker.
+ *
+ * @param text - The comment body text (without the `/*` and `*\/` delimiters).
+ * @returns True when the marker substring is present.
+ */
+export declare function commentContainsNoSideEffects(text: string): boolean;
+/**
+ * Returns the leading whitespace (column indent) of the line containing the given offset.
+ *
+ * @param sourceText - The full source text being inspected.
+ * @param offset - A character offset into `sourceText` indicating the line of interest.
+ * @returns The whitespace prefix (spaces/tabs) of that line.
+ */
+export declare function getLineIndent(sourceText: string, offset: number): string;
+/**
+ * Walks backward from the implementation FunctionDeclaration through any overload signatures
+ * with the same name, collecting:
+ *
+ * - The leading JSDoc block (preferring the one attached to the **first** overload, since that's
+ *   where the function's documentation conventionally lives).
+ * - All orphan `@__NO_SIDE_EFFECTS__` line/block comments encountered between overloads or
+ *   between the last overload and the implementation.
+ *
+ * This handles the common pattern:
+ *
+ * ```ts
+ * \/\*\* doc \*\/
+ * export function foo(a: number): number;
+ * export function foo(a: string): string;
+ * \/\/ \@__NO_SIDE_EFFECTS__
+ * export function foo(a: any) { ... }
+ * ```
+ *
+ * @param sourceCode - The ESLint `SourceCode` object used to read leading comments.
+ * @param implNode - The implementation FunctionDeclaration node.
+ * @returns The leading JSDoc (if any) and any orphan side-effect annotation comments.
+ */
+export declare function findFunctionLeadingContext(sourceCode: AstNode, implNode: AstNode): FunctionLeadingContext;
+export {};