@dereekb/dbx-cli 13.11.14 → 13.11.16

package/src/lib/manifest/build-model-decode-command.d.ts

@@ -64,6 +64,8 @@ export declare function buildModelDecodeCommand(manifest: CliModelManifest, opti
  * @param rawKey - The Firestore key string.
  * @param manifest - The generated model manifest.
  * @returns The decoded key with leaf, ancestors, and any unresolved prefixes.
+ * @throws {CliError} When `rawKey` is empty or does not parse into an even number of `prefix/id` segments.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function decodeFirestoreModelKey(rawKey: string, manifest: CliModelManifest): DecodedKey;
@@ -72,8 +74,9 @@ export declare function decodeFirestoreModelKey(rawKey: string, manifest: CliMod
  * MCP `dbx_model_decode` key-mode output for consistency between agent and
  * shell consumers.
  *
- * @param decoded - the decoded key returned by {@link decodeFirestoreModelKey}.
- * @returns the formatted block with a trailing newline.
+ * @param decoded - The decoded key returned by {@link decodeFirestoreModelKey}.
+ * @returns The formatted block with a trailing newline.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function renderDecodedKey(decoded: DecodedKey): string;

package/src/lib/manifest/model-info-utils.d.ts

@@ -6,17 +6,19 @@ import type { CliModelManifest, CliModelManifestEntry } from './types';
  * Re-exports {@link findCliModelManifestEntry} under a more descriptive name
  * for the model-info command.
  *
- * @param manifest - the generated model manifest.
- * @param query - identifier to look up.
- * @returns the matching entry or `undefined`.
+ * @param manifest - The generated model manifest.
+ * @param query - Identifier to look up.
+ * @returns The matching entry or `undefined`.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function resolveCliModel(manifest: CliModelManifest, query: string): CliModelManifestEntry | undefined;
 /**
  * Produces a column-aligned summary table of every model in the manifest.
  *
- * @param manifest - the generated model manifest.
- * @returns the formatted table as a single string with a trailing newline.
+ * @param manifest - The generated model manifest.
+ * @returns The formatted table as a single string with a trailing newline.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function renderModelManifestList(manifest: CliModelManifest): string;
@@ -24,8 +26,9 @@ export declare function renderModelManifestList(manifest: CliModelManifest): str
  * Produces a human-readable summary of one model entry: header, description,
  * and an indented field tree (recursing into `nestedFields`).
  *
- * @param entry - the manifest entry to render.
- * @returns the formatted summary as a single string with a trailing newline.
+ * @param entry - The manifest entry to render.
+ * @returns The formatted summary as a single string with a trailing newline.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function renderModelManifestEntry(entry: CliModelManifestEntry): string;
@@ -33,8 +36,9 @@ export declare function renderModelManifestEntry(entry: CliModelManifestEntry):
  * Produces the field-table portion of {@link renderModelManifestEntry} on its
  * own, used by the `--fields` flag of the `model-info` command.
  *
- * @param entry - the manifest entry whose fields should be rendered.
- * @returns the formatted field tree as a single string with a trailing newline.
+ * @param entry - The manifest entry whose fields should be rendered.
+ * @returns The formatted field tree as a single string with a trailing newline.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function renderModelManifestFields(entry: CliModelManifestEntry): string;

package/src/lib/middleware/auth.middleware.d.ts

@@ -39,11 +39,12 @@ export declare function createAuthMiddleware(input: CreateAuthMiddlewareInput):
  * Test-only middleware that skips OIDC discovery, disk token loading, and token refresh, attaching
  * a pre-built {@link CliContext} directly via {@link setCliContext}.
  *
- * @internal Intended for use by `@dereekb/dbx-cli/test`. Not for production wiring.
- *
  * @param input - The pre-built context to attach on every invocation.
  * @param input.cliContext - The {@link CliContext} that will be attached via {@link setCliContext}.
  * @returns A yargs middleware function that always sets the provided context.
+ *
+ * @internal Intended for use by `@dereekb/dbx-cli/test`. Not for production wiring.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function createPassthroughAuthMiddleware(input: {

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

@@ -0,0 +1,85 @@
+/**
+ * Shared AST/JSDoc helpers used by the per-domain `*-extract.ts` modules.
+ *
+ * Each extractor walks ts-morph nodes the same way to read JSDoc tag bodies,
+ * unwrap fenced code blocks, split list-style tag text, inspect Angular
+ * `@Directive`/`@Component` decorators, and decide whether a class member is
+ * publicly visible. Centralising these helpers avoids byte-identical
+ * duplication across `actions-extract.ts`, `filters-extract.ts`,
+ * `pipes-extract.ts`, `ui-components-extract.ts`, and
+ * `forge-fields-extract.ts`.
+ */
+import { type ClassDeclaration, type Decorator, type ObjectLiteralExpression, type PropertyDeclaration } from 'ts-morph';
+/**
+ * Strips a leading and trailing triple-backtick fence (and optional language
+ * marker) from a JSDoc `@example` body. Falls through to the trimmed input
+ * when the fence pattern doesn't match.
+ *
+ * @param text - The raw `@example` body to unwrap.
+ * @returns The body with surrounding code fence removed, or the trimmed input when no fence is present.
+ */
+export declare function unwrapFenced(text: string): string;
+/**
+ * Splits a list-style tag body (whitespace or comma separated) into trimmed,
+ * non-empty pieces.
+ *
+ * @param text - The raw tag body to split.
+ * @returns Trimmed, non-empty tokens preserved in source order.
+ */
+export declare function splitListTagText(text: string): readonly string[];
+/**
+ * Flattens an array of list-style tag bodies into a single trimmed,
+ * non-empty array of pieces.
+ *
+ * @param values - Multiple raw tag bodies whose pieces should be merged.
+ * @returns Every trimmed, non-empty token from every body, in source order.
+ */
+export declare function flattenList(values: readonly string[]): readonly string[];
+/**
+ * Reads a string-literal property from an object literal. Returns `undefined`
+ * when the property is missing, isn't a property assignment, or when the
+ * initializer isn't a (non-substitution) string literal.
+ *
+ * @param obj - The object literal expression to inspect.
+ * @param propName - The property name whose string-literal value to read.
+ * @returns The string value, or `undefined` if the property is missing or not a string literal.
+ */
+export declare function readStringProperty(obj: ObjectLiteralExpression, propName: string): string | undefined;
+/**
+ * Reads the `selector` string from the first object-literal argument of an
+ * `@Directive()` / `@Component()` decorator call. Returns `undefined` when
+ * the decorator has no call expression, no first argument, or the first
+ * argument isn't an object literal with a string `selector`.
+ *
+ * @param decorator - The Angular decorator node to read.
+ * @returns The selector string, or `undefined` if absent.
+ */
+export declare function readSelector(decorator: Decorator): string | undefined;
+/**
+ * Walks the supplied class's decorators looking for the first
+ * `@Directive()` / `@Component()` whose object literal includes a
+ * `selector`. Returns `undefined` when no qualifying decorator is found.
+ *
+ * @param decl - The class declaration to inspect.
+ * @returns An object containing the discovered selector, or `undefined` if no qualifying decorator is present.
+ */
+export declare function readDirectiveDecorator(decl: ClassDeclaration): {
+    readonly selector: string;
+} | undefined;
+/**
+ * Returns `true` when the property has neither `private` nor `protected`
+ * modifiers. Used as the default visibility filter when extracting Angular
+ * inputs/outputs.
+ *
+ * @param property - The property declaration to inspect.
+ * @returns `true` if the property is publicly visible.
+ */
+export declare function isVisibleProperty(property: PropertyDeclaration): boolean;
+/**
+ * Joins every JSDoc description block on the property with `\n\n`. Returns
+ * an empty string when the property has no JSDoc or only blank descriptions.
+ *
+ * @param property - The property declaration whose JSDoc descriptions to collect.
+ * @returns The concatenated description text, or an empty string when none is present.
+ */
+export declare function readPropertyDescription(property: PropertyDeclaration): string;

package/src/lib/scan-helpers/scan-io.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Shared I/O primitives for the build-manifest pipelines.
+ *
+ * Every scanner needs the same file-reading, glob-matching, exclude-filtering,
+ * and package-name-loading logic, so it lives here once. Individual
+ * `*-build-manifest.ts` modules import these and supply their own schema
+ * validation / entry assembly.
+ */
+import { Project } from 'ts-morph';
+/**
+ * Function shape used to read text files. Defaults to
+ * `node:fs/promises.readFile(path, 'utf-8')`.
+ */
+export type ScanReadFile = (absolutePath: string) => Promise<string>;
+/**
+ * Function shape used to resolve include/exclude globs against the project
+ * root. Defaults to `node:fs/promises.glob` filtered through a regex-derived
+ * exclude check.
+ */
+export type ScanGlobber = (input: {
+    readonly projectRoot: string;
+    readonly include: readonly string[];
+    readonly exclude: readonly string[];
+}) => Promise<readonly string[]>;
+export declare const defaultReadFile: ScanReadFile;
+export declare const defaultGlobber: ScanGlobber;
+/**
+ * Shared outcome kinds for the `no-package` / `invalid-package` error
+ * paths. Every build-manifest outcome type includes these same two
+ * variants, so the shared loader can return a compatible discriminated
+ * union.
+ */
+export type LoadPackageNameResult = {
+    readonly kind: 'ok';
+    readonly packageName: string;
+} | {
+    readonly kind: 'fail';
+    readonly outcome: {
+        readonly kind: 'no-package';
+        readonly packagePath: string;
+    } | {
+        readonly kind: 'invalid-package';
+        readonly packagePath: string;
+        readonly error: string;
+    };
+};
+/**
+ * Reads `package.json` at the supplied path and returns its `name` field, normalising file/parse errors into a discriminated outcome compatible with `*-build-manifest.ts` callers.
+ *
+ * @param packagePath - Absolute path to `package.json`.
+ * @param readFile - File-reader injected by the scan runtime.
+ * @returns Either the parsed package name or a discriminated failure outcome.
+ */
+export declare function loadPackageName(packagePath: string, readFile: ScanReadFile): Promise<LoadPackageNameResult>;
+/**
+ * Failure variants surfaced by {@link loadScanSection}. Every per-cluster
+ * `Build*ManifestOutcome` includes these same two variants so the shared
+ * loader can return a value the caller forwards directly.
+ */
+export type ScanConfigFailureOutcome = {
+    readonly kind: 'no-config';
+    readonly configPath: string;
+} | {
+    readonly kind: 'invalid-scan-config';
+    readonly configPath: string;
+    readonly error: string;
+};
+/**
+ * Discriminated outcome from {@link loadScanSection}. On success carries the
+ * cluster's already-validated section; on failure carries an outcome the
+ * caller forwards as its own `Build*ManifestOutcome`.
+ */
+export type LoadScanSectionResult<TSection> = {
+    readonly kind: 'ok';
+    readonly section: TSection;
+} | {
+    readonly kind: 'fail';
+    readonly outcome: ScanConfigFailureOutcome;
+};
+/**
+ * Reads `dbx-mcp.scan.json` at {@link configPath}, parses it as JSON, and
+ * hands the parsed object to {@link parseSection} for cluster-specific
+ * arktype validation. Centralises the missing-file / bad-JSON / invalid-
+ * schema branches that every `*-build-manifest.ts` repeats verbatim.
+ *
+ * @param input - Config path, file reader, and the cluster-specific parse callback used to validate the section.
+ * @param input.configPath - Absolute path to the `dbx-mcp.scan.json` file to read.
+ * @param input.readFile - File-reader injected by the scan runtime; defaults to `node:fs/promises.readFile` in production callers.
+ * @param input.parseSection - Cluster-specific parser that validates the parsed JSON and extracts the relevant sub-section (typically wraps an arktype validator).
+ * @returns Either the validated section or a forwardable failure outcome (`no-config` or `invalid-scan-config`).
+ */
+export declare function loadScanSection<TSection>(input: {
+    readonly configPath: string;
+    readonly readFile: ScanReadFile;
+    readonly parseSection: (parsed: unknown) => {
+        readonly ok: true;
+        readonly section: TSection;
+    } | {
+        readonly ok: false;
+        readonly error: string;
+    };
+}): Promise<LoadScanSectionResult<TSection>>;
+/**
+ * Builds an in-memory ts-morph {@link Project} populated with the supplied
+ * relative file paths. Resolves every path against {@link projectRoot},
+ * reads it via {@link readFile}, and adds it to the project as a source
+ * file. Used by every `*-build-manifest.ts` orchestrator before handing
+ * the project to its cluster-specific extractor.
+ *
+ * @param input - Project root, relative file paths to load, and the file reader used to fetch each file's contents.
+ * @param input.projectRoot - Absolute path used as the base for resolving each entry in `filePaths`.
+ * @param input.filePaths - Relative file paths to add to the in-memory project, resolved against `projectRoot`.
+ * @param input.readFile - File-reader used to fetch each file's contents before adding it to the project.
+ * @returns The populated ts-morph project ready for entry extraction.
+ */
+export declare function buildScanProject(input: {
+    readonly projectRoot: string;
+    readonly filePaths: readonly string[];
+    readonly readFile: ScanReadFile;
+}): Promise<Project>;
+/**
+ * Translates a glob pattern into a RegExp suitable for testing
+ * `relative(projectRoot, file)` paths. Supports `**`, `*`, and `?`
+ * wildcards. Used by the default globber to filter exclude patterns
+ * — the matching logic intentionally mirrors `node:fs/promises.glob`.
+ *
+ * @param pattern - A glob pattern (no character classes)
+ * @returns A RegExp that matches paths satisfying the glob.
+ */
+export declare function globToRegex(pattern: string): RegExp;

package/test/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "13.11.14",
+  "version": "13.11.16",
   "peerDependencies": {
-    "@dereekb/date": "13.11.14",
-    "@dereekb/dbx-cli": "13.11.14",
-    "@dereekb/firebase": "13.11.14",
-    "@dereekb/firebase-server/test": "13.11.14",
-    "@dereekb/model": "13.11.14",
-    "@dereekb/nestjs": "13.11.14",
-    "@dereekb/rxjs": "13.11.14",
-    "@dereekb/util": "13.11.14",
+    "@dereekb/date": "13.11.16",
+    "@dereekb/dbx-cli": "13.11.16",
+    "@dereekb/firebase": "13.11.16",
+    "@dereekb/firebase-server/test": "13.11.16",
+    "@dereekb/model": "13.11.16",
+    "@dereekb/nestjs": "13.11.16",
+    "@dereekb/rxjs": "13.11.16",
+    "@dereekb/util": "13.11.16",
     "@nestjs/common": "^11.1.19",
     "arktype": "^2.2.0",
     "yargs": "^18.0.0"