@dereekb/dbx-cli 13.15.0 → 13.17.0

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

@@ -0,0 +1,136 @@
+/**
+ * Shared types for the UIRouter route-extraction core.
+ *
+ * Originally lived in `@dereekb/dbx-components-mcp` behind the `dbx_route_*`
+ * tools; lifted here so both the dev MCP server and the build-time
+ * `dbx-cli-generate-route-manifest` binary share one extractor.
+ *
+ * The core is validator-style: it reads TypeScript source and extracts the
+ * UIRouter state tree by syntactic analysis. No DI graph evaluation; we record
+ * class-name references as strings.
+ *
+ * Routes are described as a flat list of {@link RouteNode}s during extraction
+ * and turned into a parent-linked {@link RouteTree} by `route-build-tree.ts`.
+ */
+/**
+ * One file's raw contents passed into the route extractor. Callers reading
+ * paths or globs off disk resolve them to this shape before calling into the
+ * core.
+ */
+export interface RouteSource {
+    readonly name: string;
+    readonly text: string;
+}
+/**
+ * Stable issue codes so consumers can suppress or interpret individual
+ * findings without string-matching the message text.
+ */
+export type RouteIssueCode = 'DUPLICATE_STATE_NAME' | 'CYCLE_DETECTED' | 'ORPHAN_STATE' | 'UNRESOLVED_COMPONENT' | 'DYNAMIC_STATE_NAME' | 'NO_STATES_FOUND';
+/**
+ * Severity of a route issue. Errors fail the tool call (`isError: true`);
+ * warnings are surfaced but the tree still renders.
+ */
+export type RouteIssueSeverity = 'error' | 'warning' | 'info';
+export interface RouteIssue {
+    readonly code: RouteIssueCode;
+    readonly severity: RouteIssueSeverity;
+    readonly message: string;
+    readonly file: string | undefined;
+    readonly line: number | undefined;
+    readonly stateName: string | undefined;
+}
+/**
+ * A single JSDoc tag captured from a state declaration's `export const`
+ * documentation. `name` is the tag name without the leading `@`
+ * (e.g. `dbxRouteModel`); `text` is the trimmed remainder of the tag line.
+ */
+export interface RouteNodeJsDocTag {
+    readonly name: string;
+    readonly text: string;
+}
+/**
+ * A single state declaration extracted from a `Ng2StateDeclaration` object
+ * literal. Field names mirror UIRouter's state-config shape; `name` is always
+ * populated, every other field is optional.
+ *
+ * `name` may carry a trailing `.**` (UIRouter future-state marker). We keep it
+ * verbatim for fidelity but strip the marker when computing parent linkage.
+ */
+export interface RouteNode {
+    readonly name: string;
+    readonly url: string | undefined;
+    readonly component: string | undefined;
+    /**
+     * Explicit `parent` field if set; otherwise undefined (parent is derived from the dot-prefix of `name`).
+     */
+    readonly explicitParent: string | undefined;
+    readonly redirectTo: string | undefined;
+    readonly abstract: boolean;
+    /**
+     * `name` ends with `.**` — UIRouter lazy/future-state marker.
+     */
+    readonly futureState: boolean;
+    /**
+     * Names of declared params (object keys only).
+     */
+    readonly paramKeys: readonly string[];
+    /**
+     * Names of declared resolves (object keys, or array element identifiers).
+     */
+    readonly resolveKeys: readonly string[];
+    /**
+     * Source file the state was defined in.
+     */
+    readonly file: string;
+    readonly line: number;
+    /**
+     * Identifier of the `export const` (or `const`) the state object literal is
+     * assigned to, when the state was declared as `const FOO: Ng2StateDeclaration = { ... }`.
+     * `undefined` for inline literals inside a `STATES` array or
+     * `provideStates({ states: [...] })` call.
+     */
+    readonly declaredAs: string | undefined;
+    /**
+     * `@dbxRouteModel*` JSDoc tags captured from the declaring `export const`'s
+     * documentation, when the state was declared as a typed const. Used by the
+     * route-manifest builder to augment / override the component-level model
+     * annotations. `undefined` for inline literals or consts without route-model
+     * tags.
+     */
+    readonly jsDocTags: readonly RouteNodeJsDocTag[] | undefined;
+}
+/**
+ * A node in the resolved {@link RouteTree}. Children are linked by a parent
+ * pass; the original {@link RouteNode} is preserved on `data`.
+ */
+export interface RouteTreeNode {
+    readonly data: RouteNode;
+    /**
+     * Composed URL from root → this node, or `undefined` if any segment is missing.
+     */
+    readonly fullUrl: string | undefined;
+    readonly parent: RouteTreeNode | undefined;
+    readonly children: readonly RouteTreeNode[];
+}
+export interface RouteTree {
+    /**
+     * Top-level nodes (no resolvable parent in the source set).
+     */
+    readonly roots: readonly RouteTreeNode[];
+    /**
+     * Every node, indexed by state name.
+     */
+    readonly byName: ReadonlyMap<string, RouteTreeNode>;
+    /**
+     * Issues surfaced during extraction or tree building.
+     */
+    readonly issues: readonly RouteIssue[];
+    /**
+     * Files actually parsed (after import-walking).
+     */
+    readonly filesChecked: number;
+    /**
+     * Total nodes in the tree.
+     */
+    readonly nodeCount: number;
+}

package/src/lib/route/url-match.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Pure URL ↔ route matcher, shared by the dev-server `dbx_route_resolve_url`
+ * tool and (mirrored, not imported) by the firebase-server/mcp `url-models`
+ * runtime tool.
+ *
+ * No ts-morph, no node:fs — operates on a flat list of candidates each carrying
+ * a composed `fullUrl` and an opaque `value`. Matching mirrors UIRouter's
+ * literal-then-param preference: a literal segment-for-segment match wins over a
+ * parameterised one, and ties at either tier collapse to an `ambiguous` result.
+ */
+/**
+ * One candidate fed to {@link matchUrlAgainstEntries}: a composed URL pattern
+ * plus the opaque payload to return when it matches.
+ */
+export interface UrlMatchEntry<T> {
+    readonly fullUrl: string | undefined;
+    readonly value: T;
+}
+/**
+ * A single resolved match. `via` distinguishes a literal path match from a
+ * parameterised one; `params` carries the captured `:param` / `{param}` values
+ * (empty for literal matches).
+ */
+export interface UrlMatchMatch<T> {
+    readonly kind: 'match';
+    readonly via: 'literal' | 'param';
+    readonly value: T;
+    readonly matchedFullUrl: string;
+    readonly params: Readonly<Record<string, string>>;
+}
+/**
+ * More than one candidate matched at the same tier; the caller must
+ * disambiguate (or report the tie).
+ */
+export interface UrlMatchAmbiguous<T> {
+    readonly kind: 'ambiguous';
+    readonly values: readonly T[];
+}
+/**
+ * No candidate matched. `candidates` holds the closest scored near-misses
+ * (top 5) for a "did you mean" style hint.
+ */
+export interface UrlMatchNone<T> {
+    readonly kind: 'none';
+    readonly candidates: readonly T[];
+}
+export type UrlMatchResult<T> = UrlMatchMatch<T> | UrlMatchAmbiguous<T> | UrlMatchNone<T>;
+/**
+ * Input to {@link matchUrlAgainstEntries}.
+ */
+export interface MatchUrlAgainstEntriesInput<T> {
+    readonly entries: readonly UrlMatchEntry<T>[];
+    readonly pathname: string;
+}
+/**
+ * Collapses an empty pathname to `/` and strips a single trailing slash so
+ * `/a/b/` and `/a/b` compare equal.
+ *
+ * @param pathname - The raw pathname to normalize.
+ * @returns The normalized pathname.
+ */
+export declare function normalizePathname(pathname: string): string;
+/**
+ * Splits a path into its non-empty segments (the leading slash is dropped).
+ *
+ * @param path - The path or URL pattern to split.
+ * @returns The ordered segment list, empty for `/`.
+ */
+export declare function splitSegments(path: string): readonly string[];
+/**
+ * Whether a composed URL contains at least one `:param` or `{param}` segment.
+ *
+ * @param path - The composed URL pattern.
+ * @returns `true` when the pattern declares a parameter.
+ */
+export declare function hasParamSegment(path: string): boolean;
+/**
+ * Attempts a segment-for-segment match of a route pattern against concrete
+ * input segments. `:name` and `{name}` / `{name:type}` segments capture the
+ * input value (URL-decoded); literal segments must match exactly.
+ *
+ * @param route - The route pattern's segments.
+ * @param input - The concrete URL's segments.
+ * @returns The captured params when every segment matches, else `undefined`.
+ */
+export declare function tryMatchSegments(route: readonly string[], input: readonly string[]): Readonly<Record<string, string>> | undefined;
+/**
+ * Extracts param-name segments from a composed UIRouter URL. Recognises:
+ * - `:name` (Express-style)
+ * - `{name}` (UIRouter type-less)
+ * - `{name:type}` and `{name:regex}` (UIRouter typed / regex)
+ * Order is preserved; duplicates are de-duplicated by first occurrence.
+ *
+ * @param fullUrl - Composed URL (e.g. `/{orgId}/users/:userId`) or undefined.
+ * @returns The param key list in declaration order, or an empty array.
+ */
+export declare function extractUrlParamKeys(fullUrl: string | undefined): readonly string[];
+/**
+ * Matches a pathname against a flat candidate list, preferring a literal
+ * (exact composed-URL) match over a parameterised one. A tie at either tier
+ * collapses to `ambiguous`; otherwise the closest near-misses are scored and
+ * returned in a `none` result.
+ *
+ * @param input - The candidate entries and the pathname to resolve.
+ * @returns A discriminated match / ambiguous / none result.
+ */
+export declare function matchUrlAgainstEntries<T>(input: MatchUrlAgainstEntriesInput<T>): UrlMatchResult<T>;
+/**
+ * Scores every candidate by shared leading segments (literal segment = 2,
+ * param segment = 1, mismatch stops scoring) and returns the top 5 values.
+ *
+ * @param entries - The candidate entries to score.
+ * @param pathname - The pathname being resolved.
+ * @returns Up to five closest candidate values, best first.
+ */
+export declare function scoreCandidates<T>(entries: readonly UrlMatchEntry<T>[], pathname: string): readonly T[];

package/src/lib/scan-helpers/firestore-model-extract-utils.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure ts-morph helpers shared by the two Firestore-model extractors that
+ * mirror `scripts/extract-firebase-models.mjs`: the rich `mcp-scan` walker in
+ * this package (`mcp-scan/scan/extract-models/*`) and the lightweight
+ * per-file walker in the `@dereekb/dbx-cli/manifest-extract` sub-lib. Both
+ * reimplemented the identical `firestoreModelIdentity(...)` argument parsing
+ * and `extends` passthrough-wrapper peeling; centralizing them here keeps the
+ * two extractors in lock-step without duplicating the logic.
+ */
+import { Node, type ExpressionWithTypeArguments } from 'ts-morph';
+/**
+ * The model-type, collection-prefix, and parent-identity const parsed out of a
+ * `firestoreModelIdentity(...)` call by {@link parseFirestoreModelIdentityArgs}.
+ */
+export interface ParsedModelIdentityArgs {
+    readonly modelType: string;
+    readonly collectionPrefix: string | undefined;
+    readonly parentIdentityConst: string | undefined;
+}
+/**
+ * Parses the arguments of a `firestoreModelIdentity(...)` call into its
+ * model-type / prefix / parent-identity parts, handling the 1/2/3-arg shapes:.
+ *
+ *   • `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 args - The call's argument nodes (e.g. `call.getArguments()`).
+ * @returns The parsed parts, or `undefined` when the shape is unrecognisable.
+ */
+export declare function parseFirestoreModelIdentityArgs(args: readonly Node[]): ParsedModelIdentityArgs | undefined;
+/**
+ * Resolves an `extends` clause to the concrete ancestor interface name,
+ * peeling any leading {@link PASSTHROUGH_TYPE_WRAPPERS}. Returns the leftmost
+ * identifier of the unwrapped expression so the inheritance walker can chain
+ * through utility-wrapped declarations like
+ * `extends Partial<MaybeMap<Omit<Base, '…'>>>`.
+ *
+ * @param expr - The `ExpressionWithTypeArguments` produced by `getExtends()`
+ * @returns The resolved interface name, or the original leftmost identifier when no inner reference is reachable.
+ */
+export declare function resolveExtendsName(expr: ExpressionWithTypeArguments): string;

package/test/index.cjs.js

@@ -335,7 +335,7 @@ function _ts_generator(thisArg, body) {
                 case 2:
                     address = server.address();
                     port = (typeof address === "undefined" ? "undefined" : _type_of(address)) === 'object' && address ? address.port : 0;
-                    trimmedPrefix = prefix.replace(/^\/+|\/+$/g, '');
+                    trimmedPrefix = prefix.replaceAll(/^\/+|\/+$/g, '');
                     apiBaseUrl = trimmedPrefix.length > 0 ? "http://".concat(host, ":").concat(port, "/").concat(trimmedPrefix) : "http://".concat(host, ":").concat(port);
                     return [
                         2,

package/test/index.esm.js

@@ -333,7 +333,7 @@ function _ts_generator(thisArg, body) {
                 case 2:
                     address = server.address();
                     port = (typeof address === "undefined" ? "undefined" : _type_of(address)) === 'object' && address ? address.port : 0;
-                    trimmedPrefix = prefix.replace(/^\/+|\/+$/g, '');
+                    trimmedPrefix = prefix.replaceAll(/^\/+|\/+$/g, '');
                     apiBaseUrl = trimmedPrefix.length > 0 ? "http://".concat(host, ":").concat(port, "/").concat(trimmedPrefix) : "http://".concat(host, ":").concat(port);
                     return [
                         2,

package/test/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "13.15.0",
+  "version": "13.17.0",
   "peerDependencies": {
-    "@dereekb/date": "13.15.0",
-    "@dereekb/dbx-cli": "13.15.0",
-    "@dereekb/firebase": "13.15.0",
-    "@dereekb/firebase-server/test": "13.15.0",
-    "@dereekb/model": "13.15.0",
-    "@dereekb/nestjs": "13.15.0",
-    "@dereekb/rxjs": "13.15.0",
-    "@dereekb/util": "13.15.0",
+    "@dereekb/date": "13.17.0",
+    "@dereekb/dbx-cli": "13.17.0",
+    "@dereekb/firebase": "13.17.0",
+    "@dereekb/firebase-server/test": "13.17.0",
+    "@dereekb/model": "13.17.0",
+    "@dereekb/nestjs": "13.17.0",
+    "@dereekb/rxjs": "13.17.0",
+    "@dereekb/util": "13.17.0",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "vitest": "4.1.5",