@dereekb/dbx-cli 13.11.18 → 13.12.0

package/src/lib/mcp-scan/scan/ui-components-extract.d.ts

@@ -0,0 +1,124 @@
+/**
+ * AST extraction for the `scan-ui-components` generator.
+ *
+ * Walks every source file in the supplied ts-morph `Project` looking for
+ * top-level exported class declarations tagged with the `@dbxWebComponent`
+ * JSDoc marker. Each match is normalised into an {@link ExtractedUiEntry}
+ * that {@link buildUiComponentsManifest} will assemble into a
+ * `UiComponentManifest` entry.
+ *
+ * Decorator metadata, signal `input()`/`output()` calls, and `@Input()`/
+ * `@Output()` decorated properties are auto-extracted; JSDoc tags only
+ * supply registry metadata that can't be derived from source (slug,
+ * category, related slugs, skill refs, content projection summary).
+ */
+import { type Project } from 'ts-morph';
+import { type UiComponentEntry, type UiComponentInputEntry, type UiComponentOutputEntry } from '../manifest/ui-components-schema.js';
+/**
+ * One UI entry extracted from a source file. Mirrors {@link UiComponentEntry}
+ * minus `module` (derived from the package being scanned in build-manifest).
+ * `filePath` and `line` are kept here for in-process warning reporting but
+ * never persisted to the manifest — downstream consumers can't resolve them.
+ */
+export interface ExtractedUiEntry {
+    readonly slug: string;
+    readonly category: UiComponentEntry['category'];
+    readonly kind: UiComponentEntry['kind'];
+    readonly selector: string;
+    readonly className: string;
+    readonly description: string;
+    readonly inputs: readonly UiComponentInputEntry[];
+    readonly outputs: readonly UiComponentOutputEntry[];
+    readonly contentProjection?: string;
+    readonly relatedSlugs?: readonly string[];
+    readonly skillRefs?: readonly string[];
+    readonly example?: string;
+    readonly minimalExample?: 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. The caller (build-manifest) collates these
+ * into a structured warning array so missing/invalid tag combinations
+ * surface during generation rather than silently dropping entries.
+ */
+export type ExtractWarning = {
+    readonly kind: 'missing-required-tag';
+    readonly className: string;
+    readonly tag: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'unknown-category';
+    readonly className: string;
+    readonly category: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'unknown-kind';
+    readonly className: string;
+    readonly kindValue: string;
+    readonly filePath: string;
+    readonly line: number;
+};
+/**
+ * Input to {@link extractUiEntries}. The caller is responsible for adding
+ * source files to `project` (either from disk, in-memory fixtures, or a
+ * tsconfig).
+ */
+export interface ExtractUiEntriesInput {
+    readonly project: Project;
+}
+/**
+ * Result of {@link extractUiEntries}.
+ */
+export interface ExtractUiEntriesResult {
+    readonly entries: readonly ExtractedUiEntry[];
+    readonly warnings: readonly ExtractWarning[];
+}
+/**
+ * Walks the supplied project and returns every class tagged with the
+ * `@dbxWebComponent` 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 extractUiEntries(input: ExtractUiEntriesInput): ExtractUiEntriesResult;
+/**
+ * Arktype validator that mirrors {@link ExtractedUiEntry}. Useful for tests
+ * and for runtime-validating fixture entries crafted by hand.
+ */
+export declare const ExtractedUiEntrySchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    slug: string;
+    category: "action" | "list" | "screen" | "text" | "layout" | "button" | "card" | "feedback" | "overlay" | "navigation" | "router" | "misc";
+    kind: "pipe" | "component" | "directive" | "service";
+    selector: string;
+    className: string;
+    description: string;
+    inputs: {
+        name: string;
+        type: string;
+        description: string;
+        required: boolean;
+        default?: string | undefined;
+    }[];
+    outputs: {
+        name: string;
+        emits: string;
+        description: string;
+    }[];
+    filePath: string;
+    line: number;
+    contentProjection?: string | undefined;
+    relatedSlugs?: string[] | undefined;
+    skillRefs?: string[] | undefined;
+    example?: string | undefined;
+    minimalExample?: string | undefined;
+    deprecated?: string | boolean | undefined;
+    since?: string | undefined;
+}, {}>;

package/src/lib/mcp-scan/scan/ui-components-scan-config-schema.d.ts

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

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

@@ -0,0 +1,78 @@
+/**
+ * Orchestrator for the `scan-utils` generator.
+ *
+ * Composes a complete {@link UtilManifest} from a project root by
+ *
+ *   1. reading `dbx-mcp.scan.json` against {@link UtilsScanConfig}
+ *   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 extractUtilEntries}
+ *   6. assembling the manifest envelope and validating it against
+ *      {@link UtilManifest}
+ *
+ * I/O is fully injectable so tests drive every code path without
+ * touching the real filesystem.
+ */
+import { UtilManifest } from '../manifest/utils-schema.js';
+import { type UtilExtractWarning } from './utils-extract.js';
+import { type ScanGlobber, type ScanReadFile } from '../../scan-helpers/scan-io.js';
+export type BuildUtilsReadFile = ScanReadFile;
+export type BuildUtilsGlobber = ScanGlobber;
+/**
+ * Input to {@link buildUtilsManifest}.
+ */
+export interface BuildUtilsManifestInput {
+    readonly projectRoot: string;
+    readonly generator: string;
+    readonly now?: () => Date;
+    readonly readFile?: BuildUtilsReadFile;
+    readonly globber?: BuildUtilsGlobber;
+}
+/**
+ * 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 BuildUtilsManifestOutcome = {
+    readonly kind: 'success';
+    readonly manifest: UtilManifest;
+    readonly outPath: string;
+    readonly scannedFileCount: number;
+    readonly extractWarnings: readonly UtilExtractWarning[];
+} | {
+    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 UtilManifest} 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 buildUtilsManifest(input: BuildUtilsManifestInput): Promise<BuildUtilsManifestOutcome>;
+/**
+ * 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 serializeUtilManifest(manifest: UtilManifest): string;

package/src/lib/mcp-scan/scan/utils-cli.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `scan-utils` subcommand entry point.
+ *
+ * Thin wrapper around {@link runScanCliBase} that supplies the utils
+ * domain config.
+ */
+import { type BuildUtilsGlobber } from './utils-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 UtilsScanCliReadFile = ScanCliBaseReadFile;
+/**
+ * Function shape used to write the produced manifest in write mode.
+ */
+export type UtilsScanCliWriteFile = ScanCliBaseWriteFile;
+/**
+ * Console-shaped sink for stdout and stderr lines.
+ */
+export type UtilsScanCliLogger = ScanCliBaseLogger;
+/**
+ * Input to {@link runUtilsScanCli}.
+ */
+export type RunUtilsScanCliInput = RunScanCliBaseInput<BuildUtilsGlobber>;
+/**
+ * Result of one CLI invocation.
+ */
+export type RunUtilsScanCliResult = RunScanCliResult;
+/**
+ * Runs one invocation of `scan-utils`. 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 runUtilsScanCli(input: RunUtilsScanCliInput): Promise<RunUtilsScanCliResult>;

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

@@ -0,0 +1,103 @@
+/**
+ * AST extraction for the `scan-utils` generator.
+ *
+ * Walks every source file in the supplied ts-morph `Project` looking for
+ * top-level exported declarations (functions, classes, `const` variable
+ * statements) tagged with the `@dbxUtil` JSDoc marker. Each match is
+ * normalised into an {@link ExtractedUtilEntry} that
+ * {@link buildUtilsManifest} assembles into a `UtilManifest` entry.
+ *
+ * Optional sub-tags supply overrides that can't be reliably auto-derived
+ * (slug, category, tags, related slugs, skill refs, kind). 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, etc.
+ *
+ * The extractor prefers syntactic nodes (`getReturnTypeNode()`,
+ * `getTypeNode()`) and only falls back to type-checker inference
+ * (`getReturnType()`, `getType()`) when an explicit type annotation is
+ * absent. The syntactic-first path keeps the common case cheap on
+ * in-memory fixtures while still surfacing inferred types when authors
+ * elide them.
+ */
+import { type Project } from 'ts-morph';
+import type { UtilKindValue, UtilParamEntry } from '../manifest/utils-schema.js';
+/**
+ * One util entry extracted from a source file. Mirrors {@link UtilEntry}
+ * 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 ExtractedUtilEntry {
+    readonly slug: string;
+    readonly name: string;
+    readonly kind: UtilKindValue;
+    readonly category: string;
+    readonly signature: string;
+    readonly description: string;
+    readonly params: readonly UtilParamEntry[];
+    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 UtilExtractWarning = {
+    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 extractUtilEntries}. The caller is responsible for
+ * adding source files to `project`.
+ */
+export interface ExtractUtilEntriesInput {
+    readonly project: Project;
+    /**
+     * Repo-relative project root (e.g. `packages/util`). 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 extractUtilEntries}.
+ */
+export interface ExtractUtilEntriesResult {
+    readonly entries: readonly ExtractedUtilEntry[];
+    readonly warnings: readonly UtilExtractWarning[];
+}
+/**
+ * Walks the supplied project and returns every export tagged with the
+ * `@dbxUtil` 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 extractUtilEntries(input: ExtractUtilEntriesInput): ExtractUtilEntriesResult;

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

@@ -0,0 +1,57 @@
+/**
+ * Arktype schema for the `utils` section of `dbx-mcp.scan.json`.
+ *
+ * Utils scanning lives next to the existing semantic-types, ui-components,
+ * forge-fields, and pipes 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-utils` reads only the `utils`
+ * field; sibling subcommands continue to read their own top-level fields
+ * unchanged.
+ */
+/**
+ * Inner config that drives one utils 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 UtilsScanSection: 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 UtilsScanSection}.
+ */
+export type UtilsScanSection = typeof UtilsScanSection.infer;
+/**
+ * Top-level shape used by the utils builder. Only the `utils` 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 UtilsScanConfig: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    utils: {
+        include: string[];
+        source?: string | undefined;
+        module?: string | undefined;
+        exclude?: string[] | undefined;
+        out?: string | undefined;
+    };
+}, {}>;
+/**
+ * Static type inferred from {@link UtilsScanConfig}.
+ */
+export type UtilsScanConfig = typeof UtilsScanConfig.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_UTILS_SCAN_OUT_PATH = "utils.mcp.generated.json";
+/**
+ * Filename the loader looks for at `${projectRoot}/`. Re-exported here so
+ * the utils CLI does not have to import from a sibling scan config module.
+ */
+export declare const UTILS_SCAN_CONFIG_FILENAME = "dbx-mcp.scan.json";

package/test/package.json

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

package/index.cjs.default.js

@@ -1 +0,0 @@
-exports._default = require('./index.cjs.js').default;

package/index.cjs.mjs

@@ -1,2 +0,0 @@
-export * from './index.cjs.js';
-export { _default as default } from './index.cjs.default.js';