@dereekb/util 13.11.2 → 13.11.4

package/eslint/index.cjs.js

@@ -0,0 +1,687 @@
+'use strict';
+
+/**
+ * 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: [],
+            hasOverloads: false,
+            implLineComment: null,
+            implHasSurvivingAnnotation: false,
+            chainStartStatement: getStatementAnchor(implNode)
+        };
+    }
+    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 hasOverloads = chainStartIdx >= 0 && implIdx >= 0 && chainStartIdx < implIdx;
+    var firstJsdoc = null;
+    var anyJsdocHasNoSideEffects = false;
+    var implJsdocHasNoSideEffects = false;
+    var orphanLineComments = [];
+    
+    // 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 {
+            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;
+                        if (isImplStatement) {
+                            implJsdocHasNoSideEffects = 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)) {
+                    // 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) {
+            _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], i1 === implIdx);
+        }
+    } else {
+        // Fallback: no container body found; just look at comments before the implementation.
+        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.
+    var resolved = null;
+    var captured = firstJsdoc;
+    if (captured) {
+        resolved = {
+            node: captured.node,
+            text: captured.text,
+            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,
+        hasOverloads: hasOverloads,
+        implLineComment: implLineComment,
+        implHasSurvivingAnnotation: implHasSurvivingAnnotation,
+        chainStartStatement: chainStartStatement
+    };
+}
+
+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));
+}
+ 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.',
+            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: [
+            {
+                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,
+            // 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;
+            }
+            // The bundled implementation already carries the marker — passing. This covers:
+            //   - non-overloaded with the tag in the (only) JSDoc, AND
+            
+            if (implHasSurvivingAnnotation) {
+                return;
+            }
+            // 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,
+                data: {
+                    name: name
+                },
+                fix: function fix(fixer) {
+                    var fixes = [];
+                    // 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];
+                        // 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 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([
+                            nodeStart,
+                            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.
+                        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.',
+            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: []
+    },
+    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,
+            // 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: needsImplLineCommentForOverload && !needsJsdocTag && !needsOrphanRemoval ? 'missingImplAnnotationOverloaded' : '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 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*$/, '');
+                            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));
+                        }
+                    }
+                    // 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.
+                        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
+    }
+};
+
+exports.utilEslintPlugin = utilEslintPlugin;
+exports.utilPreferNoSideEffectsInJsdocRule = utilPreferNoSideEffectsInJsdocRule;
+exports.utilRequireNoSideEffectsRule = utilRequireNoSideEffectsRule;