@dereekb/firebase 13.12.1 → 13.12.3

package/eslint/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@dereekb/firebase/eslint",
-  "version": "13.12.1",
+  "version": "13.12.3",
   "peerDependencies": {
+    "@dereekb/util": "13.12.3",
+    "@marcbachmann/cel-js": "^7.6.1",
+    "@typescript-eslint/parser": "8.59.3",
     "@typescript-eslint/utils": "8.59.3"
   },
   "devDependencies": {
-    "@dereekb/util": "13.12.1",
-    "@marcbachmann/cel-js": "^7.6.1",
-    "@typescript-eslint/parser": "8.59.3",
-    "eslint": "10.4.0"
+    "@dereekb/firebase": "13.12.3",
+    "eslint": "10.4.0",
+    "firebase": "^12.12.1"
   },
   "exports": {
     "./package.json": "./package.json",

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

@@ -14,4 +14,4 @@ export { FIREBASE_REQUIRE_DBX_MODEL_COMPANION_TAGS_RULE, type FirebaseRequireDbx
 export { parseStorageRules, MIRRORS_POLICY_KEY_MARKER_REGEX, type ParsedRuleBranch, type ParsedStorageRulesBlock } from './storage-rules-parser';
 export { parseFirestoreRules, type ParsedFirestoreMatchBlock } from './firestore-rules-parser';
 export { FIREBASE_ESLINT_PLUGIN, firebaseESLintPlugin, type FirebaseEslintPlugin } from './plugin';
-export { DBX_MODEL_FIREBASE_INDEX_MARKER, DEFAULT_CONSTRAINT_FACTORY_NAMES, DEFAULT_INDEX_AFFECTING_CONSTRAINT_NAMES, DEFAULT_PAGINATION_CONSTRAINT_NAMES, FIREBASE_MODULE, QUERY_SUFFIX, DEFAULT_CRUD_FUNCTION_TYPE_VERBS, DEFAULT_API_DETAILS_FACTORY_NAME, INPUT_TYPE_PROPERTY_NAME, API_DETAILS_IMPORT_MODULE } from './util';
+export { DBX_MODEL_FIREBASE_INDEX_MARKER, DEFAULT_CONSTRAINT_FACTORY_NAMES, DEFAULT_DISCOVERY_EXCLUDED_DIRS, DEFAULT_INDEX_AFFECTING_CONSTRAINT_NAMES, DEFAULT_PAGINATION_CONSTRAINT_NAMES, FIREBASE_MODULE, QUERY_SUFFIX, DEFAULT_CRUD_FUNCTION_TYPE_VERBS, DEFAULT_API_DETAILS_FACTORY_NAME, INPUT_TYPE_PROPERTY_NAME, API_DETAILS_IMPORT_MODULE, discoveryGlobExcludeFilter } from './util';

package/eslint/src/lib/require-firestore-rule-for-service-model.rule.d.ts

@@ -1,4 +1,4 @@
-import type { AstNode } from './util';
+import { type AstNode } from './util';
 /**
  * Default file name searched relative to the lint root when `firestoreRulesPath` is omitted.
  */

package/eslint/src/lib/require-service-factory-for-dbx-model.rule.d.ts

@@ -1,8 +1,14 @@
-import type { AstNode } from './util';
+import { type AstNode } from './util';
 /**
- * Default glob patterns (relative to ESLint `cwd`) used to locate model + factory source files.
- * Mirrors {@link require-firestore-rule-for-service-model}'s search roots so the orphan rule
- * picks up factories declared anywhere a model interface might also live.
+ * Default glob pattern (relative to ESLint `cwd`) used to locate `@dbxModelServiceFactory` source
+ * files. A single layout-agnostic `**\/*.ts` scan finds a consumer's own factory declarations no
+ * matter where they live, rather than assuming the dbx-components monorepo layout
+ * (`components/*\/src/lib/model`, `apps/*\/src/app`) — which a downstream consumer of
+ * `@dereekb/firebase` does not share. The walk prunes `node_modules`/build dirs
+ * (see {@link discoveryGlobExcludeFilter}) and the cheap `text.includes('@'+factoryTag)` pre-filter
+ * in {@link collectFactoryModelTypesFromFile} keeps it from parsing files that carry no tag, so the
+ * broad glob stays fast even in a large consumer repo. In-repo this is a superset of the former
+ * monorepo-specific roots, so the demo app's framework + local factories still resolve.
  */
 export declare const DEFAULT_FACTORY_SEARCH_ROOTS: readonly string[];
 /**

package/eslint/src/lib/require-storagefile-policy-matches-rules.rule.d.ts

@@ -1,4 +1,6 @@
+import type { Maybe } from '@dereekb/util';
 import { type AstNode } from './util';
+import { type ParserServicesLike } from './storagefile-import-resolver';
 /**
  * Default type name the rule looks for on top-level declarators. Variables whose type
  * annotation resolves to this identifier are treated as upload policies and validated
@@ -27,6 +29,12 @@ export interface FirebaseRequireStorageFilePolicyMatchesRulesRuleOptions {
      * {@link DEFAULT_STORAGE_FILE_UPLOAD_POLICY_TYPE_NAME}.
      */
     readonly policyTypeName?: string;
+    /**
+     * Policies whose `buildUploadPath` is legitimately dynamic (e.g. injects a runtime timestamp)
+     * and cannot be statically folded. Each entry matches a policy's `purpose` key or its
+     * declarator name; matching policies are skipped instead of reporting `unresolvablePolicyPath`.
+     */
+    readonly allowUnresolvablePolicies?: readonly string[];
 }
 /**
  * ESLint rule definition for require-storagefile-policy-matches-rules.
@@ -47,6 +55,10 @@ export interface FirebaseRequireStorageFilePolicyMatchesRulesRuleDefinition {
 interface RuleContext {
     readonly options: FirebaseRequireStorageFilePolicyMatchesRulesRuleOptions[];
     readonly cwd?: string;
+    readonly sourceCode?: {
+        readonly parserServices?: Maybe<ParserServicesLike>;
+    };
+    readonly parserServices?: Maybe<ParserServicesLike>;
     readonly report: (descriptor: {
         node: AstNode;
         messageId: string;
@@ -55,17 +67,25 @@ interface RuleContext {
 }
 /**
  * ESLint rule that cross-checks every `StorageFilePurposeUploadPolicy`-typed declaration in
- * a `*-firebase` component against the workspace's `storage.rules`. Each policy must have a
- * paired `// Mirrors STORAGE_FILE_PURPOSE_UPLOAD_POLICIES[<KEY>]` match block whose
- * `request.resource.size` cap and `request.resource.contentType` predicate are at least as
- * permissive as the TypeScript policy's `maxFileSizeBytes` and `allowedMimeTypes`.
+ * a `*-firebase` component against the workspace's `storage.rules`. The policy's
+ * `buildUploadPath` builder is statically folded to a concrete path template (an ordered list
+ * of literal / wildcard segments) and paired with the `storage.rules` `allow write` match
+ * block at the same path. On the paired block the `request.resource.size` cap and
+ * `request.resource.contentType` predicate must be at least as permissive as the policy's
+ * `maxFileSizeBytes` and `allowedMimeTypes`.
+ *
+ * Pairing is derived from the resolved path — not a marker comment — so the linker proves the
+ * policy's actual upload path lands in the rules block rather than trusting an unchecked
+ * assertion. When the builder cannot be folded (unknown const, unmodeled call, runtime value)
+ * the rule reports `unresolvablePolicyPath` and never guesses; genuinely dynamic builders opt
+ * out via `allowUnresolvablePolicies`.
  *
  * Reports on the TS side so drift surfaces in the normal lint pipeline; mismatches almost
  * always originate from editing one side and forgetting the other.
  *
  * @example
  * ```ts
- * // OK — storage.rules has `Mirrors ...[USER_AVATAR_PURPOSE]` block with matching constraints
+ * // OK — storage.rules has `match /uploads/u/{uid}/avatar.img` with matching constraints
  * export const USER_AVATAR_UPLOAD_POLICY: StorageFilePurposeUploadPolicy = {
  *   purpose: USER_AVATAR_PURPOSE,
  *   allowedMimeTypes: ['image/jpeg', 'image/png'],

package/eslint/src/lib/storage-rules-parser.d.ts

@@ -1,4 +1,6 @@
+import type { Maybe } from '@dereekb/util';
 import { type PredicateBranch } from './predicate-evaluator';
+import type { FoldedPathSegment } from './storagefile-path-fold';
 /**
  * Marker comment that pairs a `storage.rules` match block with a TypeScript policy key
  * in `STORAGE_FILE_PURPOSE_UPLOAD_POLICIES`. The capture group is the policy key constant
@@ -14,13 +16,15 @@ export declare const MIRRORS_POLICY_KEY_MARKER_REGEX: RegExp;
  */
 export type ParsedRuleBranch = PredicateBranch;
 /**
- * One `match /<path>` block in `storage.rules` paired with a `// Mirrors ...` marker.
- * `branches` carries the disjunction of (size, MIME) tuples extracted from the block's
- * `allow write` predicate; `unsupported` is set when the parser cannot reduce the
- * predicate to >=1 valid branch.
+ * One leaf `match /<path>` block in `storage.rules` that carries an `allow write|create|update`
+ * predicate. `branches` carries the disjunction of (size, MIME) tuples extracted from the
+ * predicate; `unsupported` is set when the parser cannot reduce the predicate to >=1 valid
+ * branch. `matchPath` is the full accumulated path stack used to pair the block with a folded
+ * upload-policy path. `mirrorsPolicyKey` is the legacy `// Mirrors ...` marker key when present
+ * — purely informational now that pairing is by path, retained for backward compatibility.
  */
 export interface ParsedStorageRulesBlock {
-    readonly mirrorsPolicyKey: string;
+    readonly mirrorsPolicyKey?: Maybe<string>;
     readonly matchPath: string;
     readonly branches: readonly ParsedRuleBranch[];
     readonly sourceLine: number;
@@ -28,11 +32,23 @@ export interface ParsedStorageRulesBlock {
     readonly unsupported?: string;
 }
 /**
- * Parses a `storage.rules` source string and returns every match block paired with a
- * `// Mirrors STORAGE_FILE_PURPOSE_UPLOAD_POLICIES[<KEY>]` marker. Catch-all deny blocks
- * are skipped; the rest of the tree is walked normally.
+ * Converts a parsed leaf block's `matchPath` (e.g. `/uploads/u/{uid}/jr/{shortKey}`) into a
+ * structural segment list for comparison against a folded upload-policy path. Empty segments
+ * (leading/trailing/duplicate slashes) are dropped; `{var}` / `{var=**}` path variables become
+ * wildcards; every other segment is a literal.
+ *
+ * @param matchPath - The accumulated match-path string.
+ * @returns The structural segment list.
+ */
+export declare function rulesMatchPathToSegments(matchPath: string): FoldedPathSegment[];
+/**
+ * Parses a `storage.rules` source string and returns every leaf `match` block that carries an
+ * `allow write|create|update` predicate, each with its full accumulated `matchPath`. Catch-all
+ * deny blocks are skipped; the rest of the tree is walked normally. Pairing with TypeScript
+ * upload policies is by path (see {@link rulesMatchPathToSegments}); the `// Mirrors ...` marker
+ * is no longer required.
  *
  * @param source - The raw rules source text.
- * @returns Parsed mirrored blocks in source order.
+ * @returns Parsed leaf blocks in source order.
  */
 export declare function parseStorageRules(source: string): ParsedStorageRulesBlock[];

package/eslint/src/lib/storagefile-import-resolver.d.ts

@@ -0,0 +1,33 @@
+import type { Maybe } from '@dereekb/util';
+import { type AstNode } from './util';
+import { type ImportedBindingResolver } from './storagefile-path-fold';
+/**
+ * The slice of `@typescript-eslint` parser services the cross-module resolver needs: the TS
+ * `Program` and the ESTree→TS node map. Typed loosely so the resolver stays decoupled from a
+ * specific `@typescript-eslint` version.
+ */
+export interface ParserServicesLike {
+    readonly program?: {
+        getTypeChecker(): unknown;
+    };
+    readonly esTreeNodeToTSNodeMap?: {
+        get(node: AstNode): unknown;
+    };
+}
+/**
+ * Builds an {@link ImportedBindingResolver} backed by the TypeScript type checker, or null when
+ * type information is unavailable (e.g. a lint config without `parserOptions.project`, or a
+ * pure-AST test harness). The resolver performs a single hop: it maps an imported identifier in
+ * the linted file to the declaration's source file, re-parses that file to ESTree (cached), and
+ * returns the named binding plus that module's scope. Identifiers local to the resolved module
+ * fold via the re-parsed program directly; transitive re-imports from a third module are not
+ * followed.
+ *
+ * Every failure mode (no symbol, unreadable file, parse error, identifier from an already
+ * re-parsed module) returns null so the analyzer falls back to reporting an unresolvable path —
+ * it never throws into the lint pass.
+ *
+ * @param services - The parser services, when present.
+ * @returns A resolver, or null when type information is unavailable.
+ */
+export declare function createImportedBindingResolver(services: Maybe<ParserServicesLike>): Maybe<ImportedBindingResolver>;

package/eslint/src/lib/storagefile-path-fold.d.ts

@@ -0,0 +1,121 @@
+import type { Maybe } from '@dereekb/util';
+import { type AstNode, type ImportRegistry } from './util';
+/**
+ * One segment of a folded upload path. A `literal` segment carries its fixed text (e.g.
+ * `uploads`, `jr`, `photo.img`); a `wildcard` segment stands in for any single path segment
+ * (a destructured param, a positional argument, a `mergeSlashPaths` variadic element) and
+ * compares equal to a Firebase rules `{var}` / `{var=**}` path variable.
+ */
+export interface FoldedPathSegment {
+    readonly kind: 'literal' | 'wildcard';
+    readonly value: string;
+}
+/**
+ * The result of statically folding a `buildUploadPath` builder: an ordered list of
+ * {@link FoldedPathSegment}s with leading/trailing/duplicate `/` collapsed.
+ */
+export interface FoldedUploadPath {
+    readonly segments: readonly FoldedPathSegment[];
+}
+/**
+ * Outcome of {@link foldUploadPath}: either a folded path or a human-readable reason the
+ * builder could not be reduced to a constant path template. The rule reports the reason via
+ * the `unresolvablePolicyPath` diagnostic so authors either make the builder foldable or opt
+ * out explicitly — the analyzer never guesses.
+ */
+export type FoldUploadPathResult = {
+    readonly ok: true;
+    readonly path: FoldedUploadPath;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Resolves an imported binding (const declarator or function/arrow declaration) to its
+ * declaration node in another module, plus the scope that node lives in so further
+ * identifiers inside it resolve against that module's own imports/consts.
+ *
+ * Supplied by the rule when type information is available; absent in pure-AST contexts
+ * (e.g. the unit tests), in which case cross-module references fold to "unresolvable".
+ */
+export interface ImportedBindingResolver {
+    resolve(name: string, referenceNode: AstNode, fromScope: FoldScope): Maybe<ResolvedBinding>;
+}
+/**
+ * A binding resolved to its declaration node plus the scope it belongs to.
+ */
+export interface ResolvedBinding {
+    readonly node: AstNode;
+    readonly scope: FoldScope;
+}
+/**
+ * The lexical scope a node is folded in: the Program it belongs to and the import registry
+ * for that module. Threaded through folding so an inlined cross-module function resolves its
+ * own identifiers against its own module.
+ */
+export interface FoldScope {
+    readonly program: AstNode;
+    readonly importRegistry: ImportRegistry;
+    readonly resolver: Maybe<ImportedBindingResolver>;
+}
+/**
+ * Statically folds a `StorageFilePurposeUploadPolicy.buildUploadPath` builder to an abstract
+ * path template. The builder is an arrow `(input) => <path expression>` whose destructured /
+ * positional params become wildcards and whose body is a composition of string literals,
+ * `const`s, `@dereekb/util` path combinators, and foldable single-`return` helper functions.
+ *
+ * @param builderNode - The `buildUploadPath` value node (arrow / function expression, possibly behind a type assertion).
+ * @param scope - The lexical scope the builder lives in.
+ * @returns The folded path, or a reason the builder is unresolvable.
+ */
+export declare function foldUploadPath(builderNode: AstNode, scope: FoldScope): FoldUploadPathResult;
+/**
+ * Folds an expression to a concrete string literal value, reusing the same fragment folder the
+ * path evaluator uses (literals, template literals, `const`s — local + cross-module — `+`
+ * concatenation, modeled combinators, inlinable helpers). Returns null when the expression cannot
+ * be reduced to a wildcard-free constant string, so callers preserve the sound "never guess"
+ * contract.
+ *
+ * @param node - The expression node.
+ * @param scope - The lexical scope the expression lives in.
+ * @returns The folded string, or null when unresolvable.
+ */
+export declare function foldStringExpression(node: AstNode, scope: FoldScope): Maybe<string>;
+/**
+ * Folds an expression to a list of concrete strings: an inline array literal (each element folded
+ * via {@link foldStringExpression}, spreads of statically-known lists expanded), or an identifier
+ * resolving to such an array const (local or cross-module). Returns null when any element is
+ * unfoldable, so a genuinely dynamic element (e.g. a function call) still surfaces as unresolvable.
+ *
+ * @param node - The expression node (e.g. an `allowedMimeTypes` value).
+ * @param scope - The lexical scope the expression lives in.
+ * @returns The folded string list, or null when unresolvable.
+ */
+export declare function foldStringArrayExpression(node: AstNode, scope: FoldScope): Maybe<readonly string[]>;
+/**
+ * Folds a numeric expression to a number: literals, unary `-`/`+`, binary `*`/`+`/`-`/`/`,
+ * type-assertion see-through, and identifiers resolving to a numeric `const` (local or
+ * cross-module, read from the AST initializer). Returns null when any operand is unresolvable.
+ *
+ * @param node - The expression node (e.g. a `maxFileSizeBytes` value).
+ * @param scope - The lexical scope the expression lives in.
+ * @returns The folded number, or null when unresolvable.
+ */
+export declare function foldNumericExpression(node: AstNode, scope: FoldScope): Maybe<number>;
+/**
+ * Structurally compares a folded upload path against a Firebase rules match-path segment list
+ * (`{var}` / `{var=**}` → wildcard, otherwise literal). Literal segments must match value;
+ * wildcard segments compare equal to one another.
+ *
+ * @param folded - The folded upload path.
+ * @param ruleSegments - The rules match-path segments.
+ * @returns True when the two segment lists match position-for-position.
+ */
+export declare function foldedPathMatchesRuleSegments(folded: FoldedUploadPath, ruleSegments: readonly FoldedPathSegment[]): boolean;
+/**
+ * Renders a folded path for diagnostics, e.g. `uploads/u/{*}/jr/{*}`.
+ *
+ * @param folded - The folded path.
+ * @returns The display string.
+ */
+export declare function describeFoldedPath(folded: FoldedUploadPath): string;

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`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.12.1",
+  "version": "13.12.3",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -24,11 +24,13 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.12.1",
-    "@dereekb/date": "13.12.1",
-    "@dereekb/model": "13.12.1",
-    "@dereekb/rxjs": "13.12.1",
+    "@dereekb/date": "13.12.3",
+    "@dereekb/model": "13.12.3",
+    "@dereekb/rxjs": "13.12.3",
+    "@dereekb/util": "13.12.3",
     "@firebase/rules-unit-testing": "5.0.0",
+    "@marcbachmann/cel-js": "^7.6.1",
+    "@typescript-eslint/parser": "8.59.3",
     "arktype": "^2.2.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",
@@ -36,6 +38,9 @@
     "rxjs": "^7.8.2",
     "ts-essentials": "^10.2.0"
   },
+  "devDependencies": {
+    "eslint": "10.4.0"
+  },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
   "types": "./index.d.ts"

package/test/package.json

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