@dereekb/firebase 13.12.3 → 13.12.5

package/eslint/index.esm.js

@@ -1,10 +1,1133 @@
-import { leadingJsdocFor, parseJsdocComment, getStatementAnchor, findFamilyTags, checkDbxTagFamily, reportOnJsdocLine, parseBooleanTagValue, buildLowercaseTagsFix } from '@dereekb/util/eslint';
 import { createRequire } from 'node:module';
-import { existsSync, readFileSync, globSync } from 'node:fs';
-import { join, dirname, isAbsolute, resolve } from 'node:path';
+import { existsSync, readFileSync, globSync, readdirSync } from 'node:fs';
+import { join, dirname, isAbsolute, resolve, sep, basename } from 'node:path';
 import { parse as parse$1 } from '@typescript-eslint/typescript-estree';
 import { parse as parse$2 } from '@typescript-eslint/parser';
 
+/**
+ * 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 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$h(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$a(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function _iterable_to_array_limit$a(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$a() {
+    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$a(arr, i) {
+    return _array_with_holes$a(arr) || _iterable_to_array_limit$a(arr, i) || _unsupported_iterable_to_array$h(arr, i) || _non_iterable_rest$a();
+}
+function _unsupported_iterable_to_array$h(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$h(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$h(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$a(_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
+    };
+}
+
+/**
+ * Shared helpers for the `@dbx<Family>` companion-tag ESLint rules. Mirrors the
+ * scanner schemas in `packages/dbx-cli/src/lib/mcp-scan/scan/*-extract.ts` so
+ * violations surface at lint time instead of at manifest-regeneration time.
+ *
+ * Each per-family rule supplies a {@link DbxTagFamilySpec} describing which
+ * companions are required/optional, what value format each accepts, and which
+ * messageId to emit when a check fails. The rule body itself only wires the
+ * visitors and message map; all value-format validation lives here.
+ */ function _array_like_to_array$g(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$9(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function _iterable_to_array_limit$9(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$9() {
+    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$9(arr, i) {
+    return _array_with_holes$9(arr) || _iterable_to_array_limit$9(arr, i) || _unsupported_iterable_to_array$g(arr, i) || _non_iterable_rest$9();
+}
+function _unsupported_iterable_to_array$g(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$g(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$g(o, minLen);
+}
+/**
+ * Kebab-case slug pattern: lowercase letters/digits, words separated by single hyphens,
+ * starts with a letter. Used to validate slug/related/skill-ref values.
+ */ var KEBAB_SLUG_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/**
+ * Pascal-case TypeScript identifier pattern (starts uppercase). Used for model
+ * identifiers and other `<ModelName>` style tag values.
+ */ var PASCAL_IDENTIFIER_PATTERN$1 = /^[A-Z][A-Za-z0-9_$]*$/;
+/**
+ * Boolean tag-value vocabulary (case-insensitive). `''` and `true|yes` map to
+ * true; `false|no` map to false. Anything else is flagged as invalid.
+ */ var TRUE_TAG_VALUES = new Set([
+    '',
+    'true',
+    'yes'
+]);
+var FALSE_TAG_VALUES = new Set([
+    'false',
+    'no'
+]);
+/**
+ * Splits a comma-separated tag-value string into trimmed items, preserving order.
+ *
+ * @param value - Raw text following the tag name on a single line.
+ * @returns Non-empty trimmed segments in declaration order.
+ */ function splitCommaSeparated(value) {
+    return value.split(',').map(function(item) {
+        return item.trim();
+    }).filter(function(item) {
+        return item.length > 0;
+    });
+}
+/**
+ * Parses a boolean tag value using the workspace vocabulary
+ * (`''`/`true`/`yes` → true; `false`/`no` → false). Other inputs return `undefined`.
+ *
+ * @param text - The trimmed tag value text.
+ * @returns The parsed boolean, or `undefined` when the text is not in the vocabulary.
+ */ function parseBooleanTagValue(text) {
+    var lowered = text.trim().toLowerCase();
+    var result;
+    if (TRUE_TAG_VALUES.has(lowered)) {
+        result = true;
+    } else if (FALSE_TAG_VALUES.has(lowered)) {
+        result = false;
+    }
+    return result;
+}
+/**
+ * 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;
+}
+/**
+ * Returns the family marker + companion tag list for the given parsed JSDoc.
+ * Family membership is determined by tag-name prefix.
+ *
+ * @param parsed - The parsed JSDoc.
+ * @param marker - The bare family marker (e.g. `'dbxPipe'`).
+ * @returns The marker tag (if present), and all companion tags in source order.
+ */ function findFamilyTags(parsed, marker) {
+    var familyTags = parsed.tags.filter(function(t) {
+        return t.tag === marker || t.tag.startsWith(marker);
+    });
+    var markerTag = parsed.tags.find(function(t) {
+        return t.tag === marker;
+    });
+    return {
+        markerTag: markerTag,
+        familyTags: familyTags
+    };
+}
+/**
+ * Groups companion tags (those after the marker) by suffix. Marker entries are excluded.
+ *
+ * @param familyTags - The family tag list from {@link findFamilyTags}.
+ * @param marker - The bare family marker.
+ * @returns Lookup keyed by companion-suffix listing matching tags in declaration order.
+ */ function groupCompanionsBySuffix(familyTags, marker) {
+    var result = new Map();
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = familyTags[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var tag = _step.value;
+            var _result_get;
+            if (tag.tag === marker) continue;
+            var suffix = tag.tag.slice(marker.length);
+            var list = (_result_get = result.get(suffix)) !== null && _result_get !== void 0 ? _result_get : [];
+            list.push(tag);
+            result.set(suffix, list);
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Per-format validators dispatched from {@link validateCompanionValue}. Each entry validates
+ * a single non-empty tag value and emits zero or more violations.
+ */ var VALUE_VALIDATORS = {
+    marker: function marker() {
+        return undefined;
+    },
+    'free-text': function() {
+        return undefined;
+    },
+    'comma-list-free-text': function() {
+        return undefined;
+    },
+    'kebab-slug': function(param) {
+        var spec = param.spec, value = param.value, lineIndex = param.lineIndex, emit = param.emit;
+        if (!KEBAB_SLUG_PATTERN.test(value)) emit({
+            kind: 'invalid-kebab',
+            suffix: spec.suffix,
+            value: value,
+            lineIndex: lineIndex
+        });
+    },
+    enum: function _enum(param) {
+        var spec = param.spec, value = param.value, lineIndex = param.lineIndex, emit = param.emit;
+        var format = spec.format;
+        if (!format.values.includes(value)) emit({
+            kind: 'invalid-enum',
+            suffix: spec.suffix,
+            value: value,
+            allowed: format.values,
+            lineIndex: lineIndex
+        });
+    },
+    'pascal-identifier': function(param) {
+        var spec = param.spec, value = param.value, lineIndex = param.lineIndex, emit = param.emit;
+        if (!PASCAL_IDENTIFIER_PATTERN$1.test(value)) emit({
+            kind: 'invalid-pascal',
+            suffix: spec.suffix,
+            value: value,
+            lineIndex: lineIndex
+        });
+    },
+    'comma-list-kebab-slug': function(param) {
+        var spec = param.spec, value = param.value, lineIndex = param.lineIndex, emit = param.emit;
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = splitCommaSeparated(value)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var item = _step.value;
+                if (!KEBAB_SLUG_PATTERN.test(item)) emit({
+                    kind: 'comma-item-not-kebab',
+                    suffix: spec.suffix,
+                    value: item,
+                    lineIndex: lineIndex
+                });
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+    },
+    'comma-list-lowercase': function(param) {
+        var spec = param.spec, tag = param.tag, value = param.value, lineIndex = param.lineIndex, emit = param.emit;
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = splitCommaSeparated(value)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var item = _step.value;
+                if (/[A-Z]/.test(item)) emit({
+                    kind: 'tags-not-lowercase',
+                    suffix: spec.suffix,
+                    value: item,
+                    lineIndex: lineIndex,
+                    raw: tag
+                });
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+    },
+    boolean: function boolean(param) {
+        var spec = param.spec, value = param.value, lineIndex = param.lineIndex, emit = param.emit;
+        if (parseBooleanTagValue(value) === undefined) emit({
+            kind: 'invalid-boolean',
+            suffix: spec.suffix,
+            value: value,
+            lineIndex: lineIndex
+        });
+    }
+};
+/**
+ * Validates one companion tag's value against the configured {@link DbxTagFormat}
+ * and emits zero-or-more violations. Used by {@link checkDbxTagFamily} to keep
+ * each rule's body small.
+ *
+ * @param spec - The companion spec being validated.
+ * @param tags - All occurrences of the companion in source order.
+ * @param emit - Callback for each violation.
+ */ function validateCompanionValue(spec, tags, emit) {
+    if (spec.format.kind === 'marker') return;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = tags[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var tag = _step.value;
+            var value = tag.description.trim();
+            var lineIndex = tag.startLineIndex;
+            if (value.length === 0) {
+                if (spec.format.kind !== 'boolean') emit({
+                    kind: 'empty',
+                    suffix: spec.suffix,
+                    lineIndex: lineIndex
+                });
+                continue;
+            }
+            var validator = VALUE_VALIDATORS[spec.format.kind];
+            if (validator) validator({
+                spec: spec,
+                tag: tag,
+                value: value,
+                lineIndex: lineIndex,
+                emit: emit
+            });
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+}
+function emitUnknownCompanions(groups, knownSuffixes, emit) {
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = groups.entries()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var _step_value = _sliced_to_array$9(_step.value, 2), suffix = _step_value[0], instances = _step_value[1];
+            if (knownSuffixes.has(suffix)) continue;
+            var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
+            try {
+                for(var _iterator1 = instances[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
+                    var tag = _step1.value;
+                    emit({
+                        kind: 'unknown',
+                        suffix: suffix,
+                        lineIndex: tag.startLineIndex
+                    });
+                }
+            } catch (err) {
+                _didIteratorError1 = true;
+                _iteratorError1 = err;
+            } finally{
+                try {
+                    if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                        _iterator1.return();
+                    }
+                } finally{
+                    if (_didIteratorError1) {
+                        throw _iteratorError1;
+                    }
+                }
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+}
+function emitDuplicateCompanions(companion, instances, emit) {
+    for(var i = 1; i < instances.length; i += 1){
+        emit({
+            kind: 'duplicate',
+            suffix: companion.suffix,
+            lineIndex: instances[i].startLineIndex
+        });
+    }
+}
+function checkCompanion(input) {
+    var companion = input.companion, instances = input.instances, markerLineIndex = input.markerLineIndex, emit = input.emit;
+    if (instances.length === 0) {
+        if (companion.required) emit({
+            kind: 'missing',
+            suffix: companion.suffix,
+            lineIndex: markerLineIndex
+        });
+        return;
+    }
+    if (!companion.multiple && instances.length > 1) emitDuplicateCompanions(companion, instances, emit);
+    validateCompanionValue(companion, instances, emit);
+}
+/**
+ * Validates a `@dbx<Family>` marker plus its companion tags against the supplied spec.
+ * Reports unknown companions, missing required companions, duplicates, and per-companion
+ * value violations through `input.emit`.
+ *
+ * @param input - Parsed JSDoc, family spec, resolved marker/companion tags, and emit sink.
+ *
+ * @example
+ * ```ts
+ * checkDbxTagFamily({ parsed, spec, markerTag, familyTags, emit });
+ * ```
+ */ function checkDbxTagFamily(input) {
+    var spec = input.spec, markerTag = input.markerTag, familyTags = input.familyTags, emit = input.emit;
+    var knownSuffixes = new Set(spec.companions.map(function(c) {
+        return c.suffix;
+    }));
+    var groups = groupCompanionsBySuffix(familyTags, spec.marker);
+    emitUnknownCompanions(groups, knownSuffixes, emit);
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = spec.companions[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var companion = _step.value;
+            var _groups_get;
+            var instances = (_groups_get = groups.get(companion.suffix)) !== null && _groups_get !== void 0 ? _groups_get : [];
+            checkCompanion({
+                companion: companion,
+                instances: instances,
+                markerLineIndex: markerTag.startLineIndex,
+                emit: emit
+            });
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+}
+/**
+ * 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
+    });
+}
+/**
+ * Computes an auto-fix descriptor that lowercases every token after a `@dbx<Family>Tags` tag
+ * name. Returns `undefined` when the line is already canonical so the caller can short-circuit.
+ *
+ * @param input - Fix context (comment node, parsed JSDoc, source code, target tag).
+ * @returns Replacement range + text when a rewrite is needed; otherwise `undefined`.
+ *
+ * @example
+ * ```ts
+ * const fix = buildLowercaseTagsFix({ commentNode, parsed, sourceCode, tag });
+ * ```
+ */ function buildLowercaseTagsFix(input) {
+    var commentNode = input.commentNode, parsed = input.parsed, sourceCode = input.sourceCode, tag = input.tag;
+    var tagLine = parsed.lines[tag.startLineIndex];
+    var result;
+    if (tagLine) {
+        var tagLineSourceStart = commentValueToSourceOffset(commentNode, tagLine.textOffsetStart);
+        var tagLineSourceEnd = tagLineSourceStart + tagLine.text.length;
+        var sourceText = sourceCode.getText();
+        var lineSource = sourceText.slice(tagLineSourceStart, tagLineSourceEnd);
+        var lowered = lineSource.replace(/^(@[A-Za-z]+\s+)(.*)$/, function(_match, prefix, body) {
+            return "".concat(prefix).concat(body.toLowerCase());
+        });
+        if (lowered !== lineSource) {
+            result = {
+                startOffset: tagLineSourceStart,
+                endOffset: tagLineSourceEnd,
+                replacement: lowered
+            };
+        }
+    }
+    return result;
+}
+
 function _array_like_to_array$f(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];
@@ -1341,7 +2464,6 @@ var DEFAULT_KNOWN_COMPANIONS = [
             if (familyTags.length === 0 || requireBareMarker && !markerTag) return;
             var triggerTag = markerTag !== null && markerTag !== void 0 ? markerTag : familyTags[0];
             checkDbxTagFamily({
-                parsed: parsed,
                 spec: spec,
                 markerTag: triggerTag,
                 familyTags: familyTags,
@@ -1980,7 +3102,7 @@ function _unsupported_iterable_to_array$c(o, minLen) {
  */ var MODEL_FIREBASE_CRUD_FUNCTION_CONFIG_MAP_TYPE_NAME = 'ModelFirebaseCrudFunctionConfigMap';
 /**
  * CRUD verb names supported by `ModelFirebaseCrudFunctionConfigMap`. Mirrors the
- * `create | read | update | delete | query` verbs in the type definition at
+ * `create | read | update | delete | query | invoke` verbs in the type definition at
  * `packages/firebase/src/lib/client/function/model.function.factory.ts`.
  */ var DEFAULT_CRUD_VERB_NAMES = [
     'create',
@@ -16105,6 +17227,415 @@ function reportCompositeKeyTag(ctx, tag, allowedEncodings) {
     }
 };
 
+var SPEC_SUFFIX = '.spec.ts';
+/**
+ * Classifies a spec filename against the conventions for the given parent
+ * folder. Pure function — never touches the filesystem.
+ *
+ * @param config - Inputs.
+ * @param config.filename - Bare filename including the `.spec.ts` suffix
+ *   (e.g. `job.scenario.requirement.spec.ts`).
+ * @param config.parentFolderName - Name of the directory containing the file
+ *   (e.g. `job`). Used to detect cross-group misplacement.
+ * @returns The classification.
+ */ function classifySpecFile(config) {
+    var filename = config.filename, parentFolderName = config.parentFolderName;
+    var result;
+    if (!filename.endsWith(SPEC_SUFFIX)) {
+        result = {
+            filename: filename,
+            group: '',
+            kind: 'non-spec',
+            subgroups: [],
+            isCanonical: false
+        };
+    } else {
+        var _parts_;
+        var stem = filename.slice(0, -SPEC_SUFFIX.length);
+        var parts = stem.split('.');
+        var group = (_parts_ = parts[0]) !== null && _parts_ !== void 0 ? _parts_ : '';
+        if (group !== parentFolderName) {
+            result = {
+                filename: filename,
+                group: group,
+                kind: 'non-group',
+                subgroups: [],
+                isCanonical: false
+            };
+        } else {
+            var rest = parts.slice(1);
+            result = classifyRemainingSegments({
+                filename: filename,
+                group: group,
+                rest: rest
+            });
+        }
+    }
+    return result;
+}
+function classifyRemainingSegments(config) {
+    var filename = config.filename, group = config.group, rest = config.rest;
+    var result;
+    var crudIdx = rest.indexOf('crud');
+    var scenarioIdx = rest.indexOf('scenario');
+    if (crudIdx === 0) {
+        if (rest.length === 1) {
+            result = {
+                filename: filename,
+                group: group,
+                kind: 'crud',
+                subgroups: [],
+                isCanonical: true
+            };
+        } else {
+            result = {
+                filename: filename,
+                group: group,
+                kind: 'crud-subgroup',
+                subgroups: rest.slice(1),
+                isCanonical: true
+            };
+        }
+    } else if (scenarioIdx === 0) {
+        if (rest.length === 1) {
+            result = {
+                filename: filename,
+                group: group,
+                kind: 'scenario',
+                subgroups: [],
+                isCanonical: true
+            };
+        } else {
+            result = {
+                filename: filename,
+                group: group,
+                kind: 'scenario-subgroup',
+                subgroups: rest.slice(1),
+                isCanonical: true
+            };
+        }
+    } else if (crudIdx > 0) {
+        var subgroups = rest.filter(function(_, i) {
+            return i !== crudIdx;
+        });
+        var recommendedRename = buildCanonicalFilename({
+            group: group,
+            bucket: 'crud',
+            subgroups: subgroups
+        });
+        result = {
+            filename: filename,
+            group: group,
+            kind: 'crud-misplaced',
+            subgroups: subgroups,
+            isCanonical: false,
+            recommendedRename: recommendedRename,
+            driftReason: '`crud` segment is not directly after the group name.'
+        };
+    } else if (scenarioIdx > 0) {
+        var subgroups1 = rest.filter(function(_, i) {
+            return i !== scenarioIdx;
+        });
+        var recommendedRename1 = buildCanonicalFilename({
+            group: group,
+            bucket: 'scenario',
+            subgroups: subgroups1
+        });
+        result = {
+            filename: filename,
+            group: group,
+            kind: 'scenario-misplaced',
+            subgroups: subgroups1,
+            isCanonical: false,
+            recommendedRename: recommendedRename1,
+            driftReason: '`scenario` segment is not directly after the group name.'
+        };
+    } else if (rest.length === 0) {
+        var recommendedRename2 = buildCanonicalFilename({
+            group: group,
+            bucket: 'scenario',
+            subgroups: []
+        });
+        result = {
+            filename: filename,
+            group: group,
+            kind: 'no-bucket',
+            subgroups: [],
+            isCanonical: false,
+            recommendedRename: recommendedRename2,
+            driftReason: 'Missing `crud` or `scenario` segment.'
+        };
+    } else {
+        var recommendedRename3 = buildCanonicalFilename({
+            group: group,
+            bucket: 'scenario',
+            subgroups: rest
+        });
+        result = {
+            filename: filename,
+            group: group,
+            kind: 'no-bucket',
+            subgroups: rest,
+            isCanonical: false,
+            recommendedRename: recommendedRename3,
+            driftReason: 'Missing `crud` or `scenario` segment — defaulting suggestion to `scenario`.'
+        };
+    }
+    return result;
+}
+/**
+ * Renders a canonical spec filename for the given group + bucket + subgroup
+ * chain. Pure data — used both by drift remediation and by the
+ * `recommendSpecPath()` helper below.
+ *
+ * @param config - Inputs.
+ * @param config.group - The model-group name (e.g. `job`).
+ * @param config.bucket - `crud` or `scenario`.
+ * @param config.subgroups - Optional ordered subgroup segments
+ *   (e.g. `['requirement','worker']`).
+ * @returns The canonical filename (e.g. `job.scenario.requirement.worker.spec.ts`).
+ */ function buildCanonicalFilename(config) {
+    var group = config.group, bucket = config.bucket, subgroups = config.subgroups;
+    var tail = subgroups.length === 0 ? '' : ".".concat(subgroups.join('.'));
+    return "".concat(group, ".").concat(bucket).concat(tail, ".spec.ts");
+}
+
+/**
+ * Default subpath segment (relative to an app source root) below which the
+ * rule expects model-group function folders. Matches the convention used by
+ * `<apiDir>/src/app/function/<group>/`.
+ */ var DEFAULT_FUNCTION_DIR_SEGMENT = 'src/app/function';
+function matchFunctionSpecPath(filename, functionDirSegment) {
+    var result;
+    if (filename.endsWith('.spec.ts')) {
+        var normalized = filename.split(sep).join('/');
+        var marker = "/".concat(functionDirSegment, "/");
+        var markerIdx = normalized.indexOf(marker);
+        if (markerIdx >= 0) {
+            var afterMarker = normalized.slice(markerIdx + marker.length);
+            var parts = afterMarker.split('/');
+            if (parts.length === 2) {
+                var _parts_, _parts_1;
+                result = {
+                    filename: (_parts_ = parts[1]) !== null && _parts_ !== void 0 ? _parts_ : '',
+                    parentFolderName: (_parts_1 = parts[0]) !== null && _parts_1 !== void 0 ? _parts_1 : ''
+                };
+            } else if (parts.length > 2) {
+                result = {
+                    filename: basename(filename),
+                    parentFolderName: basename(dirname(filename))
+                };
+            }
+        }
+    }
+    return result;
+}
+/**
+ * ESLint rule that enforces the canonical naming convention for Firebase
+ * Functions API spec files: every `.spec.ts` under
+ * `<apiDir>/src/app/function/<group>/` must be `<group>.crud[.<sub>...].spec.ts`
+ * or `<group>.scenario[.<sub>...].spec.ts`. Drift forms surface a rename
+ * suggestion derived from the shared `classifySpecFile` classifier in
+ * `@dereekb/util`, so this rule and the `dbx_model_test_validate_app` MCP
+ * tool never diverge.
+ *
+ * Not auto-fixable: renaming files (and updating any imports/snapshots they
+ * carry) is outside the safe scope of an ESLint autofix.
+ */ var FIREBASE_REQUIRE_CANONICAL_API_SPEC_FILENAME_RULE = {
+    meta: {
+        type: 'suggestion',
+        fixable: undefined,
+        docs: {
+            description: 'Require API spec filenames under `src/app/function/<group>/` to follow the `<group>.crud[.<sub>...].spec.ts` / `<group>.scenario[.<sub>...].spec.ts` convention.',
+            recommended: true
+        },
+        messages: {
+            testFileDriftRename: '`{{filename}}`: {{reason}} Rename to `{{recommendedRename}}`.',
+            testFileMissingBucket: '`{{filename}}`: missing `crud` / `scenario` segment. Rename to `{{recommendedRename}}` (default) or to a `crud` variant if the tests are CRUD-flavored.',
+            testFileNonGroupPlacement: '`{{filename}}`: first segment `{{group}}` does not match the parent folder `{{parentFolderName}}`. Move into `{{group}}/` or rename the prefix to match the current folder.'
+        },
+        schema: [
+            {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    functionDirSegment: {
+                        type: 'string'
+                    }
+                }
+            }
+        ]
+    },
+    create: function create(context) {
+        var _context_options_, _options_functionDirSegment;
+        var options = (_context_options_ = context.options[0]) !== null && _context_options_ !== void 0 ? _context_options_ : {};
+        var functionDirSegment = (_options_functionDirSegment = options.functionDirSegment) !== null && _options_functionDirSegment !== void 0 ? _options_functionDirSegment : DEFAULT_FUNCTION_DIR_SEGMENT;
+        var matched = matchFunctionSpecPath(context.filename, functionDirSegment);
+        function check(programNode) {
+            if (!matched) return;
+            var classification = classifySpecFile({
+                filename: matched.filename,
+                parentFolderName: matched.parentFolderName
+            });
+            if (classification.isCanonical) return;
+            if (classification.kind === 'non-spec') return;
+            if (classification.kind === 'crud-misplaced' || classification.kind === 'scenario-misplaced') {
+                var _classification_driftReason, _classification_recommendedRename;
+                context.report({
+                    node: programNode,
+                    messageId: 'testFileDriftRename',
+                    data: {
+                        filename: classification.filename,
+                        reason: (_classification_driftReason = classification.driftReason) !== null && _classification_driftReason !== void 0 ? _classification_driftReason : 'segment order does not match the convention.',
+                        recommendedRename: (_classification_recommendedRename = classification.recommendedRename) !== null && _classification_recommendedRename !== void 0 ? _classification_recommendedRename : ''
+                    }
+                });
+            } else if (classification.kind === 'no-bucket') {
+                var _classification_recommendedRename1;
+                context.report({
+                    node: programNode,
+                    messageId: 'testFileMissingBucket',
+                    data: {
+                        filename: classification.filename,
+                        recommendedRename: (_classification_recommendedRename1 = classification.recommendedRename) !== null && _classification_recommendedRename1 !== void 0 ? _classification_recommendedRename1 : ''
+                    }
+                });
+            } else if (classification.kind === 'non-group') {
+                context.report({
+                    node: programNode,
+                    messageId: 'testFileNonGroupPlacement',
+                    data: {
+                        filename: classification.filename,
+                        group: classification.group,
+                        parentFolderName: matched.parentFolderName
+                    }
+                });
+            }
+        }
+        return {
+            Program: function Program(node) {
+                return check(node);
+            }
+        };
+    }
+};
+
+function isGroupIndex(filename, functionDirSegment) {
+    var normalized = filename.split(sep).join('/');
+    var marker = "/".concat(functionDirSegment, "/");
+    var markerIdx = normalized.indexOf(marker);
+    var result = false;
+    if (markerIdx >= 0) {
+        var afterMarker = normalized.slice(markerIdx + marker.length);
+        var parts = afterMarker.split('/');
+        result = parts.length === 2 && parts[1] === 'index.ts';
+    }
+    return result;
+}
+function hasCrudSpec(groupDir, group) {
+    var found = false;
+    try {
+        var entries = readdirSync(groupDir);
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = entries[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var entry = _step.value;
+                var classification = classifySpecFile({
+                    filename: entry,
+                    parentFolderName: group
+                });
+                if (classification.kind === 'crud' || classification.kind === 'crud-subgroup') {
+                    found = true;
+                    break;
+                }
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+    } catch (unused) {
+    // Directory unreadable — treat as no crud spec; rule will emit the warning
+    // and the user can investigate. We do NOT swallow the error silently
+    // in any other way.
+    }
+    return found;
+}
+/**
+ * ESLint rule that fires on every `<apiDir>/src/app/function/<group>/index.ts`
+ * (the canonical anchor file for a Firebase Functions group) and verifies
+ * that the same folder contains a `<group>.crud.spec.ts` (or any
+ * `<group>.crud.<sub>.spec.ts` variant) sibling. Mirrors the coverage check
+ * in `dbx_model_test_validate_app` so editor + CI lint flag missing CRUD
+ * coverage without needing the MCP audit.
+ *
+ * Not auto-fixable: creating a spec file shell with sensible test cases is
+ * outside the safe scope of an ESLint autofix.
+ */ var FIREBASE_REQUIRE_API_CRUD_SPEC_FOR_GROUP_RULE = {
+    meta: {
+        type: 'suggestion',
+        fixable: undefined,
+        docs: {
+            description: 'Require every API model-group function folder to have a `<group>.crud.spec.ts` covering its CRUD function map.',
+            recommended: true
+        },
+        messages: {
+            modelGroupMissingCrudSpec: 'Model group `{{group}}` has no `{{expectedFilename}}`. Add it covering the CRUD function map (create/read/update/delete + permission/error paths).'
+        },
+        schema: [
+            {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    functionDirSegment: {
+                        type: 'string'
+                    }
+                }
+            }
+        ]
+    },
+    create: function create(context) {
+        var _context_options_, _options_functionDirSegment;
+        var options = (_context_options_ = context.options[0]) !== null && _context_options_ !== void 0 ? _context_options_ : {};
+        var functionDirSegment = (_options_functionDirSegment = options.functionDirSegment) !== null && _options_functionDirSegment !== void 0 ? _options_functionDirSegment : DEFAULT_FUNCTION_DIR_SEGMENT;
+        var filename = context.filename;
+        var isAnchor = isGroupIndex(filename, functionDirSegment);
+        function check(programNode) {
+            if (!isAnchor) return;
+            var groupDir = dirname(filename);
+            var group = basename(groupDir);
+            if (hasCrudSpec(groupDir, group)) return;
+            var expectedFilename = buildCanonicalFilename({
+                group: group,
+                bucket: 'crud',
+                subgroups: []
+            });
+            context.report({
+                node: programNode,
+                messageId: 'modelGroupMissingCrudSpec',
+                data: {
+                    group: group,
+                    expectedFilename: expectedFilename
+                }
+            });
+        }
+        return {
+            Program: function Program(node) {
+                return check(node);
+            }
+        };
+    }
+};
+
 /**
  * ESLint plugin for `@dereekb/firebase` rules.
  *
@@ -16124,7 +17655,9 @@ function reportCompositeKeyTag(ctx, tag, allowedEncodings) {
         'require-firestore-rule-for-service-model': FIREBASE_REQUIRE_FIRESTORE_RULE_FOR_SERVICE_MODEL_RULE,
         'require-dbx-model-service-factory-tag': FIREBASE_REQUIRE_DBX_MODEL_SERVICE_FACTORY_TAG_RULE,
         'require-service-factory-for-dbx-model': FIREBASE_REQUIRE_SERVICE_FACTORY_FOR_DBX_MODEL_RULE,
-        'require-dbx-model-companion-tags': FIREBASE_REQUIRE_DBX_MODEL_COMPANION_TAGS_RULE
+        'require-dbx-model-companion-tags': FIREBASE_REQUIRE_DBX_MODEL_COMPANION_TAGS_RULE,
+        'require-canonical-api-spec-filename': FIREBASE_REQUIRE_CANONICAL_API_SPEC_FILENAME_RULE,
+        'require-api-crud-spec-for-group': FIREBASE_REQUIRE_API_CRUD_SPEC_FOR_GROUP_RULE
     }
 };
 /**
@@ -16133,4 +17666,4 @@ function reportCompositeKeyTag(ctx, tag, allowedEncodings) {
  * @dbxAllowConstantName
  */ var firebaseESLintPlugin = FIREBASE_ESLINT_PLUGIN;
 
-export { API_DETAILS_IMPORT_MODULE, DBX_MODEL_FIREBASE_INDEX_MARKER, DBX_MODEL_SERVICE_FACTORY_TAG, DEFAULT_API_DETAILS_FACTORY_NAME, DEFAULT_CONSTRAINT_FACTORY_NAMES, DEFAULT_CRUD_FUNCTION_TYPE_VERBS, DEFAULT_CRUD_VERB_NAMES, DEFAULT_DISCOVERY_EXCLUDED_DIRS, DEFAULT_FACTORY_SEARCH_ROOTS, DEFAULT_FACTORY_TAG, DEFAULT_FIRESTORE_RULES_FILENAME, DEFAULT_IDENTITY_FACTORY_NAME, DEFAULT_INDEX_AFFECTING_CONSTRAINT_NAMES, DEFAULT_MODEL_MARKER_TAG, DEFAULT_MODEL_SEARCH_ROOTS, DEFAULT_PAGINATION_CONSTRAINT_NAMES, DEFAULT_REGISTRY_FACTORY_CALL_NAME, DEFAULT_STORAGE_FILE_UPLOAD_POLICY_TYPE_NAME, DEFAULT_STORAGE_RULES_FILENAME, FIREBASE_ESLINT_PLUGIN, FIREBASE_MODEL_SERVICE_FACTORY_MODULE, FIREBASE_MODEL_SERVICE_FACTORY_NAME, FIREBASE_MODULE, FIREBASE_REQUIRE_API_DETAILS_FOR_CRUD_FUNCTION_RULE, FIREBASE_REQUIRE_COMPLETE_CRUD_FUNCTION_CONFIG_MAP_RULE, FIREBASE_REQUIRE_DBX_MODEL_COMPANION_TAGS_RULE, FIREBASE_REQUIRE_DBX_MODEL_FIREBASE_INDEX_COMPANION_TAGS_RULE, FIREBASE_REQUIRE_DBX_MODEL_FIREBASE_INDEX_QUERY_SUFFIX_RULE, FIREBASE_REQUIRE_DBX_MODEL_FIREBASE_INDEX_VALID_DISPATCHER_RULE, FIREBASE_REQUIRE_DBX_MODEL_SERVICE_FACTORY_TAG_RULE, FIREBASE_REQUIRE_FIRESTORE_CONSTRAINT_TYPE_PARAMETER_RULE, FIREBASE_REQUIRE_FIRESTORE_RULE_FOR_SERVICE_MODEL_RULE, FIREBASE_REQUIRE_INPUT_TYPE_FOR_API_DETAILS_RULE, FIREBASE_REQUIRE_SERVICE_FACTORY_FOR_DBX_MODEL_RULE, FIREBASE_REQUIRE_STORAGEFILE_POLICY_MATCHES_RULES_RULE, FIREBASE_REQUIRE_TAGGED_FIRESTORE_CONSTRAINTS_RULE, INPUT_TYPE_PROPERTY_NAME, MIRRORS_POLICY_KEY_MARKER_REGEX, MODEL_FIREBASE_CRUD_FUNCTION_CONFIG_MAP_TYPE_NAME, QUERY_SUFFIX, discoveryGlobExcludeFilter, firebaseESLintPlugin, parseFirestoreRules, parseStorageRules };
+export { API_DETAILS_IMPORT_MODULE, DBX_MODEL_FIREBASE_INDEX_MARKER, DBX_MODEL_SERVICE_FACTORY_TAG, DEFAULT_API_DETAILS_FACTORY_NAME, DEFAULT_CONSTRAINT_FACTORY_NAMES, DEFAULT_CRUD_FUNCTION_TYPE_VERBS, DEFAULT_CRUD_VERB_NAMES, DEFAULT_DISCOVERY_EXCLUDED_DIRS, DEFAULT_FACTORY_SEARCH_ROOTS, DEFAULT_FACTORY_TAG, DEFAULT_FIRESTORE_RULES_FILENAME, DEFAULT_FUNCTION_DIR_SEGMENT, DEFAULT_IDENTITY_FACTORY_NAME, DEFAULT_INDEX_AFFECTING_CONSTRAINT_NAMES, DEFAULT_MODEL_MARKER_TAG, DEFAULT_MODEL_SEARCH_ROOTS, DEFAULT_PAGINATION_CONSTRAINT_NAMES, DEFAULT_REGISTRY_FACTORY_CALL_NAME, DEFAULT_STORAGE_FILE_UPLOAD_POLICY_TYPE_NAME, DEFAULT_STORAGE_RULES_FILENAME, FIREBASE_ESLINT_PLUGIN, FIREBASE_MODEL_SERVICE_FACTORY_MODULE, FIREBASE_MODEL_SERVICE_FACTORY_NAME, FIREBASE_MODULE, FIREBASE_REQUIRE_API_CRUD_SPEC_FOR_GROUP_RULE, FIREBASE_REQUIRE_API_DETAILS_FOR_CRUD_FUNCTION_RULE, FIREBASE_REQUIRE_CANONICAL_API_SPEC_FILENAME_RULE, FIREBASE_REQUIRE_COMPLETE_CRUD_FUNCTION_CONFIG_MAP_RULE, FIREBASE_REQUIRE_DBX_MODEL_COMPANION_TAGS_RULE, FIREBASE_REQUIRE_DBX_MODEL_FIREBASE_INDEX_COMPANION_TAGS_RULE, FIREBASE_REQUIRE_DBX_MODEL_FIREBASE_INDEX_QUERY_SUFFIX_RULE, FIREBASE_REQUIRE_DBX_MODEL_FIREBASE_INDEX_VALID_DISPATCHER_RULE, FIREBASE_REQUIRE_DBX_MODEL_SERVICE_FACTORY_TAG_RULE, FIREBASE_REQUIRE_FIRESTORE_CONSTRAINT_TYPE_PARAMETER_RULE, FIREBASE_REQUIRE_FIRESTORE_RULE_FOR_SERVICE_MODEL_RULE, FIREBASE_REQUIRE_INPUT_TYPE_FOR_API_DETAILS_RULE, FIREBASE_REQUIRE_SERVICE_FACTORY_FOR_DBX_MODEL_RULE, FIREBASE_REQUIRE_STORAGEFILE_POLICY_MATCHES_RULES_RULE, FIREBASE_REQUIRE_TAGGED_FIRESTORE_CONSTRAINTS_RULE, INPUT_TYPE_PROPERTY_NAME, MIRRORS_POLICY_KEY_MARKER_REGEX, MODEL_FIREBASE_CRUD_FUNCTION_CONFIG_MAP_TYPE_NAME, QUERY_SUFFIX, discoveryGlobExcludeFilter, firebaseESLintPlugin, parseFirestoreRules, parseStorageRules };