@ninjaxtools/slopdex 0.11.0 → 0.14.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ declare class CodeIndex {
     readonly rootDir: string;
     readonly indexPath: string;
     readonly provider: EmbeddingProvider;
+    readonly reranker: Reranker | undefined;
     readonly descriptionProvider: DescriptionProvider;
     constructor(options: CodeIndexOptions);
     close(): void;
@@ -15,6 +16,7 @@ declare class CodeIndex {
     useDescriptions(options?: {
         signal?: AbortSignal;
     }): Promise<DescriptionStats>;
+    reindexFiles(options?: ReindexFilesOptions): Promise<ReindexFilesStats>;
     disableDescriptions(): DescriptionStats;
     searchDescription(options: SimilaritySearchOptions): Promise<SimilarityResult[]>;
     similaritySearch(options: SimilaritySearchOptions): Promise<SimilarityResult[]>;
@@ -28,8 +30,10 @@ declare class CodeIndex {
         nameRegex?: string;
     }): SimilarityResult[];
     vectorForFunction(functionId: number, kind?: "code" | "description"): number[];
+    vectorForFile(filePath: string): number[];
     searchByVector(vector: readonly number[], options: {
         descriptionVector?: readonly number[];
+        fileDescriptionVector?: readonly number[];
         limit: number;
         minSimilarity: number;
         maxSimilarity?: number;
@@ -102,6 +106,24 @@ interface EmbeddingProvider {
         signal?: AbortSignal;
     }): Promise<number[]>;
 }
+interface RerankerProfile {
+    provider: string;
+    model: string;
+}
+interface Reranker {
+    readonly profile: RerankerProfile;
+    /** Preferred embedding-ranked candidate pool size for this reranker. */
+    readonly candidateCount?: number;
+    /** Maximum candidate/result count accepted by this reranker. */
+    readonly maximumCandidateCount?: number;
+    rerank(query: string, documents: readonly string[], options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<Array<{
+        index: number;
+        score: number;
+    }>>;
+}
 interface DescriptionProfile {
     provider: string;
     model: string;
@@ -112,20 +134,42 @@ interface DescriptionInput {
     callable: ParsedCallable;
     fileSource: string;
 }
+interface DescriptionFileInput {
+    repository: string;
+    path: string;
+    fileSource: string;
+}
+interface DescriptionFileSession {
+    describeFile(options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    replayFile(description: string): void;
+    describe(callable: ParsedCallable, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    replay(callable: ParsedCallable, description: string): void;
+}
 interface DescriptionProvider {
     readonly profile: DescriptionProfile;
     describe(input: DescriptionInput, options?: {
         signal?: AbortSignal;
     }): Promise<string>;
+    describeFile(input: DescriptionFileInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    startFile?(input: DescriptionFileInput): DescriptionFileSession;
 }
 interface DescriptionStats {
     descriptionsCreated: number;
+    fileDescriptionsCreated: number;
     descriptionsEnabled: boolean;
 }
 interface CodeIndexOptions {
     rootDir: string;
     indexPath?: string;
     provider: EmbeddingProvider;
+    /** Optional second-stage ranker for natural-language query searches. */
+    reranker?: Reranker;
     descriptionProvider?: DescriptionProvider;
     onWarning?: (message: string) => void;
     include?: readonly string[];
@@ -161,6 +205,15 @@ interface UpdateStats {
     embeddingsCreated: number;
     checkpoint: string | null;
 }
+interface ReindexFilesOptions {
+    includeCallables?: boolean;
+    signal?: AbortSignal;
+}
+interface ReindexFilesStats {
+    filesReindexed: number;
+    fileDescriptionsCreated: number;
+    descriptionsCreated: number;
+}
 interface SimilaritySearchOptions {
     query: string;
     /** Restrict result qualified names before ranking and limiting. */
@@ -174,16 +227,20 @@ interface SimilarityScores {
     similarity: number;
     codeSimilarity?: number;
     descriptionSimilarity?: number;
+    fileDescriptionSimilarity?: number;
 }
 interface AnalysisSimilarity {
-    similarityMode: "code" | "code-description-average";
+    similarityMode: "code" | "code-description-file-average";
     similarityWeights: {
         code: number;
         description: number;
+        fileDescription: number;
     };
 }
 interface SimilarityResult extends SimilarityScores {
     function: IndexedFunction;
+    /** Provider relevance score when a second-stage reranker ordered this result. */
+    rerankScore?: number;
 }
 type CrossSearchSourceFilter = ({
     type: "all";
@@ -209,6 +266,8 @@ interface CrossSearchOptions {
     maxSimilarity?: number;
     includeSymmetricDuplicates?: boolean;
     crossFileOnly?: boolean;
+    /** Re-rank each source's semantic matches from greatest to least physical path distance. */
+    cohesion?: boolean;
     minLines?: number;
     nameRegex?: string;
     signal?: AbortSignal;
@@ -217,9 +276,13 @@ interface CrossSearchOptions {
         total: number;
     }) => void;
 }
+interface CrossSearchMatch extends SimilarityResult {
+    /** Present when cohesion re-ranking is enabled. */
+    physicalDistance?: number;
+}
 interface CrossSearchResult {
     source: IndexedFunction;
-    matches: SimilarityResult[];
+    matches: CrossSearchMatch[];
     scoring?: AnalysisSimilarity & {
         sourceDescriptionProfile: DescriptionProfile | null;
         targetDescriptionProfile: DescriptionProfile | null;
@@ -303,7 +366,7 @@ interface CohesionAnalysisOptions {
     }) => void;
 }
 interface CohesionReport<FunctionValue = IndexedFunction> {
-    schemaVersion: 2;
+    schemaVersion: 3;
     repository: {
         generation: number;
         gitCheckpoint: string | null;
@@ -335,6 +398,9 @@ interface IndexStatus {
     embeddingProfile: Required<EmbeddingProfile>;
     descriptionsEnabled: boolean;
     descriptionCount: number;
+    fileDescriptionCount: number;
+    describableFileCount: number;
+    staleFileDescriptionCount: number;
     descriptionProfile: DescriptionProfile | null;
     indexingErrorCount: number;
     failedFileCount: number;
@@ -374,11 +440,14 @@ interface OpenAIDescriptionProviderOptions {
     apiKey?: string;
     model?: string;
     baseUrl?: string;
+    provider?: DescriptionProviderName;
 }
+declare const DESCRIPTION_PROVIDER_NAMES: readonly ["openai", "opencode", "opencode-go"];
+type DescriptionProviderName = typeof DESCRIPTION_PROVIDER_NAMES[number];
 declare class OpenAIDescriptionProvider implements DescriptionProvider {
     #private;
     readonly profile: {
-        provider: string;
+        provider: "openai" | "opencode" | "opencode-go";
         model: string;
         strategyVersion: string;
     };
@@ -386,6 +455,10 @@ declare class OpenAIDescriptionProvider implements DescriptionProvider {
     describe(input: DescriptionInput, options?: {
         signal?: AbortSignal;
     }): Promise<string>;
+    describeFile(input: DescriptionFileInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    startFile(input: DescriptionFileInput): DescriptionFileSession;
 }
 
 interface JinaEmbeddingProviderOptions {
@@ -411,6 +484,66 @@ declare class JinaEmbeddingProvider implements EmbeddingProvider {
     }): Promise<number[]>;
 }
 
+interface HostedRerankerOptions {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+}
+interface HostedRerankerSettings {
+    provider: "cohere" | "jina";
+    apiKeyName: "COHERE_API_KEY" | "JINA_API_KEY";
+    defaultModel: string;
+    defaultUrl: string;
+    returnDocuments?: boolean;
+}
+declare abstract class HostedReranker implements Reranker {
+    #private;
+    readonly profile: {
+        readonly provider: "jina" | "cohere";
+        readonly model: string;
+    };
+    protected constructor(options: HostedRerankerOptions, settings: HostedRerankerSettings);
+    rerank(query: string, documents: readonly string[], options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<Array<{
+        index: number;
+        score: number;
+    }>>;
+}
+type CohereRerankerOptions = HostedRerankerOptions;
+declare class CohereReranker extends HostedReranker {
+    constructor(options?: CohereRerankerOptions);
+}
+type JinaRerankerOptions = HostedRerankerOptions;
+declare class JinaReranker extends HostedReranker {
+    constructor(options?: JinaRerankerOptions);
+}
+
+interface OpenAILLMRerankerOptions {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+    candidateCount?: number;
+}
+declare class OpenAILLMReranker implements Reranker {
+    #private;
+    readonly profile: {
+        readonly provider: "openai";
+        readonly model: string;
+    };
+    readonly candidateCount: number;
+    readonly maximumCandidateCount = 100;
+    constructor(options?: OpenAILLMRerankerOptions);
+    rerank(query: string, documents: readonly string[], options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<Array<{
+        index: number;
+        score: number;
+    }>>;
+}
+
 declare class CodeIndexError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
@@ -428,6 +561,7 @@ declare function openCodeIndex(options: CodeIndexOptions): CodeIndex;
 declare function updateFiles(index: CodeIndex, options: UpdateFilesOptions): Promise<UpdateStats>;
 declare function updateFromGit(index: CodeIndex, options?: UpdateFromGitOptions): Promise<UpdateStats>;
 declare function updateFromWorkingTree(index: CodeIndex, options?: UpdateFromWorkingTreeOptions): Promise<UpdateStats>;
+declare function reindexFiles(index: CodeIndex, options?: ReindexFilesOptions): Promise<ReindexFilesStats>;
 declare function similaritySearch(index: CodeIndex, options: SimilaritySearchOptions): Promise<SimilarityResult[]>;
 declare function useDescriptions(index: CodeIndex, options?: {
     signal?: AbortSignal;
@@ -437,4 +571,4 @@ declare function searchDescription(index: CodeIndex, options: SimilaritySearchOp
 declare function crossSearchFunctions(options: CrossSearchOptions): AsyncGenerator<CrossSearchResult, any, any>;
 declare function analyzeCodeCohesion(options: CohesionAnalysisOptions): Promise<CohesionReport<IndexedFunction>>;
 
-export { type AnalysisSimilarity, type CallableKind, CodeIndex, CodeIndexError, type CodeIndexOptions, type CohesionAnalysisOptions, type CohesionFileReport, type CohesionFunctionReference, type CohesionGroup, type CohesionJsonReport, type CohesionLocation, type CohesionLocationCategory, type CohesionMetrics, type CohesionPair, type CohesionReport, type CrossSearchOptions, type CrossSearchResult, type CrossSearchSourceFilter, type DescriptionInput, type DescriptionProfile, type DescriptionProvider, type DescriptionStats, type EmbeddingProfile, type EmbeddingProvider, GitDivergenceError, GitUnavailableError, IncompatibleIndexError, type IndexStatus, type IndexedFunction, type IndexingError, type IndexingIssue, JinaEmbeddingProvider, type JinaEmbeddingProviderOptions, OpenAIDescriptionProvider, type OpenAIDescriptionProviderOptions, OpenAIEmbeddingProvider, type OpenAIEmbeddingProviderOptions, type ParsedCallable, type SimilarityResult, type SimilarityScores, type SimilaritySearchOptions, type SourceMode, type SupportedLanguage, type UpdateFilesOptions, type UpdateFromGitOptions, type UpdateFromWorkingTreeOptions, type UpdateStats, analyzeCodeCohesion, analyzeCohesion, cohesionLocation, crossSearch, crossSearchFunctions, disableDescriptions, openCodeIndex, readIndexErrors, searchDescription, similaritySearch, updateFiles, updateFromGit, updateFromWorkingTree, useDescriptions };
+export { type AnalysisSimilarity, type CallableKind, CodeIndex, CodeIndexError, type CodeIndexOptions, CohereReranker, type CohereRerankerOptions, type CohesionAnalysisOptions, type CohesionFileReport, type CohesionFunctionReference, type CohesionGroup, type CohesionJsonReport, type CohesionLocation, type CohesionLocationCategory, type CohesionMetrics, type CohesionPair, type CohesionReport, type CrossSearchMatch, type CrossSearchOptions, type CrossSearchResult, type CrossSearchSourceFilter, type DescriptionFileInput, type DescriptionFileSession, type DescriptionInput, type DescriptionProfile, type DescriptionProvider, type DescriptionProviderName, type DescriptionStats, type EmbeddingProfile, type EmbeddingProvider, GitDivergenceError, GitUnavailableError, IncompatibleIndexError, type IndexStatus, type IndexedFunction, type IndexingError, type IndexingIssue, JinaEmbeddingProvider, type JinaEmbeddingProviderOptions, JinaReranker, type JinaRerankerOptions, OpenAIDescriptionProvider, type OpenAIDescriptionProviderOptions, OpenAIEmbeddingProvider, type OpenAIEmbeddingProviderOptions, OpenAILLMReranker, type OpenAILLMRerankerOptions, type ParsedCallable, type ReindexFilesOptions, type ReindexFilesStats, type Reranker, type RerankerProfile, type SimilarityResult, type SimilarityScores, type SimilaritySearchOptions, type SourceMode, type SupportedLanguage, type UpdateFilesOptions, type UpdateFromGitOptions, type UpdateFromWorkingTreeOptions, type UpdateStats, analyzeCodeCohesion, analyzeCohesion, cohesionLocation, crossSearch, crossSearchFunctions, disableDescriptions, openCodeIndex, readIndexErrors, reindexFiles, searchDescription, similaritySearch, updateFiles, updateFromGit, updateFromWorkingTree, useDescriptions };