@dereekb/dbx-cli 13.11.17 → 13.12.0

package/firestore-indexes/src/model-firebase-index-build-manifest.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Orchestrator for the `scan-model-firebase-indexes` generator.
+ *
+ * Composes a complete {@link ModelFirebaseIndexManifest} from a project
+ * root by:
+ *
+ *   1. reading `dbx-mcp.scan.json` against {@link ModelFirebaseIndexScanConfig}
+ *   2. reading `package.json` to derive the entry-level `module` field
+ *   3. resolving include/exclude globs against the project root
+ *   4. feeding matched files into a ts-morph project
+ *   5. building a build-time identity resolver from the same project
+ *   6. extracting entries via {@link extractModelFirebaseIndexEntries}
+ *   7. running them through {@link analyzeModelFirebaseIndexEntries}
+ *   8. assembling the manifest envelope and validating it against
+ *      {@link ModelFirebaseIndexManifest}
+ *
+ * I/O is fully injectable so tests drive every code path without touching
+ * the real filesystem.
+ */
+import { ModelFirebaseIndexManifest } from './model-firebase-index-schema.js';
+import { type AnalyzerWarning } from './model-firebase-index-analyze.js';
+import { type ModelFirebaseIndexExtractWarning } from './model-firebase-index-extract.js';
+import { type ScanGlobber, type ScanReadFile } from '../../src/lib/scan-helpers/scan-io.js';
+export type BuildModelFirebaseIndexReadFile = ScanReadFile;
+export type BuildModelFirebaseIndexGlobber = ScanGlobber;
+/**
+ * Combined warnings emitted by one generator run — extractor warnings plus
+ * analyzer warnings. Surfaced to the CLI / MCP tool layer so authors can
+ * see ambiguity (missing model tag, unresolved field, orderby conflict)
+ * without dropping silently.
+ */
+export type ModelFirebaseIndexBuildWarning = {
+    readonly stage: 'extract';
+    readonly warning: ModelFirebaseIndexExtractWarning;
+} | {
+    readonly stage: 'analyze';
+    readonly warning: AnalyzerWarning;
+};
+/**
+ * Input to {@link buildModelFirebaseIndexManifest}.
+ */
+export interface BuildModelFirebaseIndexManifestInput {
+    readonly projectRoot: string;
+    readonly generator: string;
+    readonly now?: () => Date;
+    readonly readFile?: BuildModelFirebaseIndexReadFile;
+    readonly globber?: BuildModelFirebaseIndexGlobber;
+}
+/**
+ * One dispatcher-tagged factory's delegate summary. The `name` is the
+ * dispatcher's exported function name (matched against scanner reference
+ * counts) and `delegates` are the identifier-callee names captured from
+ * its body. Surfaced by {@link buildModelFirebaseIndexManifest} so the
+ * validator can credit dispatcher caller counts against the factories
+ * the dispatcher returns into.
+ */
+export interface ModelFirebaseIndexDispatcherSummary {
+    readonly slug: string;
+    readonly name: string;
+    readonly delegates: readonly string[];
+}
+/**
+ * Outcome of one generator run.
+ */
+export type BuildModelFirebaseIndexManifestOutcome = {
+    readonly kind: 'success';
+    readonly manifest: ModelFirebaseIndexManifest;
+    readonly outPath: string;
+    readonly scannedFileCount: number;
+    readonly extractWarnings: readonly ModelFirebaseIndexBuildWarning[];
+    readonly entryFilePathsBySlug: ReadonlyMap<string, string>;
+    readonly dispatcherSummaries: readonly ModelFirebaseIndexDispatcherSummary[];
+} | {
+    readonly kind: 'no-config';
+    readonly configPath: string;
+} | {
+    readonly kind: 'invalid-scan-config';
+    readonly configPath: string;
+    readonly error: string;
+} | {
+    readonly kind: 'no-package';
+    readonly packagePath: string;
+} | {
+    readonly kind: 'invalid-package';
+    readonly packagePath: string;
+    readonly error: string;
+} | {
+    readonly kind: 'invalid-manifest';
+    readonly error: string;
+};
+/**
+ * Builds a {@link ModelFirebaseIndexManifest} from the supplied project
+ * root. The function is pure with respect to the injected I/O hooks, so
+ * unit tests can drive every branch without disk access.
+ *
+ * @param input - The project root + injection hooks for testing.
+ * @returns A discriminated outcome describing the result.
+ */
+export declare function buildModelFirebaseIndexManifest(input: BuildModelFirebaseIndexManifestInput): Promise<BuildModelFirebaseIndexManifestOutcome>;
+/**
+ * JSON-stringifies a manifest with stable key ordering and trailing
+ * newline so `--check` mode can byte-compare against a committed file
+ * without false-positive diffs from key reordering.
+ *
+ * @param manifest - The manifest to serialise.
+ * @returns The canonical string form.
+ */
+export declare function serializeModelFirebaseIndexManifest(manifest: ModelFirebaseIndexManifest): string;
+/**
+ * Renders a {@link ModelFirebaseIndexBuildWarning} into a single human-readable
+ * line. Shared by the `scan-model-firebase-indexes` CLI and the
+ * `dbx_model_firebase_index_list_app` MCP tool so both surfaces describe the
+ * same warning identically.
+ *
+ * @param warning - Warning emitted by the extractor or analyzer.
+ * @returns A one-line description suitable for CLI logs or markdown bullets.
+ *
+ * @example
+ * ```ts
+ * outcome.extractWarnings.map(formatModelFirebaseIndexBuildWarning).forEach(log);
+ * ```
+ */
+export declare function formatModelFirebaseIndexBuildWarning(warning: ModelFirebaseIndexBuildWarning): string;

package/firestore-indexes/src/model-firebase-index-extract.d.ts

@@ -0,0 +1,246 @@
+/**
+ * AST extraction for the `scan-model-firebase-indexes` generator.
+ *
+ * Walks every source file in the supplied ts-morph `Project` looking for
+ * top-level exported functions tagged with the `@dbxModelFirebaseIndex`
+ * JSDoc marker. For each match:
+ *
+ *   1. Reads JSDoc-tag metadata (model, scope, manual/skip flags, category,
+ *      tags, related slugs).
+ *   2. Resolves the target model's short collection name and nested flag
+ *      via {@link FirestoreModelIdentityResolver}.
+ *   3. Walks the function body collecting `where(...)`, `orderBy(...)`, and
+ *      known-helper calls (from {@link FIRESTORE_QUERY_HELPERS}) in source
+ *      order, expanding helpers into their base constraint sequences.
+ *   4. Emits one {@link ExtractedModelFirebaseIndexEntry} per factory.
+ *
+ * Conditional-branch enumeration is opt-in via `@dbxModelFirebaseIndexPath`.
+ * Each path tag declares one call pattern as a comma-separated list of
+ * field paths, and the extractor produces one constraint sequence per tag
+ * (filtered to the listed fields, preserving body source order). When no
+ * path tag is declared, the extractor falls back to a single 'all'
+ * sequence containing every constraint call in the body; if any of those
+ * calls sits inside an `if`/`switch`/ternary branch, a `missing-paths`
+ * warning surfaces the conditional fields so the author can declare the
+ * meaningful subsets.
+ *
+ * Mirrors `model-snapshot-fields-extract.ts` for tag parsing + entry
+ * assembly conventions.
+ */
+import { type Project } from 'ts-morph';
+import { type ConstraintSequence, type FirestoreQueryScope, type ModelFirebaseIndexParamEntry } from './model-firebase-index-schema.js';
+import { type FirestoreModelIdentityResolver } from './firestore-model-identity-resolver.js';
+/**
+ * One firebase-index entry extracted from a source file. Mirrors
+ * {@link ModelFirebaseIndexEntry} minus `module` and `subpath` (derived in
+ * build-manifest from the package being scanned and the project root).
+ * `filePath` and `line` are kept for in-process warnings and never
+ * persisted to the manifest.
+ */
+export interface ExtractedModelFirebaseIndexEntry {
+    readonly slug: string;
+    readonly name: string;
+    readonly model: string;
+    readonly collection: string;
+    readonly isNested: boolean;
+    readonly scope: FirestoreQueryScope;
+    readonly manual: boolean;
+    readonly skip: boolean;
+    /**
+     * True when the factory carries `@dbxModelFirebaseIndexSpecFilesOnly`. The
+     * factory is intentionally for `.spec.ts` use only — the analyzer suppresses
+     * composite + fieldOverride emission (mirroring `skip`), and the validator
+     * raises `MODEL_FIREBASE_INDEX_SPEC_FILES_ONLY_VIOLATION` (error) if a
+     * non-spec file references the factory by name.
+     */
+    readonly specOnly: boolean;
+    /**
+     * True when the factory carries `@dbxModelFirebaseIndexExclude`. The
+     * constraint sequence is still parsed (unlike `skip`, which empties it)
+     * so the list-app / lookup tools can display the would-be query shape;
+     * the analyzer suppresses composite + fieldOverride emission. Every
+     * excluded factory also produces an `excluded-factory` warning so the
+     * exclusion is auditable.
+     */
+    readonly excluded: boolean;
+    /**
+     * True when the factory carries `@dbxModelFirebaseIndexDispatcher`. The
+     * factory itself produces no composite/fieldOverride (its
+     * `constraintSequences` is always empty), but the validator credits its
+     * caller count to every name listed in `dispatcherDelegates` so a
+     * dispatcher-only primitive does not perpetually false-positive on
+     * `MODEL_FIREBASE_INDEX_UNUSED_FACTORY`.
+     */
+    readonly dispatcher: boolean;
+    /**
+     * Identifier-callee names captured from the body of a dispatcher-tagged
+     * factory. Populated only when `dispatcher` is true; empty otherwise.
+     * Names are reported as written in source (no resolution to slugs) — the
+     * validator matches them against other tagged factories' `name` fields
+     * when crediting unused-factory references.
+     */
+    readonly dispatcherDelegates: readonly string[];
+    readonly allowArrayContainsAny: boolean;
+    readonly category: string;
+    readonly signature: string;
+    readonly description: string;
+    readonly params: readonly ModelFirebaseIndexParamEntry[];
+    readonly returns: string;
+    readonly tags: readonly string[];
+    readonly relatedSlugs?: readonly string[];
+    readonly skillRefs?: readonly string[];
+    readonly example: string;
+    readonly constraintSequences: readonly ConstraintSequence[];
+    readonly deprecated?: boolean | string;
+    readonly since?: string;
+    readonly filePath: string;
+    readonly line: number;
+}
+/**
+ * Discriminated union of the non-fatal events the extractor emits when an
+ * entry can't be assembled cleanly.
+ */
+export type ModelFirebaseIndexExtractWarningSeverity = 'error' | 'warning';
+/**
+ * The branch construct that disqualified a tagged query factory's body.
+ */
+export type ComplexQueryBranchKind = 'if' | 'switch' | 'ternary' | 'loop';
+export type ModelFirebaseIndexExtractWarning = {
+    readonly kind: 'missing-name';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'missing-model-tag';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'unresolved-model';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly model: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'unsupported-scope';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly scope: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'duplicate-slug';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly slug: string;
+    readonly previousName: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'unknown-helper';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly helper: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'unresolved-field';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly callee: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'missing-paths';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly conditionalFields: readonly string[];
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'unknown-path-field';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly field: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'unannotated-query-helper';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly callee: string;
+    readonly calleeFilePath: string;
+    readonly calleeLine: number;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'transitive-cycle';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly callee: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'unresolvable-transitive-callee';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly callee: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'complex-query-body';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly branchKind: ComplexQueryBranchKind;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'non-delegating-dispatcher';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly callee: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'excluded-factory';
+    readonly severity: ModelFirebaseIndexExtractWarningSeverity;
+    readonly name: string;
+    readonly filePath: string;
+    readonly line: number;
+};
+/**
+ * Input to {@link extractModelFirebaseIndexEntries}.
+ */
+export interface ExtractModelFirebaseIndexEntriesInput {
+    readonly project: Project;
+    readonly identityResolver: FirestoreModelIdentityResolver;
+    readonly projectRoot?: string;
+}
+/**
+ * Result of {@link extractModelFirebaseIndexEntries}.
+ */
+export interface ExtractModelFirebaseIndexEntriesResult {
+    readonly entries: readonly ExtractedModelFirebaseIndexEntry[];
+    readonly warnings: readonly ModelFirebaseIndexExtractWarning[];
+}
+/**
+ * Walks the supplied project and returns every export tagged with the
+ * `@dbxModelFirebaseIndex` JSDoc marker. Order is stable: source files in
+ * the order ts-morph reports them, declarations within a file in source
+ * order.
+ *
+ * @param input - The ts-morph project, identity resolver, and project root.
+ * @returns The extracted entries plus any non-fatal warnings.
+ */
+export declare function extractModelFirebaseIndexEntries(input: ExtractModelFirebaseIndexEntriesInput): ExtractModelFirebaseIndexEntriesResult;
+/**
+ * Converts an export name into its kebab-case slug form. Handles
+ * camelCase (`jobLocationWeeksDirty` → `job-location-weeks-dirty`) and
+ * SCREAMING_SNAKE_CASE; already-kebab inputs pass through unchanged.
+ *
+ * @param name - The export identifier.
+ * @returns The kebab-case slug.
+ */
+export declare function toKebabCase(name: string): string;

package/firestore-indexes/src/model-firebase-index-runtime.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Model-firebase-index runtime registry wrapper.
+ *
+ * Wraps the raw {@link LoadModelFirebaseIndexManifestsResult} produced by
+ * the loader with domain-friendly accessors so the lookup/search tools
+ * and the registry resource don't have to walk Maps directly.
+ *
+ * The registry is loaded once at server startup and passed into the tool
+ * factories. Tests can construct a registry from any entry array via
+ * {@link createModelFirebaseIndexRegistryFromEntries} to drive the tools
+ * without touching disk.
+ */
+import type { ConstraintSequence, DerivedComposite, DerivedFieldOverride, FirestoreQueryScope, ModelFirebaseIndexEntry, ModelFirebaseIndexParamEntry } from './model-firebase-index-schema.js';
+/**
+ * Subset of the `LoadModelFirebaseIndexManifestsResult` shape (defined by
+ * `model-firebase-index-loader.ts` in `@dereekb/dbx-components-mcp`) that
+ * `createModelFirebaseIndexRegistry` consumes. Inlined here so this
+ * runtime stays free of any back-import into the MCP server package.
+ *
+ * `warnings` is typed as `readonly unknown[]` because the registry never
+ * reads them — the loader collects them and surfaces them through its own
+ * (more strongly typed) return shape. Any `readonly Warning[]` is
+ * structurally assignable to `readonly unknown[]`.
+ */
+export interface LoadModelFirebaseIndexManifestsResult {
+    readonly entries: ReadonlyMap<string, ModelFirebaseIndexEntry>;
+    readonly collectionIndex: ReadonlyMap<string, readonly string[]>;
+    readonly warnings: readonly unknown[];
+    readonly loadedSources: readonly string[];
+}
+/**
+ * One curated firebase-index entry surfaced through the
+ * `dbx_model_firebase_index_*` tools.
+ *
+ * Mirrors {@link ModelFirebaseIndexEntry} but normalises optional manifest
+ * fields to empty arrays / safe defaults so callers (lookup, search,
+ * resources) don't have to defensively branch.
+ */
+export interface ModelFirebaseIndexEntryInfo {
+    readonly slug: string;
+    readonly name: string;
+    readonly module: string;
+    readonly subpath: string;
+    readonly signature: string;
+    readonly description: string;
+    readonly model: string;
+    readonly collection: string;
+    readonly isNested: boolean;
+    readonly scope: FirestoreQueryScope;
+    readonly manual: boolean;
+    readonly skip: boolean;
+    readonly category: string;
+    readonly params: readonly ModelFirebaseIndexParamEntry[];
+    readonly returns: string;
+    readonly tags: readonly string[];
+    readonly constraintSequences: readonly ConstraintSequence[];
+    readonly derivedComposites: readonly DerivedComposite[];
+    readonly derivedFieldOverrides: readonly DerivedFieldOverride[];
+    readonly example: string;
+    readonly relatedSlugs: readonly string[];
+    readonly skillRefs: readonly string[];
+    readonly deprecated: boolean | string;
+    readonly since: string;
+}
+/**
+ * Domain-friendly read API over a merged model-firebase-index manifest set.
+ * All accessors return readonly arrays preserving the order the manifests
+ * declared their entries.
+ */
+export interface ModelFirebaseIndexRegistry {
+    readonly all: readonly ModelFirebaseIndexEntryInfo[];
+    readonly loadedSources: readonly string[];
+    readonly collections: readonly string[];
+    readonly models: readonly string[];
+    readonly modules: readonly string[];
+    readonly categories: readonly string[];
+    findBySlug(slug: string): ModelFirebaseIndexEntryInfo | undefined;
+    findByName(name: string): ModelFirebaseIndexEntryInfo | undefined;
+    findByCollection(collection: string): readonly ModelFirebaseIndexEntryInfo[];
+    findByModel(model: string): readonly ModelFirebaseIndexEntryInfo[];
+    findByModule(module: string): readonly ModelFirebaseIndexEntryInfo[];
+    findByCategory(category: string): readonly ModelFirebaseIndexEntryInfo[];
+    findByTag(tag: string): readonly ModelFirebaseIndexEntryInfo[];
+}
+/**
+ * Builds a {@link ModelFirebaseIndexRegistry} from a loader result.
+ *
+ * @param loaded - The merged registry returned by `loadModelFirebaseIndexManifests`
+ * @returns A domain-friendly read API over the merged entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createModelFirebaseIndexRegistry(loaded: LoadModelFirebaseIndexManifestsResult): ModelFirebaseIndexRegistry;
+/**
+ * Builds a {@link ModelFirebaseIndexRegistry} from a raw entry array.
+ * Used by tests that need to drive the tools without going through the
+ * loader pipeline.
+ *
+ * @param input - The entries plus the source labels to advertise.
+ * @param input.entries - The full entry list.
+ * @param input.loadedSources - Source labels reported via `registry.loadedSources`
+ * @returns A domain-friendly read API over the supplied entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createModelFirebaseIndexRegistryFromEntries(input: {
+    readonly entries: readonly ModelFirebaseIndexEntryInfo[];
+    readonly loadedSources: readonly string[];
+}): ModelFirebaseIndexRegistry;
+/**
+ * Empty registry suitable as a default when the server has no
+ * model-firebase-index manifest sources to load. Tools wired against
+ * this registry behave like a registry that loaded successfully with
+ * zero entries.
+ */
+export declare const EMPTY_MODEL_FIREBASE_INDEX_REGISTRY: ModelFirebaseIndexRegistry;
+/**
+ * Converts a manifest entry into the {@link ModelFirebaseIndexEntryInfo}
+ * shape the lookup/search tools consume. Optional manifest fields fall
+ * back to safe defaults so a partially-populated entry still renders
+ * cleanly.
+ *
+ * @param entry - The manifest entry to convert.
+ * @returns The matching ModelFirebaseIndexEntryInfo.
+ */
+export declare function toModelFirebaseIndexEntryInfo(entry: ModelFirebaseIndexEntry): ModelFirebaseIndexEntryInfo;

package/firestore-indexes/src/model-firebase-index-scan-config-schema.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Arktype schema for the `modelFirebaseIndex` section of `dbx-mcp.scan.json`.
+ *
+ * Mirrors the existing `modelSnapshotFields` section — same `dbx-mcp.scan.json`
+ * filename so a project that opts into multiple pipelines keeps a single
+ * config file. The CLI subcommand `scan-model-firebase-indexes` reads only
+ * the `modelFirebaseIndex` field; sibling subcommands continue to read their
+ * own top-level fields unchanged.
+ */
+/**
+ * Inner config that drives one model-firebase-index scan run. `source`
+ * becomes the manifest's `source` label (used for collision detection across
+ * loaded sources); `module` becomes the npm package name attached to every
+ * produced entry. Both default to the project's `package.json#name` when
+ * omitted.
+ */
+export declare const ModelFirebaseIndexScanSection: import("arktype/internal/variants/object.ts").ObjectType<{
+    include: string[];
+    source?: string | undefined;
+    module?: string | undefined;
+    exclude?: string[] | undefined;
+    out?: string | undefined;
+}, {}>;
+/**
+ * Static type for {@link ModelFirebaseIndexScanSection}.
+ */
+export type ModelFirebaseIndexScanSection = typeof ModelFirebaseIndexScanSection.infer;
+/**
+ * Top-level shape used by the model-firebase-index builder. Only the
+ * `modelFirebaseIndex` key is consumed; the rest of the document is ignored
+ * so a single `dbx-mcp.scan.json` can house all the scan sections
+ * side-by-side.
+ */
+export declare const ModelFirebaseIndexScanConfig: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    modelFirebaseIndex: {
+        include: string[];
+        source?: string | undefined;
+        module?: string | undefined;
+        exclude?: string[] | undefined;
+        out?: string | undefined;
+    };
+}, {}>;
+/**
+ * Static type for {@link ModelFirebaseIndexScanConfig}.
+ */
+export type ModelFirebaseIndexScanConfig = typeof ModelFirebaseIndexScanConfig.infer;
+/**
+ * Default value used when the scan config does not specify `out`.
+ * Lives next to the scan config in the project root.
+ */
+export declare const DEFAULT_MODEL_FIREBASE_INDEX_SCAN_OUT_PATH = "model-firebase-index.mcp.generated.json";
+/**
+ * Filename the loader looks for at `${projectRoot}/`. Re-exported here so
+ * the model-firebase-index CLI does not have to import from a sibling scan
+ * config module.
+ */
+export declare const MODEL_FIREBASE_INDEX_SCAN_CONFIG_FILENAME = "dbx-mcp.scan.json";