@dereekb/dbx-cli 13.15.0 → 13.17.0

package/eslint/index.esm.js

@@ -0,0 +1,1046 @@
+/**
+ * Returns the JSDoc Block comment immediately preceding `anchor`, or `null` when
+ * the anchor has no JSDoc leader. Used by the `@dbx<Family>` companion-tag rules
+ * to locate the tagged declaration's documentation.
+ *
+ * @param sourceCode - The ESLint `SourceCode` object.
+ * @param anchor - The statement-level node ESLint attaches leading comments to.
+ * @returns The JSDoc block comment, or null when none is present.
+ */ function leadingJsdocFor(sourceCode, anchor) {
+    var comments = sourceCode.getCommentsBefore(anchor) || [];
+    var result = null;
+    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' && typeof comment.value === 'string' && comment.value.startsWith('*')) {
+                result = comment;
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return result;
+}
+
+/**
+ * Default maximum positional parameters before the warn-level rule suggests a config object.
+ * Triggers a warning when a function has more than 2 positional parameters (i.e. 3+ args).
+ */ var DEFAULT_MAX_PARAMS_WARN = 2;
+/**
+ * Default maximum positional parameters before the hard-error rule rejects the signature.
+ * Triggers an error when a function has more than 4 positional parameters (i.e. 5+ args).
+ */ var DEFAULT_MAX_PARAMS_HARD = 4;
+/**
+ * Default JSDoc tag that opts a function out of this rule.
+ */ var DEFAULT_ALLOW_JSDOC_TAG = '@dbxAllowMultiParams';
+/**
+ * Returns a human-readable display name for the function-like node, or `<anonymous>`.
+ *
+ * @param node - The function-like AST node.
+ * @returns The identifier string used in diagnostic messages.
+ */ function getFunctionDisplayName(node) {
+    var _node_id;
+    var name = '<anonymous>';
+    if (((_node_id = node.id) === null || _node_id === void 0 ? void 0 : _node_id.type) === 'Identifier') {
+        name = node.id.name;
+    } else if (node.parent) {
+        var _parent_id, _parent_key, _parent_key1, _parent_left;
+        var parent = node.parent;
+        if (parent.type === 'VariableDeclarator' && ((_parent_id = parent.id) === null || _parent_id === void 0 ? void 0 : _parent_id.type) === 'Identifier') {
+            name = parent.id.name;
+        } else if (parent.type === 'Property' && ((_parent_key = parent.key) === null || _parent_key === void 0 ? void 0 : _parent_key.type) === 'Identifier') {
+            name = parent.key.name;
+        } else if (parent.type === 'MethodDefinition' && ((_parent_key1 = parent.key) === null || _parent_key1 === void 0 ? void 0 : _parent_key1.type) === 'Identifier') {
+            name = parent.key.name;
+        } else if (parent.type === 'AssignmentExpression' && ((_parent_left = parent.left) === null || _parent_left === void 0 ? void 0 : _parent_left.type) === 'Identifier') {
+            name = parent.left.name;
+        }
+    }
+    return name;
+}
+/**
+ * Returns true if a parameter has any decorators (NestJS handler/Inject pattern).
+ *
+ * @param param - The parameter AST node.
+ * @returns True when the parameter carries at least one decorator.
+ */ function paramHasDecorator(param) {
+    var _param_decorators;
+    var decorators = (_param_decorators = param.decorators) !== null && _param_decorators !== void 0 ? _param_decorators : [];
+    return Array.isArray(decorators) && decorators.length > 0;
+}
+/**
+ * Returns true when the function is the constructor of a class.
+ *
+ * @param node - The function-like AST node.
+ * @returns True if `node` is the `constructor` body of a class.
+ */ function isConstructor(node) {
+    var _node_parent;
+    return ((_node_parent = node.parent) === null || _node_parent === void 0 ? void 0 : _node_parent.type) === 'MethodDefinition' && node.parent.kind === 'constructor';
+}
+/**
+ * Returns true if any leading JSDoc block above `anchor` contains the allow tag.
+ *
+ * @param sourceCode - The ESLint `SourceCode` instance.
+ * @param anchor - The AST node whose leading comments are scanned.
+ * @param allowTag - The JSDoc tag string that opts the function out.
+ * @returns True when a JSDoc with the allow tag is present.
+ */ function hasAllowJsdoc(sourceCode, anchor, allowTag) {
+    var comments = sourceCode.getCommentsBefore(anchor) || [];
+    var allow = false;
+    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('*') && comment.value.includes(allowTag)) {
+                allow = true;
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return allow;
+}
+/**
+ * Builds a prefer-config-object-style rule with a configurable default `maxParams` threshold.
+ * Class constructors and decorated parameters (e.g. NestJS `@Inject`) are exempted. Functions can
+ * opt out via a leading JSDoc block carrying the configured allow tag (default `@dbxAllowMultiParams`).
+ *
+ * @param config - Default threshold and rule description.
+ * @returns A complete ESLint rule definition that emits `tooManyParams` reports.
+ */ function createPreferConfigObjectRule(config) {
+    return {
+        meta: {
+            type: 'suggestion',
+            docs: {
+                description: config.description,
+                recommended: true
+            },
+            messages: {
+                tooManyParams: "Function '{{name}}' takes {{count}} positional parameters; use a single config object instead (see dbx__note__typescript-programming → Prefer Single Config Object)."
+            },
+            schema: [
+                {
+                    type: 'object',
+                    properties: {
+                        maxParams: {
+                            type: 'number',
+                            minimum: 0,
+                            description: 'Maximum number of positional parameters before the rule fires.'
+                        },
+                        allowJsdocTag: {
+                            type: 'string',
+                            description: 'JSDoc tag that opts a function out of this rule.'
+                        }
+                    },
+                    additionalProperties: false
+                }
+            ]
+        },
+        create: function create(context) {
+            var _context_options_, _options_maxParams, _options_allowJsdocTag;
+            var options = (_context_options_ = context.options[0]) !== null && _context_options_ !== void 0 ? _context_options_ : {};
+            var maxParams = (_options_maxParams = options.maxParams) !== null && _options_maxParams !== void 0 ? _options_maxParams : config.defaultMaxParams;
+            var allowTag = (_options_allowJsdocTag = options.allowJsdocTag) !== null && _options_allowJsdocTag !== void 0 ? _options_allowJsdocTag : DEFAULT_ALLOW_JSDOC_TAG;
+            var sourceCode = context.sourceCode;
+            function checkFunction(node) {
+                if (!isConstructor(node)) {
+                    var _node_params;
+                    var params = (_node_params = node.params) !== null && _node_params !== void 0 ? _node_params : [];
+                    // Decorated parameters indicate framework-driven signatures (NestJS handlers, Angular DI inside
+                    // constructors which we already skip — but standalone decorated functions exist too).
+                    if (!params.some(paramHasDecorator) && params.length > maxParams) {
+                        var _node_parent, _node_parent_parent;
+                        // Anchor for JSDoc lookup: prefer the enclosing export statement, then a VariableDeclaration
+                        // (for `const fn = () => ...`), otherwise the function node itself.
+                        var anchor = node;
+                        if (((_node_parent = node.parent) === null || _node_parent === void 0 ? void 0 : _node_parent.type) === 'VariableDeclarator' && ((_node_parent_parent = node.parent.parent) === null || _node_parent_parent === void 0 ? void 0 : _node_parent_parent.type) === 'VariableDeclaration') {
+                            anchor = node.parent.parent;
+                        }
+                        if (anchor.parent && (anchor.parent.type === 'ExportNamedDeclaration' || anchor.parent.type === 'ExportDefaultDeclaration')) {
+                            anchor = anchor.parent;
+                        }
+                        if (!hasAllowJsdoc(sourceCode, anchor, allowTag)) {
+                            var _node_id;
+                            var name = getFunctionDisplayName(node);
+                            context.report({
+                                node: (_node_id = node.id) !== null && _node_id !== void 0 ? _node_id : node,
+                                messageId: 'tooManyParams',
+                                data: {
+                                    name: name,
+                                    count: String(params.length)
+                                }
+                            });
+                        }
+                    }
+                }
+            }
+            return {
+                FunctionDeclaration: checkFunction,
+                FunctionExpression: checkFunction,
+                ArrowFunctionExpression: checkFunction
+            };
+        }
+    };
+}
+/**
+ * ESLint rule recommending a single config object when a function takes more than two positional
+ * parameters (default `maxParams: 2`, i.e. fires at 3+ args). Intended to be configured at the
+ * `warn` severity. Pair with `prefer-config-object-hard` for a stricter cap.
+ *
+ * @see `dbx__note__typescript-programming` → Prefer Single Config Object
+ */ createPreferConfigObjectRule({
+    defaultMaxParams: DEFAULT_MAX_PARAMS_WARN,
+    description: 'Prefer a single config object when a function takes more than two positional parameters.'
+});
+/**
+ * Hard-stop variant of `prefer-config-object`. Fires when a function takes more than four positional
+ * parameters (default `maxParams: 4`, i.e. fires at 5+ args). Intended to be configured at the
+ * `error` severity so genuinely unwieldy signatures break the build even when the softer warn-level
+ * rule is disabled or downgraded.
+ *
+ * @see `dbx__note__typescript-programming` → Prefer Single Config Object
+ */ createPreferConfigObjectRule({
+    defaultMaxParams: DEFAULT_MAX_PARAMS_HARD,
+    description: 'Reject function signatures with more than four positional parameters; require a single config object.'
+});
+
+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 _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 _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 _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);
+}
+var TAG_LINE_REGEX = /^@([A-Za-z_]\w*)\s*(.*)$/;
+var TYPE_ANNOTATION_REGEX = /^\{([^}]*)\}\s*(.*)$/;
+var PARAM_NAME_REGEX = /^([A-Za-z_$][A-Za-z0-9_$.[\]]*)\s*(.*)$/;
+var LINE_PREFIX_REGEX = /^(\s*\*?\s?)(.*)$/;
+/**
+ * Strips the leading whitespace + `*` + optional space prefix from a JSDoc body line and reports the length stripped.
+ *
+ * @param raw - The raw line as it appears in `comment.value`.
+ * @returns A `{ text, prefixLength }` pair.
+ *
+ * @example
+ * ```ts
+ * stripPrefix(' * @param x - desc'); // { text: '@param x - desc', prefixLength: 3 }
+ * stripPrefix(' *'); // { text: '', prefixLength: 2 }
+ * stripPrefix('* hello'); // { text: 'hello', prefixLength: 2 }
+ * ```
+ */ function stripPrefix(raw) {
+    var match = LINE_PREFIX_REGEX.exec(raw);
+    var result = {
+        text: raw,
+        prefixLength: 0
+    };
+    if (match) {
+        result.text = match[2];
+        result.prefixLength = match[1].length;
+    }
+    return result;
+}
+/**
+ * Splits the raw comment value into per-line views with prefix/offset metadata.
+ *
+ * @param commentValue - The `value` of an ESLint Block comment.
+ * @returns Array of parsed line records in source order.
+ */ function buildParsedLines(commentValue) {
+    var rawLines = commentValue.split('\n');
+    var runningOffset = 0;
+    return rawLines.map(function(raw, index) {
+        var _stripPrefix = stripPrefix(raw), stripped = _stripPrefix.text, prefixLength = _stripPrefix.prefixLength;
+        var text = stripped.trimEnd();
+        var blank = text.length === 0;
+        var valueOffsetStart = runningOffset;
+        var textOffsetStart = runningOffset + prefixLength;
+        runningOffset += raw.length + 1; // +1 for the consumed `\n` (overshoots on last line, harmless)
+        return {
+            raw: raw,
+            text: text,
+            blank: blank,
+            index: index,
+            valueOffsetStart: valueOffsetStart,
+            textOffsetStart: textOffsetStart
+        };
+    });
+}
+/**
+ * Computes, per line, whether it sits inside a fenced code block (a ```` ``` ```` block, typically
+ * an `@example` body) and therefore must not be treated as a tag boundary. Fence delimiter lines
+ * themselves are flagged too. Without this, `@`-prefixed lines inside a fence — decorators like
+ * `@Global()` / `@Module()`, or JSDoc snippets — would be mis-parsed as standalone JSDoc tags.
+ *
+ * @param lines - Parsed lines in source order.
+ * @returns Boolean mask where `true` marks a line that must not start a tag.
+ */ function computeFenceMask(lines) {
+    var mask = lines.map(function() {
+        return false;
+    });
+    var fenceOpen = false;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = lines.entries()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var _step_value = _sliced_to_array$1(_step.value, 2), i = _step_value[0], line = _step_value[1];
+            var isDelimiter = line.text.trimStart().startsWith('```');
+            if (isDelimiter) {
+                mask[i] = true;
+                fenceOpen = !fenceOpen;
+            } else {
+                mask[i] = fenceOpen;
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return mask;
+}
+/**
+ * Returns true when the line at `index` opens a JSDoc tag and is not masked out by a code fence.
+ *
+ * @param lines - Parsed lines in source order.
+ * @param fenceMask - Mask from {@link computeFenceMask} marking fenced lines.
+ * @param index - Line index to test.
+ * @returns True when the line begins a tag that should be treated as a tag boundary.
+ */ function isTagStart(lines, fenceMask, index) {
+    return !fenceMask[index] && TAG_LINE_REGEX.test(lines[index].text);
+}
+/**
+ * Returns the index of the first line that begins with a JSDoc `@tag`, or `-1` when none exists.
+ *
+ * @param lines - Parsed lines in source order.
+ * @param fenceMask - Mask from {@link computeFenceMask} marking fenced lines.
+ * @returns Zero-based line index of the first tag, or `-1` when no tag is present.
+ */ function findFirstTagIndex(lines, fenceMask) {
+    var firstTagIndex = -1;
+    for(var i = 0; i < lines.length; i += 1){
+        if (isTagStart(lines, fenceMask, i)) {
+            firstTagIndex = i;
+            break;
+        }
+    }
+    return firstTagIndex;
+}
+/**
+ * Trims leading and trailing blank lines from a contiguous run of description lines.
+ *
+ * @param descriptionLines - Description-section lines before any tag.
+ * @returns Sub-array with surrounding blank lines stripped.
+ */ function trimBlankBoundaries(descriptionLines) {
+    var descStart = 0;
+    var descEnd = descriptionLines.length;
+    while(descStart < descEnd && descriptionLines[descStart].blank)descStart += 1;
+    while(descEnd > descStart && descriptionLines[descEnd - 1].blank)descEnd -= 1;
+    return descriptionLines.slice(descStart, descEnd);
+}
+/**
+ * Splits the trimmed description lines into paragraphs separated by blank-line runs.
+ *
+ * @param trimmedDescription - Description lines with surrounding blank lines removed.
+ * @returns Paragraph strings joined by `\n`.
+ */ function buildDescriptionParagraphs(trimmedDescription) {
+    var descriptionParagraphs = [];
+    var paragraphBuffer = [];
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = trimmedDescription[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var line = _step.value;
+            if (line.blank) {
+                if (paragraphBuffer.length > 0) {
+                    descriptionParagraphs.push(paragraphBuffer.join('\n'));
+                    paragraphBuffer = [];
+                }
+            } else {
+                paragraphBuffer.push(line.text);
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    if (paragraphBuffer.length > 0) {
+        descriptionParagraphs.push(paragraphBuffer.join('\n'));
+    }
+    return descriptionParagraphs;
+}
+/**
+ * Pulls an optional `{Type}` annotation off the front of a tag remainder.
+ *
+ * @param remainder - The tag-line text after the `@tagName` prefix.
+ * @returns The annotation (or `undefined`) plus the remaining text.
+ */ function extractTypeAnnotation(remainder) {
+    var type;
+    var rest = remainder;
+    var typeMatch = TYPE_ANNOTATION_REGEX.exec(remainder);
+    if (typeMatch) {
+        type = typeMatch[1];
+        rest = typeMatch[2];
+    }
+    return {
+        type: type,
+        rest: rest
+    };
+}
+/**
+ * Pulls an optional parameter name off the front of a `@param` tag remainder.
+ *
+ * @param tagName - Tag name (only `'param'` extracts a name; other tags pass through).
+ * @param remainder - The tag-line text after the optional `{Type}` annotation.
+ * @returns The parameter name (or `undefined`) plus the remaining text.
+ */ function extractParamName(tagName, remainder) {
+    var name;
+    var rest = remainder;
+    if (tagName === 'param') {
+        var nameMatch = PARAM_NAME_REGEX.exec(remainder);
+        if (nameMatch) {
+            name = nameMatch[1];
+            rest = nameMatch[2];
+        }
+    }
+    return {
+        name: name,
+        rest: rest
+    };
+}
+/**
+ * Collects the tag line at `startIndex` plus every following non-tag continuation line.
+ *
+ * @param lines - All parsed lines in the comment.
+ * @param fenceMask - Mask from {@link computeFenceMask} marking fenced lines.
+ * @param startIndex - Index of the `@tag` opening line.
+ * @returns The collected tag lines and the index of the next unconsumed line.
+ */ function collectTagLines(lines, fenceMask, startIndex) {
+    var tagLines = [
+        lines[startIndex]
+    ];
+    var j = startIndex + 1;
+    while(j < lines.length){
+        if (isTagStart(lines, fenceMask, j)) break;
+        tagLines.push(lines[j]);
+        j += 1;
+    }
+    return {
+        tagLines: tagLines,
+        nextIndex: j
+    };
+}
+/**
+ * Joins the on-line remainder and continuation-line text into a tag description, dropping trailing
+ * blank lines while preserving interior blanks.
+ *
+ * @param remainder - The on-line remainder after stripping `@tagName {Type} name`.
+ * @param tagLines - All lines that belong to the tag (including the header line at index 0).
+ * @returns Description text joined by `\n`.
+ */ function buildTagDescription(remainder, tagLines) {
+    var descriptionParts = [];
+    if (remainder.length > 0) descriptionParts.push(remainder);
+    for(var k = 1; k < tagLines.length; k += 1){
+        descriptionParts.push(tagLines[k].text);
+    }
+    while(descriptionParts.length > 0 && descriptionParts.at(-1).trim().length === 0){
+        descriptionParts.pop();
+    }
+    return descriptionParts.join('\n');
+}
+/**
+ * Builds a single parsed-tag record starting at `startIndex` in the line array.
+ *
+ * @param lines - All parsed lines in the comment.
+ * @param fenceMask - Mask from {@link computeFenceMask} marking fenced lines.
+ * @param startIndex - Index of the `@tag` opening line.
+ * @returns The parsed tag and the next unconsumed line index.
+ */ function parseTagAt(lines, fenceMask, startIndex) {
+    var line = lines[startIndex];
+    var match = TAG_LINE_REGEX.exec(line.text);
+    var tagName = match[1];
+    var _extractTypeAnnotation = extractTypeAnnotation(match[2]), type = _extractTypeAnnotation.type, afterType = _extractTypeAnnotation.rest;
+    var _extractParamName = extractParamName(tagName, afterType), name = _extractParamName.name, afterName = _extractParamName.rest;
+    var _collectTagLines = collectTagLines(lines, fenceMask, startIndex), tagLines = _collectTagLines.tagLines, nextIndex = _collectTagLines.nextIndex;
+    var description = buildTagDescription(afterName, tagLines);
+    return {
+        tag: {
+            tag: tagName,
+            name: name,
+            type: type,
+            description: description,
+            lines: tagLines,
+            startLineIndex: startIndex,
+            endLineIndex: nextIndex - 1
+        },
+        nextIndex: nextIndex
+    };
+}
+/**
+ * Parses every `@tag` block starting from `firstTagIndex` to the end of the line array.
+ *
+ * @param lines - All parsed lines in the comment.
+ * @param fenceMask - Mask from {@link computeFenceMask} marking fenced lines.
+ * @param firstTagIndex - Index where tag parsing should begin (`-1` skips entirely).
+ * @returns All parsed tags in source order.
+ */ function parseTags(lines, fenceMask, firstTagIndex) {
+    var tags = [];
+    if (firstTagIndex !== -1) {
+        var i = firstTagIndex;
+        while(i < lines.length){
+            if (!isTagStart(lines, fenceMask, i)) {
+                i += 1;
+                continue;
+            }
+            var _parseTagAt = parseTagAt(lines, fenceMask, i), tag = _parseTagAt.tag, nextIndex = _parseTagAt.nextIndex;
+            tags.push(tag);
+            i = nextIndex;
+        }
+    }
+    return tags;
+}
+/**
+ * Parses the value of an ESLint Block comment that represents a JSDoc into a structured form.
+ *
+ * @param commentValue - The `value` of an ESLint Block comment (text between `/*` and `*\/`, including the leading `*`).
+ * @returns A structured view of the JSDoc with description, paragraphs, and tags.
+ *
+ * @example
+ * ```ts
+ * const parsed = parseJsdocComment('*\n * Hello.\n *\n * @param x - The value.\n ');
+ * // parsed.description === 'Hello.'
+ * // parsed.tags[0].tag === 'param'
+ * // parsed.tags[0].name === 'x'
+ * // parsed.tags[0].description === 'The value.'
+ * ```
+ */ function parseJsdocComment(commentValue) {
+    var singleLine = !commentValue.includes('\n');
+    var lines = buildParsedLines(commentValue);
+    var fenceMask = computeFenceMask(lines);
+    var firstTagIndex = findFirstTagIndex(lines, fenceMask);
+    var descriptionLines = firstTagIndex === -1 ? lines.slice() : lines.slice(0, firstTagIndex);
+    var trimmedDescription = trimBlankBoundaries(descriptionLines);
+    var description = trimmedDescription.map(function(l) {
+        return l.text;
+    }).join('\n');
+    var descriptionParagraphs = buildDescriptionParagraphs(trimmedDescription);
+    var tags = parseTags(lines, fenceMask, firstTagIndex);
+    return {
+        lines: lines,
+        descriptionLines: descriptionLines,
+        description: description,
+        descriptionParagraphs: descriptionParagraphs,
+        tags: tags,
+        singleLine: singleLine
+    };
+}
+
+/**
+ * Returns the source-text offset of an offset-within-comment-value, given a Block comment node.
+ *
+ * @param commentNode - The ESLint Block comment AST node.
+ * @param valueOffset - The character offset within `comment.value`.
+ * @returns The character offset in the source file.
+ */ function commentValueToSourceOffset(commentNode, valueOffset) {
+    return commentNode.range[0] + 2 + valueOffset;
+}
+/**
+ * Translates a JSDoc-line violation into an ESLint `context.report()` call by computing the
+ * source range of the offending line and attaching the supplied message + optional fixer.
+ *
+ * @param input - Reporting context (comment node, parsed JSDoc, source code, line index, message id, optional data + fixer, report sink).
+ *
+ * @example
+ * ```ts
+ * reportOnJsdocLine({ commentNode, parsed, sourceCode, lineIndex: tag.startLineIndex, messageId: 'unknown', report: context.report });
+ * ```
+ */ function reportOnJsdocLine(input) {
+    var _ref, _ref1;
+    var _line_text;
+    var commentNode = input.commentNode, parsed = input.parsed, sourceCode = input.sourceCode, lineIndex = input.lineIndex, messageId = input.messageId, data = input.data, report = input.report, fix = input.fix;
+    var line = parsed.lines[lineIndex];
+    var startInValue = (_ref = line === null || line === void 0 ? void 0 : line.textOffsetStart) !== null && _ref !== void 0 ? _ref : 0;
+    var endInValue = startInValue + ((_ref1 = line === null || line === void 0 ? void 0 : (_line_text = line.text) === null || _line_text === void 0 ? void 0 : _line_text.length) !== null && _ref1 !== void 0 ? _ref1 : 0);
+    var start = commentValueToSourceOffset(commentNode, startInValue);
+    var end = commentValueToSourceOffset(commentNode, endInValue);
+    report({
+        loc: {
+            type: 'SourceLocation',
+            start: sourceCode.getLocFromIndex(start),
+            end: sourceCode.getLocFromIndex(end)
+        },
+        messageId: messageId,
+        data: data,
+        fix: fix
+    });
+}
+
+/**
+ * Pure parser for the `@dbxRouteModel` / `@dbxRouteModelList` JSDoc tag grammar
+ * that annotates which Firestore models a route renders.
+ *
+ * Grammar:
+ *
+ * ```
+ * @dbxRouteModel <modelType> <keyTemplate> [- <description>]
+ * @dbxRouteModelList <modelType> [- <description>]
+ * ```
+ *
+ * `keyTemplate` shapes:
+ * - `:param` / `{authUid}` — single placeholder → `kind: 'id'` (the value is
+ *   promoted to `<collectionName>/<id>` at runtime via the model identity).
+ * - `gb/:id/gbe/{authUid}` — alternating literal / placeholder segments (even
+ *   count) → `kind: 'key'` (a full FirestoreModelKey for a subcollection model).
+ * - (absent, list tag) → `kind: 'list'`.
+ *
+ * This module is deliberately runtime-dependency-free (no ts-morph): the same
+ * grammar is reused by the build-time manifest builder, the dev MCP route tools,
+ * and the `@dereekb/dbx-cli/eslint` rule so they can never disagree about what a
+ * valid tag is. The ts-morph consumer (`extractComponentRouteModelTags`) lives in
+ * `./route-models-extract.ts` and re-exports these symbols for existing importers.
+ */ /**
+ * Whether a route-model entry resolves to a promoted id, a full key, or a
+ * keyless list.
+ */ 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 MODEL_TYPE_RE = RegExp("^[a-zA-Z][a-zA-Z0-9]*$", "u");
+var LITERAL_SEGMENT_RE = RegExp("^[a-zA-Z0-9][a-zA-Z0-9_-]*$", "u");
+var AUTH_UID_PLACEHOLDER = '{authUid}';
+/**
+ * The bare `@dbxRouteModel` tag name (without the leading `@`).
+ */ var ROUTE_MODEL_TAG = 'dbxRouteModel';
+/**
+ * The `@dbxRouteModelList` tag name (without the leading `@`).
+ */ var ROUTE_MODEL_LIST_TAG = 'dbxRouteModelList';
+/**
+ * Parses one `@dbxRouteModel` / `@dbxRouteModelList` tag into a structured
+ * model, or returns a malformed-tag message. The description (everything after
+ * the first ` - `) is split off first; the remaining head is tokenized.
+ *
+ * @param tag - The raw tag name + comment text.
+ * @returns The parsed model on success, else a malformed-tag message.
+ *
+ * @example
+ * ```ts
+ * parseRouteModelTag({ name: 'dbxRouteModel', text: 'profile :uid - The profile' });
+ * // => { ok: true, model: { modelType: 'profile', kind: 'id', keyTemplate: ':uid', description: 'The profile', routeParams: ['uid'] } }
+ * ```
+ */ function parseRouteModelTag(tag) {
+    var dashIdx = tag.text.indexOf(' - ');
+    var head = (dashIdx >= 0 ? tag.text.slice(0, dashIdx) : tag.text).trim();
+    var description = dashIdx >= 0 ? tag.text.slice(dashIdx + 3).trim() : undefined;
+    var tokens = head.split(RegExp("\\s+", "u")).filter(function(t) {
+        return t.length > 0;
+    });
+    var result;
+    if (tag.name === ROUTE_MODEL_LIST_TAG) {
+        result = parseListTag(tokens, description);
+    } else if (tag.name === ROUTE_MODEL_TAG) {
+        result = parseModelTag(tokens, description);
+    } else {
+        result = {
+            ok: false,
+            message: "Unknown route-model tag `@".concat(tag.name, "`. Expected `@").concat(ROUTE_MODEL_TAG, "` or `@").concat(ROUTE_MODEL_LIST_TAG, "`.")
+        };
+    }
+    return result;
+}
+function parseListTag(tokens, description) {
+    var result;
+    if (tokens.length !== 1) {
+        result = {
+            ok: false,
+            message: "`@".concat(ROUTE_MODEL_LIST_TAG, "` expects a single `<modelType>` token; got ").concat(tokens.length, ".")
+        };
+    } else if (MODEL_TYPE_RE.test(tokens[0])) {
+        result = {
+            ok: true,
+            model: {
+                modelType: tokens[0],
+                kind: 'list',
+                description: description,
+                routeParams: []
+            }
+        };
+    } else {
+        result = {
+            ok: false,
+            message: "`@".concat(ROUTE_MODEL_LIST_TAG, "` model type `").concat(tokens[0], "` is not a valid identifier.")
+        };
+    }
+    return result;
+}
+function parseModelTag(tokens, description) {
+    var result;
+    if (tokens.length !== 2) {
+        result = {
+            ok: false,
+            message: "`@".concat(ROUTE_MODEL_TAG, "` expects `<modelType> <keyTemplate>`; got ").concat(tokens.length, " token(s).")
+        };
+    } else if (MODEL_TYPE_RE.test(tokens[0])) {
+        var parsedKey = parseKeyTemplate(tokens[1]);
+        if (parsedKey.ok) {
+            result = {
+                ok: true,
+                model: {
+                    modelType: tokens[0],
+                    kind: parsedKey.kind,
+                    keyTemplate: tokens[1],
+                    description: description,
+                    routeParams: parsedKey.routeParams
+                }
+            };
+        } else {
+            result = {
+                ok: false,
+                message: parsedKey.message
+            };
+        }
+    } else {
+        result = {
+            ok: false,
+            message: "`@".concat(ROUTE_MODEL_TAG, "` model type `").concat(tokens[0], "` is not a valid identifier.")
+        };
+    }
+    return result;
+}
+function parseKeyTemplate(keyTemplate) {
+    var segments = keyTemplate.split('/');
+    var result;
+    if (segments.length === 1) {
+        result = parseSingleSegmentKey(segments[0], keyTemplate);
+    } else if (segments.length % 2 === 0) {
+        result = parseAlternatingKey(segments, keyTemplate);
+    } else {
+        result = {
+            ok: false,
+            message: "Key template `".concat(keyTemplate, "` must be a single placeholder or an even number of literal/placeholder segments.")
+        };
+    }
+    return result;
+}
+function parseSingleSegmentKey(segment, keyTemplate) {
+    var placeholder = placeholderParam(segment);
+    var result;
+    if (placeholder === undefined) {
+        result = {
+            ok: false,
+            message: "Single-segment key template `".concat(keyTemplate, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`).")
+        };
+    } else {
+        result = {
+            ok: true,
+            kind: 'id',
+            routeParams: placeholder.routeParam === undefined ? [] : [
+                placeholder.routeParam
+            ]
+        };
+    }
+    return result;
+}
+function parseAlternatingKey(segments, keyTemplate) {
+    var routeParams = [];
+    var message;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = segments.entries()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var _step_value = _sliced_to_array(_step.value, 2), i = _step_value[0], segment = _step_value[1];
+            if (i % 2 === 0) {
+                if (!LITERAL_SEGMENT_RE.test(segment)) {
+                    message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a literal collection name.");
+                    break;
+                }
+            } else {
+                var placeholder = placeholderParam(segment);
+                if (placeholder === undefined) {
+                    message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`).");
+                    break;
+                }
+                if (placeholder.routeParam !== undefined) {
+                    routeParams.push(placeholder.routeParam);
+                }
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return message === undefined ? {
+        ok: true,
+        kind: 'key',
+        routeParams: routeParams
+    } : {
+        ok: false,
+        message: message
+    };
+}
+// MARK: Segment helpers
+/**
+ * Classifies a key-template segment as a placeholder, returning the referenced
+ * route param name (for `:name`) or `undefined` for `{authUid}`. Non-placeholder
+ * segments return `undefined` for the whole result.
+ *
+ * @param segment - The single key-template segment to classify.
+ * @returns The placeholder descriptor, or `undefined` when the segment is a literal.
+ */ function placeholderParam(segment) {
+    var result;
+    if (segment.startsWith(':') && segment.length > 1) {
+        result = {
+            routeParam: segment.slice(1)
+        };
+    } else if (segment === AUTH_UID_PLACEHOLDER) {
+        result = {
+            routeParam: undefined
+        };
+    } else {
+        result = undefined;
+    }
+    return result;
+}
+
+/**
+ * ESLint rule enforcing that `@dbxRouteModel` / `@dbxRouteModelList` tags parse
+ * cleanly through the canonical route-model grammar. Reuses
+ * {@link parseRouteModelTag} from `@dereekb/dbx-cli` so a tag that lints clean is
+ * a tag the build-time manifest builder will accept.
+ *
+ * Checks (delegated to the grammar parser):
+ *
+ * - `@dbxRouteModel <modelType> <keyTemplate>` has exactly two tokens with a valid
+ *   model-type identifier and a parseable key template (`:param` / `{authUid}` /
+ *   even-segment `gb/:id/...` form).
+ * - `@dbxRouteModelList <modelType>` has a single valid model-type token.
+ * - A `@dbxRouteModel*` tag with an unknown name is flagged.
+ *
+ * Report-only — no auto-fix, since the corrected value needs judgment.
+ */ var DBX_CLI_VALID_DBX_ROUTE_MODEL_TAGS_RULE = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Validate `@dbxRouteModel` / `@dbxRouteModelList` JSDoc tag grammar against the canonical route-model parser.',
+            recommended: true
+        },
+        messages: {
+            malformedRouteModelTag: 'Malformed `@dbxRouteModel*` tag: {{reason}}'
+        },
+        schema: []
+    },
+    create: function create(context) {
+        var sourceCode = context.sourceCode;
+        var checkedComments = new WeakSet();
+        function checkJsdoc(commentNode) {
+            if (checkedComments.has(commentNode)) {
+                return;
+            }
+            checkedComments.add(commentNode);
+            var parsed = parseJsdocComment(commentNode.value);
+            var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+            try {
+                for(var _iterator = parsed.tags[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                    var tag = _step.value;
+                    if (!tag.tag.startsWith(ROUTE_MODEL_TAG)) {
+                        continue;
+                    }
+                    var raw = {
+                        name: tag.tag,
+                        text: tag.description.trim()
+                    };
+                    var result = parseRouteModelTag(raw);
+                    if (!result.ok) {
+                        reportOnJsdocLine({
+                            commentNode: commentNode,
+                            parsed: parsed,
+                            sourceCode: sourceCode,
+                            lineIndex: tag.startLineIndex,
+                            messageId: 'malformedRouteModelTag',
+                            data: {
+                                reason: result.message
+                            },
+                            report: context.report
+                        });
+                    }
+                }
+            } catch (err) {
+                _didIteratorError = true;
+                _iteratorError = err;
+            } finally{
+                try {
+                    if (!_iteratorNormalCompletion && _iterator.return != null) {
+                        _iterator.return();
+                    }
+                } finally{
+                    if (_didIteratorError) {
+                        throw _iteratorError;
+                    }
+                }
+            }
+        }
+        function visit(node, anchorParentTypes) {
+            var anchor = node.parent && anchorParentTypes.includes(node.parent.type) ? node.parent : node;
+            var jsdoc = leadingJsdocFor(sourceCode, anchor);
+            if (jsdoc) {
+                checkJsdoc(jsdoc);
+            }
+        }
+        var exportAnchors = [
+            'ExportNamedDeclaration',
+            'ExportDefaultDeclaration'
+        ];
+        return {
+            ClassDeclaration: function ClassDeclaration(node) {
+                return visit(node, exportAnchors);
+            },
+            VariableDeclaration: function VariableDeclaration(node) {
+                return visit(node, exportAnchors);
+            }
+        };
+    }
+};
+
+/**
+ * ESLint plugin for `@dereekb/dbx-cli` rules.
+ *
+ * Register as a plugin in your flat ESLint config, then enable individual rules
+ * under the chosen plugin prefix (e.g. 'dereekb-dbx-cli/valid-dbx-route-model-tags').
+ */ var DBX_CLI_ESLINT_PLUGIN = {
+    rules: {
+        'valid-dbx-route-model-tags': DBX_CLI_VALID_DBX_ROUTE_MODEL_TAGS_RULE
+    }
+};
+/**
+ * camelCase alias of {@link DBX_CLI_ESLINT_PLUGIN} matching the conventional ESLint plugin export name.
+ *
+ * @dbxAllowConstantName
+ */ var dbxCliESLintPlugin = DBX_CLI_ESLINT_PLUGIN;
+
+export { DBX_CLI_ESLINT_PLUGIN, DBX_CLI_VALID_DBX_ROUTE_MODEL_TAGS_RULE, dbxCliESLintPlugin };