@dereekb/firebase 13.12.0 → 13.12.2

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

@@ -3,6 +3,50 @@ import type { Maybe } from '@dereekb/util';
  * Module that publishes the `@dereekb/firebase` Firestore constraint factories (`where`, `orderBy`, etc.).
  */
 export declare const FIREBASE_MODULE = "@dereekb/firebase";
+/**
+ * Directory names the layout-agnostic discovery globs never descend into: installed dependencies
+ * and build/cache output. Excluding these keeps a broad `**\/*.ts` scan from walking a downstream
+ * consumer's `node_modules` (which can hold tens of thousands of declaration files) and from
+ * double-counting compiled output under `dist`.
+ */
+export declare const DEFAULT_DISCOVERY_EXCLUDED_DIRS: readonly string[];
+/**
+ * Builds the `exclude` predicate passed to `fs.globSync(pattern, { cwd, exclude })` for the broad,
+ * layout-agnostic discovery globs. Node invokes the predicate on each visited path (directories
+ * included) and prunes the subtree when it returns true, so excluding a directory name here stops
+ * the walk from ever descending into it.
+ *
+ * @param excludedDirs - Directory names to prune. Defaults to {@link DEFAULT_DISCOVERY_EXCLUDED_DIRS}.
+ * @returns A predicate that returns true for any path containing an excluded directory segment.
+ */
+export declare function discoveryGlobExcludeFilter(excludedDirs?: readonly string[]): (path: string) => boolean;
+/**
+ * Resolves the absolute path to the installed `@dereekb/firebase` package's `src/lib/model`
+ * directory, as seen from the ESLint `cwd`. Used by rules that need to read the framework model
+ * declarations (identities, service factories) directly from the package a consumer has installed —
+ * the downstream case where these live under `node_modules/@dereekb/firebase/...` as compiled
+ * bundles plus `.d.ts` rather than a scannable source tree.
+ *
+ * Resolution uses Node's own module resolver (`require.resolve('@dereekb/firebase/package.json')`
+ * anchored at `cwd`), so it transparently handles hoisting / nested `node_modules`. Returns null
+ * when `@dereekb/firebase` is not resolvable as a dependency from `cwd` (e.g. inside the
+ * dbx-components monorepo itself, where it is consumed via TS path mapping rather than
+ * `node_modules`) — callers fall back to their cwd-relative source globs in that case.
+ *
+ * @param cwd - The ESLint working directory to resolve the dependency from.
+ * @returns The absolute model directory, or null when it cannot be resolved.
+ */
+export declare function resolveInstalledFirebaseModelDir(cwd: string): Maybe<string>;
+/**
+ * Resolves the referenced type name from either a `TSTypeReference` (`Foo<…>` / `ns.Foo<…>`) or a
+ * `TSImportType` (`import("…").Foo<…>` — the form the TypeScript compiler emits in declaration
+ * files for cross-module type references). Returns the rightmost identifier name in a qualified
+ * name.
+ *
+ * @param node - A `TSTypeReference` or `TSImportType` node (or anything else).
+ * @returns The referenced type name, or null when the node is neither shape.
+ */
+export declare function referencedTypeName(node: AstNode): Maybe<string>;
 /**
  * JSDoc tag name that marks an exported query factory whose body should be scanned by
  * `dbx-components-mcp`'s index extractor (`packages/dbx-components-mcp/src/scan/model-firebase-index-extract.ts`).
@@ -105,3 +149,143 @@ export declare function getFunctionName(node: AstNode): Maybe<string>;
  * @returns The node to attach a `context.report` location to.
  */
 export declare function getFunctionNameNode(node: AstNode): AstNode;
+/**
+ * Default CRUD verb names that combine with the `ModelFunction` suffix to form a type-name
+ * pattern the api-details rules treat as a CRUD function declaration (e.g. `OnCallCreateModelFunction`,
+ * `DemoUpdateModelFunction`).
+ *
+ * Mirrors the verbs supported by `ModelFirebaseCrudFunctionConfigMap` — see
+ * `packages/firebase/src/lib/client/function/model.function.factory.ts`.
+ */
+export declare const DEFAULT_CRUD_FUNCTION_TYPE_VERBS: readonly string[];
+/**
+ * Default factory function name that wraps CRUD function declarations and attaches the
+ * `_apiDetails` metadata (`inputType`, `outputType`, `mcp.visibility`, `analytics`) consumed
+ * by the MCP manifest builder. Defined in `packages/firebase-server/src/lib/nest/model/api.details.ts`.
+ */
+export declare const DEFAULT_API_DETAILS_FACTORY_NAME: string;
+/**
+ * Property name on the `withApiDetails(...)` config object that declares the handler's input
+ * parameter type (consumed by the MCP manifest builder to generate the tool input schema).
+ */
+export declare const INPUT_TYPE_PROPERTY_NAME: string;
+/**
+ * Module the default api-details factory ({@link DEFAULT_API_DETAILS_FACTORY_NAME}) is exported
+ * from. Used by the require-api-details auto-fix to insert a missing import.
+ */
+export declare const API_DETAILS_IMPORT_MODULE: string;
+/**
+ * Unwraps `TSAsExpression` and `TSTypeAssertion` wrappers around an initializer so callers see the
+ * underlying expression (matches the helper in `require-complete-crud-function-config-map.rule.ts`).
+ *
+ * @param node - The AST node to unwrap.
+ * @returns The innermost wrapped expression, or `node` when no cast is present.
+ */
+export declare function unwrapTypeAssertion(node: AstNode): AstNode;
+/**
+ * Resolves the identifier name from a `TSTypeReference` annotation, when present.
+ *
+ * @param node - A `TSTypeReference` node (or anything else).
+ * @returns The identifier name when `node` is a TSTypeReference whose typeName is an Identifier; otherwise null.
+ */
+export declare function typeReferenceTypeName(node: AstNode): Maybe<string>;
+/**
+ * Resolves the type-argument nodes of a `TSTypeReference`, normalizing across `@typescript-eslint`
+ * versions (`typeArguments` in v6+, `typeParameters` in older releases).
+ *
+ * @param node - A `TSTypeReference` node (or anything else).
+ * @returns The generic argument nodes, or null when the reference has no type arguments.
+ */
+export declare function typeReferenceTypeArguments(node: AstNode): Maybe<AstNode[]>;
+/**
+ * Resolves the callee identifier name from a `CallExpression`, looking through both bare identifier
+ * callees (`withApiDetails(...)`) and member-expression callees (`api.withApiDetails(...)`).
+ *
+ * @param callee - The `CallExpression.callee` node.
+ * @returns The callee name when resolvable; otherwise null.
+ */
+export declare function callExpressionCalleeName(callee: AstNode): Maybe<string>;
+/**
+ * Determines whether the (already-unwrapped) initializer is a call to the configured api-details factory.
+ *
+ * @param initializer - The unwrapped initializer node.
+ * @param factoryName - The expected factory identifier name.
+ * @returns True when the initializer is a `CallExpression` whose callee resolves to `factoryName`.
+ */
+export declare function isApiDetailsCall(initializer: AstNode, factoryName: string): boolean;
+/**
+ * Returns the declarator's identifier name, when present.
+ *
+ * @param declaratorId - The `VariableDeclarator.id` node.
+ * @returns The identifier name, or null when the declarator binds a destructuring pattern.
+ */
+export declare function declaratorName(declaratorId: AstNode): Maybe<string>;
+/**
+ * Returns the CRUD verb fragment that `typeName` ends with — i.e. the `<Verb>` in a
+ * `<Verb>ModelFunction` suffix for one of the configured verbs (e.g. `OnCallCreateModelFunction` →
+ * `Create`, `DemoUpdateModelFunction` → `Update`).
+ *
+ * @param typeName - The type-reference identifier name.
+ * @param verbs - The allowed verb fragments.
+ * @returns The matched verb, or null when the suffix matches no recognized CRUD verb.
+ */
+export declare function matchedCrudFunctionVerb(typeName: string, verbs: Iterable<string>): Maybe<string>;
+/**
+ * Returns true when `typeName` ends with `<Verb>ModelFunction` for one of the configured verbs.
+ *
+ * @param typeName - The type-reference identifier name.
+ * @param verbs - The allowed verb fragments.
+ * @returns True when the suffix matches a recognized CRUD verb.
+ */
+export declare function isCrudFunctionTypeName(typeName: string, verbs: Iterable<string>): boolean;
+/**
+ * Resolves the input-parameter type-argument node from a CRUD function type reference.
+ *
+ * @param typeRef - The `TSTypeReference` annotation node.
+ * @param typeName - The resolved type-reference name (selects the generic position).
+ * @returns The input type-argument node, or null when absent.
+ */
+export declare function crudFunctionInputTypeArgNode(typeRef: AstNode, typeName: string): Maybe<AstNode>;
+/**
+ * Returns true when a CRUD function declares no meaningful input — either the input generic argument
+ * is absent or it is an empty object type literal (`{}`). Such handlers need no MCP input schema, so
+ * the require-input-type rule exempts them.
+ *
+ * @param typeRef - The `TSTypeReference` annotation node.
+ * @param typeName - The resolved type-reference name.
+ * @returns True when the input generic is empty or absent.
+ */
+export declare function isEmptyOrAbsentInputGeneric(typeRef: AstNode, typeName: string): boolean;
+/**
+ * Returns true when an `ObjectExpression` has an own (non-computed) property with the given name.
+ *
+ * @param objExpr - The `ObjectExpression` node.
+ * @param propName - The property name to look for.
+ * @returns True when a matching property is present.
+ */
+export declare function objectExpressionHasProperty(objExpr: AstNode, propName: string): boolean;
+/**
+ * Returns true when an `ObjectExpression` contains a spread element (`{ ...base }`), whose contents
+ * cannot be introspected statically.
+ *
+ * @param objExpr - The `ObjectExpression` node.
+ * @returns True when any property is a spread element.
+ */
+export declare function objectExpressionHasSpread(objExpr: AstNode): boolean;
+/**
+ * Returns the character offset at which an auto-fixer should insert a new import — the start of the
+ * first existing `ImportDeclaration`, or offset 0 when the file has no imports yet.
+ *
+ * @param program - The `Program` AST node.
+ * @returns The character offset for the import-insertion point.
+ */
+export declare function findImportInsertionOffset(program: AstNode): number;
+/**
+ * Returns true when the given identifier name is already in the module's top-level scope (imported
+ * or declared). Used by the require-api-details auto-fix to avoid inserting a duplicate import.
+ *
+ * @param program - The `Program` AST node.
+ * @param name - The identifier name to check.
+ * @returns True when an existing import or declaration brings `name` into scope.
+ */
+export declare function isFactoryNameInScope(program: AstNode, name: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.12.0",
+  "version": "13.12.2",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -24,10 +24,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.12.0",
-    "@dereekb/date": "13.12.0",
-    "@dereekb/model": "13.12.0",
-    "@dereekb/rxjs": "13.12.0",
+    "@dereekb/util": "13.12.2",
+    "@dereekb/date": "13.12.2",
+    "@dereekb/model": "13.12.2",
+    "@dereekb/rxjs": "13.12.2",
     "@firebase/rules-unit-testing": "5.0.0",
     "arktype": "^2.2.0",
     "date-fns": "^4.1.0",

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.12.0",
+  "version": "13.12.2",
   "peerDependencies": {
-    "@dereekb/date": "13.12.0",
-    "@dereekb/firebase": "13.12.0",
-    "@dereekb/model": "13.12.0",
-    "@dereekb/rxjs": "13.12.0",
-    "@dereekb/util": "13.12.0",
+    "@dereekb/date": "13.12.2",
+    "@dereekb/firebase": "13.12.2",
+    "@dereekb/model": "13.12.2",
+    "@dereekb/rxjs": "13.12.2",
+    "@dereekb/util": "13.12.2",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",