@dereekb/dbx-cli 13.15.0 → 13.17.0

package/src/lib/manifest/types.d.ts

@@ -150,6 +150,56 @@ export interface CliModelManifestEntry {
  * `<NAMESPACE>_MODEL_MANIFEST` of this type.
  */
 export type CliModelManifest = readonly CliModelManifestEntry[];
+/**
+ * One enum value with its persisted literal and the leading JSDoc paragraph.
+ *
+ * Mirrors the dbx-components MCP `FirebaseEnumValue` shape so the runtime MCP
+ * manifest carries the same value→label tables the design-time catalog builds.
+ */
+export interface CliModelEnumValue {
+    /**
+     * Enum member name (e.g. `ACTIVE`).
+     */
+    readonly name: string;
+    /**
+     * Raw persisted literal stored in Firestore (e.g. `1`, `'a'`).
+     */
+    readonly value: number | string;
+    /**
+     * First paragraph of the member's JSDoc, when present.
+     */
+    readonly description?: string;
+}
+/**
+ * One TypeScript enum referenced by some model field's `enumRef`, captured so
+ * the runtime `model-info` / `enum-info` tools can decode raw integer/string
+ * values without dropping into source.
+ *
+ * Mirrors the dbx-components MCP `FirebaseEnum` shape.
+ */
+export interface CliModelEnum {
+    /**
+     * Enum declaration name (e.g. `JobWorkerTimesheetState`).
+     */
+    readonly name: string;
+    /**
+     * Value table in source order.
+     */
+    readonly values: readonly CliModelEnumValue[];
+    /**
+     * First paragraph of the enum declaration's JSDoc, when present.
+     */
+    readonly description?: string;
+}
+/**
+ * Generated map of {@link CliModelEnum} keyed by enum name, scoped to enums
+ * referenced by some emitted model field's `enumRef`. Each downstream CLI app
+ * exports its own `<NAMESPACE>_ENUM_MANIFEST` of this type; keying by name lets
+ * the runtime do O(1) lookups for both `model-info` and `enum-info`.
+ */
+export type CliEnumManifest = {
+    readonly [enumName: string]: CliModelEnum;
+};
 export type CliApiVerb = 'create' | 'read' | 'update' | 'delete' | 'query' | 'invoke' | 'standalone';
 export interface CliApiManifestField {
     readonly name: string;
@@ -329,6 +379,8 @@ export interface McpManifestAuth {
  *
  * `tools` is keyed by {@link mcpManifestKey} so the runtime can do O(1) lookups per registered tool.
  * `models` is optional — the runtime skips the catalog-introspection tools when missing.
+ * `enums` is optional — keyed by enum name, it carries the value→label tables `model-info` /
+ * `enum-info` decode. Scoped to enums referenced by some model field's `enumRef`.
  * `auth` is optional — drives the runtime `whoami` tool.
  */
 export interface McpManifest {
@@ -341,6 +393,7 @@ export interface McpManifest {
         readonly [key: string]: McpManifestToolEntry | undefined;
     };
     readonly models?: readonly McpManifestModelEntry[];
+    readonly enums?: CliEnumManifest;
     readonly auth?: McpManifestAuth;
 }
 /**

package/src/lib/mcp-scan/manifest/package-root.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared package-root resolver for the MCP-scan registry loaders.
+ *
+ * Every `load-*-registry.ts` resolves the bundled manifest it ships in its
+ * package's `generated/` directory by walking up from the module's own URL
+ * until a `package.json` appears. Centralizing the walk here keeps each
+ * loader free of the duplicated traversal.
+ */
+/**
+ * Walks up from the directory of `startUrl` until it finds a directory that
+ * contains a `package.json`, returning that directory.
+ *
+ * @param startUrl - An `import.meta.url` from a module inside the package.
+ * @returns The absolute path of the nearest ancestor directory holding a `package.json`.
+ * @throws {Error} If no `package.json` is found before reaching the filesystem root.
+ */
+export declare function findPackageRoot(startUrl: string): string;

package/src/lib/mcp-scan/manifest/tokens-schema.d.ts

@@ -25,9 +25,10 @@ export type TokenRoleValue = (typeof TOKEN_ROLES)[number];
 /**
  * Origin of a token — used for filtering (`category=mat-sys`) and to indicate
  * authoritative source. `dbx-web` aliases live alongside `mat-sys` system
- * values; downstream apps surface as `app`.
+ * values; `dbx-form` carries the form package's component-scoped tokens;
+ * downstream apps surface as `app`.
  */
-export declare const TOKEN_SOURCES: readonly ["dbx-web", "mat-sys", "mdc", "app"];
+export declare const TOKEN_SOURCES: readonly ["dbx-web", "dbx-form", "mat-sys", "mdc", "app"];
 /**
  * Static type for the closed token-source vocabulary.
  */
@@ -56,7 +57,7 @@ export type TokenDefaults = typeof TokenDefaults.infer;
  */
 export declare const TokenEntry: import("arktype/internal/variants/object.ts").ObjectType<{
     cssVariable: string;
-    source: "app" | "dbx-web" | "mat-sys" | "mdc";
+    source: "app" | "dbx-web" | "dbx-form" | "mat-sys" | "mdc";
     role: "breakpoint" | "size" | "misc" | "spacing" | "color" | "text-color" | "surface" | "radius" | "elevation" | "shadow" | "typography" | "motion" | "state-layer";
     intents: string[];
     description: string;
@@ -94,7 +95,7 @@ export declare const TokenManifest: import("arktype/internal/variants/object.ts"
     generator: string;
     entries: {
         cssVariable: string;
-        source: "app" | "dbx-web" | "mat-sys" | "mdc";
+        source: "app" | "dbx-web" | "dbx-form" | "mat-sys" | "mdc";
         role: "breakpoint" | "size" | "misc" | "spacing" | "color" | "text-color" | "surface" | "radius" | "elevation" | "shadow" | "typography" | "motion" | "state-layer";
         intents: string[];
         description: string;

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

@@ -103,3 +103,20 @@ export interface SubObjectConstEntry {
  * @returns The assembled models and groups for the file.
  */
 export declare function assembleFile(input: AssembleFileInput): AssembledFile;
+interface SubObjectResolution {
+    readonly interfaceName: string;
+    readonly factoryKind: FirebaseSubObject['factoryKind'];
+}
+/**
+ * Resolves a field's (whitespace-collapsed) converter expression to the sub-object interface +
+ * factory kind it expands into. Recognises the inline generic form, the wrapped
+ * `firestoreObjectArray({ ... objectField|firestoreField: <const> })` form (the `firestoreField`
+ * carrier may sit behind sibling props), the inline `firestoreField: firestoreSubObject<T>({...})`
+ * form, and a bare sub-object const reference. Exported for focused unit testing.
+ *
+ * @param converter - The canonical converter expression text.
+ * @param index - The cross-file sub-object const index.
+ * @returns The resolved interface + factory kind, or `undefined` when the converter references no known sub-object.
+ */
+export declare function resolveSubObjectReference(converter: string, index: ReadonlyMap<string, SubObjectConstEntry>): SubObjectResolution | undefined;
+export {};

package/src/lib/route/component-resolve.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure component-source resolution: given a router file's text and a rendered
+ * component class name, find the source file that declares the component among
+ * an already-loaded set of {@link RouteSource} records.
+ *
+ * Unlike the dev-server tool's fs-backed resolver, this works entirely against
+ * the in-memory source set the route-manifest builder already gathered, so it
+ * performs no disk I/O. Path arithmetic uses POSIX semantics because source
+ * names are workspace-relative, slash-delimited paths.
+ */
+import type { RouteSource } from './route-types.js';
+/**
+ * Resolved component source location. `path` is the matched source name when
+ * the import resolved inside the source set, or the raw module specifier when
+ * it could not be resolved (e.g. a node-module / barrel import).
+ */
+export interface ComponentSourceResult {
+    readonly path: string;
+    readonly moduleSpecifier: string;
+}
+/**
+ * Input to {@link resolveComponentSourceFromSources}.
+ */
+export interface ResolveComponentSourceInput {
+    /**
+     * Source name of the file that declares the state (and imports the component).
+     */
+    readonly routerFile: string;
+    /**
+     * Component class name rendered by the state.
+     */
+    readonly component: string;
+    /**
+     * The full in-memory source set the manifest builder gathered.
+     */
+    readonly sources: readonly RouteSource[];
+}
+/**
+ * Resolves the source file that declares `component`, traced from its import in
+ * the router file. Returns `undefined` when the router file isn't in the set or
+ * the component isn't imported there; returns the raw specifier as `path` when
+ * the import is non-relative (node module / path alias) or can't be matched to
+ * a loaded source.
+ *
+ * @param input - The router file name, component class, and source set.
+ * @returns The resolved component source location, or `undefined`.
+ */
+export declare function resolveComponentSourceFromSources(input: ResolveComponentSourceInput): ComponentSourceResult | undefined;

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

@@ -0,0 +1,18 @@
+/**
+ * UIRouter route-extraction core, shared by the dev MCP server
+ * (`@dereekb/dbx-components-mcp`'s `dbx_route_*` tools) and the build-time
+ * `dbx-cli-generate-route-manifest` binary.
+ *
+ * The fs/glob I/O layer lives in each caller — this core operates on in-memory
+ * {@link RouteSource} records and produces a normalized {@link RouteTree}, plus
+ * a pure URL matcher and component-source resolver.
+ */
+export * from './route-types.js';
+export * from './route-extract.js';
+export * from './route-build-tree.js';
+export * from './route-resolve-sources.js';
+export * from './route-load-tree.js';
+export * from './url-match.js';
+export * from './component-resolve.js';
+export * from './route-models-extract.js';
+export * from './route-manifest.js';

package/src/lib/route/route-build-tree.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Builds a parent-linked {@link RouteTree} from a flat list of {@link RouteNode}s.
+ *
+ * Linkage strategy:
+ *
+ *   1. Use the explicit `parent` field if present.
+ *   2. Otherwise derive parent from the dot-prefix of `name`. State `a.b.c`
+ *      becomes a child of `a.b`. Trailing `.**` is stripped before lookup.
+ *   3. Nodes whose parent doesn't resolve are reported as orphan warnings and
+ *      placed at the tree root.
+ *
+ * Issues surfaced:
+ *
+ *   - `DUPLICATE_STATE_NAME` — error; second declaration is dropped.
+ *   - `CYCLE_DETECTED` — error; the cycle is broken by reverting the tail to
+ *     the root list.
+ *   - `ORPHAN_STATE` — warning.
+ */
+import type { RouteIssue, RouteNode, RouteTree } from './route-types.js';
+/**
+ * Builds the parent-child UIRouter tree from a flat node list, computing each
+ * state's full URL while preserving any extraction issues so callers see one
+ * combined diagnostics view.
+ *
+ * @param nodes - The flat route nodes extracted from sources.
+ * @param extractIssues - Issues already discovered during extraction to forward.
+ * @returns The constructed tree alongside the merged issue list.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function buildRouteTree(nodes: readonly RouteNode[], extractIssues: readonly RouteIssue[]): RouteTree;

package/src/lib/route/route-extract.d.ts

@@ -0,0 +1,46 @@
+/**
+ * AST extraction for the route core.
+ *
+ * Parses one TypeScript source file with ts-morph and emits a list of
+ * {@link RouteNode}s plus any issues surfaced during extraction.
+ *
+ * Recognized shapes (all syntactic — no type resolution):
+ *
+ *   1. Top-level `const x: Ng2StateDeclaration = { ... }` — single-state.
+ *   2. Top-level array literals of state objects (`const STATES = [a, b]` or
+ *      `const STATES: Ng2StateDeclaration[] = [...]`) — every element is
+ *      either an inline object literal or an identifier referencing one of
+ *      the single-state consts above. Identifier refs are resolved within the
+ *      same file.
+ *   3. `provideStates({ states: [...] })` — element shape matches (2).
+ *   4. `UIRouterModule.forChild({ states: [...] })` — same.
+ *
+ * `@dbxRouteModel*` JSDoc tags on a typed state const's `export const` are
+ * captured onto {@link RouteNode.jsDocTags}; the route-manifest builder reads
+ * them to augment / override the component-level model annotations.
+ *
+ * Pure ts-morph in-memory project, no tsconfig, no fs reads. The caller is
+ * responsible for funnelling files in.
+ */
+import type { RouteIssue, RouteNode, RouteSource } from './route-types.js';
+export interface ExtractFileResult {
+    readonly nodes: readonly RouteNode[];
+    readonly issues: readonly RouteIssue[];
+    /**
+     * Identifiers that this file imports — used by `route-resolve-sources.ts` to walk transitively.
+     */
+    readonly importedFromRelative: readonly RelativeImport[];
+}
+export interface RelativeImport {
+    readonly moduleSpecifier: string;
+    readonly file: string;
+}
+/**
+ * Extracts every UIRouter state declaration from a single source file plus any
+ * extraction-time diagnostics. Best-effort: malformed states surface as issues
+ * rather than throwing so the rest of the file still contributes nodes.
+ *
+ * @param source - The in-memory source name + text pair to extract.
+ * @returns The discovered route nodes alongside extraction issues.
+ */
+export declare function extractFile(source: RouteSource): ExtractFileResult;

package/src/lib/route/route-load-tree.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure tree-loading entry point. The fs/glob I/O layer lives in the caller —
+ * this module receives a list of {@link RouteSource} records and produces a
+ * normalized {@link RouteTree}.
+ */
+import type { RouteSource, RouteTree } from './route-types.js';
+export interface LoadRouteTreeArgs {
+    readonly sources: readonly RouteSource[];
+}
+/**
+ * Pure tree-loading entry point. Resolves the supplied source list and builds
+ * the parent/child tree in one step so callers can stay thin.
+ *
+ * @param args - The in-memory sources to process.
+ * @returns The constructed route tree with extraction issues attached.
+ */
+export declare function loadRouteTree(args: LoadRouteTreeArgs): RouteTree;

package/src/lib/route/route-manifest.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Build-time route manifest: the authoritative schema + builder that the
+ * `dbx-cli-generate-route-manifest` binary serializes to `route.manifest.json`.
+ *
+ * The firebase-server/mcp runtime mirrors this schema in
+ * `service/mcp.route-manifest.ts` (it does NOT import this package); both bump
+ * {@link ROUTE_MANIFEST_VERSION} together when the shape changes.
+ *
+ * The builder runs the route extractor over the app sources, drops future-state
+ * (`.**`) nodes, resolves each rendered component's `@dbxRouteModel*` tags,
+ * merges them with the state const's own tags, pre-flattens ancestor
+ * inheritance (recording each inherited entry's `from`), and emits a flat,
+ * name-sorted state array. Warnings are collected but never throw — the
+ * generator writes the manifest and logs them.
+ */
+import { type RouteModelKind } from './route-models-extract.js';
+import type { RouteSource } from './route-types.js';
+/**
+ * Version stamp embedded in `route.manifest.json`. Runtime loaders refuse
+ * manifests whose `version` does not match. Mirror in firebase-server/mcp's
+ * `ROUTE_MANIFEST_VERSION` — bump both together.
+ */
+export declare const ROUTE_MANIFEST_VERSION: 1;
+/**
+ * One model an app page renders, after tag parsing + inheritance flattening.
+ */
+export interface RouteManifestModelEntry {
+    readonly modelType: string;
+    readonly kind: RouteModelKind;
+    /**
+     * Verbatim key template (`:uid`, `{authUid}`, `gb/:id/gbe/{authUid}`). Absent
+     * for `list` entries.
+     */
+    readonly keyTemplate?: string;
+    readonly description?: string;
+    /**
+     * When the entry was inherited from an ancestor state, that ancestor's name.
+     * Absent for a state's own (component + state-tag) models.
+     */
+    readonly from?: string;
+}
+/**
+ * One UIRouter state, with inheritance pre-flattened into `models`.
+ */
+export interface RouteManifestStateEntry {
+    readonly name: string;
+    readonly url?: string;
+    readonly fullUrl?: string;
+    readonly parentName?: string;
+    readonly paramKeys: readonly string[];
+    readonly urlParamKeys: readonly string[];
+    readonly component?: string;
+    readonly componentFile?: string;
+    readonly abstract?: boolean;
+    readonly redirectTo?: string;
+    readonly models: readonly RouteManifestModelEntry[];
+}
+/**
+ * The full `route.manifest.json` shape consumed at runtime by the `url-models`
+ * tool. `states` is a flat array (inheritance pre-flattened at build).
+ */
+export interface RouteManifest {
+    readonly version: typeof ROUTE_MANIFEST_VERSION;
+    readonly generatedAt: string;
+    readonly app: {
+        readonly name: string;
+        readonly baseUrl?: string;
+    };
+    readonly states: readonly RouteManifestStateEntry[];
+}
+/**
+ * Kinds of non-fatal finding surfaced while building the manifest.
+ */
+export type RouteManifestWarningKind = 'malformed-tag' | 'unknown-route-param' | 'unknown-model-type' | 'duplicate-route-model' | 'dropped-future-state' | 'missing-route-model';
+/**
+ * Severity of a {@link RouteManifestWarning}. `error`-severity findings fail
+ * manifest generation (and CI via the build dependency); `warning`-severity
+ * findings are logged but do not block.
+ */
+export type RouteManifestSeverity = 'error' | 'warning';
+export interface RouteManifestWarning {
+    readonly kind: RouteManifestWarningKind;
+    readonly severity: RouteManifestSeverity;
+    readonly message: string;
+    readonly stateName?: string;
+    readonly modelType?: string;
+    /**
+     * The id-like route param a `missing-route-model` finding refers to (`:id` →
+     * `id`). Absent for other warning kinds.
+     */
+    readonly param?: string;
+}
+/**
+ * App identity stamped onto the manifest.
+ */
+export interface BuildRouteManifestApp {
+    readonly name: string;
+    readonly baseUrl?: string;
+}
+/**
+ * Input to {@link buildRouteManifest}.
+ */
+export interface BuildRouteManifestInput {
+    readonly app: BuildRouteManifestApp;
+    readonly sources: readonly RouteSource[];
+    /**
+     * Known Firestore model types for `unknown-model-type` validation. When
+     * omitted (no `--models-input`), the check is skipped.
+     */
+    readonly modelTypes?: readonly string[];
+}
+/**
+ * Output of {@link buildRouteManifest}: the rendered manifest plus the
+ * accumulated warnings.
+ */
+export interface BuildRouteManifestResult {
+    readonly manifest: RouteManifest;
+    readonly warnings: readonly RouteManifestWarning[];
+}
+/**
+ * Builds the route manifest from a set of app sources.
+ *
+ * @param input - The app identity, source set, and optional model-type catalog.
+ * @param now - Override for the `generatedAt` timestamp (tests pass a fixed value).
+ * @returns The rendered manifest and the collected warnings.
+ *
+ * @example
+ * ```ts
+ * const { manifest, warnings } = buildRouteManifest({ app: { name: 'demo' }, sources });
+ * ```
+ */
+export declare function buildRouteManifest(input: BuildRouteManifestInput, now?: Date): BuildRouteManifestResult;

package/src/lib/route/route-model-tag.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure parser for the `@dbxRouteModel` / `@dbxRouteModelList` JSDoc tag grammar
+ * that annotates which Firestore models a route renders.
+ *
+ * Grammar:
+ *
+ * ```
+ * @dbxRouteModel <modelType> <keyTemplate> [- <description>]
+ * @dbxRouteModelList <modelType> [- <description>]
+ * ```
+ *
+ * `keyTemplate` shapes:
+ * - `:param` / `{authUid}` — single placeholder → `kind: 'id'` (the value is
+ *   promoted to `<collectionName>/<id>` at runtime via the model identity).
+ * - `gb/:id/gbe/{authUid}` — alternating literal / placeholder segments (even
+ *   count) → `kind: 'key'` (a full FirestoreModelKey for a subcollection model).
+ * - (absent, list tag) → `kind: 'list'`.
+ *
+ * This module is deliberately runtime-dependency-free (no ts-morph): the same
+ * grammar is reused by the build-time manifest builder, the dev MCP route tools,
+ * and the `@dereekb/dbx-cli/eslint` rule so they can never disagree about what a
+ * valid tag is. The ts-morph consumer (`extractComponentRouteModelTags`) lives in
+ * `./route-models-extract.ts` and re-exports these symbols for existing importers.
+ */
+/**
+ * Whether a route-model entry resolves to a promoted id, a full key, or a
+ * keyless list.
+ */
+export type RouteModelKind = 'id' | 'key' | 'list';
+/**
+ * A successfully parsed `@dbxRouteModel*` tag.
+ */
+export interface ParsedRouteModel {
+    readonly modelType: string;
+    readonly kind: RouteModelKind;
+    /**
+     * The verbatim key template (`:uid`, `{authUid}`, `gb/:id/gbe/{authUid}`).
+     * Absent for `list` entries.
+     */
+    readonly keyTemplate?: string;
+    readonly description?: string;
+    /**
+     * Route param names (`:name` → `name`) referenced by the key template, for
+     * `unknown-route-param` validation against the state's URL params.
+     */
+    readonly routeParams: readonly string[];
+}
+/**
+ * Result of parsing one route-model tag: the parsed model or a malformed-tag
+ * message describing why it could not be parsed.
+ */
+export type ParseRouteModelTagResult = {
+    readonly ok: true;
+    readonly model: ParsedRouteModel;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * One raw `@dbxRouteModel*` tag — the tag name (without `@`) plus its trimmed
+ * comment text.
+ */
+export interface RawRouteModelTag {
+    readonly name: string;
+    readonly text: string;
+}
+/**
+ * The bare `@dbxRouteModel` tag name (without the leading `@`).
+ */
+export declare const ROUTE_MODEL_TAG = "dbxRouteModel";
+/**
+ * The `@dbxRouteModelList` tag name (without the leading `@`).
+ */
+export declare const ROUTE_MODEL_LIST_TAG = "dbxRouteModelList";
+/**
+ * Parses one `@dbxRouteModel` / `@dbxRouteModelList` tag into a structured
+ * model, or returns a malformed-tag message. The description (everything after
+ * the first ` - `) is split off first; the remaining head is tokenized.
+ *
+ * @param tag - The raw tag name + comment text.
+ * @returns The parsed model on success, else a malformed-tag message.
+ *
+ * @example
+ * ```ts
+ * parseRouteModelTag({ name: 'dbxRouteModel', text: 'profile :uid - The profile' });
+ * // => { ok: true, model: { modelType: 'profile', kind: 'id', keyTemplate: ':uid', description: 'The profile', routeParams: ['uid'] } }
+ * ```
+ */
+export declare function parseRouteModelTag(tag: RawRouteModelTag): ParseRouteModelTagResult;

package/src/lib/route/route-models-extract.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ts-morph consumer of the `@dbxRouteModel` / `@dbxRouteModelList` grammar.
+ *
+ * The pure grammar parser lives in `./route-model-tag.ts` (zero ts-morph) so it
+ * can be reused by the `@dereekb/dbx-cli/eslint` rule without dragging ts-morph
+ * into a bundled ESLint plugin. This module reads the tags off a ts-morph
+ * `SourceFile` and re-exports the grammar symbols so existing importers
+ * (`route-manifest.ts`, the route barrel) keep working unchanged.
+ */
+import type { SourceFile } from 'ts-morph';
+import { type RawRouteModelTag } from './route-model-tag.js';
+export { parseRouteModelTag, ROUTE_MODEL_TAG, ROUTE_MODEL_LIST_TAG, type RawRouteModelTag, type ParseRouteModelTagResult, type ParsedRouteModel, type RouteModelKind } from './route-model-tag.js';
+/**
+ * Extracts every `@dbxRouteModel*` tag declared on the named component class in
+ * a source file. Returns an empty list when the class is absent or carries no
+ * route-model tags.
+ *
+ * @param sourceFile - The ts-morph source file declaring the component.
+ * @param component - The component class name to read tags from.
+ * @returns The raw route-model tags found on the class.
+ */
+export declare function extractComponentRouteModelTags(sourceFile: SourceFile, component: string): readonly RawRouteModelTag[];

package/src/lib/route/route-resolve-sources.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Helpers for transitive resolution across multiple route sources.
+ *
+ * Two flavors:
+ *
+ *   1. {@link resolveRouteSources} — walks every supplied source and emits a
+ *      flat node list. Used when the caller already gathered a glob/path set.
+ *   2. {@link computeRelativeSpecifiers} — given a starting source, returns
+ *      the relative import specifiers it depends on. The off-disk loader uses
+ *      this to walk the file tree.
+ *
+ * The pure core never touches the file system — the caller does the
+ * `readFile`-and-recurse loop, calling back into {@link extractFile} for each
+ * file it loads.
+ */
+import type { RouteIssue, RouteNode, RouteSource } from './route-types.js';
+export interface ResolvedSources {
+    readonly nodes: readonly RouteNode[];
+    readonly issues: readonly RouteIssue[];
+    readonly filesChecked: number;
+}
+/**
+ * Walks every supplied source through the extractor and emits a flat node and
+ * issue list, used when the caller has already gathered a complete glob/file
+ * set in memory.
+ *
+ * @param sources - The in-memory sources to extract from.
+ * @returns The merged extraction nodes, issues, and processed file count.
+ */
+export declare function resolveRouteSources(sources: readonly RouteSource[]): ResolvedSources;
+/**
+ * Returns the relative module specifiers imported by `source` — used to plan
+ * the next round of file reads in transitive walking. Specifiers are
+ * left untouched (no `.ts` resolution); the caller normalizes them.
+ *
+ * @param source - The in-memory source to inspect.
+ * @returns The relative specifiers in original-source order.
+ */
+export declare function computeRelativeSpecifiers(source: RouteSource): readonly string[];