@dereekb/dbx-cli 13.11.18 → 13.12.0

package/src/lib/mcp-scan/scan/forge-fields-scan-config-schema.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Arktype schema for the `forgeFields` section of `dbx-mcp.scan.json`.
+ *
+ * Forge-field scanning lives next to the existing semantic-types and
+ * ui-components sections — all three use the same `dbx-mcp.scan.json`
+ * filename so a project that opts into multiple pipelines keeps a single
+ * config file. The CLI subcommand `scan-forge-fields` reads only the
+ * `forgeFields` field; sibling subcommands continue to read their own
+ * top-level fields unchanged.
+ *
+ * The schema is intentionally permissive at the root (extra keys are
+ * preserved untouched) so semantic-types and ui-components configs can
+ * coexist without cross-section validation.
+ */
+/**
+ * Inner config that drives one forge-fields 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 ForgeFieldsScanSection: import("arktype/internal/variants/object.ts").ObjectType<{
+    include: string[];
+    source?: string | undefined;
+    module?: string | undefined;
+    exclude?: string[] | undefined;
+    out?: string | undefined;
+}, {}>;
+/**
+ * Static type inferred from {@link ForgeFieldsScanSection}.
+ */
+export type ForgeFieldsScanSection = typeof ForgeFieldsScanSection.infer;
+/**
+ * Top-level shape used by the forge-fields builder. Only the `forgeFields`
+ * 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 ForgeFieldsScanConfig: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    forgeFields: {
+        include: string[];
+        source?: string | undefined;
+        module?: string | undefined;
+        exclude?: string[] | undefined;
+        out?: string | undefined;
+    };
+}, {}>;
+/**
+ * Static type inferred from {@link ForgeFieldsScanConfig}.
+ */
+export type ForgeFieldsScanConfig = typeof ForgeFieldsScanConfig.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_FORGE_FIELDS_SCAN_OUT_PATH = "forge-fields.mcp.generated.json";
+/**
+ * Filename the loader looks for at `${projectRoot}/`. Re-exported here so
+ * the forge-fields CLI does not have to import from a sibling scan config
+ * module.
+ */
+export declare const FORGE_FIELDS_SCAN_CONFIG_FILENAME = "dbx-mcp.scan.json";

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

@@ -0,0 +1,60 @@
+/**
+ * Scan barrel for the dbx-components MCP scan infrastructure.
+ *
+ * Exposes the ts-morph-backed extractors, build-manifest helpers,
+ * scan-config schemas, and CLI entrypoints used by the
+ * `generate-mcp-manifest`-family CLIs and by runtime resources that
+ * scan workspace source for downstream models / discovery.
+ */
+export * from './scan-config-schema.js';
+export * from './extract.js';
+export * from './build-manifest.js';
+export * from './cli.js';
+export * from './filters-cli.js';
+export * from './filters-extract.js';
+export * from './filters-build-manifest.js';
+export * from './filters-scan-config-schema.js';
+export * from './actions-cli.js';
+export * from './actions-extract.js';
+export * from './actions-build-manifest.js';
+export * from './actions-scan-config-schema.js';
+export * from './auth-extract.js';
+export * from './css-utilities-cli.js';
+export * from './css-utilities-extract.js';
+export * from './css-utilities-build-manifest.js';
+export * from './css-utilities-scan-config-schema.js';
+export * from './dbx-docs-ui-examples-cli.js';
+export * from './dbx-docs-ui-examples-extract.js';
+export * from './dbx-docs-ui-examples-build-manifest.js';
+export * from './dbx-docs-ui-examples-scan-config-schema.js';
+export * from './discover-downstream-packages.js';
+export { discoverDownstreamFirebasePackages, resolveExplicitFirebasePackages } from './discover-firebase-packages.js';
+export type { DownstreamFirebasePackage } from './discover-firebase-packages.js';
+export * from './forge-fields-cli.js';
+export * from './forge-fields-extract.js';
+export * from './forge-fields-build-manifest.js';
+export * from './forge-fields-scan-config-schema.js';
+export * from './model-firebase-index-cli.js';
+export * from './model-firebase-index-dispatcher-credit.js';
+export * from './model-firebase-index-reference-scan.js';
+export * from './model-snapshot-fields-cli.js';
+export * from './model-snapshot-fields-extract.js';
+export * from './model-snapshot-fields-build-manifest.js';
+export * from './model-snapshot-fields-scan-config-schema.js';
+export * from './pipes-cli.js';
+export * from './pipes-extract.js';
+export * from './pipes-build-manifest.js';
+export * from './pipes-scan-config-schema.js';
+export * from './scan-angular-io.js';
+export { runScanCliBase, parseScanArgs } from './scan-cli-base.js';
+export type { ScanCliBaseReadFile, ScanCliBaseWriteFile, ScanCliBaseLogger, ScanCliManifestLike, ScanCliBuildSuccess, ScanCliBuildFailure, ScanCliBuildOutcome, ScanCliBuildInput, ScanCliConfig, RunScanCliBaseInput } from './scan-cli-base.js';
+export * from './ui-components-cli.js';
+export type { ExtractedUiEntry, ExtractUiEntriesInput, ExtractUiEntriesResult, ExtractWarning as UiComponentExtractWarning } from './ui-components-extract.js';
+export { extractUiEntries, ExtractedUiEntrySchema } from './ui-components-extract.js';
+export * from './ui-components-build-manifest.js';
+export * from './ui-components-scan-config-schema.js';
+export * from './utils-cli.js';
+export * from './utils-extract.js';
+export * from './utils-build-manifest.js';
+export * from './utils-scan-config-schema.js';
+export * from './extract-models/index.js';

package/src/lib/mcp-scan/scan/model-firebase-index-cli.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `scan-model-firebase-indexes` subcommand entry point.
+ *
+ * Thin wrapper around {@link runScanCliBase} that supplies the
+ * model-firebase-index domain config.
+ */
+import { type BuildModelFirebaseIndexGlobber } from '../../../../firestore-indexes/src/model-firebase-index-build-manifest.js';
+import { type RunScanCliBaseInput, type RunScanCliResult, type ScanCliBaseLogger, type ScanCliBaseReadFile, type ScanCliBaseWriteFile } from './scan-cli-base.js';
+export type ModelFirebaseIndexScanCliReadFile = ScanCliBaseReadFile;
+export type ModelFirebaseIndexScanCliWriteFile = ScanCliBaseWriteFile;
+export type ModelFirebaseIndexScanCliLogger = ScanCliBaseLogger;
+export type RunModelFirebaseIndexScanCliInput = RunScanCliBaseInput<BuildModelFirebaseIndexGlobber>;
+export type RunModelFirebaseIndexScanCliResult = RunScanCliResult;
+/**
+ * Runs one invocation of `scan-model-firebase-indexes`. Never throws on
+ * user errors — every failure path returns a structured exit code so
+ * callers can wire this into `process.exit` without try/catch.
+ *
+ * @param input - Argv plus injectable I/O hooks.
+ * @returns The CLI's exit code (0 on success, 1 on drift / build failure, 2 on usage error)
+ */
+export declare function runModelFirebaseIndexScanCli(input: RunModelFirebaseIndexScanCliInput): Promise<RunModelFirebaseIndexScanCliResult>;

package/src/lib/mcp-scan/scan/model-firebase-index-dispatcher-credit.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Dispatcher → delegate caller-count credit table.
+ *
+ * Folds {@link FactoryReferenceCount}s for every tagged
+ * `@dbxModelFirebaseIndexDispatcher` into every factory the dispatcher
+ * delegates to by name. Consumed by `dbx_model_firebase_index_validate_app`
+ * and `dbx_model_firebase_index_list_app` so a primitive that is only
+ * reached through a dispatcher does not perpetually false-positive on
+ * `MODEL_FIREBASE_INDEX_UNUSED_FACTORY`.
+ *
+ * Lives in `scan/` (not under either tool) so the validator and list-app
+ * tools share a single resolution rule.
+ */
+import type { ModelFirebaseIndexDispatcherSummary } from '@dereekb/dbx-cli/firestore-indexes';
+import type { FactoryReferenceCount } from './model-firebase-index-reference-scan.js';
+/**
+ * Reference credit routed to one delegated factory through one or more
+ * dispatchers. Summed across every dispatcher whose body delegates to the
+ * factory.
+ */
+export interface DispatcherCredit {
+    readonly productionCount: number;
+    readonly specCount: number;
+}
+/**
+ * Builds the dispatcher → delegate credit table.
+ *
+ * For each summary in `dispatcherSummaries`, resolves the dispatcher's
+ * own scanner reference count (by slug) and folds it into every name in
+ * the dispatcher's `delegates` list. Dispatchers with zero references
+ * contribute nothing — there is nothing to credit. Multiple dispatchers
+ * delegating to the same factory sum their counts.
+ *
+ * @param dispatcherSummaries - Dispatcher entries surfaced by the build outcome.
+ * @param references - Per-slug reference counts from {@link scanFactoryReferences}.
+ * @returns Map keyed by delegate factory `name`.
+ *
+ * @example
+ * ```ts
+ * const creditByName = buildDispatcherCreditByName(buildOutcome.dispatcherSummaries, references);
+ * const credit = creditByName.get(entry.name);
+ * if ((references.get(entry.slug)?.productionCount ?? 0) + (credit?.productionCount ?? 0) === 0) {
+ *   // emit MODEL_FIREBASE_INDEX_UNUSED_FACTORY
+ * }
+ * ```
+ */
+export declare function buildDispatcherCreditByName(dispatcherSummaries: readonly ModelFirebaseIndexDispatcherSummary[], references: ReadonlyMap<string, FactoryReferenceCount>): ReadonlyMap<string, DispatcherCredit>;

package/src/lib/mcp-scan/scan/model-firebase-index-reference-scan.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Reference scanner for `@dbxModelFirebaseIndex`-tagged factories.
+ *
+ * Given a list of extracted entries and a glob of consumer `.ts` files,
+ * counts the external references to each factory by name. Used by
+ * `dbx_model_firebase_index_list_app` to surface the `referenceCount` +
+ * `referencedBy` columns, and by `dbx_model_firebase_index_validate_app`
+ * to emit `MODEL_FIREBASE_INDEX_UNUSED_FACTORY` when a non-skip /
+ * non-manual factory has zero external references.
+ *
+ * Scope: the consumers (`*_list_app`, `*_validate_app`) point the scan at
+ * the workspace root (`process.cwd()`) with workspace-wide globs covering
+ * `apps/**`, `components/**`, and `packages/**` so callers in sibling
+ * components, downstream apps, or shared packages are counted alongside
+ * intra-component references. {@link WORKSPACE_FACTORY_SCAN_INCLUDE} and
+ * {@link WORKSPACE_FACTORY_SCAN_EXCLUDE} are the canonical defaults.
+ *
+ * Implementation note: deliberately text-based rather than AST-based. The
+ * extractor's in-memory ts-morph project only contains `*.query.ts`
+ * files, so AST `findReferencesAsNodes()` would miss the actions /
+ * services / API callers that actually use these factories. Loading every
+ * consumer into ts-morph would be slow and would force the consumer of
+ * this module to expand the scan globs. A word-boundary text scan against
+ * the factory names is precise enough — collisions would require an
+ * unrelated identifier with the same exact name AND export-style
+ * `.query.ts` factory naming (e.g. `*Query`), which the existing factory-
+ * naming convention already rules out in practice.
+ */
+import { type ScanGlobber, type ScanReadFile } from '../../scan-helpers/scan-io.js';
+import type { ExtractedModelFirebaseIndexEntry } from '@dereekb/dbx-cli/firestore-indexes';
+/**
+ * One usage of a factory found in a consumer file.
+ */
+export interface FactoryReferenceSite {
+    readonly file: string;
+    readonly line: number;
+    /**
+     * True when the consumer file is a `*.spec.ts` (test) file. Used by the
+     * validator to enforce `@dbxModelFirebaseIndexSpecFilesOnly` semantics —
+     * spec-only factories may only have spec callers, and a regular factory's
+     * "unused" check still counts only non-spec callers.
+     */
+    readonly isSpec: boolean;
+}
+/**
+ * Per-factory reference report. Keyed by the entry's `slug` in the
+ * scanner's return value. `count` is the total site count;
+ * `productionCount` / `specCount` partition it by whether the site lives
+ * in a `*.spec.ts` file. `referencedBy` carries every site (each tagged
+ * with `isSpec`) so consumers can render the full breakdown without
+ * re-counting.
+ */
+export interface FactoryReferenceCount {
+    readonly count: number;
+    readonly productionCount: number;
+    readonly specCount: number;
+    readonly referencedBy: readonly FactoryReferenceSite[];
+}
+/**
+ * Input to {@link scanFactoryReferences}.
+ */
+export interface ScanFactoryReferencesInput {
+    readonly projectRoot: string;
+    readonly entries: readonly Pick<ExtractedModelFirebaseIndexEntry, 'slug' | 'name' | 'filePath'>[];
+    readonly include?: readonly string[];
+    readonly exclude?: readonly string[];
+    readonly readFile?: ScanReadFile;
+    readonly globber?: ScanGlobber;
+}
+/**
+ * Canonical include-glob set the tool layer hands to {@link scanFactoryReferences}
+ * when the projectRoot is the workspace root. Covers every place a downstream
+ * project may call a tagged factory: apps, sibling components, and shared
+ * packages. Keep these aligned with the Nx workspace layout — the validator's
+ * `MODEL_FIREBASE_INDEX_UNUSED_FACTORY` warning is only useful if it sees
+ * every plausible call-site.
+ */
+export declare const WORKSPACE_FACTORY_SCAN_INCLUDE: readonly string[];
+/**
+ * Canonical exclude-glob set paired with {@link WORKSPACE_FACTORY_SCAN_INCLUDE}.
+ * Strips ambient typings, build outputs, and `node_modules` so the
+ * workspace-wide scan stays fast. `*.spec.ts` files are intentionally KEPT
+ * so the scanner can flag spec callers (`isSpec: true`) — the validator
+ * uses that to enforce `@dbxModelFirebaseIndexSpecFilesOnly` and to treat
+ * spec-only references as "not a production caller" for the unused-factory
+ * warning.
+ */
+export declare const WORKSPACE_FACTORY_SCAN_EXCLUDE: readonly string[];
+/**
+ * Counts external references to each entry's exported factory by name.
+ *
+ * Walks every `.ts` file under {@link projectRoot} (default
+ * `src/**\/*.ts`, excluding specs + `.d.ts`), reads it once, and scans
+ * for word-boundary occurrences of each factory name. References inside
+ * the factory's own declaration file are excluded — only callers count.
+ *
+ * @param input - Project root, the entries to count, optional glob + IO overrides for tests.
+ * @returns Map keyed by entry slug → reference count + locations.
+ */
+export declare function scanFactoryReferences(input: ScanFactoryReferencesInput): Promise<ReadonlyMap<string, FactoryReferenceCount>>;

package/src/lib/mcp-scan/scan/model-snapshot-fields-build-manifest.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Orchestrator for the `scan-model-snapshot-fields` generator.
+ *
+ * Composes a complete {@link ModelSnapshotFieldManifest} from a project
+ * root by
+ *
+ *   1. reading `dbx-mcp.scan.json` against {@link ModelSnapshotFieldsScanConfig}
+ *   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. extracting entries via {@link extractModelSnapshotFieldEntries}
+ *   6. assembling the manifest envelope and validating it against
+ *      {@link ModelSnapshotFieldManifest}
+ *
+ * I/O is fully injectable so tests drive every code path without
+ * touching the real filesystem.
+ */
+import { ModelSnapshotFieldManifest } from '../manifest/model-snapshot-fields-schema.js';
+import { type ModelSnapshotFieldExtractWarning } from './model-snapshot-fields-extract.js';
+import { type ScanGlobber, type ScanReadFile } from '../../scan-helpers/scan-io.js';
+export type BuildModelSnapshotFieldsReadFile = ScanReadFile;
+export type BuildModelSnapshotFieldsGlobber = ScanGlobber;
+/**
+ * Input to {@link buildModelSnapshotFieldsManifest}.
+ */
+export interface BuildModelSnapshotFieldsManifestInput {
+    readonly projectRoot: string;
+    readonly generator: string;
+    readonly now?: () => Date;
+    readonly readFile?: BuildModelSnapshotFieldsReadFile;
+    readonly globber?: BuildModelSnapshotFieldsGlobber;
+}
+/**
+ * Outcome of one generator run. The success payload carries everything
+ * the caller needs to write the manifest to disk or run a freshness diff
+ * against an existing on-disk version.
+ */
+export type BuildModelSnapshotFieldsManifestOutcome = {
+    readonly kind: 'success';
+    readonly manifest: ModelSnapshotFieldManifest;
+    readonly outPath: string;
+    readonly scannedFileCount: number;
+    readonly extractWarnings: readonly ModelSnapshotFieldExtractWarning[];
+} | {
+    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 ModelSnapshotFieldManifest} 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 buildModelSnapshotFieldsManifest(input: BuildModelSnapshotFieldsManifestInput): Promise<BuildModelSnapshotFieldsManifestOutcome>;
+/**
+ * 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 serializeModelSnapshotFieldsManifest(manifest: ModelSnapshotFieldManifest): string;

package/src/lib/mcp-scan/scan/model-snapshot-fields-cli.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `scan-model-snapshot-fields` subcommand entry point.
+ *
+ * Thin wrapper around {@link runScanCliBase} that supplies the
+ * model-snapshot-fields domain config.
+ */
+import { type BuildModelSnapshotFieldsGlobber } from './model-snapshot-fields-build-manifest.js';
+import { type RunScanCliBaseInput, type RunScanCliResult, type ScanCliBaseLogger, type ScanCliBaseReadFile, type ScanCliBaseWriteFile } from './scan-cli-base.js';
+/**
+ * Function shape used to read text files during `--check`.
+ */
+export type ModelSnapshotFieldsScanCliReadFile = ScanCliBaseReadFile;
+/**
+ * Function shape used to write the produced manifest in write mode.
+ */
+export type ModelSnapshotFieldsScanCliWriteFile = ScanCliBaseWriteFile;
+/**
+ * Console-shaped sink for stdout and stderr lines.
+ */
+export type ModelSnapshotFieldsScanCliLogger = ScanCliBaseLogger;
+/**
+ * Input to {@link runModelSnapshotFieldsScanCli}.
+ */
+export type RunModelSnapshotFieldsScanCliInput = RunScanCliBaseInput<BuildModelSnapshotFieldsGlobber>;
+/**
+ * Result of one CLI invocation.
+ */
+export type RunModelSnapshotFieldsScanCliResult = RunScanCliResult;
+/**
+ * Runs one invocation of `scan-model-snapshot-fields`. Never throws on
+ * user errors — every failure path returns a structured exit code so
+ * callers can wire this into `process.exit` without try/catch.
+ *
+ * @param input - Argv plus injectable I/O hooks.
+ * @returns The CLI's exit code (0 on success, 1 on drift / build failure, 2 on usage error)
+ */
+export declare function runModelSnapshotFieldsScanCli(input: RunModelSnapshotFieldsScanCliInput): Promise<RunModelSnapshotFieldsScanCliResult>;

package/src/lib/mcp-scan/scan/model-snapshot-fields-extract.d.ts

@@ -0,0 +1,115 @@
+/**
+ * AST extraction for the `scan-model-snapshot-fields` generator.
+ *
+ * Walks every source file in the supplied ts-morph `Project` looking for
+ * top-level exported declarations (functions, `const` variable statements)
+ * tagged with the `@dbxModelSnapshotField` JSDoc marker. Each match is
+ * normalised into an {@link ExtractedModelSnapshotFieldEntry} that
+ * {@link buildModelSnapshotFieldsManifest} assembles into a
+ * `ModelSnapshotFieldManifest` entry.
+ *
+ * Optional sub-tags supply overrides that can't be reliably auto-derived
+ * (slug, category, tags, related slugs, skill refs, kind, optional flag).
+ * Sensible defaults are computed for each from the source — kebab-case of
+ * the export name, the parent folder of the source file, the export name +
+ * first JSDoc paragraph tokens, the `optional` name-prefix heuristic for
+ * `optionalFirestore*` variants, etc.
+ *
+ * Mirrors the `utils-extract.ts` shape one-to-one so the same scanner
+ * mental model applies. The differences:
+ *   - kind is restricted to `factory | const` (no class/function variants —
+ *     a snapshot field is always either a factory call or a pre-built const)
+ *   - an `optional: boolean` field is captured for the `optionalFirestore*`
+ *     name-prefix family so the lookup tool can flag required vs. optional
+ *     variants and the registry can cross-link them via `relatedSlugs`.
+ */
+import { type Project } from 'ts-morph';
+import type { ModelSnapshotFieldKindValue, ModelSnapshotFieldParamEntry } from '../manifest/model-snapshot-fields-schema.js';
+/**
+ * One snapshot-field entry extracted from a source file. Mirrors
+ * {@link ModelSnapshotFieldEntry} minus `module` (derived from the package
+ * being scanned in build-manifest) and `subpath` (also derived in
+ * build-manifest from the project root). `filePath` and `line` are kept for
+ * in-process warnings and never persisted to the manifest.
+ */
+export interface ExtractedModelSnapshotFieldEntry {
+    readonly slug: string;
+    readonly name: string;
+    readonly kind: ModelSnapshotFieldKindValue;
+    readonly category: string;
+    readonly signature: string;
+    readonly description: string;
+    readonly optional: boolean;
+    readonly params: readonly ModelSnapshotFieldParamEntry[];
+    readonly returns: string;
+    readonly tags: readonly string[];
+    readonly relatedSlugs?: readonly string[];
+    readonly skillRefs?: readonly string[];
+    readonly example: string;
+    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. Build-manifest collates these into a structured
+ * warning array so missing/invalid tag combinations surface during
+ * generation rather than silently dropping entries.
+ */
+export type ModelSnapshotFieldExtractWarning = {
+    readonly kind: 'unsupported-kind-override';
+    readonly name: string;
+    readonly override: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'missing-name';
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'duplicate-slug';
+    readonly name: string;
+    readonly slug: string;
+    readonly previousName: string;
+    readonly filePath: string;
+    readonly line: number;
+};
+/**
+ * Input to {@link extractModelSnapshotFieldEntries}. The caller is
+ * responsible for adding source files to `project`.
+ */
+export interface ExtractModelSnapshotFieldEntriesInput {
+    readonly project: Project;
+    /**
+     * Repo-relative project root (e.g. `packages/firebase`). The extractor
+     * uses this so it can drop the project prefix from the warning `filePath`
+     * fields and so the build-manifest layer can compute `subpath` against a
+     * stable base.
+     */
+    readonly projectRoot?: string;
+}
+/**
+ * Result of {@link extractModelSnapshotFieldEntries}.
+ */
+export interface ExtractModelSnapshotFieldEntriesResult {
+    readonly entries: readonly ExtractedModelSnapshotFieldEntry[];
+    readonly warnings: readonly ModelSnapshotFieldExtractWarning[];
+}
+/**
+ * Walks the supplied project and returns every export tagged with the
+ * `@dbxModelSnapshotField` 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 to scan.
+ * @returns The extracted entries plus any non-fatal warnings.
+ */
+export declare function extractModelSnapshotFieldEntries(input: ExtractModelSnapshotFieldEntriesInput): ExtractModelSnapshotFieldEntriesResult;
+/**
+ * Heuristic that flags `optionalFirestore*` exports as optional. The user
+ * can override this with `@dbxModelSnapshotFieldOptional false`.
+ *
+ * @param name - The export identifier.
+ * @returns True when the name signals an optional variant.
+ */
+export declare function deriveOptionalFromName(name: string): boolean;

package/src/lib/mcp-scan/scan/model-snapshot-fields-scan-config-schema.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Arktype schema for the `modelSnapshotFields` section of `dbx-mcp.scan.json`.
+ *
+ * Model-snapshot-fields scanning lives next to the existing semantic-types,
+ * ui-components, forge-fields, pipes, and utils sections — all use the same
+ * `dbx-mcp.scan.json` filename so a project that opts into multiple
+ * pipelines keeps a single config file. The CLI subcommand
+ * `scan-model-snapshot-fields` reads only the `modelSnapshotFields` field;
+ * sibling subcommands continue to read their own top-level fields unchanged.
+ */
+/**
+ * Inner config that drives one model-snapshot-fields 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 ModelSnapshotFieldsScanSection: import("arktype/internal/variants/object.ts").ObjectType<{
+    include: string[];
+    source?: string | undefined;
+    module?: string | undefined;
+    exclude?: string[] | undefined;
+    out?: string | undefined;
+}, {}>;
+/**
+ * Static type inferred from {@link ModelSnapshotFieldsScanSection}.
+ */
+export type ModelSnapshotFieldsScanSection = typeof ModelSnapshotFieldsScanSection.infer;
+/**
+ * Top-level shape used by the model-snapshot-fields builder. Only the
+ * `modelSnapshotFields` 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 ModelSnapshotFieldsScanConfig: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    modelSnapshotFields: {
+        include: string[];
+        source?: string | undefined;
+        module?: string | undefined;
+        exclude?: string[] | undefined;
+        out?: string | undefined;
+    };
+}, {}>;
+/**
+ * Static type inferred from {@link ModelSnapshotFieldsScanConfig}.
+ */
+export type ModelSnapshotFieldsScanConfig = typeof ModelSnapshotFieldsScanConfig.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_SNAPSHOT_FIELDS_SCAN_OUT_PATH = "model-snapshot-fields.mcp.generated.json";
+/**
+ * Filename the loader looks for at `${projectRoot}/`. Re-exported here so
+ * the model-snapshot-fields CLI does not have to import from a sibling scan
+ * config module.
+ */
+export declare const MODEL_SNAPSHOT_FIELDS_SCAN_CONFIG_FILENAME = "dbx-mcp.scan.json";

package/src/lib/mcp-scan/scan/pipes-build-manifest.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Orchestrator for the `scan-pipes` generator.
+ *
+ * Composes a complete {@link PipeManifest} from a project root by
+ *
+ *   1. reading `dbx-mcp.scan.json` against {@link PipesScanConfig}
+ *   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. extracting entries via {@link extractPipeEntries}
+ *   6. assembling the manifest envelope and validating it against
+ *      {@link PipeManifest}
+ *
+ * I/O is fully injectable so tests drive every code path without touching
+ * the real filesystem.
+ */
+import { PipeManifest } from '../manifest/pipes-schema.js';
+import { type PipeExtractWarning } from './pipes-extract.js';
+import { type ScanGlobber, type ScanReadFile } from '../../scan-helpers/scan-io.js';
+export type BuildPipesReadFile = ScanReadFile;
+export type BuildPipesGlobber = ScanGlobber;
+/**
+ * Input to {@link buildPipesManifest}.
+ */
+export interface BuildPipesManifestInput {
+    readonly projectRoot: string;
+    readonly generator: string;
+    readonly now?: () => Date;
+    readonly readFile?: BuildPipesReadFile;
+    readonly globber?: BuildPipesGlobber;
+}
+/**
+ * Outcome of one generator run. The success payload carries everything the
+ * caller needs to write the manifest to disk or run a freshness diff against
+ * an existing on-disk version.
+ */
+export type BuildPipesManifestOutcome = {
+    readonly kind: 'success';
+    readonly manifest: PipeManifest;
+    readonly outPath: string;
+    readonly scannedFileCount: number;
+    readonly extractWarnings: readonly PipeExtractWarning[];
+} | {
+    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 PipeManifest} 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 buildPipesManifest(input: BuildPipesManifestInput): Promise<BuildPipesManifestOutcome>;
+/**
+ * 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 serializePipeManifest(manifest: PipeManifest): string;