@ninjaxtools/slopdex 0.3.0 → 0.8.0

package/dist/index.d.ts

@@ -3,30 +3,63 @@ declare class CodeIndex {
     readonly rootDir: string;
     readonly indexPath: string;
     readonly provider: EmbeddingProvider;
+    readonly summaryProvider: SummaryProvider;
     constructor(options: CodeIndexOptions);
     close(): void;
     status(): IndexStatus;
     allFunctions(): IndexedFunction[];
+    indexErrors(): IndexingError[];
     updateFiles(options: UpdateFilesOptions): Promise<UpdateStats>;
+    updateFromWorkingTree(options?: UpdateFromWorkingTreeOptions): Promise<UpdateStats>;
     updateFromGit(options?: UpdateFromGitOptions): Promise<UpdateStats>;
+    useSummaries(options?: {
+        signal?: AbortSignal;
+    }): Promise<SummaryStats>;
+    searchSummary(options: SimilaritySearchOptions): Promise<SimilarityResult[]>;
     similaritySearch(options: SimilaritySearchOptions): Promise<SimilarityResult[]>;
     similarToFunction(functionId: number, options: {
+        includeSummaries?: boolean;
         limit: number;
         minSimilarity: number;
         maxSimilarity?: number;
+        excludePaths?: readonly string[];
+        minLines?: number;
+        nameRegex?: string;
     }): SimilarityResult[];
-    vectorForFunction(functionId: number): number[];
+    vectorForFunction(functionId: number, kind?: "code" | "summary"): number[];
     searchByVector(vector: readonly number[], options: {
+        summaryVector?: readonly number[];
         limit: number;
         minSimilarity: number;
         maxSimilarity?: number;
+        excludePaths?: readonly string[];
+        minLines?: number;
+        nameRegex?: string;
     }): SimilarityResult[];
     sourceFunctions(filter: CrossSearchSourceFilter): Promise<IndexedFunction[]>;
 }
 
-type SupportedLanguage = "typescript" | "tsx" | "javascript" | "jsx";
+type SupportedLanguage = "python" | "javascript" | "jsx" | "typescript" | "tsx" | "rust" | "go" | "java" | "c";
 type CallableKind = "function" | "method" | "constructor" | "generator";
 type SourceMode = "git" | "working-tree";
+interface IndexingIssue {
+    path: string;
+    language: SupportedLanguage | null;
+    scope: "file" | "function";
+    code: "parse-error" | "parse-failed" | "extraction-error" | "read-error" | "file-too-large";
+    message: string;
+    qualifiedName: string | null;
+    startLine: number | null;
+    startColumn: number | null;
+    endLine: number | null;
+    endColumn: number | null;
+    source: string | null;
+}
+interface IndexingError extends IndexingIssue {
+    id: number;
+    sourceMode: SourceMode;
+    indexedCommit: string | null;
+}
 interface ParsedCallable {
     path: string;
     language: SupportedLanguage;
@@ -39,6 +72,7 @@ interface ParsedCallable {
     startColumn: number;
     endLine: number;
     endColumn: number;
+    lineCount: number;
     source: string;
     sourceHash: string;
     embeddingInput: string;
@@ -49,6 +83,8 @@ interface IndexedFunction extends ParsedCallable {
     lastSeenCommit: string | null;
     sourceMode: SourceMode;
     embeddingId: number;
+    summary: string | null;
+    summaryEmbeddingId: number | null;
 }
 interface EmbeddingProfile {
     provider: "openai" | "jina" | string;
@@ -65,10 +101,31 @@ interface EmbeddingProvider {
         signal?: AbortSignal;
     }): Promise<number[]>;
 }
+interface SummaryProfile {
+    provider: string;
+    model: string;
+    strategyVersion: string;
+}
+interface SummaryInput {
+    repository: string;
+    callable: ParsedCallable;
+    fileSource: string;
+}
+interface SummaryProvider {
+    readonly profile: SummaryProfile;
+    summarize(input: SummaryInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+}
+interface SummaryStats {
+    summariesCreated: number;
+    summariesEnabled: boolean;
+}
 interface CodeIndexOptions {
     rootDir: string;
     indexPath?: string;
     provider: EmbeddingProvider;
+    summaryProvider?: SummaryProvider;
     onWarning?: (message: string) => void;
     include?: readonly string[];
     exclude?: readonly string[];
@@ -88,6 +145,10 @@ interface UpdateFilesOptions {
 interface UpdateFromGitOptions {
     target?: string;
     rebuildOnDivergence?: boolean;
+    includeWorkingTree?: boolean;
+    signal?: AbortSignal;
+}
+interface UpdateFromWorkingTreeOptions {
     signal?: AbortSignal;
 }
 interface UpdateStats {
@@ -101,22 +162,42 @@ interface UpdateStats {
 }
 interface SimilaritySearchOptions {
     query: string;
+    /** Restrict result qualified names before ranking and limiting. */
+    nameRegex?: string;
     limit?: number;
     minSimilarity?: number;
     maxSimilarity?: number;
     signal?: AbortSignal;
 }
-interface SimilarityResult {
-    function: IndexedFunction;
+interface SimilarityScores {
     similarity: number;
+    codeSimilarity?: number;
+    summarySimilarity?: number;
+}
+interface AnalysisSimilarity {
+    similarityMode: "code" | "code-summary-average";
+    similarityWeights: {
+        code: number;
+        summary: number;
+    };
+}
+interface SimilarityResult extends SimilarityScores {
+    function: IndexedFunction;
 }
-type CrossSearchSourceFilter = {
+type CrossSearchSourceFilter = ({
     type: "all";
     path?: string;
 } | {
-    type: "added-since";
+    type: "changed-since";
     commit: string;
     path?: string;
+    uncommitted?: boolean;
+} | {
+    type: "uncommitted";
+    path?: string;
+}) & {
+    /** Restrict source qualified names; does not restrict target candidates. */
+    nameRegex?: string;
 };
 interface CrossSearchOptions {
     source: CodeIndex;
@@ -126,6 +207,9 @@ interface CrossSearchOptions {
     minSimilarity?: number;
     maxSimilarity?: number;
     includeSymmetricDuplicates?: boolean;
+    crossFileOnly?: boolean;
+    minLines?: number;
+    nameRegex?: string;
     signal?: AbortSignal;
     onProgress?: (progress: {
         completed: number;
@@ -135,7 +219,111 @@ interface CrossSearchOptions {
 interface CrossSearchResult {
     source: IndexedFunction;
     matches: SimilarityResult[];
+    scoring?: AnalysisSimilarity & {
+        sourceSummaryProfile: SummaryProfile | null;
+        targetSummaryProfile: SummaryProfile | null;
+    };
+}
+type CohesionLocationCategory = "same-file" | "same-folder" | "different-folder";
+interface CohesionLocation {
+    category: CohesionLocationCategory;
+    physicalDistance: number;
+    folderHops: number;
+    commonAncestor: string | null;
+    sourceTestPair: boolean;
+}
+interface CohesionFunctionReference {
+    path: string;
+    qualifiedName: string;
+    kind: CallableKind;
+    signature: string | null;
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+    lineCount: number;
+    source?: string;
+}
+interface CohesionPair<FunctionValue = IndexedFunction> extends SimilarityScores {
+    rank: number;
+    left: FunctionValue;
+    right: FunctionValue;
+    reciprocal: boolean | null;
+    semanticWeight: number;
+    separationWeight: number;
+    cohesionGap: number;
+    location: CohesionLocation;
+}
+interface CohesionFileReport<FunctionValue = IndexedFunction> {
+    path: string;
+    functionCount: number;
+    internalAffinity: number;
+    sameFolderAffinity: number;
+    externalAffinity: number;
+    externalAffinityRatio: number;
+    strongestExternalMatch?: SimilarityScores & {
+        function: FunctionValue;
+        cohesionGap: number;
+    };
+}
+interface CohesionGroup<FunctionValue = IndexedFunction> {
+    rank: number;
+    memberCount: number;
+    fileCount: number;
+    minimumEdgeSimilarity: number;
+    maximumEdgeSimilarity: number;
+    maximumPhysicalDistance: number;
+    maximumCohesionGap: number;
+    members: FunctionValue[];
+}
+interface CohesionSummary {
+    scope: "repository" | "selected-sources";
+    functionsAnalyzed: number;
+    candidateFunctions: number;
+    semanticEdges: number;
+    sameFileRatio: number;
+    sameFolderRatio: number;
+    remoteRatio: number;
+    weightedMeanDistance: number;
+}
+interface CohesionAnalysisOptions {
+    source: CodeIndex;
+    sourceFilter?: CrossSearchSourceFilter;
+    neighbors?: number;
+    limit?: number;
+    minSimilarity?: number;
+    maxSimilarity?: number;
+    minLines?: number;
+    nameRegex?: string;
+    signal?: AbortSignal;
+    onProgress?: (progress: {
+        completed: number;
+        total: number;
+    }) => void;
+}
+interface CohesionReport<FunctionValue = IndexedFunction> {
+    schemaVersion: 1;
+    repository: {
+        generation: number;
+        gitCheckpoint: string | null;
+        embeddingProfile: Required<EmbeddingProfile>;
+        summaryProfile: SummaryProfile | null;
+    };
+    parameters: AnalysisSimilarity & {
+        neighbors: number;
+        limit: number;
+        minSimilarity: number;
+        maxSimilarity?: number;
+        minLines: number;
+        nameRegex?: string;
+        sourceFilter: CrossSearchSourceFilter;
+    };
+    summary: CohesionSummary;
+    pairs: CohesionPair<FunctionValue>[];
+    files: CohesionFileReport<FunctionValue>[];
+    groups: CohesionGroup<FunctionValue>[];
 }
+type CohesionJsonReport = CohesionReport<CohesionFunctionReference>;
 interface IndexStatus {
     rootDir: string;
     indexPath: string;
@@ -144,8 +332,18 @@ interface IndexStatus {
     generation: number;
     gitCheckpoint: string | null;
     embeddingProfile: Required<EmbeddingProfile>;
+    summariesEnabled: boolean;
+    summaryCount: number;
+    summaryProfile: SummaryProfile | null;
+    indexingErrorCount: number;
+    failedFileCount: number;
 }
 
+declare function readIndexErrors(indexPath: string): IndexingError[];
+
+declare function analyzeCohesion(options: CohesionAnalysisOptions): Promise<CohesionReport>;
+declare function cohesionLocation(leftPath: string, rightPath: string): CohesionLocation;
+
 declare function crossSearch(options: CrossSearchOptions): AsyncGenerator<CrossSearchResult>;
 
 interface OpenAIEmbeddingProviderOptions {
@@ -171,6 +369,24 @@ declare class OpenAIEmbeddingProvider implements EmbeddingProvider {
     }): Promise<number[]>;
 }
 
+interface OpenAISummaryProviderOptions {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+}
+declare class OpenAISummaryProvider implements SummaryProvider {
+    #private;
+    readonly profile: {
+        provider: string;
+        model: string;
+        strategyVersion: string;
+    };
+    constructor(options?: OpenAISummaryProviderOptions);
+    summarize(input: SummaryInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+}
+
 interface JinaEmbeddingProviderOptions {
     apiKey?: string;
     model?: string;
@@ -200,6 +416,9 @@ declare class CodeIndexError extends Error {
 declare class GitDivergenceError extends CodeIndexError {
     constructor(checkpoint: string, target: string);
 }
+declare class GitUnavailableError extends CodeIndexError {
+    constructor(message: string, options?: ErrorOptions);
+}
 declare class IncompatibleIndexError extends CodeIndexError {
     constructor(message: string);
 }
@@ -207,7 +426,13 @@ declare class IncompatibleIndexError extends CodeIndexError {
 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 similaritySearch(index: CodeIndex, options: SimilaritySearchOptions): Promise<SimilarityResult[]>;
+declare function useSummaries(index: CodeIndex, options?: {
+    signal?: AbortSignal;
+}): Promise<SummaryStats>;
+declare function searchSummary(index: CodeIndex, options: SimilaritySearchOptions): Promise<SimilarityResult[]>;
 declare function crossSearchFunctions(options: CrossSearchOptions): AsyncGenerator<CrossSearchResult, any, any>;
+declare function analyzeCodeCohesion(options: CohesionAnalysisOptions): Promise<CohesionReport<IndexedFunction>>;
 
-export { type CallableKind, CodeIndex, CodeIndexError, type CodeIndexOptions, type CrossSearchOptions, type CrossSearchResult, type CrossSearchSourceFilter, type EmbeddingProfile, type EmbeddingProvider, GitDivergenceError, IncompatibleIndexError, type IndexStatus, type IndexedFunction, JinaEmbeddingProvider, type JinaEmbeddingProviderOptions, OpenAIEmbeddingProvider, type OpenAIEmbeddingProviderOptions, type ParsedCallable, type SimilarityResult, type SimilaritySearchOptions, type SourceMode, type SupportedLanguage, type UpdateFilesOptions, type UpdateFromGitOptions, type UpdateStats, crossSearch, crossSearchFunctions, openCodeIndex, similaritySearch, updateFiles, updateFromGit };
+export { type AnalysisSimilarity, type CallableKind, CodeIndex, CodeIndexError, type CodeIndexOptions, type CohesionAnalysisOptions, type CohesionFileReport, type CohesionFunctionReference, type CohesionGroup, type CohesionJsonReport, type CohesionLocation, type CohesionLocationCategory, type CohesionPair, type CohesionReport, type CohesionSummary, type CrossSearchOptions, type CrossSearchResult, type CrossSearchSourceFilter, type EmbeddingProfile, type EmbeddingProvider, GitDivergenceError, GitUnavailableError, IncompatibleIndexError, type IndexStatus, type IndexedFunction, type IndexingError, type IndexingIssue, JinaEmbeddingProvider, type JinaEmbeddingProviderOptions, OpenAIEmbeddingProvider, type OpenAIEmbeddingProviderOptions, OpenAISummaryProvider, type OpenAISummaryProviderOptions, type ParsedCallable, type SimilarityResult, type SimilarityScores, type SimilaritySearchOptions, type SourceMode, type SummaryInput, type SummaryProfile, type SummaryProvider, type SummaryStats, type SupportedLanguage, type UpdateFilesOptions, type UpdateFromGitOptions, type UpdateFromWorkingTreeOptions, type UpdateStats, analyzeCodeCohesion, analyzeCohesion, cohesionLocation, crossSearch, crossSearchFunctions, openCodeIndex, readIndexErrors, searchSummary, similaritySearch, updateFiles, updateFromGit, updateFromWorkingTree, useSummaries };