@noyrax/5d-database-plugin 0.1.0

package/out/core/chromadb-vector-database.js

@@ -0,0 +1,276 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChromaDbVectorDatabase = void 0;
+const path = __importStar(require("path"));
+/**
+ * ChromaDB-based vector database implementation for Windows.
+ * Uses ChromaDB as an external vector database via HTTP API.
+ *
+ * Note: ChromaDB must be running as a local server or embedded instance.
+ * For embedded mode, ChromaDB requires Python, but we can use the HTTP client.
+ */
+class ChromaDbVectorDatabase {
+    constructor(db, workspaceRoot) {
+        this.chromaClient = null;
+        this.collection = null;
+        this.available = false;
+        this.embeddingDimensions = 1536;
+        this.collectionName = 'embeddings';
+        this.db = db;
+        this.workspaceRoot = workspaceRoot;
+    }
+    /**
+     * Checks if ChromaDB is available.
+     */
+    isAvailable() {
+        return this.available;
+    }
+    /**
+     * Initializes ChromaDB connection and collection.
+     */
+    async initialize() {
+        try {
+            // Try to import chromadb package
+            let ChromaClient;
+            try {
+                const chromadb = require('chromadb');
+                ChromaClient = chromadb.ChromaClient;
+                if (!ChromaClient) {
+                    console.warn('[ChromaDbVectorDatabase] ChromaClient not found in chromadb package.');
+                    this.available = false;
+                    return;
+                }
+            }
+            catch (importError) {
+                console.warn('[ChromaDbVectorDatabase] chromadb package not found.');
+                console.warn('[ChromaDbVectorDatabase] Please install chromadb: npm install chromadb');
+                console.warn('[ChromaDbVectorDatabase] For now, falling back to cosine similarity.');
+                this.available = false;
+                return;
+            }
+            // Initialize ChromaDB client (embedded mode)
+            // For embedded mode, we need to specify a persistent directory
+            const chromaPath = path.join(this.workspaceRoot, '.database-plugin', 'chromadb');
+            try {
+                // Use ChromaDB server (default: localhost:8000)
+                // Note: ChromaDB server needs to be started separately: chroma run --host localhost --port 8000
+                this.chromaClient = new ChromaClient({
+                    host: 'localhost',
+                    port: 8000
+                });
+                console.log(`[ChromaDbVectorDatabase] Initialized ChromaDB client (server: localhost:8000)`);
+            }
+            catch (serverError) {
+                console.warn(`[ChromaDbVectorDatabase] Failed to initialize ChromaDB client: ${serverError}`);
+                this.available = false;
+                return;
+            }
+            // Get or create collection (without default embedding function since we provide our own embeddings)
+            try {
+                this.collection = await this.chromaClient.getOrCreateCollection({
+                    name: this.collectionName,
+                    metadata: {
+                        description: 'Embeddings for 5D Database Plugin V-Dimension'
+                    }
+                    // Note: We don't specify an embedding function since we provide embeddings directly
+                });
+                this.available = true;
+                console.log('[ChromaDbVectorDatabase] ChromaDB initialized successfully.');
+            }
+            catch (collectionError) {
+                console.warn(`[ChromaDbVectorDatabase] Failed to get/create collection: ${collectionError}`);
+                this.available = false;
+            }
+        }
+        catch (error) {
+            console.warn(`[ChromaDbVectorDatabase] Initialization failed: ${error}`);
+            this.available = false;
+        }
+    }
+    /**
+     * Upserts an embedding into ChromaDB.
+     */
+    async upsertEmbedding(embeddingId, embeddingVector) {
+        if (!this.available || !this.collection) {
+            return;
+        }
+        try {
+            // Convert to number array
+            let vector;
+            if (embeddingVector instanceof Float32Array) {
+                vector = Array.from(embeddingVector);
+            }
+            else {
+                vector = embeddingVector;
+            }
+            // Get metadata from embeddings table (dimension, plugin_id, etc.)
+            // We need to query by ID directly since we don't have pluginId here
+            const embedding = await this.getEmbeddingById(embeddingId);
+            if (!embedding) {
+                console.warn(`[ChromaDbVectorDatabase] Embedding ${embeddingId} not found in embeddings table`);
+                return;
+            }
+            // Upsert to ChromaDB
+            await this.collection.upsert({
+                ids: [embeddingId],
+                embeddings: [vector],
+                metadatas: [{
+                        dimension: embedding.dimension,
+                        entity_id: embedding.entity_id,
+                        external_id: embedding.external_id,
+                        plugin_id: embedding.plugin_id,
+                        embedding_model: embedding.embedding_model
+                    }]
+            });
+        }
+        catch (error) {
+            console.warn(`[ChromaDbVectorDatabase] Failed to upsert embedding: ${error}`);
+        }
+    }
+    /**
+     * Searches for similar embeddings using ChromaDB.
+     */
+    async search(queryEmbedding, limit, dimension, pluginId) {
+        if (!this.available || !this.collection) {
+            return [];
+        }
+        try {
+            // Convert query embedding to number array
+            let queryVector;
+            if (queryEmbedding instanceof Float32Array) {
+                queryVector = Array.from(queryEmbedding);
+            }
+            else {
+                queryVector = queryEmbedding;
+            }
+            // Build where clause for filtering
+            // ChromaDB requires $and operator when multiple conditions are present
+            let where = undefined;
+            const conditions = [];
+            if (dimension) {
+                conditions.push({ dimension: dimension });
+            }
+            if (pluginId) {
+                conditions.push({ plugin_id: pluginId });
+            }
+            if (conditions.length === 1) {
+                where = conditions[0];
+            }
+            else if (conditions.length > 1) {
+                where = { $and: conditions };
+            }
+            // Query ChromaDB
+            const results = await this.collection.query({
+                queryEmbeddings: [queryVector],
+                nResults: limit,
+                where: where
+            });
+            // Map ChromaDB results to our format
+            // ChromaDB returns: { ids: string[][], distances: number[][], metadatas: any[][], ... }
+            const mappedResults = [];
+            if (results.ids && results.ids[0]) {
+                for (let i = 0; i < results.ids[0].length; i++) {
+                    const embeddingId = results.ids[0][i];
+                    const distance = results.distances?.[0]?.[i] || 0;
+                    // Get rowid from embeddings table
+                    const rowid = await this.getRowidFromEmbeddingId(embeddingId);
+                    if (rowid === null) {
+                        continue;
+                    }
+                    // Convert distance to similarity (ChromaDB uses cosine distance, 0 = identical, 1 = orthogonal)
+                    const similarity = 1 - Math.max(0, Math.min(1, distance));
+                    mappedResults.push({
+                        rowid: rowid,
+                        distance: distance,
+                        similarity: similarity
+                    });
+                }
+            }
+            return mappedResults;
+        }
+        catch (error) {
+            console.warn(`[ChromaDbVectorDatabase] Search failed: ${error}`);
+            return [];
+        }
+    }
+    /**
+     * Gets the embedding ID from a rowid.
+     */
+    async getEmbeddingIdFromRowid(rowid) {
+        return new Promise((resolve, reject) => {
+            this.db.get(`SELECT id FROM embeddings WHERE rowid = ?`, [rowid], (err, row) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve(row ? row.id : null);
+                }
+            });
+        });
+    }
+    /**
+     * Gets the rowid for an embedding ID.
+     */
+    async getRowidFromEmbeddingId(embeddingId) {
+        return new Promise((resolve, reject) => {
+            this.db.get(`SELECT rowid FROM embeddings WHERE id = ?`, [embeddingId], (err, row) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve(row ? row.rowid : null);
+                }
+            });
+        });
+    }
+    /**
+     * Gets an embedding by ID (helper method).
+     */
+    async getEmbeddingById(embeddingId) {
+        return new Promise((resolve, reject) => {
+            this.db.get(`SELECT * FROM embeddings WHERE id = ?`, [embeddingId], (err, row) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve(row || null);
+                }
+            });
+        });
+    }
+}
+exports.ChromaDbVectorDatabase = ChromaDbVectorDatabase;
+//# sourceMappingURL=chromadb-vector-database.js.map

package/out/core/chromadb-vector-database.js.map

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

package/out/core/docs-path-resolver.d.ts

@@ -0,0 +1,43 @@
+import * as vscode from 'vscode';
+/**
+ * Utility class for finding the docs directory across multiple workspace folders
+ * and parent directories. Ensures deterministic behavior by sorting workspace folders.
+ */
+export declare class DocsPathResolver {
+    /**
+     * Finds the docs directory by searching all workspace folders and optionally
+     * parent directories. Returns the first found docs directory or null.
+     *
+     * @param workspaceFolders Array of workspace folders (can be empty)
+     * @param searchParentDirectories Whether to search in parent directories if not found in workspace folders
+     * @param maxParentDepth Maximum depth to search in parent directories (default: 5)
+     * @returns The path to the docs directory or null if not found
+     */
+    static findDocsDirectory(workspaceFolders: readonly vscode.WorkspaceFolder[] | undefined, searchParentDirectories?: boolean, maxParentDepth?: number): string | null;
+    /**
+     * Checks if a docs directory exists in the given directory.
+     *
+     * @param dir The directory to check
+     * @returns The path to the docs directory if it exists, null otherwise
+     */
+    static findDocsInDirectory(dir: string): string | null;
+    /**
+     * Searches for a docs directory in parent directories, starting from the given directory.
+     * Stops when maxDepth is reached or when the root directory is reached.
+     *
+     * @param startDir The directory to start searching from
+     * @param maxDepth Maximum number of parent levels to search (default: 5)
+     * @returns The path to the docs directory if found, null otherwise
+     */
+    static findDocsInParentDirectories(startDir: string, maxDepth?: number): string | null;
+    /**
+     * Finds the docs directory from a given path (for CLI usage).
+     * Searches in the directory and parent directories.
+     *
+     * @param startPath The path to start searching from
+     * @param maxDepth Maximum number of parent levels to search (default: 5)
+     * @returns The path to the docs directory if found, null otherwise
+     */
+    static findDocsDirectoryFromPath(startPath: string, maxDepth?: number): string | null;
+}
+//# sourceMappingURL=docs-path-resolver.d.ts.map

package/out/core/docs-path-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-path-resolver.d.ts","sourceRoot":"","sources":["../../src/core/docs-path-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAIjC;;;GAGG;AACH,qBAAa,gBAAgB;IACzB;;;;;;;;OAQG;WACW,iBAAiB,CAC3B,gBAAgB,EAAE,SAAS,MAAM,CAAC,eAAe,EAAE,GAAG,SAAS,EAC/D,uBAAuB,GAAE,OAAc,EACvC,cAAc,GAAE,MAAU,GAC3B,MAAM,GAAG,IAAI;IA6BhB;;;;;OAKG;WACW,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAa7D;;;;;;;OAOG;WACW,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,GAAG,IAAI;IAwBhG;;;;;;;OAOG;WACW,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,GAAG,IAAI;CAUlG"}

package/out/core/docs-path-resolver.js

@@ -0,0 +1,137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocsPathResolver = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Utility class for finding the docs directory across multiple workspace folders
+ * and parent directories. Ensures deterministic behavior by sorting workspace folders.
+ */
+class DocsPathResolver {
+    /**
+     * Finds the docs directory by searching all workspace folders and optionally
+     * parent directories. Returns the first found docs directory or null.
+     *
+     * @param workspaceFolders Array of workspace folders (can be empty)
+     * @param searchParentDirectories Whether to search in parent directories if not found in workspace folders
+     * @param maxParentDepth Maximum depth to search in parent directories (default: 5)
+     * @returns The path to the docs directory or null if not found
+     */
+    static findDocsDirectory(workspaceFolders, searchParentDirectories = true, maxParentDepth = 5) {
+        // First, search in all workspace folders (deterministically sorted)
+        if (workspaceFolders && workspaceFolders.length > 0) {
+            // Sort workspace folders alphabetically for determinism
+            const sortedFolders = [...workspaceFolders].sort((a, b) => a.uri.fsPath.localeCompare(b.uri.fsPath));
+            for (const folder of sortedFolders) {
+                const docsPath = this.findDocsInDirectory(folder.uri.fsPath);
+                if (docsPath) {
+                    return docsPath;
+                }
+            }
+            // If not found in workspace folders and searchParentDirectories is true,
+            // search in parent directories of the first workspace folder
+            if (searchParentDirectories && sortedFolders.length > 0) {
+                const firstFolderPath = sortedFolders[0].uri.fsPath;
+                const parentDocsPath = this.findDocsInParentDirectories(firstFolderPath, maxParentDepth);
+                if (parentDocsPath) {
+                    return parentDocsPath;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Checks if a docs directory exists in the given directory.
+     *
+     * @param dir The directory to check
+     * @returns The path to the docs directory if it exists, null otherwise
+     */
+    static findDocsInDirectory(dir) {
+        const docsPath = path.join(dir, 'docs');
+        if (fs.existsSync(docsPath)) {
+            const stats = fs.statSync(docsPath);
+            if (stats.isDirectory()) {
+                return docsPath;
+            }
+        }
+        return null;
+    }
+    /**
+     * Searches for a docs directory in parent directories, starting from the given directory.
+     * Stops when maxDepth is reached or when the root directory is reached.
+     *
+     * @param startDir The directory to start searching from
+     * @param maxDepth Maximum number of parent levels to search (default: 5)
+     * @returns The path to the docs directory if found, null otherwise
+     */
+    static findDocsInParentDirectories(startDir, maxDepth = 5) {
+        let currentDir = path.resolve(startDir);
+        let depth = 0;
+        while (depth < maxDepth) {
+            const docsPath = this.findDocsInDirectory(currentDir);
+            if (docsPath) {
+                return docsPath;
+            }
+            const parentDir = path.dirname(currentDir);
+            // Stop if we've reached the root (parent equals current)
+            if (parentDir === currentDir) {
+                break;
+            }
+            currentDir = parentDir;
+            depth++;
+        }
+        return null;
+    }
+    /**
+     * Finds the docs directory from a given path (for CLI usage).
+     * Searches in the directory and parent directories.
+     *
+     * @param startPath The path to start searching from
+     * @param maxDepth Maximum number of parent levels to search (default: 5)
+     * @returns The path to the docs directory if found, null otherwise
+     */
+    static findDocsDirectoryFromPath(startPath, maxDepth = 5) {
+        // First check in the start directory
+        const docsPath = this.findDocsInDirectory(startPath);
+        if (docsPath) {
+            return docsPath;
+        }
+        // Then search in parent directories
+        return this.findDocsInParentDirectories(startPath, maxDepth);
+    }
+}
+exports.DocsPathResolver = DocsPathResolver;
+//# sourceMappingURL=docs-path-resolver.js.map

package/out/core/docs-path-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-path-resolver.js","sourceRoot":"","sources":["../../src/core/docs-path-resolver.ts"],"names":[],"mappings":"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"}

package/out/core/id-mapper.d.ts

@@ -0,0 +1,68 @@
+import { MultiDbManager, Dimension } from './multi-db-manager';
+/**
+ * ID mapping record for external to internal ID translation
+ */
+export interface IdMapping {
+    internal_id: string;
+    external_id: string;
+    plugin_id: string;
+}
+/**
+ * Manages ID mappings between external IDs (from documentation) and internal DB IDs (UUIDs).
+ * Each dimension has its own ID mapping table.
+ */
+export declare class IdMapper {
+    private dbManager;
+    /**
+     * Creates a new IdMapper instance.
+     *
+     * @param dbManager The MultiDbManager instance
+     */
+    constructor(dbManager: MultiDbManager);
+    /**
+     * Gets the table name for ID mappings for a dimension.
+     *
+     * @param dimension The dimension
+     * @returns The table name
+     */
+    private getMappingTableName;
+    /**
+     * Maps an external ID to an internal ID for a dimension.
+     * If the mapping doesn't exist, creates a new one.
+     *
+     * @param dimension The dimension
+     * @param externalId The external ID (e.g., symbol_id from JSONL, adr_number)
+     * @param internalId The internal UUID
+     * @param pluginId The plugin ID
+     * @returns Promise that resolves when the mapping is stored
+     */
+    setMapping(dimension: Dimension, externalId: string, internalId: string, pluginId: string): Promise<void>;
+    /**
+     * Gets the internal ID for an external ID.
+     *
+     * @param dimension The dimension
+     * @param externalId The external ID
+     * @param pluginId The plugin ID
+     * @returns Promise that resolves to the internal ID, or null if not found
+     */
+    getInternalId(dimension: Dimension, externalId: string, pluginId: string): Promise<string | null>;
+    /**
+     * Gets the external ID for an internal ID.
+     *
+     * @param dimension The dimension
+     * @param internalId The internal UUID
+     * @param pluginId The plugin ID
+     * @returns Promise that resolves to the external ID, or null if not found
+     */
+    getExternalId(dimension: Dimension, internalId: string, pluginId: string): Promise<string | null>;
+    /**
+     * Deletes a mapping for an external ID.
+     *
+     * @param dimension The dimension
+     * @param externalId The external ID
+     * @param pluginId The plugin ID
+     * @returns Promise that resolves when the mapping is deleted
+     */
+    deleteMapping(dimension: Dimension, externalId: string, pluginId: string): Promise<void>;
+}
+//# sourceMappingURL=id-mapper.d.ts.map

package/out/core/id-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-mapper.d.ts","sourceRoot":"","sources":["../../src/core/id-mapper.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,qBAAa,QAAQ;IACjB,OAAO,CAAC,SAAS,CAAiB;IAElC;;;;OAIG;gBACS,SAAS,EAAE,cAAc;IAIrC;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;;;;;;OASG;IACU,UAAU,CACnB,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAmBhB;;;;;;;OAOG;IACU,aAAa,CACtB,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAqBzB;;;;;;;OAOG;IACU,aAAa,CACtB,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAqBzB;;;;;;;OAOG;IACU,aAAa,CACtB,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;CAkBnB"}