@yuaone/core 0.1.0

package/dist/vector-index.d.ts

@@ -0,0 +1,314 @@
+/**
+ * @module vector-index
+ * @description Vector DB Code Indexer — pgvector 기반 시맨틱 코드 검색.
+ *
+ * 코드 임베딩을 PostgreSQL pgvector에 저장하고, 자연어 / 코드 유사도로 검색.
+ * DB 연결은 외부에서 주입 (SQLExecutor), 임베딩 생성도 외부에서 주입 (EmbeddingProvider).
+ *
+ * 주요 기능:
+ * - 코드 심볼 인덱싱 (함수, 클래스, 인터페이스, 타입, enum 등)
+ * - 시맨틱 검색 (자연어 → 코드)
+ * - 코드 유사도 검색 (중복/유사 코드 탐지)
+ * - 파일 단위 재인덱싱
+ * - 프로젝트 통계
+ */
+/** 코드 심볼의 타입 */
+export type SymbolType = "function" | "class" | "interface" | "type" | "enum" | "variable" | "method";
+/** 코드 임베딩 레코드 */
+export interface CodeEmbedding {
+    /** DB primary key (auto-generated) */
+    id?: number;
+    /** 프로젝트 식별자 */
+    projectId: string;
+    /** 소스 파일 경로 (프로젝트 루트 기준 상대경로) */
+    filePath: string;
+    /** 심볼 이름 (함수명, 클래스명 등) */
+    symbolName: string;
+    /** 심볼 종류 */
+    symbolType: SymbolType;
+    /** 코드 스니펫 원문 */
+    codeSnippet: string;
+    /** 임베딩 벡터 (1536-dim for OpenAI, 768 for others) */
+    embedding: number[];
+    /** 심볼 메타데이터 */
+    metadata: {
+        /** 시작 라인 (1-based) */
+        line: number;
+        /** 종료 라인 (1-based) */
+        endLine: number;
+        /** 함수 파라미터 시그니처 */
+        params?: string;
+        /** 반환 타입 */
+        returnType?: string;
+        /** export 여부 */
+        exported: boolean;
+        /** 코드 복잡도 (cyclomatic) */
+        complexity?: number;
+    };
+    /** 마지막 인덱싱 시각 */
+    updatedAt: Date;
+}
+/** 벡터 검색 결과 */
+export interface VectorSearchResult {
+    /** 심볼 이름 */
+    symbolName: string;
+    /** 파일 경로 */
+    filePath: string;
+    /** 심볼 종류 */
+    symbolType: string;
+    /** 코드 스니펫 */
+    codeSnippet: string;
+    /** 코사인 유사도 (0–1, 1이 완전 일치) */
+    similarity: number;
+    /** 메타데이터 */
+    metadata: Record<string, unknown>;
+}
+/**
+ * 임베딩 생성 프로바이더.
+ * 외부에서 주입 — OpenAI, Cohere, local model 등.
+ */
+export interface EmbeddingProvider {
+    /** 텍스트 배열을 임베딩 벡터 배열로 변환 */
+    embed(texts: string[]): Promise<number[][]>;
+    /** 임베딩 차원 수 (1536 for OpenAI text-embedding-3-small, 768 for others) */
+    dimension: number;
+}
+/**
+ * SQL 실행기 — 외부에서 주입 (yua-backend의 PostgreSQL pool).
+ * 이 모듈은 직접 DB 연결을 하지 않는다.
+ */
+export interface SQLExecutor {
+    /** SQL 쿼리 실행 */
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+/** VectorIndex 설정 */
+export interface VectorIndexConfig {
+    /** 프로젝트 식별자 */
+    projectId: string;
+    /** 임베딩 생성 프로바이더 */
+    embeddingProvider: EmbeddingProvider;
+    /** SQL 실행기 */
+    sqlExecutor: SQLExecutor;
+    /** 배치 인덱싱 크기 (default: 50) */
+    batchSize?: number;
+    /** 임베딩 차원 (default: 1536) */
+    dimension?: number;
+}
+/** 인덱스 통계 */
+export interface IndexStats {
+    /** 총 임베딩 수 */
+    totalEmbeddings: number;
+    /** 인덱싱된 파일 수 */
+    totalFiles: number;
+    /** 마지막 인덱싱 시각 */
+    lastIndexedAt: Date | null;
+    /** 인덱스 테이블 크기 (bytes, 추정) */
+    indexSizeBytes: number;
+}
+/**
+ * VectorIndex — pgvector 기반 코드 시맨틱 인덱서.
+ *
+ * 코드 심볼을 벡터로 변환하여 PostgreSQL에 저장하고,
+ * 자연어 질의 또는 코드 유사도로 검색하는 기능을 제공한다.
+ *
+ * @example
+ * ```ts
+ * const index = new VectorIndex({
+ *   projectId: "my-project",
+ *   embeddingProvider: openaiEmbedder,
+ *   sqlExecutor: pgPool,
+ * });
+ * await index.initialize();
+ * await index.indexBatch(symbols);
+ * const results = await index.search("user authentication logic");
+ * ```
+ */
+export declare class VectorIndex {
+    private config;
+    constructor(config: VectorIndexConfig);
+    /**
+     * CREATE TABLE + INDEX SQL을 생성한다 (idempotent).
+     * pgvector extension, 테이블, 인덱스를 모두 포함.
+     *
+     * @returns 실행할 SQL 문자열
+     */
+    getCreateTableSQL(): string;
+    /**
+     * 테이블을 초기화한다 (startup 시 호출).
+     * CREATE TABLE + INDEX를 실행한다 (idempotent).
+     */
+    initialize(): Promise<void>;
+    /**
+     * 단일 심볼을 인덱싱한다 (upsert).
+     * 이미 임베딩이 포함된 CodeEmbedding을 받는다.
+     *
+     * @param symbol - 임베딩이 포함된 코드 심볼
+     */
+    indexSymbol(symbol: CodeEmbedding): Promise<void>;
+    /**
+     * 여러 심볼을 배치로 인덱싱한다.
+     * 임베딩이 없는 심볼을 받아 자동으로 임베딩을 생성한다.
+     *
+     * @param symbols - 임베딩 없는 코드 심볼 배열
+     * @returns 인덱싱된 심볼 수
+     */
+    indexBatch(symbols: Omit<CodeEmbedding, "embedding">[]): Promise<number>;
+    /**
+     * 파일 하나를 재인덱싱한다.
+     * 기존 임베딩을 삭제하고 새로운 심볼로 교체한다.
+     *
+     * @param filePath - 파일 경로 (프로젝트 루트 기준)
+     * @param symbols - 새로운 심볼 배열 (임베딩 없음)
+     * @returns 인덱싱된 심볼 수
+     */
+    reindexFile(filePath: string, symbols: Omit<CodeEmbedding, "embedding">[]): Promise<number>;
+    /**
+     * 파일의 모든 임베딩을 삭제한다.
+     *
+     * @param filePath - 파일 경로
+     * @returns 삭제된 행 수
+     */
+    removeFile(filePath: string): Promise<number>;
+    /**
+     * 프로젝트의 모든 임베딩을 삭제한다.
+     *
+     * @returns 삭제된 행 수
+     */
+    clearProject(): Promise<number>;
+    /**
+     * 자연어 쿼리로 시맨틱 검색한다.
+     *
+     * @param query - 자연어 검색 쿼리 (e.g., "user authentication logic")
+     * @param limit - 최대 결과 수 (default: 10)
+     * @returns 유사도 순으로 정렬된 검색 결과
+     */
+    search(query: string, limit?: number): Promise<VectorSearchResult[]>;
+    /**
+     * 코드 스니펫 유사도로 검색한다.
+     *
+     * @param codeSnippet - 비교할 코드 스니펫
+     * @param limit - 최대 결과 수 (default: 10)
+     * @param threshold - 최소 유사도 임계값 (default: 0.7)
+     * @returns 유사도 순으로 정렬된 검색 결과 (threshold 이상만)
+     */
+    searchBySimilarity(codeSnippet: string, limit?: number, threshold?: number): Promise<VectorSearchResult[]>;
+    /**
+     * 심볼 타입으로 필터링하여 검색한다.
+     *
+     * @param query - 자연어 검색 쿼리
+     * @param symbolType - 필터링할 심볼 타입 (e.g., "function", "class")
+     * @param limit - 최대 결과 수 (default: 10)
+     * @returns 유사도 순으로 정렬된 검색 결과
+     */
+    searchByType(query: string, symbolType: string, limit?: number): Promise<VectorSearchResult[]>;
+    /**
+     * 중복/유사 코드를 탐지한다.
+     *
+     * @param codeSnippet - 비교할 코드 스니펫
+     * @param threshold - 최소 유사도 임계값 (default: 0.85, 높은 값으로 중복 탐지)
+     * @returns 유사도 순으로 정렬된 검색 결과
+     */
+    findSimilarCode(codeSnippet: string, threshold?: number): Promise<VectorSearchResult[]>;
+    /**
+     * 파일의 모든 심볼을 조회한다.
+     *
+     * @param filePath - 파일 경로
+     * @returns 해당 파일의 CodeEmbedding 배열
+     */
+    getFileSymbols(filePath: string): Promise<CodeEmbedding[]>;
+    /**
+     * 인덱스 통계를 조회한다.
+     *
+     * @returns 인덱스 통계 (총 임베딩 수, 파일 수, 마지막 인덱싱 시각, 테이블 크기)
+     */
+    getStats(): Promise<IndexStats>;
+    /**
+     * 파일이 인덱싱되어 있는지 확인한다.
+     *
+     * @param filePath - 파일 경로
+     * @returns 인덱싱 여부
+     */
+    isFileIndexed(filePath: string): Promise<boolean>;
+    /**
+     * 코드 심볼을 임베딩용 텍스트로 변환한다.
+     * 파일 경로, 심볼 타입, 이름, 코드를 포함한 리치 텍스트를 생성하여
+     * 임베딩 품질을 높인다.
+     *
+     * @param symbol - 심볼 정보
+     * @returns 임베딩용 텍스트
+     *
+     * @example
+     * ```
+     * File: src/auth/login.ts
+     * Type: function
+     * Name: validateUser
+     * Code:
+     * async function validateUser(email: string): Promise<User | null> { ... }
+     * ```
+     */
+    buildSnippetForEmbedding(symbol: {
+        name: string;
+        type: string;
+        code: string;
+        file: string;
+    }): string;
+    /**
+     * 텍스트 배열의 임베딩을 생성한다.
+     * 프로바이더의 batch API를 사용한다.
+     */
+    private generateEmbeddings;
+    /**
+     * 임베딩 벡터를 PostgreSQL vector 리터럴 형식으로 변환한다.
+     *
+     * @param embedding - 숫자 배열
+     * @returns "[0.1,0.2,...]" 형식의 문자열
+     */
+    private formatVector;
+    /**
+     * Upsert SQL을 생성한다.
+     * (project_id, file_path, symbol_name, symbol_type) 기준으로 UPSERT.
+     */
+    private buildUpsertSQL;
+    /**
+     * 벡터 검색 SQL을 생성한다.
+     * 코사인 거리(<=>)를 사용하여 유사도 순으로 정렬한다.
+     *
+     * @param embedding - 쿼리 임베딩 벡터
+     * @param limit - 최대 결과 수
+     * @param filters - 선택적 필터 (symbolType, threshold)
+     */
+    private buildSearchSQL;
+    /**
+     * DB 행 배열을 VectorSearchResult 배열로 변환한다.
+     */
+    private mapSearchResults;
+    /**
+     * DB 행을 CodeEmbedding으로 변환한다.
+     */
+    private mapRowToEmbedding;
+    /**
+     * PostgreSQL vector 리터럴 "[0.1,0.2,...]"을 숫자 배열로 파싱한다.
+     */
+    private parseVector;
+    /**
+     * JSONB 값을 Record<string, unknown>으로 파싱한다.
+     */
+    private parseJsonb;
+    /**
+     * JSONB 메타데이터를 CodeEmbedding.metadata 형식으로 파싱한다.
+     */
+    private parseEmbeddingMetadata;
+    /**
+     * 코드에서 함수/메서드 시그니처를 추출한다.
+     * 임베딩에 시그니처를 포함하면 검색 품질이 향상된다.
+     */
+    private extractSignature;
+    /**
+     * SQL 문자열을 개별 statement로 분리한다.
+     * DO $$ ... $$ 블록을 올바르게 처리한다.
+     */
+    private splitStatements;
+}
+//# sourceMappingURL=vector-index.d.ts.map

package/dist/vector-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-index.d.ts","sourceRoot":"","sources":["../src/vector-index.ts"],"names":[],"mappings":"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"}