@unbrained/pm-cli 2026.6.13 → 2026.6.17

package/dist/cli/commands/search.d.ts

@@ -1,7 +1,16 @@
+import { type ItemTypeRegistry } from "../../core/item/type-registry.js";
+import { type EmbeddingProviderConfig, type EmbeddingProviderResolution } from "../../core/search/providers.js";
+import { type QueryExpansionConfig, type RerankConfig } from "../../core/search/relevance.js";
+import { type VectorQueryHit, type VectorStoreConfig, type VectorStoreResolution } from "../../core/search/vector-stores.js";
+import { type LifecycleClassifier } from "../../core/governance/metadata-coverage.js";
+import { type RuntimeFieldRegistry, type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
 import type { GlobalOptions } from "../../core/shared/command-types.js";
-import type { ItemFrontMatter } from "../../types/index.js";
+import type { ItemDocument, ItemFormat, ItemFrontMatter, ItemStatus, PmSettings } from "../../types/index.js";
 export interface SearchOptions {
     mode?: string;
+    matchMode?: string;
+    minScore?: string | number;
+    count?: boolean;
     semanticWeight?: string | number;
     includeLinked?: boolean;
     titleExact?: boolean;
@@ -12,18 +21,55 @@ export interface SearchOptions {
     priority?: string;
     deadlineBefore?: string;
     deadlineAfter?: string;
+    updatedAfter?: string;
+    updatedBefore?: string;
+    createdAfter?: string;
+    createdBefore?: string;
+    assignee?: string;
+    sprint?: string;
+    release?: string;
+    parent?: string;
     limit?: string;
     compact?: boolean;
     full?: boolean;
     fields?: string;
+    filterReviewerMissing?: boolean;
+    filterRiskMissing?: boolean;
+    filterConfidenceMissing?: boolean;
+    filterSprintMissing?: boolean;
+    filterReleaseMissing?: boolean;
+    hasNotes?: boolean;
+    hasLearnings?: boolean;
+    hasFiles?: boolean;
+    hasDocs?: boolean;
+    hasTests?: boolean;
+    hasComments?: boolean;
+    hasDeps?: boolean;
+    hasBody?: boolean;
+    hasLinkedCommand?: boolean;
+    noNotes?: boolean;
+    noLearnings?: boolean;
+    noFiles?: boolean;
+    noDocs?: boolean;
+    noTests?: boolean;
+    noComments?: boolean;
+    noDeps?: boolean;
+    emptyBody?: boolean;
+    noLinkedCommand?: boolean;
     [key: string]: unknown;
 }
+export type SearchMatchMode = "and" | "or" | "exact";
 type SearchMode = "keyword" | "semantic" | "hybrid";
 type SearchProjectionMode = "compact" | "full" | "fields";
+interface SearchProjectionConfig {
+    mode: SearchProjectionMode;
+    fields: string[];
+}
 export interface SearchHit {
     item: ItemFrontMatter;
     score: number;
     matched_fields: string[];
+    matched_all_terms?: boolean;
 }
 export type SearchResultItem = SearchHit | Record<string, unknown>;
 interface SearchResultBase {
@@ -31,6 +77,8 @@ interface SearchResultBase {
     mode: SearchMode;
     items: SearchResultItem[];
     count: number;
+    total?: number;
+    count_only?: boolean;
     warnings?: string[];
 }
 export interface SearchCompactResult extends SearchResultBase {
@@ -47,6 +95,96 @@ export interface SearchVerboseResult extends SearchResultBase {
     now: string;
 }
 export type SearchResult = SearchCompactResult | SearchVerboseResult;
+declare function buildCompactSearchFilterSummary(params: {
+    mode: SearchMode;
+    matchMode: SearchMatchMode;
+    options: SearchOptions;
+    includeLinked: boolean;
+    titleExact: boolean;
+    phraseExact: boolean;
+    scoreThreshold: number;
+    hybridSemanticWeight: number;
+    runtimeFieldFilters?: Record<string, unknown>;
+}): Record<string, unknown>;
+declare function buildVerboseSearchFilters(params: {
+    effectiveMode: SearchMode;
+    matchMode: SearchMatchMode;
+    options: SearchOptions;
+    includeLinked: boolean;
+    titleExact: boolean;
+    phraseExact: boolean;
+    scoreThreshold: number;
+    hybridSemanticWeight: number;
+    queryExpansion: QueryExpansionConfig;
+    rerank: RerankConfig;
+    runtimeFieldFilters: Record<string, unknown>;
+}): Record<string, unknown>;
+interface ExtensionSearchProviderContext {
+    query: string;
+    mode: SearchMode;
+    tokens: string[];
+    options: SearchOptions;
+    settings: PmSettings;
+    documents: ItemDocument[];
+}
+interface ExtensionSearchProviderHit {
+    id: string;
+    score: number;
+    matched_fields?: string[];
+}
+type ExtensionSearchProviderQuery = (context: ExtensionSearchProviderContext) => Promise<ExtensionSearchProviderHit[] | {
+    hits?: ExtensionSearchProviderHit[];
+}> | ExtensionSearchProviderHit[] | {
+    hits?: ExtensionSearchProviderHit[];
+};
+interface ExtensionSearchProviderQueryExpansionContext {
+    query: string;
+    mode: Exclude<SearchMode, "keyword">;
+    settings: PmSettings;
+}
+type ExtensionSearchProviderQueryExpansion = (context: ExtensionSearchProviderQueryExpansionContext) => Promise<string[] | {
+    queries?: string[];
+}> | string[] | {
+    queries?: string[];
+};
+interface ExtensionSearchProviderRerankCandidate {
+    id: string;
+    text: string;
+    score: number;
+}
+interface ExtensionSearchProviderRerankContext {
+    query: string;
+    mode: "hybrid";
+    model: string;
+    top_k: number;
+    settings: PmSettings;
+    candidates: ExtensionSearchProviderRerankCandidate[];
+}
+type ExtensionSearchProviderRerank = (context: ExtensionSearchProviderRerankContext) => Promise<Array<{
+    id?: unknown;
+    score?: unknown;
+}> | {
+    hits?: Array<{
+        id?: unknown;
+        score?: unknown;
+    }>;
+}> | Array<{
+    id?: unknown;
+    score?: unknown;
+}> | {
+    hits?: Array<{
+        id?: unknown;
+        score?: unknown;
+    }>;
+};
+type ExtensionVectorQuery = (context: {
+    vector: number[];
+    limit: number;
+    settings: PmSettings;
+}) => Promise<VectorQueryHit[]> | VectorQueryHit[];
+type ExtensionVectorAdapter = {
+    query?: ExtensionVectorQuery;
+};
 type ImplicitSemanticFallbackReason = "timeout" | "connection" | "error";
 /**
  * Aggregate the `code` strings found along an error's `cause` chain.
@@ -64,6 +202,91 @@ export declare function collectErrorCauseCodes(error: unknown): string;
  * so undici's generic "fetch failed" is recognised as a connection failure.
  */
 export declare function classifyImplicitSemanticFallbackReason(error: unknown): ImplicitSemanticFallbackReason;
+declare function buildImplicitSemanticFallbackWarning(error: unknown): string;
+declare function buildExplicitSemanticFallbackWarning(requestedMode: SearchMode, error: unknown): string;
+/**
+ * Compare the vectorization-status ledger against the filtered corpus and, when
+ * the vector index is behind, emit a one-line stderr warning plus a structured
+ * `vector_index_stale:N` entry in the JSON warnings array. Best-effort: ledger
+ * read failures fall through silently — the existing semantic/hybrid fallback
+ * paths cover backend errors.
+ */
+declare function maybeEmitVectorIndexStaleWarning(pmRoot: string, filteredDocuments: ItemDocument[], warnings: string[]): Promise<void>;
+declare function parseTimestampWindow(raw: unknown, fieldLabel: string): string | undefined;
+declare function parseProjectionConfig(options: SearchOptions): SearchProjectionConfig;
+export declare const _testOnlySearchCommand: {
+    applyFilters: typeof applyFilters;
+    applyExactQueryFilters: typeof applyExactQueryFilters;
+    buildVerboseSearchFilters: typeof buildVerboseSearchFilters;
+    buildExplicitSemanticFallbackWarning: typeof buildExplicitSemanticFallbackWarning;
+    buildCompactSearchFilterSummary: typeof buildCompactSearchFilterSummary;
+    buildHybridLexicalScore: typeof buildHybridLexicalScore;
+    buildImplicitSemanticFallbackWarning: typeof buildImplicitSemanticFallbackWarning;
+    buildRerankCorpus: typeof buildRerankCorpus;
+    buildSemanticHits: typeof buildSemanticHits;
+    classifyImplicitSemanticFallbackReason: typeof classifyImplicitSemanticFallbackReason;
+    collectErrorCauseCodes: typeof collectErrorCauseCodes;
+    collectExactPhraseFields: typeof collectExactPhraseFields;
+    collectLinkedPaths: typeof collectLinkedPaths;
+    combineHybridHits: typeof combineHybridHits;
+    computeSemanticOrHybridHits: typeof computeSemanticOrHybridHits;
+    countOccurrences: typeof countOccurrences;
+    dependencyEntries: typeof dependencyEntries;
+    documentContainsExactPhrase: typeof documentContainsExactPhrase;
+    emptySearchResult: typeof emptySearchResult;
+    loadDocuments: typeof loadDocuments;
+    maybeEmitVectorIndexStaleWarning: typeof maybeEmitVectorIndexStaleWarning;
+    loadLinkedCorpus: typeof loadLinkedCorpus;
+    mergeVectorHitsById: typeof mergeVectorHitsById;
+    normalizeExtensionProviderHits: typeof normalizeExtensionProviderHits;
+    normalizeScoreMap: typeof normalizeScoreMap;
+    parseProjectionConfig: typeof parseProjectionConfig;
+    parseTimestampWindow: typeof parseTimestampWindow;
+    parseTokens: typeof parseTokens;
+    readSearchFieldValue: typeof readSearchFieldValue;
+    requireSemanticDependencies: typeof requireSemanticDependencies;
+    resolveExtensionSearchProvider: typeof resolveExtensionSearchProvider;
+    resolveExtensionSearchProviderByName: typeof resolveExtensionSearchProviderByName;
+    resolveExtensionVectorAdapter: typeof resolveExtensionVectorAdapter;
+    resolveLinkedCorpusRoots: typeof resolveLinkedCorpusRoots;
+    scoreDocument: typeof scoreDocument;
+    sortHits: typeof sortHits;
+    stringArray: typeof stringArray;
+    textEntries: typeof textEntries;
+    validateSearchProjectionFields: typeof validateSearchProjectionFields;
+};
+declare function validateSearchProjectionFields(projection: SearchProjectionConfig, runtimeFieldRegistry: RuntimeFieldRegistry): void;
+declare function parseTokens(query: string): string[];
+declare function stringArray(value: unknown): string[];
+declare function textEntries(value: unknown): Array<{
+    text: string;
+}>;
+declare function dependencyEntries(value: unknown): Array<{
+    id: string;
+    kind: string;
+}>;
+declare function collectExactPhraseFields(document: ItemDocument): string[];
+declare function documentContainsExactPhrase(document: ItemDocument, normalizedQuery: string): boolean;
+declare function applyExactQueryFilters(items: ItemDocument[], normalizedQuery: string, options: {
+    titleExact: boolean;
+    phraseExact: boolean;
+}): ItemDocument[];
+declare function applyFilters(items: ItemDocument[], options: SearchOptions, typeRegistry: ItemTypeRegistry, runtimeFieldFilters: Record<string, unknown>, statusFilter: ItemStatus[] | undefined, lifecycleClassifier: LifecycleClassifier): ItemDocument[];
+declare function countOccurrences(haystack: string, needle: string): number;
+declare function collectLinkedPaths(item: ItemFrontMatter): Array<{
+    scope: "project" | "global";
+    path: string;
+}>;
+interface ContainmentRoot {
+    resolved: string;
+    realpath: string;
+}
+interface LinkedCorpusRoots {
+    projectContainmentRoot: ContainmentRoot | null;
+    globalContainmentRoot: ContainmentRoot | null;
+}
+declare function resolveLinkedCorpusRoots(projectRoot: string, globalRoot: string): Promise<LinkedCorpusRoots>;
+declare function loadLinkedCorpus(document: ItemDocument, roots: LinkedCorpusRoots): Promise<string>;
 export interface SearchTuning {
     title_exact_bonus: number;
     title_weight: number;
@@ -79,9 +302,74 @@ export interface SearchTuning {
     dependencies_weight: number;
     linked_content_weight: number;
 }
+declare function scoreDocument(document: ItemDocument, tokens: string[], normalizedQuery: string, linkedCorpus: string, tuning: SearchTuning, applyCoverageBonus?: boolean): SearchHit | null;
+declare function sortHits(items: SearchHit[], statusRegistry: RuntimeStatusRegistry): SearchHit[];
+declare function buildHybridLexicalScore(document: ItemDocument, tokens: string[], normalizedQuery: string, includeLinked: boolean, linkedCorpusById: Map<string, string>, tuning: SearchTuning, applyCoverageBonus?: boolean): SearchHit | null;
+declare function normalizeScoreMap(scoreById: Map<string, number>): Map<string, number>;
 export declare function resolveSearchMaxResults(settings: unknown): number;
 export declare function resolveSearchScoreThreshold(settings: unknown): number;
 export declare function resolveHybridSemanticWeight(settings: unknown): number;
 export declare function resolveSearchTuning(settings: unknown): SearchTuning;
+declare function emptySearchResult(query: string, mode: SearchMode, matchMode: SearchMatchMode, options: SearchOptions, includeLinked: boolean, scoreThreshold: number, hybridSemanticWeight: number, queryExpansion: QueryExpansionConfig, rerank: RerankConfig, projection: SearchProjectionConfig, warnings: string[], runtimeFieldFilters?: Record<string, unknown>, countOnly?: boolean): SearchResult;
+declare function requireSemanticDependencies(requestedMode: Exclude<SearchMode, "keyword">, providerResolution: EmbeddingProviderResolution, vectorResolution: VectorStoreResolution, hasExtensionVectorQuery: boolean): {
+    provider: EmbeddingProviderConfig;
+    vectorStore: VectorStoreConfig | null;
+};
+interface ExtensionSearchProviderHooks {
+    providerName: string;
+    query?: ExtensionSearchProviderQuery;
+    queryExpansion?: ExtensionSearchProviderQueryExpansion;
+    rerank?: ExtensionSearchProviderRerank;
+}
+declare function resolveExtensionSearchProviderByName(providerName: string | undefined): ExtensionSearchProviderHooks | null;
+declare function resolveExtensionSearchProvider(settings: PmSettings): {
+    providerName: string;
+    query: ExtensionSearchProviderQuery;
+} | null;
+declare function resolveExtensionVectorAdapter(settings: PmSettings): ExtensionVectorAdapter | null;
+declare function normalizeExtensionProviderHits(providerName: string, raw: unknown, filteredById: Map<string, ItemDocument>): SearchHit[];
+declare function buildSemanticHits(vectorHits: VectorQueryHit[], filteredById: Map<string, ItemDocument>): {
+    semanticHits: SearchHit[];
+    semanticScores: Map<string, number>;
+};
+declare function combineHybridHits(filteredById: Map<string, ItemDocument>, semanticScores: Map<string, number>, keywordHits: SearchHit[], hybridSemanticWeight: number): SearchHit[];
+interface SemanticQueryContext {
+    requestedMode: Exclude<SearchMode, "keyword">;
+    query: string;
+    filteredDocuments: ItemDocument[];
+    keywordHits: SearchHit[];
+    hybridSemanticWeight: number;
+    limit: number | undefined;
+    maxResults: number;
+    provider: EmbeddingProviderConfig;
+    vectorStore: VectorStoreConfig | null;
+    extensionVectorAdapter: ExtensionVectorAdapter | null;
+    queryExpansion: QueryExpansionConfig;
+    queryExpansionExtension: {
+        providerName: string;
+        expand: ExtensionSearchProviderQueryExpansion;
+    } | null;
+    rerank: RerankConfig;
+    rerankExtension: {
+        providerName: string;
+        rerank: ExtensionSearchProviderRerank;
+    } | null;
+    warnings: string[];
+    settings: PmSettings;
+    embeddingTimeoutMs?: number;
+    vectorQueryTimeoutMs?: number;
+}
+interface SemanticQueryResult {
+    hits: SearchHit[];
+    vectorMatchCount: number;
+}
+declare function mergeVectorHitsById(vectorHitGroups: VectorQueryHit[][]): VectorQueryHit[];
+declare function buildRerankCorpus(document: ItemDocument): string;
+declare function computeSemanticOrHybridHits(context: SemanticQueryContext): Promise<SemanticQueryResult>;
+declare function loadDocuments(pmRoot: string, itemFormat: ItemFormat, typeToFolder: Record<string, string>, schema: PmSettings["schema"]): Promise<{
+    documents: ItemDocument[];
+    warnings: string[];
+}>;
+declare function readSearchFieldValue(hit: SearchHit, field: string): unknown;
 export declare function runSearch(query: string, options: SearchOptions, global: GlobalOptions): Promise<SearchResult>;
 export {};