@dereekb/dbx-cli 13.11.17 → 13.12.0

package/src/lib/mcp-scan/scan/discover-firebase-packages.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Discovery for downstream `-firebase` component packages.
+ *
+ * `dbx_model_search` and `dbx_model_lookup` extend their reach beyond the
+ * upstream `@dereekb/firebase` registry by globbing the caller's workspace
+ * for `components/<name>-firebase` packages on first use, then handing each
+ * match's `src/lib/model/` directory to the runtime ts-morph extractor.
+ *
+ * The result is intentionally narrow: just the package name plus the model
+ * root that the extractor needs. Errors during package-json reads degrade
+ * to the directory basename so a malformed package never breaks discovery.
+ */
+/**
+ * One downstream `-firebase` component package discovered under the caller's
+ * workspace root. Both paths are workspace-relative and use forward slashes
+ * regardless of platform — the extractor and the formatter render them as-is.
+ */
+export interface DownstreamFirebasePackage {
+    /**
+     * Canonical package name from `package.json` (e.g. `'demo-firebase'`).
+     * Falls back to the directory basename when no `package.json` exists or
+     * the file is unreadable.
+     */
+    readonly packageName: string;
+    /**
+     * Workspace-relative path to the component package root
+     * (e.g. `'components/demo-firebase'`).
+     */
+    readonly componentDir: string;
+    /**
+     * Workspace-relative path to the model root, i.e.
+     * `<componentDir>/src/lib/model` (forward-slash form).
+     */
+    readonly modelDir: string;
+}
+/**
+ * Globs `components/*-firebase/` under `workspaceRoot` and returns every
+ * directory whose `src/lib/model/` exists.
+ *
+ * Other layouts (`apps/*-firebase`, `libs/*-firebase`, `packages/*-firebase`)
+ * are deliberately not scanned — `dbx_model_search` / `dbx_model_lookup`
+ * accept an explicit `componentDirs` override for non-standard layouts.
+ *
+ * @param workspaceRoot - Absolute path to the caller's workspace root.
+ * @returns The discovered packages sorted by `packageName`
+ */
+export declare function discoverDownstreamFirebasePackages(workspaceRoot: string): Promise<readonly DownstreamFirebasePackage[]>;
+/**
+ * Resolves an explicit `componentDirs` override against the workspace root.
+ * Each entry is checked for a `src/lib/model/` directory; entries that
+ * don't have one are dropped. Mirrors the post-glob filtering in
+ * {@link discoverDownstreamFirebasePackages}.
+ *
+ * @param workspaceRoot - Absolute path to the caller's workspace root.
+ * @param componentDirs - Workspace-relative directories to inspect.
+ * @returns The resolved packages (may be shorter than `componentDirs`)
+ */
+export declare function resolveExplicitFirebasePackages(workspaceRoot: string, componentDirs: readonly string[]): Promise<readonly DownstreamFirebasePackage[]>;

package/src/lib/mcp-scan/scan/extract-models/assemble.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Per-file model assembly. Combines the per-file outputs of
+ * {@link findIdentities}, {@link findInterfaces}, {@link findConverters},
+ * {@link findEnums}, {@link findModelGroups}, and
+ * {@link findCollectionFactoryCalls} into the {@link FirebaseModel} +
+ * {@link FirebaseModelGroup} entries the registry exposes.
+ *
+ * Mirrors the per-file body of `extractFromFile` in
+ * `scripts/extract-firebase-models.mjs`.
+ */
+import type { FirebaseModel, FirebaseModelGroup, FirebaseSubObject, FirestoreCollectionKind } from '../../registry/firebase-models.js';
+import type { ExtractedConverter, ExtractedEnum, ExtractedIdentity, ExtractedInterface, ExtractedModelGroup } from './types.js';
+/**
+ * Field names that show up on many models and shouldn't seed
+ * {@link FirebaseModel.detectionHints}. Matches the `.mjs`
+ * extractor's `COMMON_FIELDS` set.
+ */
+export declare const COMMON_FIELDS: ReadonlySet<string>;
+/**
+ * Marker-interface name for documents whose Firestore id IS the user's
+ * Firebase Auth uid (sourced from `@dereekb/firebase` `user.ts`).
+ */
+export declare const USER_KEYED_BY_ID_MARKER = "UserRelatedById";
+/**
+ * Marker-interface name for documents that carry an explicit `uid` field
+ * referencing a Firebase Auth user (sourced from `@dereekb/firebase`
+ * `user.ts`; alias of `FirebaseAuthUserIdRef`).
+ */
+export declare const USER_RELATED_MARKER = "UserRelated";
+/**
+ * Marker-interface name for documents whose Firestore id IS a region key.
+ * Mirrors `REGION_KEYED_BY_ID_MARKER` in the `.mjs` extractor.
+ */
+export declare const REGION_KEYED_BY_ID_MARKER = "RegionRelatedById";
+/**
+ * Marker-interface name for documents whose Firestore id IS a district key.
+ * Mirrors `DISTRICT_KEYED_BY_ID_MARKER` in the `.mjs` extractor.
+ */
+export declare const DISTRICT_KEYED_BY_ID_MARKER = "DistrictRelatedById";
+/**
+ * Marker-interface name for documents whose Firestore id IS an external
+ * vendor's id, regardless of which vendor. Models extend
+ * `ExternalRelatedById<TId>` from `@dereekb/firebase`.
+ */
+export declare const EXTERNAL_ID_KEYED_BY_ID_MARKER = "ExternalRelatedById";
+/**
+ * Marker-interface name suffixes for documents keyed by a temporal bucket
+ * code (year-week, year-month, …). Matched as suffixes so per-bucket markers
+ * like `YearWeekRelatedById` and `WeekRelatedById` are picked up.
+ */
+export declare const BUCKET_KEYED_BY_ID_SUFFIXES: readonly string[];
+/**
+ * Result of assembling one source file's models + groups.
+ */
+export interface AssembledFile {
+    readonly models: readonly FirebaseModel[];
+    readonly modelGroups: readonly FirebaseModelGroup[];
+}
+/**
+ * Configuration for assembling one source file.
+ */
+export interface AssembleFileInput {
+    readonly sourcePackage: string;
+    readonly sourceFile: string;
+    readonly identities: readonly ExtractedIdentity[];
+    readonly interfaces: readonly ExtractedInterface[];
+    readonly converters: readonly ExtractedConverter[];
+    readonly enums: readonly ExtractedEnum[];
+    readonly modelGroups: readonly ExtractedModelGroup[];
+    readonly factoryKinds: ReadonlyMap<string, FirestoreCollectionKind>;
+    /**
+     * Cross-file sub-object index built by the extractor's pre-pass. Maps
+     * a sub-object factory const name (e.g. `workerPayStubItem`) to the
+     * record describing the underlying interface plus its factory shape.
+     * When omitted (e.g. legacy callers, tests that don't exercise
+     * sub-objects), the assembler skips field-level sub-object resolution.
+     */
+    readonly subObjectConstIndex?: ReadonlyMap<string, SubObjectConstEntry>;
+    /**
+     * Cross-file map of `@dbxModelSubObject`-tagged interface declarations
+     * keyed by interface name. Used together with {@link subObjectConstIndex}
+     * to recursively render nested sub-objects in the catalog.
+     */
+    readonly subObjectInterfaceIndex?: ReadonlyMap<string, ExtractedInterface>;
+}
+/**
+ * One entry in the cross-file sub-object const index. The
+ * {@link interfaceName} resolves to a tagged
+ * `@dbxModelSubObject` declaration in
+ * {@link AssembleFileInput.subObjectInterfaceIndex}; the
+ * {@link factoryKind} drives the catalog's section label
+ * (`object` / `array` / `map`).
+ */
+export interface SubObjectConstEntry {
+    readonly interfaceName: string;
+    readonly factoryKind: FirebaseSubObject['factoryKind'];
+}
+/**
+ * Combines the per-file extraction outputs into ready-to-publish
+ * {@link FirebaseModel} / {@link FirebaseModelGroup} entries.
+ *
+ * @param input - The per-file extraction outputs.
+ * @returns The assembled models and groups for the file.
+ */
+export declare function assembleFile(input: AssembleFileInput): AssembledFile;

package/src/lib/mcp-scan/scan/extract-models/collect-inherited.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Walks an interface's `extends` chain through a same-file lookup map and
+ * merges every ancestor's properties into a single name → prop record.
+ * Closer ancestors override more distant ones, matching the `.mjs`
+ * extractor's `collectInheritedProps`.
+ *
+ * Cross-file inheritance is intentionally ignored — the registry only
+ * follows the chain inside the model's own file. Model interfaces in this
+ * codebase consistently keep their inheritance local, so this matches the
+ * existing behaviour.
+ */
+import type { ExtractedInterface, ExtractedInterfaceProp } from './types.js';
+/**
+ * Returns a map of property-name → prop merged across the supplied
+ * interface and every ancestor reachable via `extendsNames`. Walk order
+ * is parents-first so the supplied interface's own props win on conflict.
+ *
+ * @param iface - The interface to start from.
+ * @param interfaceByName - Lookup map of every interface in the same file.
+ * @returns The merged property map.
+ */
+export declare function collectInheritedProps(iface: ExtractedInterface, interfaceByName: ReadonlyMap<string, ExtractedInterface>): ReadonlyMap<string, ExtractedInterfaceProp>;

package/src/lib/mcp-scan/scan/extract-models/find-converters.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Finds `export const <x>Converter = snapshotConverterFunctions<<X>>({ fields: { ... } })`
+ * declarations and reads the canonical persisted-field list straight off the AST.
+ *
+ * Mirrors `findConverters` + `parseFieldsBody` in the `.mjs` extractor; the
+ * AST replaces the manual brace/string state machine with ts-morph
+ * `getProperties()` walks.
+ */
+import { type SourceFile } from 'ts-morph';
+import type { ExtractedConverter } from './types.js';
+/**
+ * Walks every exported variable declaration in the source file and returns
+ * the converter consts whose initializer is a `snapshotConverterFunctions`
+ * call.
+ *
+ * @param sf - The parsed source file to inspect.
+ * @returns One entry per detected converter.
+ */
+export declare function findConverters(sf: SourceFile): readonly ExtractedConverter[];

package/src/lib/mcp-scan/scan/extract-models/find-enums.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Walks every exported `enum` in a ts-morph source file and captures the
+ * member name, persisted value, and JSDoc description. Mirrors the `.mjs`
+ * `findEnums` + `parseEnumBody` pair via the AST.
+ *
+ * Numeric enums auto-increment when no explicit value is supplied, matching
+ * TypeScript's runtime behaviour and the upstream extractor's expectations.
+ */
+import { type SourceFile } from 'ts-morph';
+import type { ExtractedEnum } from './types.js';
+/**
+ * Returns every exported enum declared in the source file along with its
+ * members. Enum members without an explicit initializer auto-increment
+ * starting from 0 (or from the previous explicit numeric value + 1).
+ *
+ * @param sf - The parsed source file to inspect.
+ * @returns The enums in source order.
+ */
+export declare function findEnums(sf: SourceFile): readonly ExtractedEnum[];

package/src/lib/mcp-scan/scan/extract-models/find-identities.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Locates `export const <X>Identity = firestoreModelIdentity(...)` declarations
+ * in a ts-morph source file. Mirrors the regex-based extractor in
+ * `scripts/extract-firebase-models.mjs` (`findIdentities`) but operates on
+ * the AST so generic call shapes round-trip cleanly.
+ */
+import { type SourceFile } from 'ts-morph';
+import type { ExtractedIdentity } from './types.js';
+/**
+ * Walks every `export const` declaration in the source file and pulls the
+ * model-type / prefix / parent-identity arguments out of any
+ * `firestoreModelIdentity(...)` call.
+ *
+ * Mirrors the `.mjs` 1/2/3-arg branching:
+ *
+ *   • `firestoreModelIdentity('user')` → `modelType: 'user'`
+ *   • `firestoreModelIdentity('storageFile', 'sf')` → `modelType: 'storageFile'`, `prefix: 'sf'`
+ *   • `firestoreModelIdentity(notificationBoxIdentity, 'notification')` → `parent: 'notificationBoxIdentity'`, `modelType: 'notification'`
+ *   • `firestoreModelIdentity(guestbookIdentity, 'guestbookEntry', 'gbe')` → all three
+ *
+ * @param sf - The parsed source file to inspect.
+ * @returns The identity declarations in source order; entries with an
+ *   unrecognisable shape are skipped.
+ */
+export declare function findIdentities(sf: SourceFile): readonly ExtractedIdentity[];

package/src/lib/mcp-scan/scan/extract-models/find-interfaces.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Walks every `export interface` declaration in a ts-morph source file and
+ * captures the JSDoc tag flags (`@dbxModel`), `extends` references, and
+ * per-property metadata (TS type, optionality, JSDoc description, and the
+ * `@dbxModelVariable` long-name tag).
+ *
+ * Mirrors the regex-based extractor's `findInterfaces` + `parseInterfaceBody`
+ * pair from `scripts/extract-firebase-models.mjs`, but the AST drops the
+ * cumbersome property-by-property regex.
+ */
+import { type JSDoc, type SourceFile } from 'ts-morph';
+import type { ExtractedInterface } from './types.js';
+/**
+ * Returns every exported interface in the source file with the metadata the
+ * model assembler needs. Non-exported interfaces are skipped because the
+ * upstream registry only considers exported model interfaces (matching the
+ * `.mjs` extractor's `export interface` regex).
+ *
+ * @param sf - The parsed source file to inspect.
+ * @returns The interfaces in source order.
+ */
+export declare function findInterfaces(sf: SourceFile): readonly ExtractedInterface[];
+/**
+ * Returns the first non-empty paragraph of the leading JSDoc description.
+ * Mirrors the `.mjs` `parseJsdocBlock` that splits on the first blank line
+ * before the first `@`-tag.
+ *
+ * @param jsDocs - The JSDoc blocks attached to a declaration.
+ * @returns The description paragraph, or `undefined` when none exists.
+ */
+export declare function readDescription(jsDocs: readonly JSDoc[]): string | undefined;

package/src/lib/mcp-scan/scan/extract-models/find-model-groups.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Locates `<X>FirestoreCollections` containers tagged with `@dbxModelGroup`
+ * (either `export abstract class <X>FirestoreCollections` or
+ * `export interface <X>FirestoreCollections`) and lifts the group's name
+ * plus the model classes its body references.
+ *
+ * Mirrors `findModelGroups` + `extractGroupModelNames` in
+ * `scripts/extract-firebase-models.mjs`.
+ */
+import { type SourceFile } from 'ts-morph';
+import type { ExtractedModelGroup } from './types.js';
+/**
+ * Returns every `<X>FirestoreCollections` container in the source file
+ * tagged with `@dbxModelGroup`. The group name comes from the explicit
+ * tag argument; bare `@dbxModelGroup` markers fall back to the container
+ * name with the `FirestoreCollections` suffix stripped.
+ *
+ * @param sf - The parsed source file to inspect.
+ * @returns The model-group containers in source order.
+ */
+export declare function findModelGroups(sf: SourceFile): readonly ExtractedModelGroup[];

package/src/lib/mcp-scan/scan/extract-models/find-service-factories.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Walks every `@dbxModelServiceFactory <modelType>`-tagged variable export in a ts-morph
+ * source file and returns one {@link ExtractedServiceFactory} per tagged binding.
+ *
+ * The model extractor calls this once per parsed source file; the extractor's post-pass joins
+ * the resulting entries onto each {@link FirebaseModel} by `modelType`.
+ */
+import type { SourceFile } from 'ts-morph';
+import type { ExtractedServiceFactory } from './types.js';
+/**
+ * Collects every `@dbxModelServiceFactory <modelType>` tagged variable export from a source
+ * file. Each tagged statement yields one entry per declarator (mirroring the underlying
+ * `collectTaggedVariables` shape). Invalid or missing values are silently dropped — the
+ * ESLint rule is the user-facing gate.
+ *
+ * @param sf - The parsed source file to inspect.
+ * @returns The tagged factories in source order.
+ */
+export declare function findServiceFactories(sf: SourceFile): readonly ExtractedServiceFactory[];

package/src/lib/mcp-scan/scan/extract-models/find-sub-object-consts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Walks every `export const <name> = firestoreSubObject<T>(...)` /
+ * `firestoreObjectArray<T>(...)` / `firestoreMap<T>(...)` declaration and
+ * records the const-name → type-arg-interface mapping the rich catalog
+ * uses to resolve sub-object converters back to their underlying
+ * interface.
+ */
+import { type SourceFile } from 'ts-morph';
+import type { ExtractedSubObjectConst } from './types.js';
+/**
+ * Returns one entry per detected `firestoreSubObject<T>` /
+ * `firestoreObjectArray<T>` / `firestoreMap<T>` declaration whose first
+ * generic type-argument is a bare type-reference identifier. Inline
+ * object types and generic parameters are skipped because they never
+ * resolve to a declared interface.
+ *
+ * @param sf - The parsed source file to inspect.
+ * @returns One entry per detected sub-object factory const, in source order.
+ */
+export declare function findSubObjectConsts(sf: SourceFile): readonly ExtractedSubObjectConst[];

package/src/lib/mcp-scan/scan/extract-models/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Public entry point for the rich Firebase-model ts-morph extractor.
+ *
+ * Walks every `.ts` file under `rootDir` (skipping `*.spec.ts`, `*.test.ts`,
+ * and `*.id.ts` as the build-time `.mjs` extractor does), parses each into an
+ * in-memory ts-morph project, and assembles {@link FirebaseModel} +
+ * {@link FirebaseModelGroup} entries with full parity to the upstream
+ * `scripts/extract-firebase-models.mjs`.
+ *
+ * Used by:
+ *   - the runtime downstream-models cache to scan
+ *     `components/<x>-firebase` packages on first use
+ *   - `dbx_model_list_component`'s thin extractor (after refactor)
+ *
+ * The build-time `.mjs` script remains the canonical source for the
+ * upstream `firebase-models.generated.{json,ts}` catalog. A parity spec
+ * keeps the two implementations in lock-step on the upstream model corpus.
+ */
+import type { FirebaseModel, FirebaseModelGroup } from '../../registry/firebase-models.js';
+/**
+ * Outcome of one model-root scan. The `errors` array carries per-file
+ * failures so an individual malformed file never blocks the rest.
+ */
+export interface ExtractModelsResult {
+    readonly models: readonly FirebaseModel[];
+    readonly modelGroups: readonly FirebaseModelGroup[];
+    readonly errors: readonly {
+        readonly sourceFile: string;
+        readonly message: string;
+    }[];
+}
+/**
+ * Configuration for {@link extractModels}.
+ */
+export interface ExtractModelsInput {
+    /**
+     * Absolute path to the model-root directory. Typically
+     * `<componentRoot>/src/lib/model` for downstream packages, or
+     * `packages/firebase/src/lib/model` for the upstream catalog.
+     */
+    readonly rootDir: string;
+    /**
+     * The `sourcePackage` value to stamp on every produced entry
+     * (e.g. `'@dereekb/firebase'` or `'demo-firebase'`).
+     */
+    readonly sourcePackage: string;
+    /**
+     * Workspace root used to compute the workspace-relative `sourceFile`
+     * field on each entry. When omitted, the path is computed relative to
+     * `rootDir`'s parent (rare — only useful for ad-hoc tests).
+     */
+    readonly workspaceRoot?: string;
+    /**
+     * Reserved top-level folder names to skip during the walk
+     * (e.g. `system`, `notification`, `storagefile`). Files inside reserved
+     * folders are excluded from the scan.
+     *
+     * Provide the {@link RESERVED_MODEL_FOLDERS} set when scanning a
+     * downstream package that extends shared groups via dedicated
+     * validators; pass an empty array (or omit) when scanning the upstream
+     * `@dereekb/firebase` source where the same folders host the canonical
+     * group implementations.
+     */
+    readonly skipReservedFolders?: readonly string[];
+}
+/**
+ * Scans the supplied model root and returns every detected model and
+ * model-group entry. Per-file errors are aggregated rather than thrown so
+ * a single malformed file never blocks the rest of the scan.
+ *
+ * @param input - The scan configuration.
+ * @returns The assembled models, groups, and per-file errors.
+ */
+export declare function extractModels(input: ExtractModelsInput): Promise<ExtractModelsResult>;

package/src/lib/mcp-scan/scan/extract-models/infer-collection-kind.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Builds a map of `<modelType>FirestoreCollection(Factory)?` factory function
+ * names to the {@link FirestoreCollectionKind} their body declares.
+ *
+ * Mirrors the `findCollectionFactoryCalls` + `detectCollectionKindInBody`
+ * pair in `scripts/extract-firebase-models.mjs`. The kind is read off the
+ * first matching `firestoreContext.<method>(...)` call inside each
+ * function body — the pattern matches whether the call is direct
+ * (`firestoreContext.firestoreCollection({...})`) or returned from an
+ * inner factory closure.
+ */
+import { type SourceFile } from 'ts-morph';
+import type { FirestoreCollectionKind } from '../../registry/firebase-models.js';
+/**
+ * Returns a map of factory function name to its declared
+ * {@link FirestoreCollectionKind}. Functions that don't make a recognised
+ * `firestoreContext.*` call are omitted.
+ *
+ * @param sf - The parsed source file to inspect.
+ * @returns The factory-name → kind map (may be empty)
+ */
+export declare function findCollectionFactoryCalls(sf: SourceFile): ReadonlyMap<string, FirestoreCollectionKind>;

package/src/lib/mcp-scan/scan/extract-models/service-factory-constants.d.ts

@@ -0,0 +1,6 @@
+/**
+ * JSDoc tag that declares which Firestore model a `firebaseModelServiceFactory(...)` export
+ * implements. Value is the canonical `FirestoreModelIdentity.modelType` string. Mirrors the
+ * ESLint rule's `DBX_MODEL_SERVICE_FACTORY_TAG` constant so scanner + lint align.
+ */
+export declare const DBX_MODEL_SERVICE_FACTORY_TAG = "dbxModelServiceFactory";

package/src/lib/mcp-scan/scan/extract-models/types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Internal helper types for the rich Firebase-model ts-morph extractor.
+ *
+ * These types describe the per-file extraction outputs that
+ * {@link ../../scan/extract-models/index.ts} stitches together into
+ * {@link FirebaseModel} / {@link FirebaseModelGroup} entries.
+ */
+import type { FirestoreCollectionKind } from '../../registry/firebase-models.js';
+/**
+ * One `firestoreModelIdentity(...)` declaration.
+ */
+export interface ExtractedIdentity {
+    readonly identityConst: string;
+    readonly modelType: string;
+    readonly collectionPrefix: string | undefined;
+    readonly parentIdentityConst: string | undefined;
+}
+/**
+ * One field declared on an interface body. Captures the JSDoc
+ * description plus the explicit `@dbxModelVariable` long-name tag and
+ * the optional `@dbxModelVariableSyncFlag` sync-description tag.
+ */
+export interface ExtractedInterfaceProp {
+    readonly name: string;
+    readonly tsType: string;
+    readonly optional: boolean;
+    readonly description: string | undefined;
+    readonly longName: string | undefined;
+    readonly syncFlag: string | undefined;
+}
+/**
+ * Parsed `@dbxModelArchetype <slug>[ axisKey=val,...]` JSDoc override.
+ * Mirrors the `.mjs` extractor's `parseArchetypeTagValue` output.
+ */
+export interface ExtractedArchetypeTag {
+    readonly slug: string;
+    readonly axes: {
+        readonly [key: string]: string;
+    };
+}
+/**
+ * Parsed `@dbxModelCompositeKey from=<ModelA>,<ModelB> encoding=<two-way|one-way>`
+ * JSDoc tag, applied to interfaces whose Firestore doc id is a composite-flat-key
+ * encoding of one or more source model keys. `from=*` is the wildcard form used
+ * by framework models that accept any source identity (e.g. `NotificationBox`).
+ */
+export interface ExtractedCompositeKeyTag {
+    /**
+     * `'*'` for the wildcard form, or an ordered list of source-model names
+     * (interface name, identity const name, or modelType — same resolution as
+     * `getFirebaseModel`). Empty array when the tag is malformed (missing `from=`).
+     */
+    readonly from: readonly string[] | '*';
+    /**
+     * `'two-way'` for `twoWayFlatFirestoreModelKey` encoding, `'one-way'` for
+     * `flatFirestoreModelKey`. `undefined` when the tag is malformed.
+     */
+    readonly encoding: 'two-way' | 'one-way' | undefined;
+}
+/**
+ * Allowed `@dbxModelRead` levels. Three statically-inferable cases plus the `permissions`
+ * escape hatch for any non-trivial computed read grant. Mirrors the ESLint rule's
+ * `READ_LEVEL_VALUES` (see `require-dbx-model-companion-tags.rule.ts`).
+ */
+export type DbxModelReadLevel = 'system' | 'owner' | 'admin-only' | 'permissions';
+/**
+ * JSDoc-derived tag bag attached to one `export interface` declaration.
+ * `dbxModelArchetypes` is repeatable — every `@dbxModelArchetype` occurrence
+ * appends to the array. `dbxModelAggregatesFrom` is also repeatable.
+ * `dbxModelOrganizationalGroupRoot` is a boolean presence flag.
+ * `dbxModelCompositeKey` is at most one per interface — if multiple are
+ * declared, only the first is captured and the rest produce validation
+ * findings. `dbxModelRead` is at most one per interface; invalid values are
+ * dropped silently (the ESLint rule is the user-facing gate).
+ */
+export interface ExtractedInterfaceTags {
+    readonly dbxModel: boolean;
+    readonly dbxModelSubObject: boolean;
+    readonly dbxModelArchetypes: readonly ExtractedArchetypeTag[];
+    readonly dbxModelAggregatesFrom: readonly string[];
+    readonly dbxModelOrganizationalGroupRoot: boolean;
+    readonly dbxModelCompositeKey?: ExtractedCompositeKeyTag;
+    readonly dbxModelRead?: DbxModelReadLevel;
+}
+/**
+ * One `export interface` declaration. The `tags` flags drive model
+ * detection (`@dbxModel`) and embedded-sub-object detection
+ * (`@dbxModelSubObject` — interfaces persisted as part of a parent
+ * model's converter via `firestoreSubObject<T>`, lacking their own
+ * `firestoreModelIdentity`). `dbxModelArchetypes` carries any explicit
+ * archetype-slug overrides; the heuristic only runs when the array is empty.
+ */
+export interface ExtractedInterface {
+    readonly name: string;
+    readonly description: string | undefined;
+    readonly tags: ExtractedInterfaceTags;
+    readonly extendsNames: readonly string[];
+    readonly props: readonly ExtractedInterfaceProp[];
+}
+/**
+ * One `<x>Converter = snapshotConverterFunctions<<X>>({ fields: { ... } })`
+ * declaration. The `fields` array preserves the canonical persisted name.
+ */
+export interface ExtractedConverter {
+    readonly converterConst: string;
+    readonly interfaceName: string;
+    readonly fields: readonly {
+        readonly key: string;
+        readonly converter: string;
+    }[];
+}
+/**
+ * One enum value with its persisted integer/string and JSDoc paragraph.
+ */
+export interface ExtractedEnumValue {
+    readonly name: string;
+    readonly value: number | string;
+    readonly description: string | undefined;
+}
+/**
+ * One `export enum` declaration.
+ */
+export interface ExtractedEnum {
+    readonly name: string;
+    readonly values: readonly ExtractedEnumValue[];
+    readonly description: string | undefined;
+}
+/**
+ * One `<X>FirestoreCollections` container tagged with `@dbxModelGroup`.
+ */
+export interface ExtractedModelGroup {
+    readonly name: string;
+    readonly containerName: string;
+    readonly description: string | undefined;
+    readonly modelNames: readonly string[];
+}
+/**
+ * Map of `<modelType>FirestoreCollection(Factory)?` factory function names to
+ * the {@link FirestoreCollectionKind} their body declares.
+ */
+export type ExtractedFactoryKindMap = ReadonlyMap<string, FirestoreCollectionKind>;
+/**
+ * One `export const <name> = firestoreSubObject<T>(...)` /
+ * `firestoreObjectArray<T>(...)` / `firestoreMap<T>(...)` declaration. The
+ * registered `interfaceName` is the bare type-argument (`T`); the
+ * `factoryName` discriminates the call shape so the catalog can surface
+ * an `array` or `map` annotation when rendering the embedded sub-object.
+ */
+export interface ExtractedSubObjectConst {
+    readonly constName: string;
+    readonly interfaceName: string;
+    readonly factoryName: 'firestoreSubObject' | 'firestoreObjectArray' | 'firestoreMap';
+}
+/**
+ * One `@dbxModelServiceFactory <modelType>`-tagged variable export. The model extractor
+ * joins these onto matching {@link ExtractedInterface}s by `modelType` so each
+ * {@link FirebaseModel} entry surfaces the factory that implements it.
+ */
+export interface ExtractedServiceFactory {
+    /**
+     * The `FirestoreModelIdentity.modelType` string declared by the tag (e.g. `guestbook`,
+     * `guestbookEntry`). Only camelCase identifiers are emitted — invalid values are dropped
+     * silently at scan time.
+     */
+    readonly modelType: string;
+    /**
+     * Name of the exported binding the factory call was assigned to
+     * (e.g. `guestbookFirebaseModelServiceFactory`).
+     */
+    readonly exportName: string;
+}