@dereekb/firebase 13.11.15 → 13.11.16

package/eslint/src/lib/require-dbx-model-firebase-index-valid-dispatcher.rule.d.ts

@@ -0,0 +1,54 @@
+import { type AstNode } from './util';
+/**
+ * Options for the require-dbx-model-firebase-index-valid-dispatcher rule.
+ */
+export interface FirebaseRequireDbxModelFirebaseIndexValidDispatcherRuleOptions {
+    readonly constraintNames?: readonly string[];
+    readonly allowedImportSources?: readonly string[];
+    readonly markerTag?: string;
+    readonly dispatcherTag?: string;
+    readonly presumedTaggedSuffix?: string;
+}
+/**
+ * ESLint rule definition for require-dbx-model-firebase-index-valid-dispatcher.
+ */
+export interface FirebaseRequireDbxModelFirebaseIndexValidDispatcherRuleDefinition {
+    readonly meta: {
+        readonly type: 'problem';
+        readonly fixable: undefined;
+        readonly docs: {
+            readonly description: string;
+            readonly recommended: boolean;
+        };
+        readonly messages: Readonly<Record<string, string>>;
+        readonly schema: readonly object[];
+    };
+    create(context: {
+        options: FirebaseRequireDbxModelFirebaseIndexValidDispatcherRuleOptions[];
+        report: (descriptor: {
+            node: AstNode;
+            messageId: string;
+            data?: Record<string, string>;
+        }) => void;
+        sourceCode: AstNode;
+    }): Record<string, (node: AstNode) => void>;
+}
+/**
+ * ESLint rule enforcing that `@dbxModelFirebaseIndexDispatcher`-tagged factories delegate to
+ * other `@dbxModelFirebaseIndex`-tagged query factories instead of building constraints directly.
+ *
+ * A dispatcher must never:
+ *
+ *   1. Call a `@dereekb/firebase` constraint factory (`where`/`orderBy`/`limit`/...) directly.
+ *   2. Construct its own `FirestoreQueryConstraint[]` array via `[].push(...)`-style assembly.
+ *
+ * Permitted bodies return another tagged factory's result directly, spread several tagged
+ * factories' results into a return array, or use a conditional to pick between tagged
+ * factories — matching the dispatcher pattern documented at
+ * `packages/dbx-components-mcp/src/tools/validate-app-model-firebase-index.tool.ts`.
+ *
+ * Not auto-fixable: extracting an inline constraint into a sibling tagged factory requires
+ * choosing a name + signature + call-site replacement that is outside the safe scope of an
+ * ESLint autofix.
+ */
+export declare const FIREBASE_REQUIRE_DBX_MODEL_FIREBASE_INDEX_VALID_DISPATCHER_RULE: FirebaseRequireDbxModelFirebaseIndexValidDispatcherRuleDefinition;

package/eslint/src/lib/require-tagged-firestore-constraints.rule.d.ts

@@ -0,0 +1,46 @@
+import { type AstNode } from './util';
+/**
+ * Options for the require-tagged-firestore-constraints rule.
+ */
+export interface FirebaseRequireTaggedFirestoreConstraintsRuleOptions {
+    readonly constraintNames?: readonly string[];
+    readonly additionalConstraintNames?: readonly string[];
+    readonly allowedImportSources?: readonly string[];
+    readonly markerTag?: string;
+}
+/**
+ * ESLint rule definition for require-tagged-firestore-constraints.
+ */
+export interface FirebaseRequireTaggedFirestoreConstraintsRuleDefinition {
+    readonly meta: {
+        readonly type: 'problem';
+        readonly fixable: undefined;
+        readonly docs: {
+            readonly description: string;
+            readonly recommended: boolean;
+        };
+        readonly messages: Readonly<Record<string, string>>;
+        readonly schema: readonly object[];
+    };
+    create(context: {
+        options: FirebaseRequireTaggedFirestoreConstraintsRuleOptions[];
+        report: (descriptor: {
+            node: AstNode;
+            messageId: string;
+            data?: Record<string, string>;
+        }) => void;
+        sourceCode: AstNode;
+    }): Record<string, (node: AstNode) => void>;
+}
+/**
+ * ESLint rule that forbids inline `@dereekb/firebase` Firestore constraint factory calls
+ * (`where`, `orderBy`, `limit`, ...) outside a function whose leading JSDoc carries the
+ * `@dbxModelFirebaseIndex` marker. The dbx-components-mcp index extractor only sees
+ * constraints inside tagged factories — anything else is invisible to index generation
+ * and must be extracted into a dedicated `*Query` factory.
+ *
+ * Not auto-fixable: extracting an inline constraint into a new function requires choosing
+ * a name, signature, and call-site replacement that are outside the safe scope of an ESLint
+ * autofix.
+ */
+export declare const FIREBASE_REQUIRE_TAGGED_FIRESTORE_CONSTRAINTS_RULE: FirebaseRequireTaggedFirestoreConstraintsRuleDefinition;

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

@@ -0,0 +1,107 @@
+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";
+/**
+ * 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`).
+ */
+export declare const DBX_MODEL_FIREBASE_INDEX_MARKER = "dbxModelFirebaseIndex";
+/**
+ * The canonical suffix expected on every `@dbxModelFirebaseIndex`-tagged factory name.
+ */
+export declare const QUERY_SUFFIX = "Query";
+/**
+ * Index-affecting Firestore constraint factory identifiers exported from `@dereekb/firebase`
+ * (see `packages/firebase/src/lib/common/firestore/query/constraint.ts`). These shape the
+ * composite index Firestore needs to satisfy the query — calls to them must originate inside
+ * a `@dbxModelFirebaseIndex`-tagged function so the dbx-components-mcp index extractor can
+ * collect them.
+ *
+ * `where` and `orderBy` are the only constraint factories that influence composite indexes;
+ * pagination/cursor factories (`limit`, `limitToLast`, `whereDocumentId`, `startAt`/`After`,
+ * `endAt`/`Before`) only narrow the cursor/window of an already-indexed query and may be
+ * composed freely outside tagged factories — see {@link DEFAULT_PAGINATION_CONSTRAINT_NAMES}.
+ */
+export declare const DEFAULT_INDEX_AFFECTING_CONSTRAINT_NAMES: readonly string[];
+/**
+ * Pagination/cursor Firestore constraint factory identifiers exported from `@dereekb/firebase`.
+ * These do not influence composite indexes and may be composed externally — e.g. a generic
+ * pagination helper that appends `limit` + `startAfter` onto a caller-supplied tagged-query
+ * constraint array. The "tagged-firestore-constraints" rule does not flag calls to these by
+ * default.
+ */
+export declare const DEFAULT_PAGINATION_CONSTRAINT_NAMES: readonly string[];
+/**
+ * Combined list of every Firestore constraint factory exported from `@dereekb/firebase`. Used
+ * by the body-coherence rule to ensure a tagged factory body contains at least one constraint
+ * call of any kind (index-affecting or pagination) before warning that the marker is orphaned.
+ */
+export declare const DEFAULT_CONSTRAINT_FACTORY_NAMES: readonly string[];
+/**
+ * Loose AST node alias used by the rule implementations.
+ */
+export type AstNode = any;
+/**
+ * Per-file registry of import information used by the firebase-eslint rules.
+ *
+ * `localToImported` maps the local binding name (which may be a rename, e.g. `fbWhere` from
+ * `import { where as fbWhere }`) back to the imported name (`where`) — the rules check the
+ * imported name against the firestore-constraint allowlist.
+ */
+export interface ImportRegistry {
+    readonly bySource: Map<string, Set<string>>;
+    readonly localToSource: Map<string, string>;
+    readonly localToImported: Map<string, string>;
+}
+/**
+ * Creates an empty {@link ImportRegistry}.
+ *
+ * @returns A fresh empty registry.
+ */
+export declare function createImportRegistry(): ImportRegistry;
+/**
+ * Records an `ImportDeclaration` node in the registry.
+ *
+ * @param registry - The registry to mutate.
+ * @param node - The ImportDeclaration AST node.
+ */
+export declare function trackImportDeclaration(registry: ImportRegistry, node: AstNode): void;
+/**
+ * Returns true when the given local identifier name was imported from the given module.
+ *
+ * @param registry - The import registry built from the file's import declarations.
+ * @param localName - The local identifier (as it appears in code).
+ * @param fromSource - The expected source-module string.
+ * @returns True when the local name maps to the given source.
+ */
+export declare function isImportedFrom(registry: ImportRegistry, localName: string, fromSource: string): boolean;
+/**
+ * Returns the statement-level anchor node that ESLint attaches leading comments to for the
+ * given function-like node. For function declarations this is the declaration (or its
+ * `Export*Declaration` wrapper); for arrow/function expressions assigned to a variable, it
+ * is the variable declaration (or its `Export*Declaration` wrapper); otherwise `null`.
+ *
+ * @param node - The function-like AST node (FunctionDeclaration / FunctionExpression / ArrowFunctionExpression).
+ * @returns The anchor statement node, or null when the function has no JSDoc-anchorable container.
+ */
+export declare function getFunctionJsdocAnchor(node: AstNode): Maybe<AstNode>;
+/**
+ * Returns the function name when resolvable: `node.id.name` for declarations, or the
+ * containing `VariableDeclarator.id.name` for arrow/function expressions. Returns `null`
+ * when the function is anonymous in an unrecognized context.
+ *
+ * @param node - The function-like AST node.
+ * @returns The function name, or null when anonymous.
+ */
+export declare function getFunctionName(node: AstNode): Maybe<string>;
+/**
+ * Returns the name-bearing AST node for reporting on a function: the `id` for a
+ * declaration, the `VariableDeclarator.id` for an arrow assignment, or the function node
+ * itself as a last resort.
+ *
+ * @param node - The function-like AST node.
+ * @returns The node to attach a `context.report` location to.
+ */
+export declare function getFunctionNameNode(node: AstNode): AstNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.11.15",
+  "version": "13.11.16",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -9,6 +9,12 @@
       "import": "./test/index.cjs.mjs",
       "default": "./test/index.cjs.js"
     },
+    "./eslint": {
+      "module": "./eslint/index.esm.js",
+      "types": "./eslint/index.d.ts",
+      "import": "./eslint/index.cjs.mjs",
+      "default": "./eslint/index.cjs.js"
+    },
     "./package.json": "./package.json",
     ".": {
       "module": "./index.esm.js",
@@ -18,10 +24,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.11.15",
-    "@dereekb/date": "13.11.15",
-    "@dereekb/model": "13.11.15",
-    "@dereekb/rxjs": "13.11.15",
+    "@dereekb/util": "13.11.16",
+    "@dereekb/date": "13.11.16",
+    "@dereekb/model": "13.11.16",
+    "@dereekb/rxjs": "13.11.16",
     "@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.11.15",
+  "version": "13.11.16",
   "peerDependencies": {
-    "@dereekb/date": "13.11.15",
-    "@dereekb/firebase": "13.11.15",
-    "@dereekb/model": "13.11.15",
-    "@dereekb/rxjs": "13.11.15",
-    "@dereekb/util": "13.11.15",
+    "@dereekb/date": "13.11.16",
+    "@dereekb/firebase": "13.11.16",
+    "@dereekb/model": "13.11.16",
+    "@dereekb/rxjs": "13.11.16",
+    "@dereekb/util": "13.11.16",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",