@dereekb/dbx-cli 13.11.18 → 13.12.0

package/src/lib/mcp-scan/registry/semantic-types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Semantic-types registry wrapper.
+ *
+ * Wraps the raw {@link LoadSemanticTypeManifestsResult} produced by the
+ * loader with domain-friendly accessors so the lookup / search tools and
+ * the registry resource don't have to walk Maps directly.
+ *
+ * The registry is loaded once at server startup (see Step 6) and passed
+ * into the tool factories. Tests can construct a registry from any
+ * `SemanticTypeEntry` array via {@link createSemanticTypeRegistryFromEntries}
+ * to drive the tools without touching disk.
+ */
+import type { LoadSemanticTypeManifestsResult } from '../manifest/loader.js';
+import type { SemanticTypeEntry } from '../manifest/semantic-types-schema.js';
+/**
+ * Domain-friendly read API over a merged semantic-types manifest set. All
+ * accessors return readonly arrays sorted by name to keep tool output
+ * deterministic.
+ */
+export interface SemanticTypeRegistry {
+    readonly all: readonly SemanticTypeEntry[];
+    readonly loadedSources: readonly string[];
+    readonly topics: readonly string[];
+    readonly packages: readonly string[];
+    readonly baseTypes: readonly string[];
+    /**
+     * Returns every entry that matches `name` exactly. Names are case-sensitive.
+     */
+    findByName(name: string): readonly SemanticTypeEntry[];
+    /**
+     * Returns every entry tagged with `topic`. Topics are case-sensitive.
+     */
+    findByTopic(topic: string): readonly SemanticTypeEntry[];
+    /**
+     * Returns every entry whose `package` field matches `packageLabel` exactly.
+     */
+    findByPackage(packageLabel: string): readonly SemanticTypeEntry[];
+    /**
+     * Returns every entry whose `baseType` matches `baseType` exactly.
+     */
+    findByBaseType(baseType: string): readonly SemanticTypeEntry[];
+    /**
+     * Substring search across `name`, `module`, and `definition`. Case-
+     * insensitive.
+     */
+    findByQuery(query: string): readonly SemanticTypeEntry[];
+}
+/**
+ * Builds a {@link SemanticTypeRegistry} from a loader result. The wrapper
+ * keeps a single sorted-by-name copy of every entry plus pre-computed
+ * topic / package / baseType buckets so each lookup is O(n) at worst and
+ * subsequent calls hit the cached bucket lists.
+ *
+ * @param loaded - The merged registry returned by `loadSemanticTypeManifests`
+ * @returns A domain-friendly read API over the merged entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createSemanticTypeRegistry(loaded: LoadSemanticTypeManifestsResult): SemanticTypeRegistry;
+/**
+ * Builds a {@link SemanticTypeRegistry} from a raw entry array. Used by tests
+ * that need to drive the tools without going through the loader pipeline.
+ *
+ * @param input - The entries plus the source labels to advertise.
+ * @param input.entries - The full entry list (will be sorted by name)
+ * @param input.loadedSources - Source labels reported via `registry.loadedSources`
+ * @returns A domain-friendly read API over the supplied entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createSemanticTypeRegistryFromEntries(input: {
+    readonly entries: readonly SemanticTypeEntry[];
+    readonly loadedSources: readonly string[];
+}): SemanticTypeRegistry;
+/**
+ * Empty registry suitable as a default when the server has no manifest
+ * sources to load. Tools wired against this registry behave like a
+ * registry that loaded successfully with zero entries — they emit
+ * "no results" responses rather than crashing.
+ */
+export declare const EMPTY_SEMANTIC_TYPE_REGISTRY: SemanticTypeRegistry;

package/src/lib/mcp-scan/registry/tokens-runtime.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Tokens runtime registry wrapper.
+ *
+ * Wraps the raw {@link LoadTokenManifestsResult} produced by the tokens
+ * loader with domain-friendly accessors so `dbx_css_token_lookup` and
+ * `dbx_ui_smell_check` don't have to walk Maps directly.
+ *
+ * The registry is loaded once at server startup and passed into the tool
+ * factories. Tests can construct a registry from any `TokenEntry` array via
+ * {@link createTokenRegistryFromEntries} to drive the tools without
+ * touching disk.
+ */
+import type { LoadTokenManifestsResult } from '../manifest/tokens-loader.js';
+import type { TokenEntry } from '../manifest/tokens-schema.js';
+/**
+ * One scored candidate produced by the registry's intent / value matching
+ * helpers. `score` is a non-normalised non-negative number — higher means
+ * more confident — that the calling tool uses for top-N truncation and
+ * cross-resolver tie-breaking.
+ */
+export interface ScoredTokenMatch {
+    readonly entry: TokenEntry;
+    readonly score: number;
+}
+/**
+ * Domain-friendly read API over a merged token-manifest set. All accessors
+ * return readonly arrays sorted by `cssVariable` so tool output stays
+ * deterministic across runs.
+ */
+export interface TokenRegistry {
+    readonly all: readonly TokenEntry[];
+    readonly loadedSources: readonly string[];
+    readonly bySource: ReadonlyMap<string, readonly TokenEntry[]>;
+    readonly byRole: ReadonlyMap<string, readonly TokenEntry[]>;
+    /**
+     * Returns the first entry whose `cssVariable` matches `name` (case-sensitive
+     * — CSS custom property names are case-sensitive).
+     */
+    findByCssVariable(name: string): TokenEntry | undefined;
+    /**
+     * Returns the first entry whose `scssVariable` matches `name`.
+     */
+    findByScssVariable(name: string): TokenEntry | undefined;
+    /**
+     * Returns scored candidates whose `intents[]` array contains a string that
+     * matches `query` (case-insensitive substring). Optional `role` filter
+     * narrows the candidate pool before scoring.
+     */
+    findByIntent(query: string, role?: string): readonly ScoredTokenMatch[];
+    /**
+     * Returns scored candidates whose `defaults.{light,dark}` matches the
+     * supplied raw CSS value via the substring-match fallback. Tools with
+     * domain-specific value parsing (OKLCH color distance, length tolerance,
+     * shadow layers) implement their own scoring on top of `all`.
+     */
+    findByValue(value: string, role?: string): readonly ScoredTokenMatch[];
+    /**
+     * Returns every entry whose `componentScope` matches the supplied
+     * Angular Material slug exactly (e.g. `mat-progress-bar`).
+     */
+    findByComponent(component: string): readonly TokenEntry[];
+}
+/**
+ * Builds a {@link TokenRegistry} from a loader result. The wrapper keeps a
+ * single sorted-by-`cssVariable` copy of every entry plus pre-computed
+ * source / role buckets so each lookup is O(n) at worst and subsequent
+ * calls hit the cached bucket lists.
+ *
+ * @param loaded - The merged registry returned by `loadTokenManifests`
+ * @returns A domain-friendly read API over the merged entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createTokenRegistry(loaded: LoadTokenManifestsResult): TokenRegistry;
+/**
+ * Builds a {@link TokenRegistry} from a raw entry array. Used by tests and
+ * by callers that want to drive the tools without going through the loader
+ * pipeline.
+ *
+ * @param input - The entries plus the source labels to advertise.
+ * @param input.entries - The full entry list (will be sorted by cssVariable)
+ * @param input.loadedSources - Source labels reported via `registry.loadedSources`
+ * @returns A domain-friendly read API over the supplied entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createTokenRegistryFromEntries(input: {
+    readonly entries: readonly TokenEntry[];
+    readonly loadedSources: readonly string[];
+}): TokenRegistry;
+/**
+ * Empty registry suitable as a default when the server has no manifest
+ * sources to load. Tools wired against this behave like a registry that
+ * loaded successfully with zero entries.
+ */
+export declare const EMPTY_TOKEN_REGISTRY: TokenRegistry;

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

@@ -0,0 +1,90 @@
+/**
+ * UI components runtime registry wrapper.
+ *
+ * Wraps the raw {@link LoadUiComponentManifestsResult} produced by the
+ * loader with domain-friendly accessors so the lookup / search tools and
+ * the registry resource don't have to walk Maps directly.
+ *
+ * The registry is loaded once at server startup and passed into the tool
+ * factories. Tests can construct a registry from any `UiComponentEntry`
+ * array via {@link createUiComponentRegistryFromEntries} to drive the
+ * tools without touching disk.
+ */
+import type { LoadUiComponentManifestsResult } from '../manifest/ui-components-loader.js';
+import type { UiComponentEntry } from '../manifest/ui-components-schema.js';
+/**
+ * Domain-friendly read API over a merged ui-components manifest set. All
+ * accessors return readonly arrays sorted by slug to keep tool output
+ * deterministic.
+ */
+export interface UiComponentRegistry {
+    readonly all: readonly UiComponentEntry[];
+    readonly loadedSources: readonly string[];
+    readonly categories: readonly string[];
+    readonly kinds: readonly string[];
+    readonly modules: readonly string[];
+    /**
+     * Returns every entry whose slug matches `slug` exactly. Slugs are
+     * case-sensitive.
+     */
+    findBySlug(slug: string): readonly UiComponentEntry[];
+    /**
+     * Returns every entry whose `category` field matches exactly. Categories
+     * are case-sensitive.
+     */
+    findByCategory(category: string): readonly UiComponentEntry[];
+    /**
+     * Returns every entry whose `kind` field matches exactly.
+     */
+    findByKind(kind: string): readonly UiComponentEntry[];
+    /**
+     * Returns the entry whose `selector` includes the supplied string as
+     * one of its comma-separated tokens. Selector tokens are matched
+     * verbatim including the bracket form (`[dbxAction]`).
+     */
+    findBySelector(selector: string): UiComponentEntry | undefined;
+    /**
+     * Returns the entry whose `className` matches the supplied string
+     * (case-insensitive).
+     */
+    findByClassName(className: string): UiComponentEntry | undefined;
+    /**
+     * Substring search across `slug`, `selector`, `className`, and
+     * `description`. Case-insensitive.
+     */
+    findByQuery(query: string): readonly UiComponentEntry[];
+}
+/**
+ * Builds a {@link UiComponentRegistry} from a loader result. The wrapper
+ * keeps a single sorted-by-slug copy of every entry plus pre-computed
+ * category / kind / module buckets so each lookup is O(n) at worst and
+ * subsequent calls hit the cached bucket lists.
+ *
+ * @param loaded - The merged registry returned by `loadUiComponentManifests`
+ * @returns A domain-friendly read API over the merged entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createUiComponentRegistry(loaded: LoadUiComponentManifestsResult): UiComponentRegistry;
+/**
+ * Builds a {@link UiComponentRegistry} from a raw entry array. Used by tests
+ * that need to drive the tools without going through the loader pipeline.
+ *
+ * @param input - The entries plus the source labels to advertise.
+ * @param input.entries - The full entry list (will be sorted by slug)
+ * @param input.loadedSources - Source labels reported via `registry.loadedSources`
+ * @returns A domain-friendly read API over the supplied entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createUiComponentRegistryFromEntries(input: {
+    readonly entries: readonly UiComponentEntry[];
+    readonly loadedSources: readonly string[];
+}): UiComponentRegistry;
+/**
+ * Empty registry suitable as a default when the server has no manifest
+ * sources to load. Tools wired against this registry behave like a
+ * registry that loaded successfully with zero entries — they emit
+ * "no results" responses rather than crashing.
+ */
+export declare const EMPTY_UI_COMPONENT_REGISTRY: UiComponentRegistry;

package/src/lib/mcp-scan/registry/utils-runtime.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Utils runtime registry wrapper.
+ *
+ * Wraps the raw {@link LoadUtilManifestsResult} produced by the loader with
+ * domain-friendly accessors so the lookup/search tools and the registry
+ * resource don't have to walk Maps directly.
+ *
+ * The registry is loaded once at server startup and passed into the tool
+ * factories. Tests can construct a registry from any entry array via
+ * {@link createUtilRegistryFromEntries} to drive the tools without touching
+ * disk.
+ */
+import type { LoadUtilManifestsResult } from '../manifest/utils-loader.js';
+import type { UtilEntry } from '../manifest/utils-schema.js';
+/**
+ * Closed kind vocabulary describing the shape of one utility entry.
+ */
+export type UtilKind = 'function' | 'class' | 'const' | 'factory';
+/**
+ * One documented parameter of a function/factory utility, or one
+ * constructor parameter for a class utility.
+ */
+export interface UtilParamInfo {
+    readonly name: string;
+    readonly type: string;
+    readonly description: string;
+    readonly optional: boolean;
+}
+/**
+ * One curated utility entry surfaced through the `dbx_util_*` tools.
+ *
+ * Mirrors {@link UtilEntry} but normalises optional manifest fields to
+ * empty arrays so callers (lookup, search, resources) don't have to
+ * defensively branch.
+ */
+export interface UtilEntryInfo {
+    readonly slug: string;
+    readonly name: string;
+    readonly kind: UtilKind;
+    readonly category: string;
+    readonly module: string;
+    readonly subpath: string;
+    readonly signature: string;
+    readonly description: string;
+    readonly params: readonly UtilParamInfo[];
+    readonly returns: string;
+    readonly tags: readonly string[];
+    readonly example: string;
+    readonly relatedSlugs: readonly string[];
+    readonly skillRefs: readonly string[];
+    readonly deprecated: boolean | string;
+    readonly since: string;
+}
+/**
+ * Domain-friendly read API over a merged utils manifest set. All accessors
+ * return readonly arrays preserving the order the manifests declared their
+ * entries (manifests are walked in source order).
+ */
+export interface UtilRegistry {
+    readonly all: readonly UtilEntryInfo[];
+    readonly loadedSources: readonly string[];
+    readonly categories: readonly string[];
+    readonly modules: readonly string[];
+    /**
+     * Returns the entry whose slug matches `slug` exactly. Slugs are unique
+     * across manifests (collisions emit a loader warning and the
+     * second-loaded entry wins).
+     */
+    findBySlug(slug: string): UtilEntryInfo | undefined;
+    /**
+     * Returns the entry whose exported identifier matches `name`. Lookup is
+     * case-sensitive — most utility names are camelCase.
+     */
+    findByName(name: string): UtilEntryInfo | undefined;
+    /**
+     * Returns the entry whose exported identifier matches `name`
+     * case-insensitively. Falls back to the case-sensitive path first to
+     * keep camelCase hits prioritised.
+     */
+    findByNameInsensitive(name: string): UtilEntryInfo | undefined;
+    /**
+     * Returns every entry whose `category` field matches `category` exactly,
+     * in registry order.
+     */
+    findByCategory(category: string): readonly UtilEntryInfo[];
+    /**
+     * Returns every entry whose `module` field matches `module` exactly, in
+     * registry order.
+     */
+    findByModule(module: string): readonly UtilEntryInfo[];
+    /**
+     * Returns every entry whose `tags` array includes `tag` (case-sensitive,
+     * tags are stored lowercased), in registry order.
+     */
+    findByTag(tag: string): readonly UtilEntryInfo[];
+}
+/**
+ * Builds a {@link UtilRegistry} from a loader result.
+ *
+ * @param loaded - The merged registry returned by `loadUtilManifests`
+ * @returns A domain-friendly read API over the merged entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createUtilRegistry(loaded: LoadUtilManifestsResult): UtilRegistry;
+/**
+ * Builds a {@link UtilRegistry} from a raw {@link UtilEntryInfo} array.
+ * Used by tests that need to drive the tools without going through the
+ * loader pipeline.
+ *
+ * @param input - The entries plus the source labels to advertise.
+ * @param input.entries - The full entry list.
+ * @param input.loadedSources - Source labels reported via `registry.loadedSources`
+ * @returns A domain-friendly read API over the supplied entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createUtilRegistryFromEntries(input: {
+    readonly entries: readonly UtilEntryInfo[];
+    readonly loadedSources: readonly string[];
+}): UtilRegistry;
+/**
+ * Empty registry suitable as a default when the server has no utils
+ * manifest sources to load. Tools wired against this registry behave like
+ * a registry that loaded successfully with zero entries.
+ */
+export declare const EMPTY_UTIL_REGISTRY: UtilRegistry;
+/**
+ * Converts a manifest entry into the {@link UtilEntryInfo} shape the
+ * lookup/search tools consume. Optional manifest fields fall back to safe
+ * defaults so a partially-populated entry still renders cleanly.
+ *
+ * @param entry - The manifest entry to convert.
+ * @returns The matching UtilEntryInfo.
+ */
+export declare function toUtilEntryInfo(entry: UtilEntry): UtilEntryInfo;

package/src/lib/mcp-scan/scan/_jsdoc-tagged-export/extract-base.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Shared infrastructure for the `*-extract.ts` modules that walk a ts-morph
+ * `Project` looking for JSDoc-tagged exports.
+ *
+ * Each per-domain extractor (utils, model-snapshot-fields, …) repeats the
+ * same scaffolding: pull every exported function/class/variable statement,
+ * check whether it carries a domain-specific JSDoc marker tag, normalise the
+ * tag list, parse common JSDoc fields (summary, params, returns, examples,
+ * deprecated/since), extract parameter declarations, and derive a default
+ * kebab-case slug + category from the source file's path.
+ *
+ * Lifting that scaffolding here keeps each per-domain extractor focused on
+ * its domain-specific differences (marker names, kind union, optional field
+ * derivation, …) instead of repeating the AST plumbing.
+ */
+import { type ClassDeclaration, type FunctionDeclaration, type JSDoc, type ParameterDeclaration, type SourceFile, type VariableDeclaration, type VariableStatement } from 'ts-morph';
+/**
+ * Tagged exported function declaration. The `decl` is the implementation
+ * (ts-morph returns only the impl for overloaded functions); `jsDocs` may
+ * include docs aggregated from overload signatures when the collector ran
+ * with `includeOverloadDocs: true`.
+ */
+export interface TaggedExportFunctionCandidate {
+    readonly kind: 'function';
+    readonly decl: FunctionDeclaration;
+    readonly jsDocs: readonly JSDoc[];
+}
+/**
+ * Tagged exported class declaration. Only emitted when
+ * {@link collectTaggedExports} was called with `includeClasses: true`.
+ */
+export interface TaggedExportClassCandidate {
+    readonly kind: 'class';
+    readonly decl: ClassDeclaration;
+    readonly jsDocs: readonly JSDoc[];
+}
+/**
+ * Tagged exported variable declaration. Emitted once per declaration in an
+ * `export const x = …, y = …` statement; `statement` is the enclosing
+ * VariableStatement so callers can read its JSDoc and source position.
+ */
+export interface TaggedExportVariableCandidate {
+    readonly kind: 'variable';
+    readonly statement: VariableStatement;
+    readonly decl: VariableDeclaration;
+    readonly jsDocs: readonly JSDoc[];
+}
+/**
+ * Discriminated union over the three tagged-export shapes the per-domain
+ * extractors care about. Helpers below operate on the wider union; per-
+ * domain extractors typically narrow to `function | variable` by not
+ * enabling `includeClasses`.
+ */
+export type TaggedExportCandidate = TaggedExportFunctionCandidate | TaggedExportClassCandidate | TaggedExportVariableCandidate;
+/**
+ * Returns the original JSDoc list when at least one tag in any doc has
+ * `tagName === markerName`, otherwise an empty array. Used by the per-
+ * collector helpers below to skip undecorated exports cheaply.
+ *
+ * @param jsDocs - The JSDocs attached to an exported declaration.
+ * @param markerName - The marker tag name (without `@`, e.g. `'dbxUtil'`).
+ * @returns The input docs when the marker was found, else `[]`.
+ */
+export declare function findTaggedDocs(jsDocs: readonly JSDoc[], markerName: string): readonly JSDoc[];
+/**
+ * Options for {@link collectTaggedFunctions}.
+ */
+export interface CollectTaggedFunctionsOptions {
+    /**
+     * When `true`, JSDoc from overload signatures is merged with the
+     * implementation's JSDoc (overloads are where authors typically put
+     * `@param` and `@returns`). Defaults to `false`.
+     */
+    readonly includeOverloadDocs?: boolean;
+}
+/**
+ * Collects exported function declarations whose JSDoc carries `markerName`.
+ *
+ * @param sourceFile - The ts-morph source file to scan.
+ * @param markerName - The marker tag name (e.g. `'dbxUtil'`).
+ * @param options - Optional flags (see {@link CollectTaggedFunctionsOptions}).
+ * @returns The tagged function candidates in source order.
+ */
+export declare function collectTaggedFunctions(sourceFile: SourceFile, markerName: string, options?: CollectTaggedFunctionsOptions): readonly TaggedExportFunctionCandidate[];
+/**
+ * Collects exported class declarations whose JSDoc carries `markerName`.
+ *
+ * @param sourceFile - The ts-morph source file to scan.
+ * @param markerName - The marker tag name.
+ * @returns The tagged class candidates in source order.
+ */
+export declare function collectTaggedClasses(sourceFile: SourceFile, markerName: string): readonly TaggedExportClassCandidate[];
+/**
+ * Collects exported variable declarations whose enclosing
+ * `VariableStatement`'s JSDoc carries `markerName`. Emits one candidate per
+ * declaration in a comma-separated `export const a = …, b = …` statement.
+ *
+ * @param sourceFile - The ts-morph source file to scan.
+ * @param markerName - The marker tag name.
+ * @returns The tagged variable candidates in source order.
+ */
+export declare function collectTaggedVariables(sourceFile: SourceFile, markerName: string): readonly TaggedExportVariableCandidate[];
+/**
+ * Options for {@link collectTaggedExports}.
+ */
+export interface CollectTaggedExportsOptions {
+    /**
+     * When `true`, exported classes carrying `markerName` are included.
+     * Defaults to `false` — most per-domain extractors only care about
+     * function and variable exports.
+     */
+    readonly includeClasses?: boolean;
+    /**
+     * Forwarded to {@link collectTaggedFunctions}. Defaults to `false`.
+     */
+    readonly includeOverloadDocs?: boolean;
+}
+/**
+ * Source-position of a candidate, used by {@link collectTaggedExports} to
+ * sort the combined output in source order.
+ *
+ * @param candidate - The tagged-export candidate to position.
+ * @returns The 0-based start offset within the source file.
+ */
+export declare function candidateSourceStart(candidate: TaggedExportCandidate): number;
+/**
+ * Combines the per-kind collectors and returns the candidates in source
+ * order.
+ *
+ * @param sourceFile - The ts-morph source file to scan.
+ * @param markerName - The marker tag name.
+ * @param options - Optional flags (see {@link CollectTaggedExportsOptions}).
+ * @returns The combined candidate list in source order.
+ */
+export declare function collectTaggedExports(sourceFile: SourceFile, markerName: string, options?: CollectTaggedExportsOptions): readonly TaggedExportCandidate[];
+/**
+ * Callback bundle for {@link walkJsDocs}.
+ */
+export interface JsDocTagHandlers {
+    /**
+     * Invoked once per JSDoc block whose description text (the prose above
+     * the tag list) is non-empty.
+     */
+    readonly onSummary: (summary: string) => void;
+    /**
+     * Invoked once per `@param` tag with the documented parameter name and
+     * its description text (both trimmed; `paramName` is `undefined`-filtered
+     * before the callback so it's always a non-empty string).
+     */
+    readonly onParam: (paramName: string, text: string) => void;
+    /**
+     * Invoked once per non-`@param` tag.
+     */
+    readonly onTag: (tagName: string, text: string) => void;
+}
+/**
+ * Walks a list of JSDoc blocks, dispatching descriptions, `@param` tags,
+ * and the remaining tags to the supplied callbacks.
+ *
+ * @param jsDocs - The JSDocs to walk.
+ * @param handlers - The summary/param/tag callbacks.
+ */
+export declare function walkJsDocs(jsDocs: readonly JSDoc[], handlers: JsDocTagHandlers): void;
+/**
+ * Best-effort extraction of the parameter name from a raw `@param ...` tag
+ * text when ts-morph's typed accessor isn't available (older AST shapes).
+ *
+ * @param rawTag - The raw `@param` tag text.
+ * @returns The parameter name, or `undefined` when the tag doesn't match.
+ */
+export declare function extractParamNameFromRawTag(rawTag: string): string | undefined;
+/**
+ * Shared parameter shape produced by {@link extractCandidateParams}.
+ * Matches the structure of both `UtilParamEntry` and
+ * `ModelSnapshotFieldParamEntry` so per-domain extractors can pass it
+ * straight through.
+ */
+export interface ExtractedParam {
+    readonly name: string;
+    readonly type: string;
+    readonly description: string;
+    readonly optional: boolean;
+}
+/**
+ * Returns the parameter declarations for a candidate. For functions, this
+ * is the impl's parameter list; for classes, the first constructor's; for
+ * variables initialized with an arrow function or function expression, the
+ * initializer's. Otherwise (a plain `const` like
+ * `firestorePassthroughField`), an empty list.
+ *
+ * @param candidate - The candidate to inspect.
+ * @returns The parameter declarations, possibly empty.
+ */
+export declare function getCandidateParameters(candidate: TaggedExportCandidate): readonly ParameterDeclaration[];
+/**
+ * Reads a candidate's parameters, pairing each with its JSDoc-`@param`
+ * description (or empty string when none was documented).
+ *
+ * @param candidate - The candidate whose parameters to extract.
+ * @param descriptions - Map from parameter name to its `@param` text.
+ * @returns The extracted parameter list.
+ */
+export declare function extractCandidateParams(candidate: TaggedExportCandidate, descriptions: ReadonlyMap<string, string>): readonly ExtractedParam[];
+/**
+ * Converts an export name into its kebab-case slug form. Handles
+ * camelCase (`expirationDetails` → `expiration-details`), PascalCase
+ * (`ExpirationDetails` → `expiration-details`), and SCREAMING_SNAKE_CASE
+ * (`FIRESTORE_PASSTHROUGH_FIELD` → `firestore-passthrough-field`);
+ * already-kebab inputs pass through unchanged.
+ *
+ * @param name - The export identifier.
+ * @returns The kebab-case slug.
+ */
+export declare function toKebabCase(name: string): string;
+/**
+ * Picks a default `category` from a source file path. The category is the
+ * first folder beneath `src/lib/` (or `src/` when `src/lib/` isn't
+ * present), so `packages/util/src/lib/date/expires.ts` → `date`.
+ *
+ * @param filePath - The absolute or repo-relative path to the source file.
+ * @returns The derived category slug, or `'misc'` when no folder is found.
+ */
+export declare function deriveCategoryFromPath(filePath: string): string;
+/**
+ * Input to {@link buildTagSet}.
+ */
+export interface BuildTagSetInput {
+    readonly name: string;
+    readonly slug: string;
+    readonly summary: string;
+    readonly explicit: readonly string[];
+    readonly category: string;
+}
+/**
+ * Builds the deduped, lowercased tag set for a tagged-export entry. Tags
+ * are seeded from any `@*Tags` JSDoc body (`explicit`), then the category,
+ * the slug pieces, the export name (raw + kebab-cased pieces). When no
+ * explicit tags were supplied, up to eight summary-derived tokens are
+ * appended so the registry has some matchable text even when the author
+ * skipped the explicit tag.
+ *
+ * @param input - Source pieces to assemble the tag set from.
+ * @returns The deduped, lowercased tag list.
+ */
+export declare function buildTagSet(input: BuildTagSetInput): readonly string[];