@dereekb/dbx-cli 13.11.17 → 13.12.0

package/src/lib/mcp-scan/scan/css-utilities-extract.d.ts

@@ -0,0 +1,187 @@
+/**
+ * SCSS extractor for the `scan-css-utilities` pipeline.
+ *
+ * Scans a flat `.scss` source string for top-level utility-class rules
+ * annotated with `/// @dbx-utility …`. Returns one
+ * {@link ExtractedCssUtilityEntry} per annotated selector plus
+ * {@link ExtractWarning}s for malformed annotation blocks.
+ *
+ * Supported annotation tags (each on its own `///` line, immediately
+ * preceding the selector):
+ *
+ * - `@dbx-utility <slug>` — required curation gate; defaults the slug to
+ *   `<host-class minus leading dot>` when the value is omitted.
+ * - `@intent <plain-english>` — short description used by intent search.
+ * - `@role <role>` — one of `layout`, `flex`, `text`, `spacing`, `state`,
+ *   `interaction`, `color`, `text-color`, `surface`, `size`, `radius`,
+ *   `misc`. Drives role filters and structural-property weighting in the
+ *   equivalency engine.
+ * - `@see-also <slug>[, <slug>, …]` — comma-separated related slugs.
+ * - `@anti-use <plain-english>` — when NOT to use this utility.
+ * - `@since <version>` — version tag.
+ * - `@parent <slug>` — group this utility as a child of another utility.
+ *   Children (entries with a `parent` field) are filtered out of bulk
+ *   browse / search / intent results in the runtime registry by default;
+ *   callers can opt in with `parent="<slug>"` (scope to that parent's
+ *   children) or `includeChildren=true`. Use this for helper classes that
+ *   compose around a parent class (e.g. `dbx-list-two-line-item-icon`
+ *   carries `@parent dbx-list-two-line-item`). The leading dot on a parent
+ *   value is stripped, so `@parent .dbx-foo` and `@parent dbx-foo` are
+ *   equivalent. Parent slugs are NOT validated against the registry at
+ *   extract time — cross-source references and forward references both
+ *   work.
+ * - `@component <ClassName>` — names the Angular component class that
+ *   owns this rule (e.g. `@component DbxIconTileComponent`). Surfaces in
+ *   the lookup output so consumers know which component to use instead
+ *   of applying the class by hand.
+ * - `@scope <utility|component-class>` — defaults to `utility` when
+ *   omitted. Set to `component-class` when the rule ships as part of a
+ *   component template and should not be applied to arbitrary elements.
+ *   The lookup tool renders a "use the component, not the class" hint in
+ *   that case while still surfacing tokens.
+ *
+ * Two arrays are derived automatically from the rule's body during
+ * extraction (no annotation needed):
+ *
+ * - `tokensRead` — every CSS custom property referenced via `var(--name,
+ *   …)` inside any declaration value (including nested `var()` calls in
+ *   fallbacks). Sorted, deduped.
+ * - `tokensSet` — every CSS custom property declared by the rule (a
+ *   declaration whose property starts with `--`). Sorted, deduped.
+ *
+ * Curation gate: only selectors whose preceding comment block contains
+ * `/// @dbx-utility` make it into the output.
+ *
+ * Selector shapes accepted:
+ *
+ * - **Flat single-class** (`.dbx-foo`) — the canonical case. Slug defaults
+ *   to `dbx-foo`; `selectorContext` is omitted.
+ * - **Flat comma-list** (`.text-center, .dbx-text-center`) — picks the
+ *   `.dbx-*` variant as canonical; the chosen class is the host. Each
+ *   comma-separated part must be a flat single-class selector.
+ * - **Compound descendant chain** (`.dbx-list-no-item-padding .dbx-list >
+ *   .dbx-list-content …`) — the FIRST flat class in the chain becomes the
+ *   host (canonical) selector; the full original text is preserved on the
+ *   entry as `selectorContext` so consumers see the usage context. The
+ *   first segment must be a flat single class (no compound `.foo.bar`,
+ *   pseudo-classes, or attribute selectors as the host); everything after
+ *   the first whitespace combinator can be arbitrary CSS. This lets a
+ *   curator annotate a rule like `.dbx-list-no-item-padding .dbx-list …
+ *   { padding: 0 }` directly without rewriting it as nested SCSS.
+ *
+ * Nested SCSS rules inside an annotated block (e.g. `.item-icon` inside a
+ * `.dbx-list-two-line-item` rule) are NOT cataloged; lift them to flat
+ * top-level classes if they should be discoverable as utilities, then
+ * carry `@parent` to group them under their conceptual parent.
+ *
+ * Implementation: a lightweight line-based scanner. The SCSS family this
+ * package targets uses flat top-level rules (or rules nested one level deep
+ * inside a `@mixin core()` block); brace-counting is sufficient for both.
+ * No PostCSS dependency.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type CssUtilityRoleValue, type CssUtilityScopeValue } from '../manifest/css-utilities-schema.js';
+/**
+ * One declaration captured from the annotated rule.
+ */
+export interface ExtractedCssDeclaration {
+    readonly property: string;
+    readonly value: string;
+}
+/**
+ * One annotated-utility entry produced by {@link extractCssUtilityEntries}.
+ * `file` is the relative file path supplied by the caller; `line` is the
+ * 1-based line number where the selector begins.
+ */
+export interface ExtractedCssUtilityEntry {
+    readonly slug: string;
+    readonly selector: string;
+    readonly file: string;
+    readonly line: number;
+    readonly declarations: readonly ExtractedCssDeclaration[];
+    readonly role?: CssUtilityRoleValue;
+    readonly intent?: string;
+    readonly seeAlso?: readonly string[];
+    readonly antiUse?: string;
+    readonly since?: string;
+    readonly parent?: string;
+    readonly selectorContext?: string;
+    readonly component?: string;
+    readonly scope?: CssUtilityScopeValue;
+    readonly tokensRead?: readonly string[];
+    readonly tokensSet?: readonly string[];
+}
+/**
+ * Discriminated union of warning kinds produced by the extractor. Strict
+ * curation errors (like a `/// @dbx-utility` block followed by a non-class
+ * selector) are surfaced as warnings rather than thrown so a single bad
+ * annotation does not break the whole scan.
+ */
+export type ExtractWarning = {
+    readonly kind: 'unsupported-selector';
+    readonly file: string;
+    readonly line: number;
+    readonly selector: string;
+} | {
+    readonly kind: 'unknown-role';
+    readonly file: string;
+    readonly line: number;
+    readonly slug: string;
+    readonly role: string;
+} | {
+    readonly kind: 'unknown-scope';
+    readonly file: string;
+    readonly line: number;
+    readonly slug: string;
+    readonly scope: string;
+} | {
+    readonly kind: 'orphan-annotation';
+    readonly file: string;
+    readonly line: number;
+};
+/**
+ * Input to {@link extractCssUtilityEntries}.
+ */
+export interface ExtractCssUtilityEntriesInput {
+    readonly file: string;
+    readonly source: string;
+}
+/**
+ * Result of one extraction run.
+ */
+export interface ExtractCssUtilityEntriesResult {
+    readonly entries: readonly ExtractedCssUtilityEntry[];
+    readonly warnings: readonly ExtractWarning[];
+}
+interface ParsedAnnotation {
+    readonly utilitySlug: Maybe<string>;
+    readonly intent?: string;
+    readonly role?: string;
+    readonly seeAlso?: readonly string[];
+    readonly antiUse?: string;
+    readonly since?: string;
+    readonly parent?: string;
+    readonly component?: string;
+    readonly scope?: string;
+}
+/**
+ * Parses a buffer of `///` annotation lines (each already stripped of the
+ * leading `/// `) into a structured shape. Lines without a recognised tag
+ * are ignored — the curation marker itself is the only required line.
+ *
+ * @param lines - The annotation lines belonging to one block.
+ * @returns The parsed annotation; `utilitySlug` is `null` when no
+ *          `@dbx-utility` line appears.
+ */
+export declare function parseAnnotation(lines: readonly string[]): ParsedAnnotation;
+/**
+ * Walks the supplied SCSS source and extracts every `/// @dbx-utility`
+ * annotated rule. Only flat single-class selectors are supported in v1 —
+ * compound or descendant selectors are reported via the
+ * `unsupported-selector` warning.
+ *
+ * @param input - The file label (relative path) and the SCSS source string.
+ * @returns The extracted entries plus deterministic warnings.
+ */
+export declare function extractCssUtilityEntries(input: ExtractCssUtilityEntriesInput): ExtractCssUtilityEntriesResult;
+export {};

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

@@ -0,0 +1,57 @@
+/**
+ * Arktype schema for the `cssUtilities` section of `dbx-mcp.scan.json`.
+ *
+ * CSS-utility scanning lives next to the existing semantic-types,
+ * ui-components, forge-fields, and pipes sections — they all use the same
+ * `dbx-mcp.scan.json` filename so a project that opts into multiple
+ * pipelines keeps a single config file.
+ *
+ * The schema is intentionally permissive at the root (extra keys are
+ * preserved untouched) so co-located scan sections don't trigger
+ * cross-section validation.
+ */
+/**
+ * Inner config that drives one css-utilities 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 CssUtilitiesScanSection: 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 CssUtilitiesScanSection}.
+ */
+export type CssUtilitiesScanSection = typeof CssUtilitiesScanSection.infer;
+/**
+ * Top-level shape used by the css-utilities builder. Only the
+ * `cssUtilities` key is consumed; the rest of the document is ignored so a
+ * single `dbx-mcp.scan.json` can house multiple cluster configurations.
+ */
+export declare const CssUtilitiesScanConfig: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    cssUtilities: {
+        include: string[];
+        source?: string | undefined;
+        module?: string | undefined;
+        exclude?: string[] | undefined;
+        out?: string | undefined;
+    };
+}, {}>;
+/**
+ * Static type inferred from {@link CssUtilitiesScanConfig}.
+ */
+export type CssUtilitiesScanConfig = typeof CssUtilitiesScanConfig.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_CSS_UTILITIES_SCAN_OUT_PATH = "css-utilities.mcp.generated.json";
+/**
+ * Filename the loader looks for at `${projectRoot}/`.
+ */
+export declare const CSS_UTILITIES_SCAN_CONFIG_FILENAME = "dbx-mcp.scan.json";

package/src/lib/mcp-scan/scan/dbx-docs-ui-examples-build-manifest.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Orchestrator for the `scan-dbx-docs-ui-examples` generator.
+ *
+ * Composes a complete {@link DbxDocsUiExampleManifest} from a project root
+ * by reading `dbx-mcp.scan.json` against
+ * {@link DbxDocsUiExamplesScanConfig}, resolving include/exclude globs,
+ * loading matched example files into a ts-morph project, extracting
+ * entries via {@link extractDbxDocsUiExampleEntries}, and assembling the
+ * manifest envelope. I/O is fully injectable for tests.
+ */
+import { DbxDocsUiExampleManifest } from '../manifest/dbx-docs-ui-examples-schema.js';
+import { type DbxDocsUiExamplesExtractWarning } from './dbx-docs-ui-examples-extract.js';
+import { type ScanGlobber, type ScanReadFile } from '../../scan-helpers/scan-io.js';
+export type BuildDbxDocsUiExamplesManifestReadFile = ScanReadFile;
+export type BuildDbxDocsUiExamplesManifestGlobber = ScanGlobber;
+/**
+ * Input to {@link buildDbxDocsUiExamplesManifest}.
+ */
+export interface BuildDbxDocsUiExamplesManifestInput {
+    readonly projectRoot: string;
+    readonly generator: string;
+    readonly now?: () => Date;
+    readonly readFile?: BuildDbxDocsUiExamplesManifestReadFile;
+    readonly globber?: BuildDbxDocsUiExamplesManifestGlobber;
+}
+/**
+ * Outcome of one generator run.
+ */
+export type BuildDbxDocsUiExamplesManifestOutcome = {
+    readonly kind: 'success';
+    readonly manifest: DbxDocsUiExampleManifest;
+    readonly outPath: string;
+    readonly scannedFileCount: number;
+    readonly extractWarnings: readonly DbxDocsUiExamplesExtractWarning[];
+} | {
+    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 DbxDocsUiExampleManifest} from the supplied project root.
+ *
+ * @param input - The project root + injection hooks for testing.
+ * @returns A discriminated outcome describing the result.
+ */
+export declare function buildDbxDocsUiExamplesManifest(input: BuildDbxDocsUiExamplesManifestInput): Promise<BuildDbxDocsUiExamplesManifestOutcome>;
+/**
+ * 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 validated manifest to serialize.
+ * @returns A pretty-printed JSON string terminated with a newline.
+ */
+export declare function serializeDbxDocsUiExamplesManifest(manifest: DbxDocsUiExampleManifest): string;

package/src/lib/mcp-scan/scan/dbx-docs-ui-examples-cli.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `scan-dbx-docs-ui-examples` subcommand entry point.
+ *
+ * Thin wrapper around {@link runScanCliBase} that supplies the
+ * dbx-docs-ui-examples domain config.
+ */
+import { type BuildDbxDocsUiExamplesManifestGlobber } from './dbx-docs-ui-examples-build-manifest.js';
+import { type RunScanCliBaseInput, type RunScanCliResult, type ScanCliBaseLogger, type ScanCliBaseReadFile, type ScanCliBaseWriteFile } from './scan-cli-base.js';
+export type DbxDocsUiExamplesScanCliReadFile = ScanCliBaseReadFile;
+export type DbxDocsUiExamplesScanCliWriteFile = ScanCliBaseWriteFile;
+export type DbxDocsUiExamplesScanCliLogger = ScanCliBaseLogger;
+export type RunDbxDocsUiExamplesScanCliInput = RunScanCliBaseInput<BuildDbxDocsUiExamplesManifestGlobber>;
+export type RunDbxDocsUiExamplesScanCliResult = RunScanCliResult;
+/**
+ * Runs one invocation of `scan-dbx-docs-ui-examples`.
+ *
+ * @param input - Parsed CLI input including project root, optional `--out` override, and `--check` flag.
+ * @returns The CLI exit code, written file paths, and any warnings produced by the scan.
+ */
+export declare function runDbxDocsUiExamplesScanCli(input: RunDbxDocsUiExamplesScanCliInput): Promise<RunDbxDocsUiExamplesScanCliResult>;

package/src/lib/mcp-scan/scan/dbx-docs-ui-examples-extract.d.ts

@@ -0,0 +1,160 @@
+/**
+ * AST extraction for the `scan-dbx-docs-ui-examples` generator.
+ *
+ * Walks every source file in the supplied ts-morph `Project` looking for
+ * top-level exported class declarations tagged with the `@dbxDocsUiExample`
+ * JSDoc marker. Each match is normalised into an
+ * {@link ExtractedDbxDocsUiExampleEntry} that
+ * {@link buildDbxDocsUiExamplesManifest} will assemble into a
+ * `DbxDocsUiExampleManifest` entry.
+ *
+ * The extractor parses the example component's `@Component` template to find
+ * the well-known `<dbx-docs-ui-example*>` element tree (header attribute,
+ * info/content/imports/notes children) and resolves every
+ * `@dbxDocsUiExampleUses` tag through the example file's import declarations,
+ * lazily loading the referenced source files so each supporting class /
+ * interface declaration and (for components) its template body land in the
+ * entry's `uses[]` array. The tag accepts either a bare identifier
+ * (`@dbxDocsUiExampleUses Foo role`) or a JSDoc link
+ * (`@dbxDocsUiExampleUses {@link Foo} role`), so authors get IDE
+ * cross-referencing on supporting types.
+ */
+import { type Project } from 'ts-morph';
+import { type DbxDocsUiExampleEntry, type DbxDocsUiExampleUseEntry } from '../manifest/dbx-docs-ui-examples-schema.js';
+import { type ScanReadFile } from '../../scan-helpers/scan-io.js';
+/**
+ * One example entry extracted from a source file. Mirrors
+ * {@link DbxDocsUiExampleEntry} minus `module` and `appRef` (defaulted in
+ * build-manifest). The originating `filePath` and `line` are kept so
+ * extract warnings can point a developer back to the source file —
+ * neither is persisted to the manifest because downstream consumers
+ * never have access to the source tree.
+ */
+export interface ExtractedDbxDocsUiExampleEntry {
+    readonly slug: string;
+    readonly category: DbxDocsUiExampleEntry['category'];
+    readonly summary: string;
+    readonly header: string;
+    readonly hint?: string;
+    readonly className: string;
+    readonly selector: string;
+    readonly appRef?: string;
+    readonly relatedSlugs?: readonly string[];
+    readonly skillRefs?: readonly string[];
+    readonly info: string;
+    readonly snippet: string;
+    readonly imports?: string;
+    readonly notes?: string;
+    readonly uses: readonly DbxDocsUiExampleUseEntry[];
+    readonly filePath: string;
+    readonly line: number;
+}
+/**
+ * Discriminated union of the non-fatal events the extractor emits. 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 DbxDocsUiExamplesExtractWarning = {
+    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: 'missing-component-decorator';
+    readonly className: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'missing-template';
+    readonly className: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'missing-example-root';
+    readonly className: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'missing-example-content';
+    readonly className: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'template-url-unreadable';
+    readonly className: string;
+    readonly templatePath: string;
+    readonly filePath: string;
+    readonly line: number;
+} | {
+    readonly kind: 'uses-unresolved';
+    readonly className: string;
+    readonly identifier: string;
+    readonly filePath: string;
+    readonly line: number;
+};
+/**
+ * Input to {@link extractDbxDocsUiExampleEntries}. The caller is responsible
+ * for adding example source files to `project`; the extractor will lazily
+ * pull in additional source files referenced by `@dbxDocsUiExampleUses` tags
+ * via the supplied `readFile` injection.
+ */
+export interface ExtractDbxDocsUiExampleEntriesInput {
+    readonly project: Project;
+    readonly readFile: ScanReadFile;
+}
+/**
+ * Result of {@link extractDbxDocsUiExampleEntries}.
+ */
+export interface ExtractDbxDocsUiExampleEntriesResult {
+    readonly entries: readonly ExtractedDbxDocsUiExampleEntry[];
+    readonly warnings: readonly DbxDocsUiExamplesExtractWarning[];
+}
+/**
+ * Walks the supplied project and returns every class tagged with the
+ * `@dbxDocsUiExample` 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 plus a readFile for resolving
+ *   supporting sources referenced by `@dbxDocsUiExampleUses` tags.
+ * @returns The extracted entries plus any non-fatal warnings.
+ */
+export declare function extractDbxDocsUiExampleEntries(input: ExtractDbxDocsUiExampleEntriesInput): Promise<ExtractDbxDocsUiExampleEntriesResult>;
+/**
+ * Arktype validator that mirrors {@link ExtractedDbxDocsUiExampleEntry}.
+ * Useful for tests that want to runtime-validate hand-crafted fixtures.
+ */
+export declare const ExtractedDbxDocsUiExampleEntrySchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    slug: string;
+    category: "action" | "list" | "screen" | "text" | "layout" | "button" | "card" | "feedback" | "overlay" | "navigation" | "router" | "misc";
+    summary: string;
+    header: string;
+    className: string;
+    selector: string;
+    info: string;
+    snippet: string;
+    uses: {
+        kind: "function" | "pipe" | "component" | "directive" | "service" | "class" | "const" | "interface" | "typeAlias";
+        className: string;
+        classSource: string;
+        role?: string | undefined;
+        selector?: string | undefined;
+        pipeName?: string | undefined;
+    }[];
+    filePath: string;
+    line: number;
+    hint?: string | undefined;
+    appRef?: string | undefined;
+    relatedSlugs?: string[] | undefined;
+    skillRefs?: string[] | undefined;
+    imports?: string | undefined;
+    notes?: string | undefined;
+}, {}>;

package/src/lib/mcp-scan/scan/dbx-docs-ui-examples-scan-config-schema.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Arktype schema for the `dbxDocsUiExamples` section of `dbx-mcp.scan.json`.
+ *
+ * Mirrors the `uiComponents` cluster contract — same `dbx-mcp.scan.json`
+ * filename, same `include`/`exclude`/`out`/`source`/`module` shape — so a
+ * project that wants to ship downstream-app UI examples alongside any other
+ * scan cluster keeps a single config file. The CLI subcommand
+ * `scan-dbx-docs-ui-examples` reads only the `dbxDocsUiExamples` field; other
+ * cluster CLIs continue to read their respective sections unchanged.
+ */
+/**
+ * Inner config that drives one dbx-docs-ui-examples scan run. `source` becomes
+ * the manifest's `source` label (used for collision detection across loaded
+ * sources); `module` becomes the entry-level `module` field attached to every
+ * produced entry. Both default to the project's `package.json#name` when
+ * omitted.
+ */
+export declare const DbxDocsUiExamplesScanSection: 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 DbxDocsUiExamplesScanSection}.
+ */
+export type DbxDocsUiExamplesScanSection = typeof DbxDocsUiExamplesScanSection.infer;
+/**
+ * Top-level shape used by the dbx-docs-ui-examples builder. Only the
+ * `dbxDocsUiExamples` key is consumed; the rest of the document is ignored so
+ * a single `dbx-mcp.scan.json` can house multiple cluster configurations.
+ */
+export declare const DbxDocsUiExamplesScanConfig: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    dbxDocsUiExamples: {
+        include: string[];
+        source?: string | undefined;
+        module?: string | undefined;
+        exclude?: string[] | undefined;
+        out?: string | undefined;
+    };
+}, {}>;
+/**
+ * Static type inferred from {@link DbxDocsUiExamplesScanConfig}.
+ */
+export type DbxDocsUiExamplesScanConfig = typeof DbxDocsUiExamplesScanConfig.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_DBX_DOCS_UI_EXAMPLES_SCAN_OUT_PATH = "dbx-docs-ui-examples.mcp.generated.json";
+/**
+ * Filename the loader looks for at `${projectRoot}/`.
+ */
+export declare const DBX_DOCS_UI_EXAMPLES_SCAN_CONFIG_FILENAME = "dbx-mcp.scan.json";

package/src/lib/mcp-scan/scan/discover-downstream-packages.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Discovery for downstream packages that may contribute manifests to the
+ * `dbx-components-mcp` registries (forms, UI, pipes, actions, filters,
+ * semantic types).
+ *
+ * Generalises {@link discoverDownstreamFirebasePackages} from one cluster
+ * (Firebase models) to the full set so the new `dbx_mcp_config` tool can
+ * inspect a workspace, suggest where to add scan configs, and feed the
+ * startup-warning hook in `server.ts`.
+ *
+ * Discovery axes:
+ *   - `components/*-{firebase,shared,web,core}` — the conventional dbx
+ *     component layout.
+ *   - `apps/*` — included only when the app already has a
+ *     `dbx-mcp.scan.json`, since most apps don't author exportable types.
+ *   - Any folder with a `dbx-mcp.scan.json` — explicit opt-in always wins.
+ *
+ * Cluster candidacy is decided by cheap file-suffix heuristics over
+ * `src/**\/*.ts` (e.g. `*.component.ts` → `uiComponents`). The scan CLIs
+ * themselves do the real extraction; this helper only narrows which scan
+ * sections `init` writes and which startup hints fire.
+ */
+/**
+ * The six cluster keys also used by `dbx-mcp.config.json` and the per-cluster
+ * registry loaders. Kept in sync with `DbxMcpConfig` (`config-schema.ts`).
+ */
+export type DownstreamCluster = 'semanticTypes' | 'uiComponents' | 'forgeFields' | 'pipes' | 'actions' | 'filters';
+/**
+ * Every cluster in the order the config schema declares them. Re-exported for
+ * the tool and the startup warning so they don't redeclare the list.
+ */
+export declare const DOWNSTREAM_CLUSTERS: readonly DownstreamCluster[];
+/**
+ * One downstream package discovered under the workspace root. `slug` is the
+ * conventional manifest-filename token derived from the package name (lowered,
+ * `@scope/` stripped, slashes collapsed to dashes) so two packages from
+ * different scopes never collide on disk.
+ */
+export interface DownstreamPackage {
+    readonly packageName: string;
+    readonly slug: string;
+    readonly relDir: string;
+    readonly absDir: string;
+    readonly hasScanConfig: boolean;
+    readonly candidateClusters: readonly DownstreamCluster[];
+    readonly declaredScanClusters: readonly DownstreamCluster[];
+}
+/**
+ * Input to {@link discoverDownstreamPackages}.
+ */
+export interface DiscoverDownstreamPackagesInput {
+    readonly workspaceRoot: string;
+    /**
+     * Optional explicit list of workspace-relative dirs to inspect. When set,
+     * the default glob discovery is skipped — only these dirs are returned
+     * (filtered to those that actually look like packages).
+     */
+    readonly explicitDirs?: readonly string[];
+}
+/**
+ * Globs the workspace for downstream packages and returns one entry per
+ * package with the heuristic candidate-cluster list attached.
+ *
+ * @param input - Workspace root (absolute) plus optional explicit override.
+ * @returns The discovered packages sorted by `packageName`
+ */
+export declare function discoverDownstreamPackages(input: DiscoverDownstreamPackagesInput): Promise<readonly DownstreamPackage[]>;
+/**
+ * Converts a package name (possibly scoped) into a slug suitable for a
+ * manifest filename. `@dereekb/dbx-form` becomes `dereekb-dbx-form`; bare
+ * names become themselves lowered.
+ *
+ * @param packageName - The raw package.json `name` value to slugify.
+ * @returns The lowered, scope-stripped, separator-normalised slug.
+ */
+export declare function packageNameToSlug(packageName: string): string;